For Gauche 0.9.10


Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]

11.30 srfi-170 - POSIX API

Module: srfi-170

This module provides a portable interface to a part of POSIX API, mainly filesystem interface.

In Gauche, it is a thin wrapper of Gauche’s native system interface (see System interface). You may want to use this module for a portable code.

POSIX Error

Function: posix-error? obj

[SRFI-170] {srfi-170} Returns #t iff obj is a condition thrown due to underlying POSIX-layer error. On Gauche, POSIX-layer condition is the same as <system-error> (see Conditions).

Function: posix-error-name err

[SRFI-170] {srfi-170} The argument must be a POSIX-layer condition (<system-error> object). Returns the POSIX error name such as ENOENT.

See also sys-errno->symbol (see System inquiry).

Function: posix-error-message err

[SRFI-170] {srfi-170} The argument must be a POSIX-layer condition (<system-error> object). Returns the error message describing the error.

See also sys-strerror (see System inquiry).

I/O

Function: open-file fname port-type flags :optional permission buffer-mode

[SRFI-170] {srfi-170} Opens a file named by fname and returns a port to read or write the file. You have finer control than open-input-file/open-output-file.

The port-type argument must be either one of the value of the constant binary-input, textual-input, binary-output, textual-output and binary-input/output. The direction of the returned port is determined by this argument.

Gauche doesn’t distinguish textual ports and binary ports.

The flags argument is a bitwise ior of zero or more of the following bitmasks: open/append, open/create, open/exclusive, open/nofollow and open/truncate. These corresponds to the POSIX flags O_APPEND, O_CREAT, O_EXCL, O_NOFOLLOW and O_TRUNC. Gauche exposes the POSIX flags in gauche.fcntl (see Low-level file operations).

Note: POSIX open(2) also requires one of the bitmasks O_RDONLY, O_WRONLY and O_RDWR. These flags are deduced from the port-type argument.

The optional permission is an integer permission bits to be used when a new file is created. The actual permission bits are also affected by the current umask.

The optional buffer-mode is a value of either one of the followings: buffer-none, buffer-block, and buffer-line.

Function: fd->port fd port-type :optional buffer-mode

[SRFI-170] {srfi-170} Creates a Scheme port wrapping an integer file descriptor fd. The descriptor shouldn’t be used by other Scheme ports. After calling this procedure, no I/O should be done via fd directly; the descriptor is “owned” by the port, and will be closed once the port is closed.

The port-type argument must be either one of the value of the constant binary-input, textual-input, binary-output, textual-output and binary-input/output. The direction must match how fd was opened.

The optional buffer-mode is a value of either one of the followings: buffer-none, buffer-block, and buffer-line.

Constant: binary-input
Constant: textual-input
Constant: binary-output
Constant: textual-output
Constant: binary-input/output

[SRFI-170] {srfi-170} Constants to be used as port-type argument of open-file and fd->port.

Constant: buffer-none
Constant: buffer-block
Constant: buffer-line

[SRFI-170] {srfi-170} Constants to be used as buffer-mode argument of open-file and fd->port.

Constant: open/append
Constant: open/create
Constant: open/exclusive
Constant: open/nofollow
Constant: open/truncate

[SRFI-170] {srfi-170} Bitmask constants to be used as flags argument of open-file.

File System

Function: create-directory fname :optional permission
Function: create-fifo fname :optional permission
Function: create-hard-link old-fname new-fname
Function: create-symlink old-fname new-fname

[SRFI-170] {srfi-170} Corresponds to Gauche’s built-in sys-mkdir, sys-mkfifo, sys-link and sys-symlink.

The default value of permission is #o775 for create-directory, and #o664 for create-fifo (It’s not optoinal for Gauche’s built-in).

On Windows, create-fifo and create-symlink are not supported. Procedures exist, but raise an error when called.

Function: read-symlink name

[SRFI-170] {srfi-170} Gauche’s sys-readlink.

Function: rename-file old new

[SRFI-170] {srfi-170} Gauche’s sys-rename.

Function: delete-directory name

[SRFI-170] {srfi-170} Gauche’s sys-rmdir. The directory must be empty.

Function: set-file-owner fname uid gid

