[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.6 gauche.fcntl - Low-level file operations

Module: gauche.fcntl

Provides an interface to fcntl(2), including advisory file locking.

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

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 I/O is blocking or non-blocking, by O_NONBLOCK.
  • Whether it grabs terminal control, by O_NOCTTY.

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>

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.

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.