For Development HEAD DRAFTSearch (procedure/syntax/module):

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

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.


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


For Development HEAD DRAFTSearch (procedure/syntax/module):
DRAFT