[SRFI-170] {srfi-170} Gauche’s sys-chown. The uid and gid arguments should be an integer uid/gid, or the value of the constant owner/unchanged and group/unchanged, respectively, to indicate to keep the original value.

Constant: owner/unchanged
Constant: group/unchanged

[SRFI-170] {srfi-170} Constants to be passed as uid and gid arguments of set-file-owner, respectively.

Function: set-file-times funame :optional atime mtime

[SRFI-170] {srfi-170} Gauche’s sys-utime. The atime and mtime arguments must be a <time> object (see Time), or either one of the values of constants time/now or time/unchanged. The constant time/now indicates the time when the procedure is called, and the constant time/unchanged indicates the corresponding timestamp remains the same.

Constant: time/now
Constant: time/unchanged

[SRFI-170] {srfi-170} Constants that can be passed to atime and mtime arguments of set-file-times.

Function: truncate-file fname-or-port len

[SRFI-170] {srfi-170} The first argument can be a string filename or a open port associated to a file. If it is a filename, sys-truncate is called, and if it is a port, sys-ftruncate is called.

Function: file-info fname-or-port follow?

[SRFI-170] {srfi-170} Gauche’s sys-stat, sys-lstat or sys-fstat.

The first argument can be a string filename or a open port associated to a file. If it is a filename, sys-stat or sys-lstat is called depending on whether follow? is #t or #f. If it is a port, sys-fstat is called.

Returns a file-info object, which is a <sys-stat> instance in Gauche (see File stats).

Function: file-info? obj

[SRFI-170] {srfi-170} Returns #t iff obj is a file-info object, which is a <sys-stat> instance in Gauche (see File stats).

Function: file-info:device file-info
Function: file-info:inode file-info
Function: file-info:mode file-info
Function: file-info:nlinks file-info
Function: file-info:uid file-info
Function: file-info:gid file-info
Function: file-info:rdev file-info
Function: file-info:size file-info
Function: file-info:blksize file-info
Function: file-info:blocks file-info
Function: file-info:atime file-info
Function: file-info:mtime file-info
Function: file-info:ctime file-info

[SRFI-170] {srfi-170} Accessorso of file-info object (<sys-stat>) (see File stats). Access its dev, ino, mode, nlink, uid, gid, rdev, size, blksize, blocks, atim, mtim, ctim slots, respectively.

Note: <sys-stat>’s atime, mtime and ctime contains integer for the backward compatibility, while file-info:atime, file-info:mtime and file-info:ctime returns <time> object.

Function: file-info-directory? file-info
Function: file-info-fifo? file-info
Function: file-info-symlink? file-info
Function: file-info-regular? file-info
Function: file-info-socket? file-info
Function: file-info-device? file-info

