9.11 gauche.fcntl - Low-level file operations

Module: gauche.fcntl ¶

Provides interface for low-level filesystem operations, including fcntl(2).

Function: sys-fcntl port-or-fd operation :optional arg ¶

{gauche.fcntl} Performs certain operation on the file specified by port-or-fd, which should be a port object or an integer that specifies a system file descriptor. If it is a port, it must be associated to the opened file (i.e. port-type returns file, see Common port operations).

The operation is specified by an integer operation. Several variables are defined for valid operation.

F_GETFD ¶

Returns flags associated to the file descriptor of port-or-fd. The optional argument arg is not used. The return value is an integer whose definition is system specific, except one flag, FD_CLOEXEC, which indicates the file descriptor should be closed on exec. See the manual entry of fcntl(2) of your system for the details.

F_SETFD ¶

Sets the file descriptor flags given as arg to port-or-fd. For example, the portable way of setting FL_CLOEXEC flag is as follows:

(sys-fcntl port F_SETFD
          (logior FD_CLOEXEC
                  (sys-fcntl port F_GETFD)))

F_GETFL ¶

Returns flags associated to the open files specified by port-or-fd. The flags includes the following information:

• File access mode. When masked by O_ACCMODE, it’s either one of O_RDONLY, O_WRONLY or O_RDWR.
• File creation options. O_CREAT, O_EXCL and/or O_TRUNC.
• Whether appending is allowed or not, by O_APPEND
• Whether the file is closed automatically on fork.
• Whether I/O is blocking or non-blocking, by O_NONBLOCK.
• Whether it grabs terminal control, by O_NOCTTY.
• Let the system call fail with ELOOP when the pathname is a symbolink link.

The system may define system-specific flags.

F_SETFL ¶

Sets flags to the open files specified by port-or-fd. Among the flags listed above, only O_NONBLOCK and O_APPEND can be changed.

Note that F_GETFD/F_SETFD concern flags associated to the file descriptor itself, while F_GETFL/F_SETFL concern flags associated to the opened file itself. This makes difference when more than one file descriptor points to the same opened file.

F_DUPFD ¶

Creates new file descriptor that points to the same file referred by port-or-fd. An integer must be provided as arg, and that specifies the minimum value of file descriptor to be assigned.

F_GETLK ¶

The third argument must be provided and be an instance of <sys-flock> object described below. It searches the lock information specified by arg, and modifies arg accordingly.

F_SETLK ¶

F_SETLKW

The third argument must be provided and be an instance of <sys-flock> object described below. Sets the advisory file lock according to arg. If the lock is successfully obtained, #t is returned. If the other process has the lock conflicting the request, F_SETLK returns #f, while F_SETLKW waits until the lock is available.

F_GETOWN ¶

Returns the process id or process group that will receive SIGIO and SIGURG signals for events on the file descriptor. Process group is indicated by a negative value. This flag is only available on the systems that has this feature (BSD and Linux have this).

F_SETOWN ¶

Sets the process id or process group that will receive SIGIO and SIGURG signals for events on the file descriptor. Process group is indicated by a negative value. This flag is only available on the systems that has this feature (BSD and Linux have this). Check out fcntl(2) manpage of your system for the details.

Other value for operation causes an error.

Builtin Class: <sys-flock> ¶

{gauche.fcntl} A structure represents POSIX advisory record locking. Advisory record locking means the system may not prevents the process from operating on files that it doesn’t have an appropriate lock. All the processes are expected to use fcntl to check locks before it operates on the files that may be shared.

The following slots are defined.

Note that fcntl lock is per-process, per-file. If you try to lock the same file more than once within the same process, it always succeeds. But it’s not a recursive lock, so the process loses any locks to the file as soon as any of such lock is released, or any of such file is closed. It makes fcntl lock difficult to use in libraries. See with-lock-file (see Lock files) for an alternative way to realize inter-process locks.

Instance Variable of <sys-flock>: type ¶

An integer represents lock type. Following variables are predefined for the valid values:

F_RDLCK ¶

Read locking

F_WRLCK ¶

Write locking

F_UNLCK ¶

To remove a lock by F_SETLK, or to indicate the record is not locked by F_GETLK.

Instance Variable of <sys-flock>: whence ¶

Indicates from where start is measured.

Instance Variable of <sys-flock>: start ¶

The offset of beginning of the locked region.

Instance Variable of <sys-flock>: len ¶

The number of bytes to lock. Zero means “until EOF”.

Instance Variable of <sys-flock>: pid ¶

An integer process id that holding the lock; used only by F_GETLK.

Function: sys-open path flags :optional mode ¶

{gauche.fcntl} A low-level interface corresponds to POSIX open(). Open a file named by path, and returns an integer file descriptor. The file descriptor should be closed with sys-close, or can be turned into a port by open-{input|output}-fd-oprt and to be closed when the port is closed.

This is provided for the code that needs to deal with low-level fd. Unless absolutely necessary, user code should use high-level open-{input|output}-file.

The flags argument is a logical ior of bitmasks O_RDONLY, O_WRONLY, O_RDWR, O_APPEND, O_CREAT, O_EXCL, O_TRUNC, O_CLOEXEC, O_NOCTTY, O_NOFOLLOW, O_NONBLOCK and O_ASYNC. Either one of O_RDONLY, O_WRONLY or O_RDWR must present.

The mode argument specifies the permission bits when a new file is created. The default is #o664.

Function: sys-statvfs path ¶

Function: sys-fstatvfs port-or-fd ¶

{gauche.fcntl} Interface to POSIX statvfs and fstatvfs.

Returns information about the filesystem where path, or a file associated to port-or-fd, as <sys-statvfs> instance described below.

These procedures are only defined if the system supports them. You can use the feature identifier gauche.sys.statvfs for the availability (see Feature conditional).

(cond-expand
  [gauche.sys.statvfs
    (... code using sys-statvfs ...)]
  [else
    (... alternative code ...)])

Builtin Class: <sys-statvfs> ¶

{gauche.fcntl} POSIX struct statvfs. This class is only defined if a feature gauche.sys.statvfs is provided.

Instance Variable of <sys-statvfs>: bsize ¶

Filesystem block size.

Instance Variable of <sys-statvfs>: frsize ¶

Fragment size.

Instance Variable of <sys-statvfs>: blocks ¶

Instance Variable of <sys-statvfs>: bfree ¶

Instance Variable of <sys-statvfs>: bavail ¶

Number of blocks, number of free blocks, and number of free blocks for unprivileged users, in frsize units.

Instance Variable of <sys-statvfs>: files ¶

Instance Variable of <sys-statvfs>: ffree ¶

Instance Variable of <sys-statvfs>: favail ¶

Number of inodes, number of free inodes, and number of free inodes for unprivileged users.

Instance Variable of <sys-statvfs>: fsid ¶

An exact integer filesystem ID.

Instance Variable of <sys-statvfs>: flag ¶

An exact integer, logical IOR of the bitflags. Portable bitflag values is provided with constants ST_NOSUID a ST_RDONLY.

Instance Variable of <sys-statvfs>: namemax ¶

Maximum filename length.

Constant: ST_NOSUID ¶

Constant: ST_RDONLY ¶

{gauche.fcntl} Bitflag values that can be used in flag slot of <sys-statvfs>. These constants are only defined if a feature gauche.sys.statvfs is provided.

If ST_NOSUID bit is on, suid and sgid bits of the files on this filesystem are ignored by exec(3).

If ST_RDONLY bit is on, the filesystem is mounted read-only.