Module (chicken file posix) (historical revision 34094)

You are looking at historical revision 34094 of this page. It may differ significantly from its current revision.

manual

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.

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

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.

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 floating point number). 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 string or 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])
[procedure] (open-output-file* FILENO [OPENMODE])

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

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.

Retrieving file attributes

file-access-time

file-change-time

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

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

file-access-time and file-change-time also accept a port object as their argument.

file-modification-time

[procedure] (file-modification-time FILE)
[procedure] (set! (file-modification-time FILE) SECONDS)

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

file-modification-time also accepts a port object as its argument.

(set! (file-modification-time FILE) SECONDS) sets the access- and modification time of FILE to SECONDS.

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. FILE may be a filename, a file-descriptor or a port object.

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.

Changing file attributes

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 or a file-descriptor.

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)

 (file-creation-mode MODE)

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

Hard links

file-link

[procedure] (file-link OLDNAME NEWNAME)

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

Record locking

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

file-lock

[procedure] (file-lock PORT [START [LEN]])

Locks the file associated with PORT for reading or writing (according to whether PORT is an input- or output-port). START specifies the starting position in the file to be locked and defaults to 0. LEN specifies the length of the portion to be locked and defaults to #t, which means the complete file. file-lock returns a lock-object.

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 [START [LEN]])

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-test-lock

[procedure] (file-test-lock PORT [START [LEN]])

Tests whether the file associated with PORT is locked for reading or writing (according to whether PORT is an input- or output-port) and returns either #f or the process-id of the locking process.

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

file-unlock

[procedure] (file-unlock LOCK)

Unlocks the previously locked portion of a file given in LOCK.

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)