The Standard ML Basis Library

The `Posix.FileSys` structure

Synopsis

signature POSIX_FILE_SYS structure FileSys : POSIX_FILE_SYS

The structure Posix.FileSys provides access to file system operations as described in Section 5 of the POSIX standard 1003.1,1996[CITE].

Interface

eqtype uid eqtype gid eqtype file_desc val fdToWord : file_desc -> SysWord.word val wordToFD : SysWord.word -> file_desc val fdToIOD : file_desc -> OS.IO.iodesc val iodToFD : OS.IO.iodesc -> file_desc option type dirstream val opendir : string -> dirstream val readdir : dirstream -> string option val rewinddir : dirstream -> unit val closedir : dirstream -> unit val chdir : string -> unit val getcwd : unit -> string val stdin : file_desc val stdout : file_desc val stderr : file_desc structure S : sig eqtype mode include BIT_FLAGS where type flags = mode val irwxu : mode val irusr : mode val iwusr : mode val ixusr : mode val irwxg : mode val irgrp : mode val iwgrp : mode val ixgrp : mode val irwxo : mode val iroth : mode val iwoth : mode val ixoth : mode val isuid : mode val isgid : mode end structure O : sig include BIT_FLAGS val append : flags val excl : flags val noctty : flags val nonblock : flags val sync : flags val trunc : flags end datatype open_mode = O_RDONLY | O_WRONLY | O_RDWR val openf : string * open_mode * O.flags -> file_desc val createf : string * open_mode * O.flags * S.mode -> file_desc val creat : string * S.mode -> file_desc val umask : S.mode -> S.mode val link : {old : string, new : string} -> unit val mkdir : string * S.mode -> unit val mkfifo : string * S.mode -> unit val unlink : string -> unit val rmdir : string -> unit val rename : {old : string, new : string} -> unit val symlink : {old : string, new : string} -> unit val readlink : string -> string eqtype dev val wordToDev : SysWord.word -> dev val devToWord : dev -> SysWord.word eqtype ino val wordToIno : SysWord.word -> ino val inoToWord : ino -> SysWord.word structure ST : sig type stat val isDir : stat -> bool val isChr : stat -> bool val isBlk : stat -> bool val isReg : stat -> bool val isFIFO : stat -> bool val isLink : stat -> bool val isSock : stat -> bool val mode : stat -> S.mode val ino : stat -> ino val dev : stat -> dev val nlink : stat -> int val uid : stat -> uid val gid : stat -> gid val size : stat -> Position.int val atime : stat -> Time.time val mtime : stat -> Time.time val ctime : stat -> Time.time end val stat : string -> ST.stat val lstat : string -> ST.stat val fstat : file_desc -> ST.stat datatype access_mode = A_READ | A_WRITE | A_EXEC val access : string * access_mode list -> bool val chmod : string * S.mode -> unit val fchmod : file_desc * S.mode -> unit val chown : string * uid * gid -> unit val fchown : file_desc * uid * gid -> unit val utime : string * {actime : Time.time, modtime : Time.time} option -> unit val ftruncate : file_desc * Position.int -> unit val pathconf : string * string -> SysWord.word option val fpathconf : file_desc * string -> SysWord.word option

Description

eqtype uid

User identifier; identical to Posix.ProcEnv.uid.

eqtype gid

Group identifier; identical to Posix.ProcEnv.gid.

eqtype file_desc

Open file descriptor.

val fdToWord : file_desc -> SysWord.word val wordToFD : SysWord.word -> file_desc

These functions convert between an abstract open file descriptor and the integer representation used by the operating system. These calls should be avoided where possible, for the SML implementation may be able to garbage collect (i.e., automatically close) any file_desc value that is not accessible, but it cannot do this for any file_desc that has ever been made concrete by fdToWord. Also, there is no validation that the file descriptor created by wordToFD corresponds to an actually open file.

val fdToIOD : file_desc -> OS.IO.iodesc val iodToFD : OS.IO.iodesc -> file_desc option

These convert between a POSIX open file descriptor and the handle used by the OS subsystem. The function iodToFD returns an option type because, on certain systems, some open I/O devices are not associated with an underlying open file descriptor.

