The Standard ML Basis Library


The OS.IO structure


Synopsis

signature OS_IO
structure IO : OS_IO

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


Interface

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
  end
eqtype 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

Description

eqtype iodesc
An iodesc is an abstraction for an opened OS object that supports I/O (e.g., a file, console, or socket). In Unix, an iodesc corresponds to a file descriptor, while in Microsoft Windows it corresponds 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
returns a hash value for the I/O 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 : 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
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:
file
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.
dir
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.
symlink
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.
tty
A terminal console.
pipe
A pipe to another system process.
socket
A network socket.
device
A logical or physical hardware device.
Note that a given implementation may define other iodesc values not covered by these definitions.

eqtype poll_desc
An abstract representation of a polling operation on an I/O 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 I/O device.

pollToIODesc pd
return the I/O descriptor that is being polled using pd.

pollIn pd
pollOut pd
pollPri pd
These return a poll descriptor that has input (respectively, output, high-priority) polling added to the poll descriptor pd. It raises Poll if input (respectively, output, high-priority events) is not appropriate for the underlying I/O device.

poll (l, timeout)
polls a collection of I/O devices for the conditions specified by the list of poll descriptors l. The argument timeout specifies the timeout where: This returns a list of poll_info values corresponding to those descriptors in l whose conditions are enabled. The returned list respects the order of the argument list, and a value in the returned list will reflect a (nonempty) subset of the conditions specified in the corresponding argument descriptor. The poll function will raise OS.SysErr if, for example, one of the file descriptors refers to a closed file.

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

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

See Also

PRIM_IO, OS

Discussion

Question:

Why are the file attributes only available for open files?


[ Top | Parent | Contents | Index | Root ]

Generated October 02, 2003
Last Modified July 1, 2002
Comments to John Reppy.


This document may be distributed freely over the internet as long as the copyright notice and license terms below are prominently displayed within every machine-readable copy.

Copyright © 2003 AT&T and Lucent Technologies. All rights reserved.

Permission is granted for internet users to make one paper copy for their own personal use. Further hardcopy reproduction is strictly prohibited. Permission to distribute the HTML document electronically on any medium other than the internet must be requested from the copyright holders by contacting the editors. Printed versions of the SML Basis Manual are available from Cambridge University Press. To order, please visit www.cup.org (North America) or www.cup.cam.ac.uk (outside North America).