The Standard ML Basis Library

The `Posix.IO` structure

The structure Posix.IO specifies functions that provide the primitive POSIX input/output operations, as described in Section 6 of the POSIX standard [CITE]1003.1,1996/.

Synopsis

signature POSIX_IO structure IO : POSIX_IO

Interface

eqtype file_desc eqtype pid val pipe : unit -> {infd : file_desc, outfd : file_desc} val dup : file_desc -> file_desc val dup2 : {old : file_desc, new : file_desc} -> unit val close : file_desc -> unit val readVec : (file_desc * int) -> Word8Vector.vector val readArr : (file_desc * {buf : Word8Array.array, i : int, sz : int option}) -> int val writeVec : (file_desc * {buf : Word8Vector.vector, i : int, sz : int option}) -> int val writeArr : (file_desc * {buf : Word8Array.array, i : int, sz : int option}) -> int datatype whence = SEEK_SET | SEEK_CUR | SEEK_END structure FD : sig include POSIX_FLAGS val cloexec : flags end structure O : sig include POSIX_FLAGS val append : flags val nonblock : flags val sync : flags end datatype open_mode = O_RDONLY | O_WRONLY | O_RDWR val dupfd : {old : file_desc, base : file_desc} -> file_desc val getfd : file_desc -> FD.flags val setfd : (file_desc * FD.flags) -> unit val getfl : file_desc -> (O.flags * open_mode) val setfl : (file_desc * O.flags) -> unit val lseek : (file_desc * Position.int * whence) -> Position.int val fsync : file_desc -> unit datatype lock_type = F_RDLCK | F_WRLCK | F_UNLCK structure FLock : sig type flock val flock : {ltype : lock_type, whence : whence, start : Position.int, len : Position.int, pid : pid option} -> flock val ltype : flock -> lock_type val whence : flock -> whence val start : flock -> Position.int val len : flock -> Position.int val pid : flock -> pid option end val getlk : (file_desc * FLock.flock) -> FLock.flock val setlk : (file_desc * FLock.flock) -> FLock.flock val setlkw : (file_desc * FLock.flock) -> FLock.flock

Description

eqtype file_desc

eqtype pid

pipe ()

creates a pipe (channel) and returns two file descriptors that refer to the read (infd) and write (outfd) ends of the pipe.

dup fd

returns a new file descriptor that refers to the same open file, with the same file pointer and access mode, as fd. The underlying word (see Posix.FileSys.fdToWord) of the returned file descriptor is the lowest one available. Equivalent to dupfd {old=fd, base=Posix.FileSys.wordToFD 0w0}.

dup2 {old, new}

duplicates the open file descriptor old as file descriptor new.

close fd

closes the file descriptor fd.

readVec (fd, n)

reads n bytes from the file referred to by fd. The size of the resulting vector is the number of bytes that were successfully read, which may be less than n.

readArr (fd, {buf, i, sz})

reads SOME(sz) bytes from file fd into buffer buf starting at buffer position i. Returns the number of bytes actually read. If sz is NONE, reads as many bytes as are available up to the number of bytes that can be placed in buffer starting at buffer position i. Raises Subscript if buffer bounds are violated.

writeVec (fd, {buf, i, sz})

writes SOME(sz) bytes from the vector buf, starting from position i, to the open file fd. If sz is NONE, writes the bytes from position i to the end of the buffer. Returns the number of bytes actually written. Raises Subscript if buffer bounds are violated.

writeArr (fd, {buf, i, sz})

writes SOME(sz) bytes from the array buf, starting from position i, to the open file fd. If sz is NONE, writes the bytes from position i to the end of the buffer. Returns the number of bytes actually written. Raises Subscript if buffer bounds are violated.

datatype whence

structure FD

cloexec: file descriptor flag that, if set for fd, will close fd should the opening process replace itself (through exec, etc.). If cloexec is not set, the file associated with fd will remain open in the new process.

structure O

append: file status flag that forces the file offset to be set to the end of the file prior to each write.
nonblock: file status flag to enable non-blocking IO.
sync: file status flag to enable writes using ``synchronized I/O file integrity completion.''

datatype open_mode

dupfd {old, base}

returns a file descriptor bound to old that is greater than or equal to (according to the underlying integer mapping; see Posix.FileSys.fdToWord and Posix.FileSys.wordToFD) the file descriptor base. Corresponds to the POSIX fcntl function with the F_DUPFD command.

getfd fd

gets the file descriptor flags associated with fd. Corresponds to the POSIX fcntl function with the F_GETFD command.

setfd (fd, fl)

sets the flags of file descriptor fd to fl. Corresponds to the POSIX fcntl function with the F_SETFD command.

getfl fd

gets the file status flags for the open file descriptor fd. Corresponds to the POSIX fcntl function with the F_GETFL command.

setfl (fd, fl)

sets the file status flags for the open file descriptor fd to fl. Corresponds to the POSIX fcntl function with the F_SETFL command.

lseek (fd, off, wh)

sets the file offset for open file descriptor fd to off if wh is SEEK_SET; to its current value plus off bytes if wh is SEEK_CUR; or, to the size of the file plus off bytes if wh is SEEK_END.

fsync fd

indicates that all data for the open file descriptor fd is to be transferred to the device associated with the descriptor; similar to a "flush" operation.

datatype lock_type

structure FLock

type flock
flock {ltype, whence, start, len, pid}: creates a flock data structure given ltype, whence, start, len and pid.
ltype fl: returns the ltype field for flock fl.
whence fl: returns the whence field for flock fl.
start fl: returns the start field for flock fl.
len fl: returns the len field for flock fl.
pid fl: returns the pid field for flock fl.

getlk (fd, fl)

gets the first lock that blocks the lock description fl on the open file descriptor fd. Corresponds to the POSIX fcntl function with the F_GETLK command.

setlk (fd, fl)

set or clear a file segment lock according to the lock description fl on the open file descriptor fd. Corresponds to the POSIX fcntl function with the F_SETLK command.

setlkw (fd, fl)

similar to the setlk function above except that setlkw waits on blocked locks until they released. Corresponds to the POSIX fcntl function with the F_SETLKW command.

Discussion

Many POSIX I/O functions can raise OS.SysErr. The above descriptions do not describe the particular system errors a function may raise; for now, consult more detailed POSIX documentation.