1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
\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{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, arg}
This function is identical to the \function{fcntl()} function, except
that the operations are typically defined in the library module
\refmodule{termios}.
\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{len, \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{fcntl.lockf} and \function{fcntl.flock}
functions, providing a more platform-independent file
locking facility.}
\end{seealso}
|
