| \section{\module{fcntl} --- |
| The \function{fcntl()} and \function{ioctl()} system calls} |
| |
| \declaremodule{builtin}{fcntl} |
| \platform{Unix} |
| \modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.} |
| \sectionauthor{Jaap Vermeulen}{} |
| |
| \indexii{UNIX@\UNIX}{file control} |
| \indexii{UNIX@\UNIX}{I/O control} |
| |
| This module performs file control and I/O control on file descriptors. |
| It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()} |
| \UNIX{} routines. |
| |
| All functions in this module take a file descriptor \var{fd} as their |
| first argument. This can be an integer file descriptor, such as |
| returned by \code{sys.stdin.fileno()}, or a file object, such as |
| \code{sys.stdin} itself, which provides a \method{fileno()} which |
| returns a genuine file descriptor. |
| |
| The module defines the following functions: |
| |
| |
| \begin{funcdesc}{fcntl}{fd, op\optional{, arg}} |
| Perform the requested operation on file descriptor \var{fd} (file |
| objects providing a \method{fileno()} method are accepted as well). |
| The operation is defined by \var{op} and is operating system |
| dependent. These codes are also found in the \module{fcntl} |
| module. The argument \var{arg} is optional, and defaults to the |
| integer value \code{0}. When present, it can either be an integer |
| value, or a string. With the argument missing or an integer value, |
| the return value of this function is the integer return value of the |
| C \cfunction{fcntl()} call. When the argument is a string it |
| represents a binary structure, e.g.\ created by |
| \function{\refmodule{struct}.pack()}. The binary data is copied to a buffer |
| whose address is passed to the C \cfunction{fcntl()} call. The |
| return value after a successful call is the contents of the buffer, |
| converted to a string object. The length of the returned string |
| will be the same as the length of the \var{arg} argument. This is |
| limited to 1024 bytes. If the information returned in the buffer by |
| the operating system is larger than 1024 bytes, this is most likely |
| to result in a segmentation violation or a more subtle data |
| corruption. |
| |
| If the \cfunction{fcntl()} fails, an \exception{IOError} is |
| raised. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ioctl}{fd, op\optional{, arg\optional{, mutate_flag}}} |
| This function is identical to the \function{fcntl()} function, |
| except that the operations are typically defined in the library |
| module \refmodule{termios} and the argument handling is even more |
| complicated. |
| |
| The parameter \var{arg} can be one of an integer, absent (treated |
| identically to the integer \code{0}), an object supporting the |
| read-only buffer interface (most likely a plain Python string) or an |
| object supporting the read-write buffer interface. |
| |
| In all but the last case, behaviour is as for the \function{fcntl()} |
| function. |
| |
| If a mutable buffer is passed, then the behaviour is determined by |
| the value of the \var{mutate_flag} parameter. |
| |
| If it is false, the buffer's mutability is ignored and behaviour is |
| as for a read-only buffer, except that the 1024 byte limit mentioned |
| above is avoided -- so long as the buffer you pass is longer than |
| what the operating system wants to put there, things should work. |
| |
| If \var{mutate_flag} is true, then the buffer is (in effect) passed |
| to the underlying \function{ioctl()} system call, the latter's |
| return code is passed back to the calling Python, and the buffer's |
| new contents reflect the action of the \function{ioctl()}. This is a |
| slight simplification, because if the supplied buffer is less than |
| 1024 bytes long it is first copied into a static buffer 1024 bytes |
| long which is then passed to \function{ioctl()} and copied back into |
| the supplied buffer. |
| |
| If \var{mutate_flag} is not supplied, then in 2.3 it defaults to |
| false. This is planned to change over the next few Python versions: |
| in 2.4 failing to supply \var{mutate_flag} will get a warning but |
| the same behavior and in versions later than 2.5 it will default to |
| true. |
| |
| An example: |
| |
| \begin{verbatim} |
| >>> import array, fcntl, struct, termios, os |
| >>> os.getpgrp() |
| 13341 |
| >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] |
| 13341 |
| >>> buf = array.array('h', [0]) |
| >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) |
| 0 |
| >>> buf |
| array('h', [13341]) |
| \end{verbatim} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{flock}{fd, op} |
| Perform the lock operation \var{op} on file descriptor \var{fd} (file |
| objects providing a \method{fileno()} method are accepted as well). |
| See the \UNIX{} manual \manpage{flock}{3} for details. (On some |
| systems, this function is emulated using \cfunction{fcntl()}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lockf}{fd, operation, |
| \optional{length, \optional{start, \optional{whence}}}} |
| This is essentially a wrapper around the \function{fcntl()} locking |
| calls. \var{fd} is the file descriptor of the file to lock or unlock, |
| and \var{operation} is one of the following values: |
| |
| \begin{itemize} |
| \item \constant{LOCK_UN} -- unlock |
| \item \constant{LOCK_SH} -- acquire a shared lock |
| \item \constant{LOCK_EX} -- acquire an exclusive lock |
| \end{itemize} |
| |
| When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it |
| can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on |
| lock acquisition. If \constant{LOCK_NB} is used and the lock cannot |
| be acquired, an \exception{IOError} will be raised and the exception |
| will have an \var{errno} attribute set to \constant{EACCES} or |
| \constant{EAGAIN} (depending on the operating system; for portability, |
| check for both values). On at least some systems, \constant{LOCK_EX} |
| can only be used if the file descriptor refers to a file opened for |
| writing. |
| |
| \var{length} is the number of bytes to lock, \var{start} is the byte |
| offset at which the lock starts, relative to \var{whence}, and |
| \var{whence} is as with \function{fileobj.seek()}, specifically: |
| |
| \begin{itemize} |
| \item \constant{0} -- relative to the start of the file |
| (\constant{SEEK_SET}) |
| \item \constant{1} -- relative to the current buffer position |
| (\constant{SEEK_CUR}) |
| \item \constant{2} -- relative to the end of the file |
| (\constant{SEEK_END}) |
| \end{itemize} |
| |
| The default for \var{start} is 0, which means to start at the |
| beginning of the file. The default for \var{length} is 0 which means |
| to lock to the end of the file. The default for \var{whence} is also |
| 0. |
| \end{funcdesc} |
| |
| Examples (all on a SVR4 compliant system): |
| |
| \begin{verbatim} |
| import struct, fcntl |
| |
| file = open(...) |
| rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY) |
| |
| lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) |
| rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata) |
| \end{verbatim} |
| |
| Note that in the first example the return value variable \var{rv} will |
| hold an integer value; in the second example it will hold a string |
| value. The structure lay-out for the \var{lockdata} variable is |
| system dependent --- therefore using the \function{flock()} call may be |
| better. |
| |
| \begin{seealso} |
| \seemodule{os}{The \function{os.open()} function supports locking flags |
| and is available on a wider variety of platforms than |
| the \function{lockf()} and \function{flock()} |
| functions, providing a more platform-independent file |
| locking facility.} |
| \end{seealso} |