type dirstream

A directory stream opened for reading. A directory stream is an ordered sequence of all the directory entries in a particular directory. This type is identical to OS.FileSys.dirstream.

opendir dirName

opens the directory designated by the dirName parameter and associates a directory stream with it. The directory stream is positioned at the first entry.

readdir dir

returns and removes one filename from the directory stream dir. When the directory stream is empty (that is, when all entries have been read from the stream), NONE is returned. Entries for "." (current directory) and ".." (parent directory) are never returned.

Rationale:

The reason for filtering out the current and parent directory entries is that it makes recursive walks of a directory tree easier.

rewinddir d

repositions the directory stream d for reading at the beginning.

closedir d

closes the directory stream d. Closing a previously closed dirstream does not raise an exception.

chdir s

changes the current working directory to s.

val getcwd : unit -> string

The absolute pathname of the current working directory.

val stdin : file_desc val stdout : file_desc val stderr : file_desc

The standard input, output, and error file descriptors.

structure S

eqtype mode: A file mode is a set of (read, write, execute) permissions for the owner of the file, members of the file's group, and others.
val irwxu : mode: Read, write, and execute permission for ``user'' (the file's owner).
val irusr : mode: Read permission for ``user'' (the file's owner).
val iwusr : mode: Write permission for ``user'' (the file's owner).
val ixusr : mode: Execute permission for ``user'' (the file's owner).
val irwxg : mode: Read, write, and execute permission for members of the file's group.
val irgrp : mode: Read permission for members of the file's group.
val iwgrp : mode: Write permission for members of the file's group.
val ixgrp : mode: Execute permission for members of the file's group.
val irwxo : mode: Read, write, and execute permission for ``others'' (all users).
val iroth : mode: Read permission for ``others'' (all users).
val iwoth : mode: Write permission for ``others'' (all users).
val ixoth : mode: Execute permission for ``others'' (all users).
val isuid : mode: Set-user-id mode, indicating that the effective user ID of any user executing the file should be made the same as that of the owner of the file.
val isgid : mode: Set-group-id mode, indicating that the effective group ID of any user executing the file should be made the same as the group of the file.

structure O

The structure Posix.FileSys.O contains file status flags used in calls to openf.

val append : flags: If set, the file pointer is set to the end of the file prior to each write.
val excl : flags: This flag causes the open to fail if the file already exists.
val noctty : flags: If the path parameter identifies a terminal device, this flag assures that the terminal device does not become the controlling terminal for the process.
val nonblock : flags: Open, read, and write operations on the file will be nonblocking.
val sync : flags: If set, updates and writes to regular files and block devices are synchronous updates. On return from a function that performs a synchronous update (writeVec, writeArr, ftruncate, openf with trunc), the calling process is assured that all data for the file has been written to permanent storage, even if the file is also open for deferred update.
val trunc : flags: This causes the file to be truncated (to zero length) upon opening.

datatype open_mode

Operations allowed on an open file.

= O_RDONLY: Open a file for reading only.
| O_WRONLY: Open a file for writing only.
| O_RDWR: Open a file for reading and writing.

openf (s, om, f)

createf (s, om, f, m)

These calls open a file named s for reading, writing, or both (depending on the open mode om). The flags f specify the state of the open file. If the file does not exist, openf raises the OS.SysErr exception whereas createf creates the file, setting its protection mode to m (as modified by the umask).

Note that, in C, the roles of openf and createf are combined in the function open. The first acts like open without the O_CREAT flag; the second acts like open with the O_CREAT flag and the specified permission mode. Also, the createf function should not be confused with the creat function below, which behaves like its C namesake.

creat (s, m)

opens a file s for writing. If the file exists, this call truncates the file to zero length. If the file does not exist, it creates the file, setting its protection mode to m (as modified by the umask). This is equivalent to the expression:

createf(s,O_WRONLY,O.trunc,m)

umask cmask

sets the file mode creation mask of the process to cmask and returns the previous value of the mask.

Whenever a file is created (by openf, creat, mkdir, etc.), all file permission set in the file mode creation mask are removed from the mode of the created file. This clearing allows users to restrict the default access to their files.

The mask is inherited by child processes.

link {old, new}

creates an additional hard link (directory entry) for an existing file. Both the old and the new link share equal access rights to the underlying object.

Both old and new must reside on the same file system. A hard link to a directory cannot be created.

Upon successful completion, link updates the file status change time of the old file, and updates the file status change and modification times of the directory containing the new entry. (See Posix.FileSys.ST.)

mkdir (s, m)

creates a new directory named s with protection mode m (as modified by the umask).

mkfifo (s, m)

makes a FIFO special file (or named pipe) s, with protection mode m (as modified by the umask).

unlink path

removes the directory entry specified by path and, if the entry is a hard link, decrements the link count of the file referenced by the link.

When all links to a file are removed and no process has the file open or mapped, all resources associated with the file are reclaimed, and the file is no longer accessible. If one or more processes have the file open or mapped when the last link is removed, the link is removed before unlink returns, but the removal of the file contents is postponed until all open or map references to the file are removed. If the path parameter names a symbolic link, the symbolic link itself is removed.

rmdir s

removes a directory s, which must be empty.

rename {old, new}

changes the name of a file system object from old to new.

symlink {old, new}

creates a symbolic link new. Any component of a pathname resolving to new will be replaced by the text old. Note that old may be a relative or absolute pathname, and might not be the pathname of any existing file.

readlink s

reads the value of a symbolic link s.

eqtype dev

Device identifier. The device identifier and the file serial number (inode or ino) uniquely identify a file.

val wordToDev : SysWord.word -> dev val devToWord : dev -> SysWord.word

These functions convert between dev values and words by which the operating system identifies a device. There is no verification that a value created by wordToDev corresponds to a to a valid device identifier.

eqtype ino

File serial number (inode).

val wordToIno : SysWord.word -> ino val inoToWord : ino -> SysWord.word

These functions convert between ino values and words by which the operating system identifies an inode. There is no verification that a value created by wordToIno corresponds to a to a valid inode.

structure ST

type stat: This type models status information concerning a file.
val isDir : stat -> bool val isChr : stat -> bool val isBlk : stat -> bool val isReg : stat -> bool val isFIFO : stat -> bool val isLink : stat -> bool val isSock : stat -> bool: These functions return true if the file described by the parameter is, respectively, a directory, a character special device, a block special device, a regular file, a FIFO, a symbolic link, or a socket.

mode st: returns the protection mode of the file described by st.
val ino : stat -> ino val dev : stat -> dev: These return the file serial number (inode) and the device identifier, respectively, of the corresponding file.

nlink st: returns the number of hard links to the file described by st.
val uid : stat -> uid val gid : stat -> gid: These return the owner and group ID of the file.

size st: returns the size (number of bytes) of the file described by st.
val atime : stat -> Time.time val mtime : stat -> Time.time val ctime : stat -> Time.time: These functions return, respectively, the last access time, the last modification time or the last status change time of the file.

val stat : string -> ST.stat val lstat : string -> ST.stat val fstat : file_desc -> ST.stat

These return information on a file system object. For stat and lstat, the object is specified by its pathname. Note that an empty string causes an exception. For fstat, an open file descriptor is supplied.

lstat differs from stat in that, if the pathname argument is a symbolic link, the information concerns the link itself, not the file to which the link points.

datatype access_mode = A_READ | A_WRITE | A_EXEC

This type is identical to OS.FileSys.access_mode.

access (s, l)

checks for accessibility of file s. If l is the empty list, it checks for the existence of the file; if l contains A_READ, it checks for the readability of s based on the real user and group IDs of the process; and so on.

The value returned depends only the appropriate privileges of the process and the permissions of the file. A directory may be indicated as writable by access, but an attempt to open it for writing will fail (although files may be created there). A file's permissions may indicate that it is executable, but the exec can fail if the file is not in the proper format. Conversely, if the process has appropriate privileges, access will return true if none of the appropriate file permissions are set.

chmod (s, mode)

changes the permissions of s to mode.

fchmod (fd, mode)

changes the permissions of the file opened as fd to mode.

chown (s, uid, gid)

changes the owner and group of file s to uid and gid, respectively.

fchown (fd, uid, gid)

changes the owner and group of the file opened as fd to uid and gid, respectively.

utime (f, SOME{actime,modtime})

sets the access and modification times of the file f to actime and modtime, respectively.

utime (f, NONE)

sets the access and modification times of a file to the current time.

ftruncate (fd, n)

changes the length of a file opened as fd to n bytes. If the new length is less than the previous length, all data beyond n bytes is discarded. If the new length is greater than the previous length, the file is extended to its new length by the necessary number of zero bytes.

pathconf (s, p)

fpathconf (fd, p)

These functions return the value of property p of the file system underlying the file specified by s or fd. For integer-valued properties, if the value is unbounded, NONE is returned. If the value is bounded, SOME(v) is returned, where v is the value. For boolean-value properties, if the value is true, SOME(1) is returned; otherwise, SOME(0) or NONE is returned. The OS.SysErr exception is raised if something goes wrong, including when p is not a valid property or when the implementation does not associate the property with the file.

In the case of pathconf, read, write, or execute permission of the named file is not required, but all directories in the path leading to the file must be searchable.

The properties required by POSIX are described below. A given implementation may support additional properties.

"CHOWN_RESTRICTED": True if the use of chown on any files (other than directories) in the specified directory is restricted to processes with appropriate privileges. This property only applies to directories.
"LINK_MAX": The maximum value of a file's link count as returned by the ST.nlink function.
"MAX_CANON": The maximum number of bytes that can be stored in an input queue. This property only applies to terminal devices.
"MAX_INPUT": The maximum number of bytes allowed in an input queue before being read by a process. This property only applies to terminal devices.
"NAME_MAX": The maximum number of bytes in a filename. This value may be as small as 13, but is never larger than 255. This property only applies to directories and its value applies to filenames within the directory.
"NO_TRUNC": True if supplying a filename longer than allowed by "NAME_MAX" causes an error; false if long filenames are truncated. This property only applies to directories.
"PATH_MAX": The maximum number of bytes in a pathname. This value is never larger than 65,535 and is the maximum length of a relative pathname when the specified directory is the working directory. This property only applies to directories.
"PIPE_BUF": Maximum number of bytes guaranteed to be written atomically. This is applicable only to a FIFO. The value returned applies to the referenced object. If the path or file descriptor parameter refers to a directory, the value returned applies to any FIFO that exists or can be created within the directory.
"VDISABLE": If defined, the integer code ord(c) of the character c which can be used to disable the terminal special characters specified in Posix.TTY.V. This property only applies to terminal devices.
"ASYNC_IO": True if asynchronous input or output operations may be performed on the file.
"SYNC_IO": True if synchronous input or output operations may be performed on the file.
"PRIO_IO": True if prioritized input or output operations may be performed on the file.

Implementation note:

An implementation can call the operating system's pathconf or fpathconf functions, which return an integer. If the returned value is -1 and errno has been set, an exception is raised. Otherwise, a returned value of -1 should be mapped to NONE, and other values should be wrapped in SOME and returned.

Rationale:

The encoding of boolean values as int option, with false having two values, is an unpleasant choice. It would be preferable to split these two functions into four, with one pair handling integer-valued properties, with the present return type, and the other pair handling boolean-valued properties, returning values of type bool. Unfortunately, the nature of the POSIX pathconf and fpathconf functions would make this a nightmare for the implementor.
First, the specification of these functions provides a non-negative integer return value for both booleans and numbers. System include files provide no inherent information as to the type of a property. Although the basic properties specified by POSIX have fixed types, each system is allowed to add its own non-standard properties. Thus, for an SML implementation to make the distinction, it would have to rely on somehow gleaning the information from, e.g., system-specific manual pages.
In addition, the POSIX specification is unclear on how boolean values are encoded. Some systems return 0 for false; others appear to return -1 without setting errno. Technically, the latter value may be interpreted as meaning that the property value is unknown or unspecified. From the programmer's point of view, this means that the property is not usable.
This situation probably precludes automatically generating these functions on a per system basis. Given this, the current return types and values appear to be the only reasonable choice.

The Standard ML Basis Library

The Posix.FileSys structure

Synopsis

Interface

Description

See Also

The `Posix.FileSys` structure