Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{fcntl} --- |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 2 | The \function{fcntl()} and \function{ioctl()} system calls} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{fcntl} |
Fred Drake | a54a887 | 1999-03-02 17:03:42 +0000 | [diff] [blame] | 5 | \platform{Unix} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | \modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 7 | \sectionauthor{Jaap Vermeulen}{} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 8 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 9 | \indexii{UNIX@\UNIX}{file control} |
| 10 | \indexii{UNIX@\UNIX}{I/O control} |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 11 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 12 | This module performs file control and I/O control on file descriptors. |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 13 | It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()} |
Fred Drake | d0de57c | 2001-05-09 21:09:57 +0000 | [diff] [blame] | 14 | \UNIX{} routines. |
| 15 | |
| 16 | All functions in this module take a file descriptor \var{fd} as their |
| 17 | first argument. This can be an integer file descriptor, such as |
| 18 | returned by \code{sys.stdin.fileno()}, or a file object, such as |
Fred Drake | 6a6bb18 | 2001-11-28 07:48:32 +0000 | [diff] [blame] | 19 | \code{sys.stdin} itself, which provides a \method{fileno()} which |
| 20 | returns a genuine file descriptor. |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 21 | |
| 22 | The module defines the following functions: |
| 23 | |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 24 | |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 25 | \begin{funcdesc}{fcntl}{fd, op\optional{, arg}} |
Fred Drake | 6a6bb18 | 2001-11-28 07:48:32 +0000 | [diff] [blame] | 26 | Perform the requested operation on file descriptor \var{fd} (file |
| 27 | objects providing a \method{fileno()} method are accepted as well). |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 28 | The operation is defined by \var{op} and is operating system |
Fred Drake | d0de57c | 2001-05-09 21:09:57 +0000 | [diff] [blame] | 29 | dependent. These codes are also found in the \module{fcntl} |
| 30 | module. The argument \var{arg} is optional, and defaults to the |
| 31 | integer value \code{0}. When present, it can either be an integer |
| 32 | value, or a string. With the argument missing or an integer value, |
| 33 | the return value of this function is the integer return value of the |
| 34 | C \cfunction{fcntl()} call. When the argument is a string it |
| 35 | represents a binary structure, e.g.\ created by |
Fred Drake | 990a46b | 2004-01-16 16:07:04 +0000 | [diff] [blame] | 36 | \function{\refmodule{struct}.pack()}. The binary data is copied to a buffer |
Fred Drake | d0de57c | 2001-05-09 21:09:57 +0000 | [diff] [blame] | 37 | whose address is passed to the C \cfunction{fcntl()} call. The |
| 38 | return value after a successful call is the contents of the buffer, |
| 39 | converted to a string object. The length of the returned string |
| 40 | will be the same as the length of the \var{arg} argument. This is |
| 41 | limited to 1024 bytes. If the information returned in the buffer by |
| 42 | the operating system is larger than 1024 bytes, this is most likely |
| 43 | to result in a segmentation violation or a more subtle data |
| 44 | corruption. |
Fred Drake | 6c7a46a | 2000-08-02 20:53:51 +0000 | [diff] [blame] | 45 | |
| 46 | If the \cfunction{fcntl()} fails, an \exception{IOError} is |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 47 | raised. |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 48 | \end{funcdesc} |
| 49 | |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 50 | \begin{funcdesc}{ioctl}{fd, op\optional{, arg\optional{, mutate_flag}}} |
| 51 | This function is identical to the \function{fcntl()} function, |
| 52 | except that the operations are typically defined in the library |
| 53 | module \refmodule{termios} and the argument handling is even more |
| 54 | complicated. |
| 55 | |
| 56 | The parameter \var{arg} can be one of an integer, absent (treated |
| 57 | identically to the integer \code{0}), an object supporting the |
| 58 | read-only buffer interface (most likely a plain Python string) or an |
| 59 | object supporting the read-write buffer interface. |
| 60 | |
| 61 | In all but the last case, behaviour is as for the \function{fcntl()} |
| 62 | function. |
| 63 | |
| 64 | If a mutable buffer is passed, then the behaviour is determined by |
| 65 | the value of the \var{mutate_flag} parameter. |
| 66 | |
| 67 | If it is false, the buffer's mutability is ignored and behaviour is |
| 68 | as for a read-only buffer, except that the 1024 byte limit mentioned |
Michael W. Hudson | 5c47355 | 2005-03-30 16:25:34 +0000 | [diff] [blame] | 69 | above is avoided -- so long as the buffer you pass is as least as |
| 70 | long as what the operating system wants to put there, things should |
| 71 | work. |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 72 | |
| 73 | If \var{mutate_flag} is true, then the buffer is (in effect) passed |
| 74 | to the underlying \function{ioctl()} system call, the latter's |
| 75 | return code is passed back to the calling Python, and the buffer's |
Fred Drake | 990a46b | 2004-01-16 16:07:04 +0000 | [diff] [blame] | 76 | new contents reflect the action of the \function{ioctl()}. This is a |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 77 | slight simplification, because if the supplied buffer is less than |
| 78 | 1024 bytes long it is first copied into a static buffer 1024 bytes |
Fred Drake | 990a46b | 2004-01-16 16:07:04 +0000 | [diff] [blame] | 79 | long which is then passed to \function{ioctl()} and copied back into |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 80 | the supplied buffer. |
| 81 | |
Michael W. Hudson | 02d74f6 | 2004-11-30 14:31:54 +0000 | [diff] [blame] | 82 | If \var{mutate_flag} is not supplied, then from Python 2.5 it |
| 83 | defaults to true, which is a change from versions 2.3 and 2.4. |
| 84 | Supply the argument explicitly if version portability is a priority. |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 85 | |
| 86 | An example: |
| 87 | |
| 88 | \begin{verbatim} |
Raymond Hettinger | ff294fe | 2003-12-07 13:00:25 +0000 | [diff] [blame] | 89 | >>> import array, fcntl, struct, termios, os |
Michael W. Hudson | f008998 | 2003-03-03 12:29:42 +0000 | [diff] [blame] | 90 | >>> os.getpgrp() |
| 91 | 13341 |
| 92 | >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] |
| 93 | 13341 |
| 94 | >>> buf = array.array('h', [0]) |
| 95 | >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) |
| 96 | 0 |
| 97 | >>> buf |
| 98 | array('h', [13341]) |
| 99 | \end{verbatim} |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 100 | \end{funcdesc} |
| 101 | |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 102 | \begin{funcdesc}{flock}{fd, op} |
Fred Drake | 6a6bb18 | 2001-11-28 07:48:32 +0000 | [diff] [blame] | 103 | Perform the lock operation \var{op} on file descriptor \var{fd} (file |
| 104 | objects providing a \method{fileno()} method are accepted as well). |
Fred Drake | 55e3cbd | 1998-04-03 06:54:27 +0000 | [diff] [blame] | 105 | See the \UNIX{} manual \manpage{flock}{3} for details. (On some |
| 106 | systems, this function is emulated using \cfunction{fcntl()}.) |
Guido van Rossum | 50ec5c0 | 1996-06-26 19:20:33 +0000 | [diff] [blame] | 107 | \end{funcdesc} |
| 108 | |
Barry Warsaw | 8ee1a4b | 2001-01-25 00:36:54 +0000 | [diff] [blame] | 109 | \begin{funcdesc}{lockf}{fd, operation, |
Neal Norwitz | 965eeca | 2004-06-13 21:11:03 +0000 | [diff] [blame] | 110 | \optional{length, \optional{start, \optional{whence}}}} |
Barry Warsaw | 8ee1a4b | 2001-01-25 00:36:54 +0000 | [diff] [blame] | 111 | This is essentially a wrapper around the \function{fcntl()} locking |
| 112 | calls. \var{fd} is the file descriptor of the file to lock or unlock, |
| 113 | and \var{operation} is one of the following values: |
| 114 | |
| 115 | \begin{itemize} |
| 116 | \item \constant{LOCK_UN} -- unlock |
| 117 | \item \constant{LOCK_SH} -- acquire a shared lock |
| 118 | \item \constant{LOCK_EX} -- acquire an exclusive lock |
| 119 | \end{itemize} |
| 120 | |
| 121 | When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it |
| 122 | can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on |
| 123 | lock acquisition. If \constant{LOCK_NB} is used and the lock cannot |
| 124 | be acquired, an \exception{IOError} will be raised and the exception |
| 125 | will have an \var{errno} attribute set to \constant{EACCES} or |
| 126 | \constant{EAGAIN} (depending on the operating system; for portability, |
Fred Drake | 6a6bb18 | 2001-11-28 07:48:32 +0000 | [diff] [blame] | 127 | check for both values). On at least some systems, \constant{LOCK_EX} |
| 128 | can only be used if the file descriptor refers to a file opened for |
| 129 | writing. |
Barry Warsaw | 8ee1a4b | 2001-01-25 00:36:54 +0000 | [diff] [blame] | 130 | |
| 131 | \var{length} is the number of bytes to lock, \var{start} is the byte |
| 132 | offset at which the lock starts, relative to \var{whence}, and |
| 133 | \var{whence} is as with \function{fileobj.seek()}, specifically: |
| 134 | |
| 135 | \begin{itemize} |
| 136 | \item \constant{0} -- relative to the start of the file |
| 137 | (\constant{SEEK_SET}) |
| 138 | \item \constant{1} -- relative to the current buffer position |
| 139 | (\constant{SEEK_CUR}) |
| 140 | \item \constant{2} -- relative to the end of the file |
| 141 | (\constant{SEEK_END}) |
| 142 | \end{itemize} |
| 143 | |
| 144 | The default for \var{start} is 0, which means to start at the |
| 145 | beginning of the file. The default for \var{length} is 0 which means |
| 146 | to lock to the end of the file. The default for \var{whence} is also |
| 147 | 0. |
Guido van Rossum | 9b05811 | 1996-10-11 17:43:34 +0000 | [diff] [blame] | 148 | \end{funcdesc} |
| 149 | |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 150 | Examples (all on a SVR4 compliant system): |
| 151 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 152 | \begin{verbatim} |
Neal Norwitz | 7728b47 | 2004-07-21 01:41:14 +0000 | [diff] [blame] | 153 | import struct, fcntl, os |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 154 | |
Neal Norwitz | 7728b47 | 2004-07-21 01:41:14 +0000 | [diff] [blame] | 155 | f = open(...) |
| 156 | rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 157 | |
Fred Drake | d0de57c | 2001-05-09 21:09:57 +0000 | [diff] [blame] | 158 | lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) |
Skip Montanaro | 2ccf5d6 | 2004-06-30 21:06:45 +0000 | [diff] [blame] | 159 | rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 160 | \end{verbatim} |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 161 | |
Fred Drake | b942c2f | 2001-04-11 21:33:47 +0000 | [diff] [blame] | 162 | Note that in the first example the return value variable \var{rv} will |
Guido van Rossum | 7f61b35 | 1994-05-19 09:09:50 +0000 | [diff] [blame] | 163 | hold an integer value; in the second example it will hold a string |
Fred Drake | 55e3cbd | 1998-04-03 06:54:27 +0000 | [diff] [blame] | 164 | value. The structure lay-out for the \var{lockdata} variable is |
Fred Drake | c71585e | 1998-03-12 05:33:40 +0000 | [diff] [blame] | 165 | system dependent --- therefore using the \function{flock()} call may be |
Guido van Rossum | 50ec5c0 | 1996-06-26 19:20:33 +0000 | [diff] [blame] | 166 | better. |
Skip Montanaro | a5caa6f | 2003-01-15 21:08:19 +0000 | [diff] [blame] | 167 | |
| 168 | \begin{seealso} |
Skip Montanaro | 684364c | 2005-06-08 02:28:11 +0000 | [diff] [blame] | 169 | \seemodule{os}{If the locking flags \constant{O_SHLOCK} and |
| 170 | \constant{O_EXLOCK} are present in the \module{os} module, |
| 171 | the \function{os.open()} function provides a more |
| 172 | platform-independent alternative to the \function{lockf()} |
| 173 | and \function{flock()} functions.} |
Skip Montanaro | a5caa6f | 2003-01-15 21:08:19 +0000 | [diff] [blame] | 174 | \end{seealso} |