Chicken » Module (chicken file posix)

## Module (chicken file posix)

This module provides various operations on files and directories that are more POSIX-oriented than the generic higher-level operations from Module (chicken file).

Note that the following definitions are not all available on non-UNIX systems like Windows. See below for Windows specific notes.

All errors related to failing file-operations will signal a condition of kind `(exn i/o file)`.

- New in CHICKEN 5.4.0: Errors caused by underlying C calls that change errno will produce a condition object with an `errno` property, which can be accessed with `(get-condition-property <the-condition-object> 'exn 'errno)`.

### Constants

#### File-control Commands

fcntl/dupfdconstant
fcntl/getfdconstant
fcntl/setfdconstant
fcntl/getflconstant
fcntl/setflconstant

  Operations used with `file-control`.

  NOTE: On native Windows builds (all except cygwin), these are all defined as zero. The `file-control` procedure to use these with is also unimplemented and will raise an error when called.

#### File positions

seek/curconstant
seek/setconstant
seek/endconstant

  File positions for `set-file-position!`.

#### Standard I/O file-descriptors

fileno/stdinconstant
fileno/stdoutconstant
fileno/stderrconstant

  Standard I/O file descriptor numbers, used with procedures such as `open-input-file*` which take file descriptors.

#### Open flags

open/rdonlyconstant
open/wronlyconstant
open/rdwrconstant
open/readconstant
open/writeconstant
open/creatconstant
open/appendconstant
open/exclconstant
open/nocttyconstant
open/nonblockconstant
open/truncconstant
open/syncconstant
open/fsyncconstant
open/binaryconstant
open/textconstant

  Open flags used with the `file-open` procedure. `open/read` is a convenience synonym for `open/rdonly`, as is `open/write` for `open/wronly`.

  NOTE: On native Windows builds (all except cygwin), `open/noctty`, `open/nonblock`, `open/fsync` and `open/sync` are defined as zero because the corresponding flag doesn't exist. This means you can safely add these to any set of flags when opening a file or pipe, but it simply won't have an effect.

#### Open flags for create-pipe

open/noinheritconstant

  This variable is a mode value for `create-pipe`. Useful when spawning a child process on Windows. On UNIX it is defined as zero, so you can safely pass it there, but it will have no effect.

#### Permission bits

perm/irusrconstant
perm/iwusrconstant
perm/ixusrconstant
perm/irgrpconstant
perm/iwgrpconstant
perm/ixgrpconstant
perm/irothconstant
perm/iwothconstant
perm/ixothconstant
perm/irwxuconstant
perm/irwxgconstant
perm/irwxoconstant
perm/isvtxconstant
perm/isuidconstant
perm/isgidconstant

  Permission bits used with, for example, `file-open`.

  NOTE: On native Windows builds (all except cygwin), `perm/isvtx`, `perm/isuid` and `perm/isgid` are defined as zero because the corresponding permission doesn't exist. This means you can safely add these to any set of flags when opening a file or pipe, but it simply won't have an effect.

### Information about files

#### directory?

directory? FILEprocedure

  Returns `#t` if FILE designates a directory. Otherwise, it returns `#f`. FILE may be a pathname, a file-descriptor or a port object.

#### file-type

file-type FILE #!optional LINK ERRORprocedure

  Returns the file-type for FILE, which should be a filename, a file-descriptor or a port object. If LINK is given and true, symbolic-links are not followed:

       regular-file
       directory
       fifo
       socket
       symbolic-link
       character-device
       block-device

  Note that not all types are supported on every platform. If ERROR is given and false, then `file-type` returns `#f` if the file does not exist; otherwise, it signals an error.

#### character-device?

#### block-device?

#### socket?

character-device? FILEprocedure
block-device? FILEprocedure
socket? FILEprocedure

  These procedures return `#t` if FILE given is of the appropriate type. FILE may be a filename, a file-descriptor or a port object. Note that these operations follow symbolic links. If the file does not exist, `#f` is returned.

#### regular-file?

regular-file? FILEprocedure

  Returns true, if FILE names a regular file (not a directory, socket, etc.) This operation follows symbolic links; use either `symbolic-link?` or `file-type` if you need to test for symlinks. FILE may refer to a filename, file descriptor or ports object.

### Fifos

#### create-fifo

create-fifo FILENAME #!optional MODEprocedure

  Creates a FIFO with the name FILENAME and the permission bits MODE, which defaults to

       (+ perm/irwxu perm/irwxg perm/irwxo)

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### fifo?

fifo? FILEprocedure

  Returns `#t` if FILE names a FIFO. FILE may be a filename, a port or a file-descriptor.

### Retrieving file attributes

#### file-access-time

#### file-change-time

#### file-modification-time

file-access-time FILEprocedure
file-change-time FILEprocedure
file-modification-time FILEprocedure

  Returns time (in seconds) of the last access, inode change or content modification of FILE, respectively. FILE may be a filename, a file-descriptor or a file-backed port. If the file does not exist, an error is signaled.

#### set-file-times!

set-file-times! FILE #!optional MTIME ATIMEprocedure

  Sets the time of last modification MTIME and/or time of last access ATIME (in seconds) for FILE. FILE may be a filename, a file-descriptor or a file-backed port. If the file does not exist, an error is signaled.

  If neither MTIME nor ATIME is supplied, the current time is used. If only MTIME is supplied, ATIME will be set to the same value. If an argument is `#f`, it will not be changed.

  Consequently, if only MTIME is passed and it is `#f`, ATIME is assumed to be `#f` as well and neither will be changed.

#### file-stat

file-stat FILE #!optional LINKprocedure

  Returns a 13-element vector with the following contents:

  index | value | field | notes
  --- | --- | --- | ---
  0 | inode number | `st_ino` |
  1 | mode | `st_mode` | bitfield combining file permissions and file type
  2 | number of hard links | `st_nlink` |
  3 | UID of owner | `st_uid` | as with `file-owner`
  4 | GID of owner | `st_gid` |
  5 | size | `st_size` | as with `file-size`
  6 | access time | `st_atime` | as with `file-access-time`
  7 | change time | `st_ctime` | as with `file-change-time`
  8 | modification time | `st_mtime` | as with `file-modification-time`
  9 | parent device ID | `st_dev` | ID of device on which this file resides
  10 | device ID | `st_rdev` | device ID for special files (i.e. the raw major/minor number)
  11 | block size | `st_blksize` |
  12 | number of blocks allocated | `st_blocks` |

  On Windows systems, the last 4 values are undefined.

  By default, symbolic links are followed and the status of the referenced file is returned; however, if the optional argument LINK is given and not `#f`, the status of the link itself is returned.

  FILE may be a filename, port or file-descriptor.

  Note that for very large files, the `file-size` value may be an inexact integer.

#### file-position

file-position FILEprocedure

  Returns the current file position of FILE, which should be a port or a file-descriptor.

#### file-size

file-size FILEprocedure

  Returns the size of the file designated by FILE. FILE may be a filename, a file-descriptor or a port object. If the file does not exist, an error is signaled. Note that for very large files, `file-size` may return an inexact integer.

#### file-owner

file-owner FILEprocedure

  Returns the user-id of FILE (an exact integer). FILE may be a filename, a file-descriptor or a port object.

#### set-file-owner!

set-file-owner! FILE UIDprocedure
set! (file-owner FILE) UIDprocedure

  Changes the ownership of FILE to user-id UID (which should be an exact integer) using the `chown()` system call. FILE may be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-group

file-group FILEprocedure

  Returns the group-id of FILE. FILE may be a filename, a file-descriptor or a port object.

#### set-file-group!

set-file-group! FILE GIDprocedure
set! (file-group FILE) GIDprocedure

  Changes the group ownership of FILE to group-id GID (which should be an exact integer) using the `chgrp()` system call. FILE may be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-permissions

file-permissions FILEprocedure

  Returns the permission bits for FILE. You can test this value by performing bitwise operations on the result and the `perm/...` values. FILE may be a filename, a file-descriptor or a port object.

#### set-file-permissions!

set-file-permissions! FILE MODEprocedure
set! (file-permissions FILE) MODEprocedure

  Changes the current permission bits for FILE to MODE using the `chmod()` system call. The `perm/...` variables contain the various permission bits and can be combinded with the `bitwise-ior` procedure. FILE may be a filename, a file-descriptor or a port object, MODE should be a fixnum.

#### file-truncate

file-truncate FILE OFFSETprocedure

  Truncates the file FILE to the length OFFSET, which should be an integer. If the file-size is smaller or equal to OFFSET then nothing is done. FILE should be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### set-file-position!

set-file-position! FILE POSITION #!optional WHENCEprocedure
set! (file-position FILE) POSITIONprocedure

  Sets the current read/write position of FILE to POSITION, which should be an exact integer. FILE should be a port or a file-descriptor. WHENCE specifies how the position is to interpreted and should be one of the values `seek/set, seek/cur` and `seek/end`. It defaults to `seek/set`.

  Exceptions: `(exn bounds)`, `(exn i/o file)`

#### file-creation-mode

file-creation-mode #!optional MODEprocedure

  Returns the initial file permissions used for newly created files (as with `umask(2)`). If MODE is supplied, the mode is changed to this value. You can set the mode by executing

       (set! (file-creation-mode) MODE)

  or

       (file-creation-mode MODE)

  where MODE is a bitwise combination of one or more of the `perm/...` flags.

### Hard and symbolic links

#### file-link

file-link OLDNAME NEWNAMEprocedure

  Creates a hard link from OLDNAME to NEWNAME (both strings).

#### symbolic-link?

symbolic-link? FILEprocedure

  Returns true, if FILE names a symbolic link. If no such file exists, `#f` is returned. This operation does not follow symbolic links itself. FILE could be a filename, file descriptor or port object.

#### create-symbolic-link

create-symbolic-link OLDNAME NEWNAMEprocedure

  Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### read-symbolic-link

read-symbolic-link FILENAME #!optional CANONICALIZEprocedure

  Returns the filename to which the symbolic link FILENAME points. If CANONICALIZE is given and true, then symbolic links are resolved repeatedly until the result is not a link.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

### File descriptors and low-level I/O

#### duplicate-fileno

duplicate-fileno OLD #!optional NEWprocedure

  If NEW is given, then the file-descriptor NEW is opened to access the file with the file-descriptor OLD. Otherwise a fresh file-descriptor accessing the same file as OLD is returned.

#### file-close

file-close FILENOprocedure

  Closes the input/output file with the file-descriptor FILENO.

#### file-open

file-open FILENAME FLAGS #!optional MODEprocedure

  Opens the file specified with the string FILENAME and open-flags FLAGS using the C function `open(2)`. On success a file-descriptor for the opened file is returned.

  FLAGS is a bitmask of `open/...` values ored together using `bitwise-ior` (or simply added together). You must provide exactly one of the access flags `open/rdonly`, `open/wronly`, or `open/rdwr`. Additionally, you may provide zero or more creation flags (`open/creat`, `open/excl`, `open/trunc`, and `open/noctty`) and status flags (the remaining `open/...` values). For example, to open a possibly new output file for appending:

      (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))

  The optional MODE should be a bitmask composed of one or more permission values like `perm/irusr` and is only relevant when a new file is created. The default mode is `perm/irwxu | perm/irgrp | perm/iroth`.

#### file-mkstemp

file-mkstemp TEMPLATE-FILENAMEprocedure

  Create a file based on the given TEMPLATE-FILENAME, in which the six last characters must be XXXXXX. These will be replaced with a string that makes the filename unique. The file descriptor of the created file and the generated filename is returned. See the `mkstemp(3)` manual page for details on how this function works. The template string given is not modified.

  Example usage:

       (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
        (let ((temp-port (open-output-file* fd)))
          (format temp-port "This file is ~A.~%" temp-path)
          (close-output-port temp-port)))

#### file-read

file-read FILENO SIZE #!optional BUFFERprocedure

  Reads SIZE bytes from the file with the file-descriptor FILENO. If a string or bytevector is passed in the optional argument BUFFER, then this string will be destructively modified to contain the read data. This procedure returns a list with two values: the buffer containing the data and the number of bytes read.

#### file-select

file-select READFDLIST WRITEFDLIST #!optional TIMEOUTprocedure

  Waits until any of the file-descriptors given in the lists READFDLIST and WRITEFDLIST is ready for input or output, respectively. If the optional argument TIMEOUT is given and not false, then it should specify the number of seconds after which the wait is to be aborted (the value may be a float). This procedure returns two values: the lists of file-descriptors ready for input and output, respectively. READFDLIST and WRITEFDLIST may also be file-descriptors instead of lists. In this case the returned values are booleans indicating whether input/output is ready by `#t` or `#f` otherwise. You can also pass `#f` as READFDLIST or WRITEFDLIST argument, which is equivalent to `()`.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-write

file-write FILENO BUFFER #!optional SIZEprocedure

  Writes the contents of the bytevector BUFFER into the file with the file-descriptor FILENO. If the optional argument SIZE is given, then only the specified number of bytes are written.

#### file-control

file-control FILENO COMMAND #!optional ARGUMENTprocedure

  Performs the fcntl operation COMMAND with the given FILENO and optional ARGUMENT. The return value is meaningful depending on the COMMAND.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### open-input-file*

#### open-output-file*

`(open-input-file* FILENO [OPENMODE ENCODING])`procedure
`(open-output-file* FILENO [OPENMODE ENCODING])`procedure

  Opens file for the file-descriptor `FILENO` for input or output and returns a port. `FILENO` should be a positive exact integer. `OPENMODE` specifies an additional mode for opening the file (currently only the keyword `#:append` is supported, which opens an output-file for appending). `ENCODING` should be a symbol specifying a file encoding and defaults to `utf-8`.

#### port->fileno

port->fileno PORTprocedure

  If PORT is a file- or tcp-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

### File locking

These procedures are all unsupported on native Windows builds (all except cygwin).

#### file-lock

file-lock PORT #!optional SHAREDprocedure

  Locks the file associated with PORT using an "exclusive" lock (see `flock(2)` for more information on shared vs exclusive locks). If SHARED is given and true, then a shared lock will be requested. Returns `#t` if requesting the lock succeeded or `#f` otherwise.

  PORT may be a file port or a file-descriptor.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-lock/blocking

file-lock/blocking PORT #!optional SHAREDprocedure

  Similar to `file-lock`, but if a lock is held on the file, the current process blocks (including all threads) until the lock is released.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-unlock

file-unlock PORTprocedure

  Unlocks the previously locked file given PORT which may be a file port or a file-scriptor.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

Previous: Module (chicken file)

Next: Module (chicken fixnum)