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.

See Also

POSIX_FLAGS, Posix, Posix.IO, Posix.FileSys, Posix.Error, OS

[ INDEX | TOP | Parent | Root ]

Last Modified April 17, 1996
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies