blob: 1aba52095e7fc4a9767c38fb5526191c7d230613 [file] [log] [blame]
Guido van Rossum7f61b351994-05-19 09:09:50 +00001% Manual text by Jaap Vermeulen
Guido van Rossum470be141995-03-17 16:07:09 +00002\section{Built-in Module \sectcode{fcntl}}
Guido van Rossum7f61b351994-05-19 09:09:50 +00003\bimodindex{fcntl}
Guido van Rossum6bb1adc1995-03-13 10:03:32 +00004\indexii{\UNIX{}}{file control}
5\indexii{\UNIX{}}{I/O control}
Guido van Rossum7f61b351994-05-19 09:09:50 +00006
Guido van Rossum6bb1adc1995-03-13 10:03:32 +00007This module performs file control and I/O control on file descriptors.
8It is an interface to the \dfn{fcntl()} and \dfn{ioctl()} \UNIX{} routines.
Guido van Rossum7f61b351994-05-19 09:09:50 +00009File descriptors can be obtained with the \dfn{fileno()} method of a
10file or socket object.
11
12The module defines the following functions:
13
14\renewcommand{\indexsubitem}{(in module struct)}
15
Guido van Rossum16d6e711994-08-08 12:30:22 +000016\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}}
Guido van Rossum7f61b351994-05-19 09:09:50 +000017 Perform the requested operation on file descriptor \code{\var{fd}}.
18 The operation is defined by \code{\var{op}} and is operating system
19 dependent. Typically these codes can be retrieved from the library
Guido van Rossum16d6e711994-08-08 12:30:22 +000020 module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
21 defaults to the integer value \code{0}. When
Guido van Rossum7f61b351994-05-19 09:09:50 +000022 it is present, it can either be an integer value, or a string. With
23 the argument missing or an integer value, the return value of this
24 function is the integer return value of the real \code{fcntl()}
25 call. When the argument is a string it represents a binary
Guido van Rossum6bb1adc1995-03-13 10:03:32 +000026 structure, e.g.\ created by \code{struct.pack()}. The binary data is
Guido van Rossum7f61b351994-05-19 09:09:50 +000027 copied to a buffer whose address is passed to the real \code{fcntl()}
28 call. The return value after a successful call is the contents of
Guido van Rossum6bb1adc1995-03-13 10:03:32 +000029 the buffer, converted to a string object. In case the
Guido van Rossum7f61b351994-05-19 09:09:50 +000030 \code{fcntl()} fails, an \code{IOError} will be raised.
31\end{funcdesc}
32
33\begin{funcdesc}{ioctl}{fd\, op\, arg}
34 This function is identical to the \code{fcntl()} function, except
35 that the operations are typically defined in the library module
36 \code{IOCTL}.
37\end{funcdesc}
38
Guido van Rossum50ec5c01996-06-26 19:20:33 +000039\begin{funcdesc}{flock}{fd\, op}
40Perform the lock operation \var{op} on file descriptor \var{fd}.
41See the Unix manual for details. (On some systems, this function is
42emulated using \code{fcntl}.)
43\end{funcdesc}
44
Guido van Rossum7f61b351994-05-19 09:09:50 +000045If the library modules \code{FCNTL} or \code{IOCTL} are missing, you
46can find the opcodes in the C include files \code{sys/fcntl} and
47\code{sys/ioctl}. You can create the modules yourself with the h2py
Guido van Rossum0bbbea11995-08-10 14:21:11 +000048script, found in the \code{Tools/scripts} directory.
49\stmodindex{FCNTL}
50\stmodindex{IOCTL}
Guido van Rossum7f61b351994-05-19 09:09:50 +000051
52Examples (all on a SVR4 compliant system):
53
54\bcode\begin{verbatim}
55import struct, FCNTL
56
57file = open(...)
58rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
59
60lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
61rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
62\end{verbatim}\ecode
63
64Note that in the first example the return value variable \code{rv} will
65hold an integer value; in the second example it will hold a string
Guido van Rossum50ec5c01996-06-26 19:20:33 +000066value. The structure lay-out for the \var{lockadata} variable is
67system dependent -- therefore using the \code{flock()} call may be
68better.