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.



See Also

Posix, Posix.ProcEnv, Posix.Process, Posix.IO

[ INDEX | TOP | Parent | Root ]

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