[SRFI-170] {srfi-170} Returns true iff the file-info object (<sys-stat> is of the respective type. (file-info-device? returns true if the file is either block or character device). It corresponds to the type slot of <sys-stat>.

Function: set-file-mode fname mode-bits

[SRFI-170] {srfi-170} Gauche’s sys-chmod.

Function: directory-files dir :optional dotfiles?

[SRFI-170] {srfi-170} Returns a list of filenames in the directory named dir. Similar to directory-list in file.util (see Directory utilities), but (1) it never includes . and .. (as true value is given to :children? argument of directory-list), and (2) it doesn’t include files beginning with . by default, unless dotfiles? is true.

Function: make-directory-files-generator dir :optional dotfiles?

[SRFI-170] {srfi-170} Returns a generator (see Generators) that generates file names in the directory named dir. The names never include . and .., and the filenames beginning with . is omitted unless dotfiles? is true.

Function: open-directory dir :optional dotfiles?
Function: read-directory dir-object
Function: close-directory dir-object

[SRFI-170] {srfi-170} This is a directory scanner API more close to POSIX opendir, readdir and closedir. A directory object is opened with open-directory, and its entries (filenames) can be read one by one using read-directory. If the file names are exausted, read-directory returns an EOF object. A directory object must be closed with close-directory.

The filenames to be retrieved are the same as directory-files; that is, . and .. are never included, and names beginning with . is exluded unless dotfiles? is true.

Function: real-path path

[SRFI-170] {srfi-170} Gauche’s sys-realpath.

Function: file-space path-or-port

[SRFI-170] {srfi-170} Returns the free space of a file system where a file specified by path-or-port resides, in number of bytes.

Parameter: temp-file-prefix

[SRFI-170] {srfi-170} A parameter holding a path prefix to be used by create-temp-file and call-with-temporary-filename. In Gauche, the default value is set to (build-path (temporary-directory) (x->string (sys-getpid))). See Temporary files and directories, for the description of temporary-directory.

Function: create-temp-file :optional prefix

[SRFI-170] {srfi-170}

Function: call-with-temporary-filename maker :optional prefix

[SRFI-170] {srfi-170}

Process state

Note: For srfi-170’s current-directory, we reuse file.util’s one. See Directory utilities, for the description.

Function: umask

[SRFI-170] {srfi-170} Returns the current umask value. Gauche’s sys-umask without argument.

Function: set-umask! mask

[SRFI-170] {srfi-170} Sets mask, which must be a nonnegative exact integer, as the current umask. Gauche’s sys-umask, except that it returns unspecified value.

Function: set-current-directory! dir

[SRFI-170] {srfi-170} Sets the process’s current working directory to dir. Gauche’s sys-chdir. It can also be done with current-working-directory in file.util (see Directory utilities).

Function: pid

[SRFI-170] {srfi-170} Returns the current process id. Gauche’s sys-getpid.

Function: nice :optional delta

[SRFI-170] {srfi-170} Increments the current process’s nice value by delta, which must be an exact integer. The lower the nice value is, the more chance the process gets run. If omitted, delta is assumed to be 1. Gauche’s sys-nice.

Function: user-uid
Function: user-gid
Function: user-effective-uid
Function: user-effecitve-gid
Function: user-supplementary-gids

[SRFI-170] {srfi-170} Gauche’s sys-getuid, sys-getgid, sys-geteuid, sys-getegid, and sys-getgroups, respectievly.

User and group database access

Function: user-info uid-or-name

[SRFI-170] {srfi-170} Returns a user-info object, which is a <sys-passwd> instance in Gauche, of a user specified by uid-or-name, which must be an exact integer uid or a string username. If it is an uid, sys-getpwuid is called, and if it is a username sys-getpwnam is called.

Function: user-info? obj

[SRFI-170] {srfi-170} Returns #t iff obj is a user-info object (<sys-passwd>).

Function: user-info:name uinfo
Function: user-info:uid uinfo
Function: user-info:gid uinfo
Function: user-info:home-dir uinfo
Function: user-info:shell uinfo
Function: user-info:full-name uinfo

[SRFI-170] {srfi-170} Returns the value of name, uid, gid, dir, shell and gecos slots of a user-info object (<sys-passwd) uinfo.

Function: user-info:parsed-full-name uinfo

[SRFI-170] {srfi-170}

Function: group-info gid-or-name

[SRFI-170] {srfi-170} Returns a group-info object, which is a <sys-group> instance in Gauche, of a group specified by gid-or-name, which must be an exact integer gid or a string groupname. If it is an gid, sys-getgrgid is called, and if it is a groupname sys-getgrnam is called.

Function: group-info? obj

[SRFI-170] {srfi-170} Returns #t iff obj is a group-info object (<sys-group).

Function: group-info:name ginfo
Function: group-info:gid ginfo

[SRFI-170] {srfi-170} Returns the value of name and gid slot of a group info (<sys-group>).

Time

Function: posix-time

[SRFI-170] {srfi-170} Same as current-time (see Time). Return value is a <time> instance of time-utc.

Function: monotonic-time

[SRFI-170] {srfi-170} Returns a <time> instance of time-monotonic, representing a elapsed time since an unspecified epoch. It is guaranteed to monotonically increasing during the lifetime of the process, even if the system clock is modified.

Environment variables

See Accessing environment variables, for getting environment variables. This srfi defines the means to modify them.

Function: set-enviroment-variable! name value

[SRFI-170] {srfi-170} Gauche’s sys-setenv with the third argument being #t (overwrite the existing value).

Function: delete-environment-variable! name

[SRFI-170] {srfi-170} Gauche’s sys-unsetenv.

Terminal device control

Function: terminal? port

[SRFI-170] {srfi-170} Gauche’s sys-isatty.


Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]