|
1 :mod:`posixfile` --- File-like objects with locking support |
|
2 =========================================================== |
|
3 |
|
4 .. module:: posixfile |
|
5 :platform: Unix |
|
6 :synopsis: A file-like object with support for locking. |
|
7 :deprecated: |
|
8 .. moduleauthor:: Jaap Vermeulen |
|
9 .. sectionauthor:: Jaap Vermeulen |
|
10 |
|
11 |
|
12 .. index:: pair: POSIX; file object |
|
13 |
|
14 .. deprecated:: 1.5 |
|
15 The locking operation that this module provides is done better and more portably |
|
16 by the :func:`fcntl.lockf` call. |
|
17 |
|
18 .. index:: single: fcntl() (in module fcntl) |
|
19 |
|
20 This module implements some additional functionality over the built-in file |
|
21 objects. In particular, it implements file locking, control over the file |
|
22 flags, and an easy interface to duplicate the file object. The module defines a |
|
23 new file object, the posixfile object. It has all the standard file object |
|
24 methods and adds the methods described below. This module only works for |
|
25 certain flavors of Unix, since it uses :func:`fcntl.fcntl` for file locking. |
|
26 |
|
27 To instantiate a posixfile object, use the :func:`open` function in the |
|
28 :mod:`posixfile` module. The resulting object looks and feels roughly the same |
|
29 as a standard file object. |
|
30 |
|
31 The :mod:`posixfile` module defines the following constants: |
|
32 |
|
33 |
|
34 .. data:: SEEK_SET |
|
35 |
|
36 Offset is calculated from the start of the file. |
|
37 |
|
38 |
|
39 .. data:: SEEK_CUR |
|
40 |
|
41 Offset is calculated from the current position in the file. |
|
42 |
|
43 |
|
44 .. data:: SEEK_END |
|
45 |
|
46 Offset is calculated from the end of the file. |
|
47 |
|
48 The :mod:`posixfile` module defines the following functions: |
|
49 |
|
50 |
|
51 .. function:: open(filename[, mode[, bufsize]]) |
|
52 |
|
53 Create a new posixfile object with the given filename and mode. The *filename*, |
|
54 *mode* and *bufsize* arguments are interpreted the same way as by the built-in |
|
55 :func:`open` function. |
|
56 |
|
57 |
|
58 .. function:: fileopen(fileobject) |
|
59 |
|
60 Create a new posixfile object with the given standard file object. The resulting |
|
61 object has the same filename and mode as the original file object. |
|
62 |
|
63 The posixfile object defines the following additional methods: |
|
64 |
|
65 |
|
66 .. method:: posixfile.lock(fmt, [len[, start[, whence]]]) |
|
67 |
|
68 Lock the specified section of the file that the file object is referring to. |
|
69 The format is explained below in a table. The *len* argument specifies the |
|
70 length of the section that should be locked. The default is ``0``. *start* |
|
71 specifies the starting offset of the section, where the default is ``0``. The |
|
72 *whence* argument specifies where the offset is relative to. It accepts one of |
|
73 the constants :const:`SEEK_SET`, :const:`SEEK_CUR` or :const:`SEEK_END`. The |
|
74 default is :const:`SEEK_SET`. For more information about the arguments refer to |
|
75 the :manpage:`fcntl(2)` manual page on your system. |
|
76 |
|
77 |
|
78 .. method:: posixfile.flags([flags]) |
|
79 |
|
80 Set the specified flags for the file that the file object is referring to. The |
|
81 new flags are ORed with the old flags, unless specified otherwise. The format |
|
82 is explained below in a table. Without the *flags* argument a string indicating |
|
83 the current flags is returned (this is the same as the ``?`` modifier). For |
|
84 more information about the flags refer to the :manpage:`fcntl(2)` manual page on |
|
85 your system. |
|
86 |
|
87 |
|
88 .. method:: posixfile.dup() |
|
89 |
|
90 Duplicate the file object and the underlying file pointer and file descriptor. |
|
91 The resulting object behaves as if it were newly opened. |
|
92 |
|
93 |
|
94 .. method:: posixfile.dup2(fd) |
|
95 |
|
96 Duplicate the file object and the underlying file pointer and file descriptor. |
|
97 The new object will have the given file descriptor. Otherwise the resulting |
|
98 object behaves as if it were newly opened. |
|
99 |
|
100 |
|
101 .. method:: posixfile.file() |
|
102 |
|
103 Return the standard file object that the posixfile object is based on. This is |
|
104 sometimes necessary for functions that insist on a standard file object. |
|
105 |
|
106 All methods raise :exc:`IOError` when the request fails. |
|
107 |
|
108 Format characters for the :meth:`lock` method have the following meaning: |
|
109 |
|
110 +--------+-----------------------------------------------+ |
|
111 | Format | Meaning | |
|
112 +========+===============================================+ |
|
113 | ``u`` | unlock the specified region | |
|
114 +--------+-----------------------------------------------+ |
|
115 | ``r`` | request a read lock for the specified section | |
|
116 +--------+-----------------------------------------------+ |
|
117 | ``w`` | request a write lock for the specified | |
|
118 | | section | |
|
119 +--------+-----------------------------------------------+ |
|
120 |
|
121 In addition the following modifiers can be added to the format: |
|
122 |
|
123 +----------+--------------------------------+-------+ |
|
124 | Modifier | Meaning | Notes | |
|
125 +==========+================================+=======+ |
|
126 | ``|`` | wait until the lock has been | | |
|
127 | | granted | | |
|
128 +----------+--------------------------------+-------+ |
|
129 | ``?`` | return the first lock | \(1) | |
|
130 | | conflicting with the requested | | |
|
131 | | lock, or ``None`` if there is | | |
|
132 | | no conflict. | | |
|
133 +----------+--------------------------------+-------+ |
|
134 |
|
135 Note: |
|
136 |
|
137 (1) |
|
138 The lock returned is in the format ``(mode, len, start, whence, pid)`` where |
|
139 *mode* is a character representing the type of lock ('r' or 'w'). This modifier |
|
140 prevents a request from being granted; it is for query purposes only. |
|
141 |
|
142 Format characters for the :meth:`flags` method have the following meanings: |
|
143 |
|
144 +--------+-----------------------------------------------+ |
|
145 | Format | Meaning | |
|
146 +========+===============================================+ |
|
147 | ``a`` | append only flag | |
|
148 +--------+-----------------------------------------------+ |
|
149 | ``c`` | close on exec flag | |
|
150 +--------+-----------------------------------------------+ |
|
151 | ``n`` | no delay flag (also called non-blocking flag) | |
|
152 +--------+-----------------------------------------------+ |
|
153 | ``s`` | synchronization flag | |
|
154 +--------+-----------------------------------------------+ |
|
155 |
|
156 In addition the following modifiers can be added to the format: |
|
157 |
|
158 +----------+---------------------------------+-------+ |
|
159 | Modifier | Meaning | Notes | |
|
160 +==========+=================================+=======+ |
|
161 | ``!`` | turn the specified flags 'off', | \(1) | |
|
162 | | instead of the default 'on' | | |
|
163 +----------+---------------------------------+-------+ |
|
164 | ``=`` | replace the flags, instead of | \(1) | |
|
165 | | the default 'OR' operation | | |
|
166 +----------+---------------------------------+-------+ |
|
167 | ``?`` | return a string in which the | \(2) | |
|
168 | | characters represent the flags | | |
|
169 | | that are set. | | |
|
170 +----------+---------------------------------+-------+ |
|
171 |
|
172 Notes: |
|
173 |
|
174 (1) |
|
175 The ``!`` and ``=`` modifiers are mutually exclusive. |
|
176 |
|
177 (2) |
|
178 This string represents the flags after they may have been altered by the same |
|
179 call. |
|
180 |
|
181 Examples:: |
|
182 |
|
183 import posixfile |
|
184 |
|
185 file = posixfile.open('/tmp/test', 'w') |
|
186 file.lock('w|') |
|
187 ... |
|
188 file.lock('u') |
|
189 file.close() |
|
190 |