blob: bf4f375a8bfa9dd5e02c4af69984698cc2e5e39d [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{fcntl} ---
Fred Drakef6863c11999-03-02 16:37:17 +00002 The \function{fcntl()} and \function{ioctl()} system calls}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakef6863c11999-03-02 16:37:17 +00004\declaremodule{builtin}{fcntl}
Fred Drakea54a8871999-03-02 17:03:42 +00005 \platform{Unix}
Fred Drakeb91e9341998-07-23 17:59:49 +00006\modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
Fred Drake38e5d272000-04-03 20:13:55 +00007\sectionauthor{Jaap Vermeulen}{}
Fred Drakeb91e9341998-07-23 17:59:49 +00008
Fred Drake19b97b11998-02-09 20:16:18 +00009\indexii{UNIX@\UNIX{}}{file control}
10\indexii{UNIX@\UNIX{}}{I/O control}
Guido van Rossum7f61b351994-05-19 09:09:50 +000011
Guido van Rossum6bb1adc1995-03-13 10:03:32 +000012This module performs file control and I/O control on file descriptors.
Fred Drakec71585e1998-03-12 05:33:40 +000013It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
14\UNIX{} routines. File descriptors can be obtained with the
15\method{fileno()} method of a file or socket object.
Guido van Rossum7f61b351994-05-19 09:09:50 +000016
17The module defines the following functions:
18
Guido van Rossum7f61b351994-05-19 09:09:50 +000019
Fred Drakec71585e1998-03-12 05:33:40 +000020\begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
21 Perform the requested operation on file descriptor \var{fd}.
22 The operation is defined by \var{op} and is operating system
Guido van Rossum7f61b351994-05-19 09:09:50 +000023 dependent. Typically these codes can be retrieved from the library
Fred Drake55e3cbd1998-04-03 06:54:27 +000024 module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg}
25 is optional, and defaults to the integer value \code{0}. When
26 present, it can either be an integer value, or a string. With
Guido van Rossum7f61b351994-05-19 09:09:50 +000027 the argument missing or an integer value, the return value of this
Fred Drakef6863c11999-03-02 16:37:17 +000028 function is the integer return value of the C \cfunction{fcntl()}
Guido van Rossum7f61b351994-05-19 09:09:50 +000029 call. When the argument is a string it represents a binary
Fred Drakec71585e1998-03-12 05:33:40 +000030 structure, e.g.\ created by \function{struct.pack()}. The binary
Fred Drakef6863c11999-03-02 16:37:17 +000031 data is copied to a buffer whose address is passed to the C
Fred Drakec71585e1998-03-12 05:33:40 +000032 \cfunction{fcntl()} call. The return value after a successful call
Fred Drake6c7a46a2000-08-02 20:53:51 +000033 is the contents of the buffer, converted to a string object. The length
34 of the returned string will be the same as the length of the \var{arg}
35 argument. This is limited to 1024 bytes. If the information returned
36 in the buffer by the operating system is larger than 1024 bytes,
37 this is most likely to result in a segmentation violation or a more
38 subtle data corruption.
39
40 If the \cfunction{fcntl()} fails, an \exception{IOError} is
Fred Drakec71585e1998-03-12 05:33:40 +000041 raised.
Guido van Rossum7f61b351994-05-19 09:09:50 +000042\end{funcdesc}
43
Fred Drakec71585e1998-03-12 05:33:40 +000044\begin{funcdesc}{ioctl}{fd, op, arg}
45 This function is identical to the \function{fcntl()} function, except
Guido van Rossum7f61b351994-05-19 09:09:50 +000046 that the operations are typically defined in the library module
Fred Drakec71585e1998-03-12 05:33:40 +000047 \module{IOCTL}.
Guido van Rossum7f61b351994-05-19 09:09:50 +000048\end{funcdesc}
49
Fred Drakec71585e1998-03-12 05:33:40 +000050\begin{funcdesc}{flock}{fd, op}
Guido van Rossum50ec5c01996-06-26 19:20:33 +000051Perform the lock operation \var{op} on file descriptor \var{fd}.
Fred Drake55e3cbd1998-04-03 06:54:27 +000052See the \UNIX{} manual \manpage{flock}{3} for details. (On some
53systems, this function is emulated using \cfunction{fcntl()}.)
Guido van Rossum50ec5c01996-06-26 19:20:33 +000054\end{funcdesc}
55
Fred Drakec71585e1998-03-12 05:33:40 +000056\begin{funcdesc}{lockf}{fd, code, \optional{len, \optional{start, \optional{whence}}}}
57This is a wrapper around the \constant{FCNTL.F_SETLK} and
58\constant{FCNTL.F_SETLKW} \function{fcntl()} calls. See the \UNIX{}
59manual for details.
Guido van Rossum9b058111996-10-11 17:43:34 +000060\end{funcdesc}
61
Fred Drakec71585e1998-03-12 05:33:40 +000062If the library modules \module{FCNTL}\refstmodindex{FCNTL} or
63\module{IOCTL}\refstmodindex{IOCTL} are missing, you can find the
Fred Drakef6863c11999-03-02 16:37:17 +000064opcodes in the C include files \code{<sys/fcntl.h>} and
Fred Drakec71585e1998-03-12 05:33:40 +000065\code{<sys/ioctl.h>}. You can create the modules yourself with the
66\program{h2py} script, found in the \file{Tools/scripts/} directory.
67
Guido van Rossum7f61b351994-05-19 09:09:50 +000068
69Examples (all on a SVR4 compliant system):
70
Fred Drake19479911998-02-13 06:58:54 +000071\begin{verbatim}
Guido van Rossumcf6905f1999-06-24 17:58:44 +000072import struct, fcntl, FCNTL
Guido van Rossum7f61b351994-05-19 09:09:50 +000073
74file = open(...)
75rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
76
77lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
Guido van Rossumcf6905f1999-06-24 17:58:44 +000078rv = fcntl.fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
Fred Drake19479911998-02-13 06:58:54 +000079\end{verbatim}
Fred Drakec71585e1998-03-12 05:33:40 +000080
Guido van Rossum7f61b351994-05-19 09:09:50 +000081Note that in the first example the return value variable \code{rv} will
82hold an integer value; in the second example it will hold a string
Fred Drake55e3cbd1998-04-03 06:54:27 +000083value. The structure lay-out for the \var{lockdata} variable is
Fred Drakec71585e1998-03-12 05:33:40 +000084system dependent --- therefore using the \function{flock()} call may be
Guido van Rossum50ec5c01996-06-26 19:20:33 +000085better.