Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(206690)

Side by Side Diff: Doc/library/fcntl.rst

Issue 19194: Improve cross-references in fcntl documentation
Patch Set: Created 6 years, 2 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls 1 :mod:`fcntl` --- The :c:func:`fcntl` and :c:func:`ioctl` system calls
Georg 2013/10/08 22:19:35 these references should just be replaced by ``fcnt
2 ================================================================= 2 =====================================================================
3 3
4 .. module:: fcntl 4 .. module:: fcntl
5 :platform: Unix 5 :platform: Unix
6 :synopsis: The fcntl() and ioctl() system calls. 6 :synopsis: The fcntl() and ioctl() system calls.
7 .. sectionauthor:: Jaap Vermeulen 7 .. sectionauthor:: Jaap Vermeulen
8 8
9 9
10 .. index:: 10 .. index::
11 pair: UNIX; file control 11 pair: UNIX; file control
12 pair: UNIX; I/O control 12 pair: UNIX; I/O control
13 13
14 This module performs file control and I/O control on file descriptors. It is an 14 This module performs file control and I/O control on file descriptors. It is an
15 interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. 15 interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.
16 16
17 All functions in this module take a file descriptor *fd* as their first 17 All functions in this module take a file descriptor *fd* as their first
18 argument. This can be an integer file descriptor, such as returned by 18 argument. This can be an integer file descriptor, such as returned by
19 ``sys.stdin.fileno()``, or a :class:`io.IOBase` object, such as ``sys.stdin`` 19 ``sys.stdin.fileno()``, or a :class:`io.IOBase` object, such as ``sys.stdin``
20 itself, which provides a :meth:`fileno` that returns a genuine file descriptor. 20 itself, which provides a :meth:`~io.IOBase.fileno` that returns a genuine file
21 descriptor.
21 22
22 .. versionchanged:: 3.3 23 .. versionchanged:: 3.3
23 Operations in this module used to raise a :exc:`IOError` where they now 24 Operations in this module used to raise a :exc:`IOError` where they now
24 raise a :exc:`OSError`. 25 raise a :exc:`OSError`.
25 26
26 27
27 The module defines the following functions: 28 The module defines the following functions:
28 29
29 30
30 .. function:: fcntl(fd, op[, arg]) 31 .. function:: fcntl(fd, op[, arg])
31 32
32 Perform the requested operation on file descriptor *fd* (file objects providi ng 33 Perform the requested operation on file descriptor *fd* (file objects providi ng
33 a :meth:`fileno` method are accepted as well). The operation is defined by *o p* 34 a :meth:`~io.IOBase.fileno` method are accepted as well). The operation is
35 defined by *op*
34 and is operating system dependent. These codes are also found in the 36 and is operating system dependent. These codes are also found in the
35 :mod:`fcntl` module. The argument *arg* is optional, and defaults to the inte ger 37 :mod:`fcntl` module. The argument *arg* is optional, and defaults to the inte ger
36 value ``0``. When present, it can either be an integer value, or a string. 38 value ``0``. When present, it can either be an integer value, or a string.
37 With the argument missing or an integer value, the return value of this funct ion 39 With the argument missing or an integer value, the return value of this funct ion
38 is the integer return value of the C :c:func:`fcntl` call. When the argument is 40 is the integer return value of the C :c:func:`fcntl` call. When the argument is
39 a string it represents a binary structure, e.g. created by :func:`struct.pack `. 41 a string it represents a binary structure, e.g. created by :func:`struct.pack `.
40 The binary data is copied to a buffer whose address is passed to the C 42 The binary data is copied to a buffer whose address is passed to the C
41 :c:func:`fcntl` call. The return value after a successful call is the conten ts 43 :c:func:`fcntl` call. The return value after a successful call is the conten ts
42 of the buffer, converted to a string object. The length of the returned stri ng 44 of the buffer, converted to a string object. The length of the returned stri ng
43 will be the same as the length of the *arg* argument. This is limited to 102 4 45 will be the same as the length of the *arg* argument. This is limited to 102 4
44 bytes. If the information returned in the buffer by the operating system is 46 bytes. If the information returned in the buffer by the operating system is
45 larger than 1024 bytes, this is most likely to result in a segmentation 47 larger than 1024 bytes, this is most likely to result in a segmentation
46 violation or a more subtle data corruption. 48 violation or a more subtle data corruption.
47 49
48 If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. 50 If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
49 51
50 52
51 .. function:: ioctl(fd, op[, arg[, mutate_flag]]) 53 .. function:: ioctl(fd, op[, arg[, mutate_flag]])
52 54
53 This function is identical to the :func:`fcntl` function, except that the 55 This function is identical to the :func:`~fcntl.fcntl` function, except
54 argument handling is even more complicated. 56 that the argument handling is even more complicated.
55 57
56 The op parameter is limited to values that can fit in 32-bits. 58 The op parameter is limited to values that can fit in 32-bits.
57 59
58 The parameter *arg* can be one of an integer, absent (treated identically to the 60 The parameter *arg* can be one of an integer, absent (treated identically to the
59 integer ``0``), an object supporting the read-only buffer interface (most lik ely 61 integer ``0``), an object supporting the read-only buffer interface (most lik ely
60 a plain Python string) or an object supporting the read-write buffer interfac e. 62 a plain Python string) or an object supporting the read-write buffer interfac e.
61 63
62 In all but the last case, behaviour is as for the :func:`fcntl` function. 64 In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
65 function.
63 66
64 If a mutable buffer is passed, then the behaviour is determined by the value of 67 If a mutable buffer is passed, then the behaviour is determined by the value of
65 the *mutate_flag* parameter. 68 the *mutate_flag* parameter.
66 69
67 If it is false, the buffer's mutability is ignored and behaviour is as for a 70 If it is false, the buffer's mutability is ignored and behaviour is as for a
68 read-only buffer, except that the 1024 byte limit mentioned above is avoided -- 71 read-only buffer, except that the 1024 byte limit mentioned above is avoided --
69 so long as the buffer you pass is as least as long as what the operating syst em 72 so long as the buffer you pass is as least as long as what the operating syst em
70 wants to put there, things should work. 73 wants to put there, things should work.
71 74
72 If *mutate_flag* is true (the default), then the buffer is (in effect) passed 75 If *mutate_flag* is true (the default), then the buffer is (in effect) passed
(...skipping 14 matching lines...) Expand all
87 >>> buf = array.array('h', [0]) 90 >>> buf = array.array('h', [0])
88 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) 91 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
89 0 92 0
90 >>> buf 93 >>> buf
91 array('h', [13341]) 94 array('h', [13341])
92 95
93 96
94 .. function:: flock(fd, op) 97 .. function:: flock(fd, op)
95 98
96 Perform the lock operation *op* on file descriptor *fd* (file objects providi ng 99 Perform the lock operation *op* on file descriptor *fd* (file objects providi ng
97 a :meth:`fileno` method are accepted as well). See the Unix manual 100 a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
98 :manpage:`flock(2)` for details. (On some systems, this function is emulated 101 :manpage:`flock(2)` for details. (On some systems, this function is emulated
99 using :c:func:`fcntl`.) 102 using :c:func:`fcntl`.)
100 103
101 104
102 .. function:: lockf(fd, operation, [length, [start, [whence]]]) 105 .. function:: lockf(fd, operation, [length, [start, [whence]]])
103 106
104 This is essentially a wrapper around the :func:`fcntl` locking calls. *fd* i s 107 This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
105 the file descriptor of the file to lock or unlock, and *operation* is one of the 108 *fd* is the file descriptor of the file to lock or unlock, and *operation*
106 following values: 109 is one of the following values:
107 110
108 * :const:`LOCK_UN` -- unlock 111 * :const:`LOCK_UN` -- unlock
109 * :const:`LOCK_SH` -- acquire a shared lock 112 * :const:`LOCK_SH` -- acquire a shared lock
110 * :const:`LOCK_EX` -- acquire an exclusive lock 113 * :const:`LOCK_EX` -- acquire an exclusive lock
111 114
112 When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be 115 When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
113 bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. 116 bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
114 If :const:`LOCK_NB` is used and the lock cannot be acquired, an 117 If :const:`LOCK_NB` is used and the lock cannot be acquired, an
115 :exc:`OSError` will be raised and the exception will have an *errno* 118 :exc:`OSError` will be raised and the exception will have an *errno*
116 attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the 119 attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
117 operating system; for portability, check for both values). On at least some 120 operating system; for portability, check for both values). On at least some
118 systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a 121 systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
119 file opened for writing. 122 file opened for writing.
120 123
121 *length* is the number of bytes to lock, *start* is the byte offset at which the 124 *length* is the number of bytes to lock, *start* is the byte offset at
122 lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.see k`, 125 which the lock starts, relative to *whence*, and *whence* is as with
123 specifically: 126 :func:`io.IOBase.seek`, specifically:
124 127
125 * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) 128 * :const:`0` -- relative to the start of the file (:const:`os.SEEK_SET`)
Georg 2013/10/08 22:19:35 :data: is the correct role for module-level consta
126 * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) 129 * :const:`1` -- relative to the current buffer position (:const:`os.SEEK_CUR` )
127 * :const:`2` -- relative to the end of the file (:const:`SEEK_END`) 130 * :const:`2` -- relative to the end of the file (:const:`os.SEEK_END`)
128 131
129 The default for *start* is 0, which means to start at the beginning of the fi le. 132 The default for *start* is 0, which means to start at the beginning of the fi le.
130 The default for *length* is 0 which means to lock to the end of the file. Th e 133 The default for *length* is 0 which means to lock to the end of the file. Th e
131 default for *whence* is also 0. 134 default for *whence* is also 0.
132 135
133 Examples (all on a SVR4 compliant system):: 136 Examples (all on a SVR4 compliant system)::
134 137
135 import struct, fcntl, os 138 import struct, fcntl, os
136 139
137 f = open(...) 140 f = open(...)
138 rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) 141 rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
139 142
140 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) 143 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
141 rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) 144 rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
142 145
143 Note that in the first example the return value variable *rv* will hold an 146 Note that in the first example the return value variable *rv* will hold an
144 integer value; in the second example it will hold a string value. The structure 147 integer value; in the second example it will hold a string value. The structure
145 lay-out for the *lockdata* variable is system dependent --- therefore using the 148 lay-out for the *lockdata* variable is system dependent --- therefore using the
146 :func:`flock` call may be better. 149 :func:`flock` call may be better.
147 150
148 151
149 .. seealso:: 152 .. seealso::
150 153
151 Module :mod:`os` 154 Module :mod:`os`
152 If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present 155 If the locking flags :const:`~os.O_SHLOCK` and :const:`~os.O_EXLOCK` are
153 in the :mod:`os` module (on BSD only), the :func:`os.open` function 156 present in the :mod:`os` module (on BSD only), the :func:`os.open`
154 provides an alternative to the :func:`lockf` and :func:`flock` functions. 157 function provides an alternative to the :func:`lockf` and :func:`flock`
158 functions.
155 159
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+