The Standard ML Basis Library

The OS.IO structure

The OS.IO structure provides a general interface for polling IO devices. This has been modelled after the Unix SVR4 poll interface. A poll_desc, created from an IO descriptor, can be used to test for various polling conditions.


signature OS_IO
structure IO : OS_IO


eqtype iodesc
val hash : iodesc -> word
val compare : (iodesc * iodesc) -> order
eqtype iodesc_kind
val kind : iodesc -> iodesc_kind
structure Kind : sig
    val file : iodesc_kind
    val dir : iodesc_kind
    val symlink : iodesc_kind
    val tty : iodesc_kind
    val pipe : iodesc_kind
    val socket : iodesc_kind
    val device : iodesc_kind
type poll_desc
type poll_info
val pollDesc : iodesc -> poll_desc option
val pollToIODesc : poll_desc -> iodesc
exception Poll
val pollIn : poll_desc -> poll_desc
val pollOut : poll_desc -> poll_desc
val pollPri : poll_desc -> poll_desc
val poll : (poll_desc list * Time.time option) -> poll_info list
val isIn : poll_info -> bool
val isOut : poll_info -> bool
val isPri : poll_info -> bool
val infoToPollDesc : poll_info -> poll_desc


eqtype iodesc
an iodesc is an abstraction for an opened OS object that supports IO (e.g., file, tty, device, socket, ...). In Unix, an iodesc would correspond to a file descriptor; in DOS, it would correspond to a file handle.

Since iodesc values correspond to low-level, OS-specific objects, they are not typically created explicitly by the user, but are generated as a side-effect of the creation of a more high-level abstraction. For example, TextIO.openIn creates an instream value, from which the underlying PrimIO.reader can be accessed. This latter value may contain the corresponding iodesc value.

If the underlying operating system is known, there will usually be mechanisms for converting between iodesc values and the type of value used by the operating system. For example, the functions Posix.FileSys.fdToIOD and Posix.FileSys.iodToFD provide this service for Posix implementations, translating between iodescs and open file descriptors.

hash iod
return a hash value for the IO descriptor iod.
Implementation note:

hash must have the property that values produced are well distributed when taken modulo 2(n) for any n.

compare (iod, iod')
returns LESS, EQUAL or GREATER when iod is less than, equal to, or greater than iod', respectively, in some underlying linear ordering on iodesc values.

eqtype iodesc_kind
This abstract type is used to represent the kind of system object that an iodesc represents. The possible values are defined in the Kind substructure.

kind iod
returns the kind of system object that the I/O descriptor iod represents. This will raise OS.SysErr if, for example, iod refers to a closed file.

structure Kind

val file
val dir
val symlink
val tty
val pipe
val socket
val device
These values represent the various kinds of system objects that an I/O descriptor might represent. The following list summarizes the intended meaning of these values:
A regular file in the file system. The I/O descriptor associated with a stream produced by one of the BinIO or TextIO file opening operations will always have this kind.
A directory in the file system. I/O descriptors associated with file-system objects for which OS.FileSys.isDir returns true will have this kind.
A symbolic link or file system alias. I/O descriptors associated with file-system objects for which OS.FileSys.isLink returns true will have this kind.
A terminal console.
A pipe to another system process.
A network socket.
A logical or physical hardware device.

type poll_desc
an abstract representation of a polling operation on an IO descriptor.

type poll_info
an abstract representation of the per-descriptor information returned by the poll operation.

pollDesc iod
create a polling operation on the given descriptor; NONE is returned when no polling is supported by the IO device.

pollToIODesc pd
return the IO descriptor that is being polled using pd.

exception Poll

pollIn pd
pollOut pd
pollPri pd
returns poll descriptor that has input (respectively, output, high-priority) polling added to the poll descriptor pd. Raises Poll if input (respectively, output, high-priority events) is not appropriate for the underlying IO device.

poll (l, opt)
polls a list of poll descriptors l. The argument opt specifies the timeout where: This will raise OS.SysErr if, for example, one of the file descriptors refers to a closed file.

isIn info
isOut info
isPri info
returns true if input (respectively, output, priority information) is present in info.

infoToPollDesc pi
returns the underlying poll descriptor from poll information pi.

[ INDEX | TOP | Parent | Root ]

Last Modified January 9, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies