1. Module (chicken file posix)
    1. Constants
      1. File-control Commands
      2. File positions
      3. Standard I/O file-descriptors
      4. Open flags
      5. Open flags for create-pipe
      6. Permission bits
    2. Information about files
      1. directory?
      2. file-type
      3. character-device?
      4. block-device?
      5. socket?
      6. regular-file?
    3. Fifos
      1. create-fifo
      2. fifo?
    4. Retrieving file attributes
      1. file-access-time
      2. file-change-time
      3. file-modification-time
      4. set-file-times!
      5. file-stat
      6. file-position
      7. file-size
      8. file-owner
      9. set-file-owner!
      10. file-group
      11. set-file-group!
      12. file-permissions
      13. set-file-permissions!
      14. file-truncate
      15. set-file-position!
      16. file-creation-mode
    5. Hard and symbolic links
      1. file-link
      2. symbolic-link?
      3. create-symbolic-link
      4. read-symbolic-link
    6. File descriptors and low-level I/O
      1. duplicate-fileno
      2. file-close
      3. file-open
      4. file-mkstemp
      5. file-read
      6. file-select
      7. file-write
      8. file-control
      9. open-input-file*
      10. open-output-file*
      11. port->fileno
    7. File locking
      1. file-lock
      2. file-lock/blocking
      3. file-unlock

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

Constants

File-control Commands

[constant] fcntl/dupfd
[constant] fcntl/getfd
[constant] fcntl/setfd
[constant] fcntl/getfl
[constant] fcntl/setfl

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

[constant] seek/cur
[constant] seek/set
[constant] seek/end

File positions for set-file-position!.

Standard I/O file-descriptors

[constant] fileno/stdin
[constant] fileno/stdout
[constant] fileno/stderr

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

Open flags

[constant] open/rdonly
[constant] open/wronly
[constant] open/rdwr
[constant] open/read
[constant] open/write
[constant] open/creat
[constant] open/append
[constant] open/excl
[constant] open/noctty
[constant] open/nonblock
[constant] open/trunc
[constant] open/sync
[constant] open/fsync
[constant] open/binary
[constant] open/text

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

[constant] open/noinherit

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

[constant] perm/irusr
[constant] perm/iwusr
[constant] perm/ixusr
[constant] perm/irgrp
[constant] perm/iwgrp
[constant] perm/ixgrp
[constant] perm/iroth
[constant] perm/iwoth
[constant] perm/ixoth
[constant] perm/irwxu
[constant] perm/irwxg
[constant] perm/irwxo
[constant] perm/isvtx
[constant] perm/isuid
[constant] perm/isgid

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?

[procedure] (directory? FILE)

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

[procedure] (file-type FILE [LINK [ERROR]])

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?

[procedure] (character-device? FILE)
[procedure] (block-device? FILE)
[procedure] (socket? FILE)

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?

[procedure] (regular-file? FILE)

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

[procedure] (create-fifo FILENAME [MODE])

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?

[procedure] (fifo? FILE)

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

[procedure] (file-access-time FILE)
[procedure] (file-change-time FILE)
[procedure] (file-modification-time FILE)

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!

[procedure] (set-file-times! FILE [MTIME [ATIME]])

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

[procedure] (file-stat FILE [LINK])

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

[procedure] (file-position FILE)

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

file-size

[procedure] (file-size FILE)

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

[procedure] (file-owner FILE)

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

set-file-owner!

[procedure] (set-file-owner! FILE UID)
[procedure] (set! (file-owner FILE) UID)

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

[procedure] (file-group FILE)

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

set-file-group!

[procedure] (set-file-group! FILE GID)
[procedure] (set! (file-group FILE) GID)

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

[procedure] (file-permissions FILE)

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!

[procedure] (set-file-permissions! FILE MODE)
[procedure] (set! (file-permissions FILE) MODE)

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

[procedure] (file-truncate FILE OFFSET)

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!

[procedure] (set-file-position! FILE POSITION [WHENCE])
[procedure] (set! (file-position FILE) POSITION)

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

[procedure] (file-creation-mode [MODE])

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.

[procedure] (file-link OLDNAME NEWNAME)

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

[procedure] (symbolic-link? FILE)

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.

[procedure] (create-symbolic-link OLDNAME NEWNAME)

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.

[procedure] (read-symbolic-link FILENAME [CANONICALIZE])

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

[procedure] (duplicate-fileno OLD [NEW])

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

[procedure] (file-close FILENO)

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

file-open

[procedure] (file-open FILENAME FLAGS [MODE])

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

[procedure] (file-mkstemp TEMPLATE-FILENAME)

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

[procedure] (file-read FILENO SIZE [BUFFER])

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

[procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])

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 by 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

[procedure] (file-write FILENO BUFFER [SIZE])

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

[procedure] (file-control FILENO COMMAND [ARGUMENT])

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*

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

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

[procedure] (port->fileno PORT)

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

[procedure] (file-lock PORT [SHARED])

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

[procedure] (file-lock/blocking PORT [SHARED])

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

[procedure] (file-unlock PORT)

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)