The Standard ML Basis Library

The `Posix.FileSys` structure

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

Synopsis

signature POSIX_FILE_SYS structure FileSys : POSIX_FILE_SYS

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 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 type mode include POSIX_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 POSIX_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

fdToWord fd

wordToFD i

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 ML 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.

fdToIOD fd

iodToFD iod

Convert between a POSIX open file descriptor and 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 opened for reading. This type is identical to OS.FileSys.dirstream.

opendir dirName

Opens the directory designated by dirName parameter and associates a directory stream with it. The directory stream is positioned at the first entry. A directory stream is an ordered sequence of all the directory entries in a particular directory.

readdir d

Read the next filename in the directory stream d. 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

Position the directory stream d for reading at the beginning.

closedir d

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

chdir s

Change the current working directory to s.

getcwd ()

returns the pathname of the current working directory.

stdin

stdout

stderr

The standard input, output and error file descriptors.

structure S

type 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: Read, write, and execute permission for ``user'' (the file's owner).
val irusr: Read permission for ``user'' (the file's owner).
val iwusr: Write permission for ``user'' (the file's owner).
val ixusr: Execute permission for ``user'' (the file's owner).
val irwxg: Read, write, and execute permission for members of the file's group.
val irgrp: Read permission for members of the file's group.
val iwgrp: Write permission for members of the file's group.
val ixgrp: Execute permission for members of the file's group.
val irwxo: Read, write, and execute permission for ``others'' (all users).
val iroth: Read permission for ``others'' (all users).
val iwoth: Write permission for ``others'' (all users).
val ixoth: Execute permission for ``others'' (all users).
val isuid: 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: 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: If set, the file pointer is set to the end of the file prior to each write.
val excl: Cause the open to fail if the file already exists.
val noctty: 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: Open, read and write operations on the file will be nonblocking.
val sync: 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.
trunc: Cause the file to be truncated (to zero length) upon opening.

datatype open_mode

O_RDONLY: Specifies opening a file for reading only.
O_WRONLY: Specifies opening a file for writing only.
O_RDWR: Specifies opening a file for reading and writing.

openf (s, om, f)

createf (s, om, f, m)

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, it is truncated to length 0. If the file does not exist, it creates it, 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 parameter and returns the previous value of the mask.

Whenever a file is created (by openf, creat, mkdir etc.), all file permission bits set in the file mode creation mask are cleared in 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 ST.)

mkdir (s, m)

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

mkfifo (s, m)

Make a FIFO special file s, with protection mode m (as modified by the umask).

unlink path

Remove the directory entry specified by path and, if the entry is a hard link, decrement 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 post- poned 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

Remove a directory s, which must be empty.

rename {old, new}

Rename a directory or a file within a file system.

symlink {old, new}

Create a symbolic link with the name specified by the new that refers to the file named by old.

readlink s

Read the value of a symbolic link s.

eqtype dev

Device Identifier. File serial number (I-node) and device ID uniquely identify a file.

wordToDev i

Convert a word (by which the operating system identifies a device) to a device identifier. There is no verification that i corresponds to a valid device identifier.

devToWord dev

Convert dev to the word by which the operating system identifies the device.

eqtype ino

File Serial Number (I-node).

wordToIno i

Convert a word (by which the operating system identifies an i-node) to an ino value.

inoToWord ino

Convert ino to the word by which the operating system identifies it.

structure ST

type stat: provides information concerning a file.
isDir st: returns true if the file is a directory.
isChr st: returns true if the file is a character special device.
isBlk st: returns true if the file is a block special device.
isReg st: returns true if the file is a regular file.
isFIFO st: returns true if the file is a FIFO.
isLink st: returns true if the file is a symbolic link.
isSock st: returns true if the file is a socket.
mode st: returns the protection mode of the file described by st.
ino st: returns the file serial number (I-node) of the file described by st.
dev st: returns the device identifier of the file described by st.
nlink st: returns the number of hard links to the file described by st.
uid st: returns the owner of the file described by st.
gid st: returns the group ID of the file described by st.
size st: returns the size (number of bytes) of the file described by st.
atime st: returns the last access time of the file described by st.
mtime st: returns the last modification time of the file described by st.
ctime st: returns the time last status change of the file described by st.

stat s

lstat s

fstat fd

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

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

datatype access_mode

This type is identical to OS.FileSys.access_mode.

access (s, l)

Check for accessibility of file s. If l is nil, checks for the existence of the file; if l contains A_READ, checks for the readability of s, and so on.

Only access bits are checked. 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 access bits may indicate that it is executable, but the exec can fail if the file does not contain the proper format.

chmod (s, mode)

Change the protection mode of s to mode.

fchmod (fd, mode)

Change the protection mode of the file opened as fd to mode.

chown (s, uid, gid)

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

fchown (fd, uid, gid)

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

utime (s, SOME(a,m))

utime (s, NONE)

The first form sets the access and modification times of a file to a and m, respectively. The second form sets the access and modification times of a file to the current time.

ftruncate (fd, n)

Change the length of a file opened as fd to the n bytes. If the new length is less than the previous length, remove all data beyond n bytes from the specified file. All file data between the new end-of-file and the previous end-of-file is discarded. If the new length is greater than the previous length, new file data between the previous end-of-file and the new end-of-file is added, consisting of all zeros.

pathconf (s, p)

fpathconf (fd, p)

Determine the value of property p supported by the file system underlying the file specified by s or fd. If the value is false or unbounded, NONE is returned. If the value is true or bounded, SOME v is returned, where v is the value. The OS.SysErr exception is raised if something goes wrong, including if the name p is not a valid property, or if 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": This is applicable only to a directory file. The value returned applies to any files (other than directories) that exist or can be created within the directory.
"LINK_MAX": The maximum number of links to the file.
"MAX_CANON": The maximum number of bytes in a canonical input line. This is applicable only to terminal devices.
"MAX_INPUT": The number of types allowed in an input queue. This is applicable only to terminal devices.
"NAME_MAX": Maximum number of bytes in a filename (not including a terminating null). This may be as small as 13, but is never larger than 255. This is applicable only to a directory file. The value returned applies to filenames within the directory.
"NO_TRUNC": Returns 1 if supplying a component name longer than allowed by NAME_MAX will cause an error. Returns 0 (zero) if long component names are truncated. This is applicable only to a directory file.
"PATH_MAX": Maximum number of bytes in a pathname (not including a terminating null). This is never larger than 65,535. This is applicable only to a directory file. The value returned is the maximum length of a relative pathname when the specified directory is the working directory.
"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": Tell the disabling character of a terminal device.
"ASYNC_IO": Tell if asynchronous I/O may be performed on the file.
"SYNC_IO": Tell if synchronous I/O may be performed on the file.
"PRIO_IO": Tell if prioritized I/O may be performed on the file.

The Standard ML Basis Library

The Posix.FileSys structure

Synopsis

Interface

Description

See Also

The `Posix.FileSys` structure