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

9.5 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 specfied 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.

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.

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.

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: <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: <sys-flock> whence
Indicates from where start is measured.

Instance Variable: <sys-flock> start
The offset of beginning of the locked region.

Instance Variable: <sys-flock> len
The number of bytes to lock. Zero means "until EOF".

Instance Variable: <sys-flock> pid
An integer process id that holding the lock; used only by F_GETLK.


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

This document was generated by Ken Dickey on November, 28 2002 using texi2html