summaryrefslogtreecommitdiffstats
path: root/Doc/libposix.tex
blob: 16742c5f9b07082233c5bf888fe4ede17dc46863 (plain)
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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
\section{Built-in Module \sectcode{posix}}
\label{module-posix}
\bimodindex{posix}

This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised
\UNIX{} interface).

\strong{Do not import this module directly.}  Instead, import the
module \code{os}, which provides a \emph{portable} version of this
interface.  On \UNIX{}, the \code{os} module provides a superset of
the \code{posix} interface.  On non-\UNIX{} operating systems the
\code{posix} module is not available, but a subset is always available
through the \code{os} interface.  Once \code{os} is imported, there is
\emph{no} performance penalty in using it instead of
\code{posix}.  In addition, \code{os} provides some additional
functionality, such as automatically calling \code{putenv()}
when an entry is \code{os.environ} is changed.
\refstmodindex{os}

The descriptions below are very terse; refer to the corresponding
\UNIX{} manual (or POSIX documentation) entry for more information.
Arguments called \var{path} refer to a pathname given as a string.

Errors are reported as exceptions; the usual exceptions are given
for type errors, while errors reported by the system calls raise
\code{posix.error}, described below.

Module \code{posix} defines the following data items:

\renewcommand{\indexsubitem}{(data in module posix)}
\begin{datadesc}{environ}
A dictionary representing the string environment at the time
the interpreter was started.
For example,
\code{posix.environ['HOME']}
is the pathname of your home directory, equivalent to
\code{getenv("HOME")}
in C.

Modifying this dictionary does not affect the string environment
passed on by \code{execv()}, \code{popen()} or \code{system()}; if you
need to change the environment, pass \code{environ} to \code{execve()}
or add variable assignments and export statements to the command
string for \code{system()} or \code{popen()}.

\emph{However:} If you are using this module via the \code{os} module
(as you should -- see the introduction above), \code{environ} is a
a mapping object that behaves almost like a dictionary but invokes
\code{putenv()} automatically called whenever an item is changed.
\end{datadesc}

\renewcommand{\indexsubitem}{(exception in module posix)}
\begin{excdesc}{error}
This exception is raised when a POSIX function returns a
POSIX-related error (e.g., not for illegal argument types).  Its
string value is \code{'posix.error'}.  The accompanying value is a
pair containing the numeric error code from \code{errno} and the
corresponding string, as would be printed by the C function
\code{perror()}.
\end{excdesc}

It defines the following functions and constants:

\renewcommand{\indexsubitem}{(in module posix)}
\begin{funcdesc}{chdir}{path}
Change the current working directory to \var{path}.
\end{funcdesc}

\begin{funcdesc}{chmod}{path\, mode}
Change the mode of \var{path} to the numeric \var{mode}.
\end{funcdesc}

\begin{funcdesc}{chown}{path\, uid, gid}
Change the owner and group id of \var{path} to the numeric \var{uid}
and \var{gid}.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{close}{fd}
Close file descriptor \var{fd}.

Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \code{posix.open()} or
\code{posix.pipe()}.  To close a ``file object'' returned by the
built-in function \code{open} or by \code{posix.popen} or
\code{posix.fdopen}, use its \code{close()} method.
\end{funcdesc}

\begin{funcdesc}{dup}{fd}
Return a duplicate of file descriptor \var{fd}.
\end{funcdesc}

\begin{funcdesc}{dup2}{fd\, fd2}
Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
first if necessary.  Return \code{None}.
\end{funcdesc}

\begin{funcdesc}{execv}{path\, args}
Execute the executable \var{path} with argument list \var{args},
replacing the current process (i.e., the Python interpreter).
The argument list may be a tuple or list of strings.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{execve}{path\, args\, env}
Execute the executable \var{path} with argument list \var{args},
and environment \var{env},
replacing the current process (i.e., the Python interpreter).
The argument list may be a tuple or list of strings.
The environment must be a dictionary mapping strings to strings.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{_exit}{n}
Exit to the system with status \var{n}, without calling cleanup
handlers, flushing stdio buffers, etc.
(Not on MS-DOS.)

Note: the standard way to exit is \code{sys.exit(\var{n})}.
\code{posix._exit()} should normally only be used in the child process
after a \code{fork()}.
\end{funcdesc}

\begin{funcdesc}{fdopen}{fd\optional{\, mode\optional{\, bufsize}}}
Return an open file object connected to the file descriptor \var{fd}.
The \var{mode} and \var{bufsize} arguments have the same meaning as
the corresponding arguments to the built-in \code{open()} function.
\end{funcdesc}

\begin{funcdesc}{fork}{}
Fork a child process.  Return 0 in the child, the child's process id
in the parent.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{fstat}{fd}
Return status for file descriptor \var{fd}, like \code{stat()}.
\end{funcdesc}

\begin{funcdesc}{ftruncate}{fd\, length}
Truncate the file corresponding to file descriptor \var{fd}, 
so that it is at most \var{length} bytes in size.
\end{funcdesc}

\begin{funcdesc}{getcwd}{}
Return a string representing the current working directory.
\end{funcdesc}

\begin{funcdesc}{getegid}{}
Return the current process' effective group id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{geteuid}{}
Return the current process' effective user id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{getgid}{}
Return the current process' group id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{getpgrp}{}
Return the current process group id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{getpid}{}
Return the current process id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{getppid}{}
Return the parent's process id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{getuid}{}
Return the current process' user id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{kill}{pid\, sig}
Kill the process \var{pid} with signal \var{sig}.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{link}{src\, dst}
Create a hard link pointing to \var{src} named \var{dst}.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{listdir}{path}
Return a list containing the names of the entries in the directory.
The list is in arbitrary order.  It does not include the special
entries \code{'.'} and \code{'..'} even if they are present in the
directory.
\end{funcdesc}

\begin{funcdesc}{lseek}{fd\, pos\, how}
Set the current position of file descriptor \var{fd} to position
\var{pos}, modified by \var{how}: 0 to set the position relative to
the beginning of the file; 1 to set it relative to the current
position; 2 to set it relative to the end of the file.
\end{funcdesc}

\begin{funcdesc}{lstat}{path}
Like \code{stat()}, but do not follow symbolic links.  (On systems
without symbolic links, this is identical to \code{posix.stat()}.)
\end{funcdesc}

\begin{funcdesc}{mkfifo}{path\optional{\, mode}}
Create a FIFO (a POSIX named pipe) named \var{path} with numeric mode
\var{mode}.  The default \var{mode} is 0666 (octal).  The current
umask value is first masked out from the mode.
(Not on MS-DOS.)

FIFOs are pipes that can be accessed like regular files.  FIFOs exist
until they are deleted (for example with \code{os.unlink}).
Generally, FIFOs are used as rendez-vous between ``client'' and
``server'' type processes: the server opens the FIFO for reading, and
the client opens it for writing.  Note that \code{mkfifo()} doesn't
open the FIFO -- it just creates the rendez-vous point.
\end{funcdesc}

\begin{funcdesc}{mkdir}{path\optional{\, mode}}
Create a directory named \var{path} with numeric mode \var{mode}.
The default \var{mode} is 0777 (octal).  On some systems, \var{mode}
is ignored.  Where it is used, the current umask value is first
masked out.
\end{funcdesc}

\begin{funcdesc}{nice}{increment}
Add \var{incr} to the process' ``niceness''.  Return the new niceness.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{open}{file\, flags\optional{\, mode}}
Open the file \var{file} and set various flags according to
\var{flags} and possibly its mode according to \var{mode}.
The default \var{mode} is 0777 (octal), and the current umask value is
first masked out.  Return the file descriptor for the newly opened
file.

For a description of the flag and mode values, see the \UNIX{} or C
run-time documentation; flag constants (like \code{O_RDONLY} and
\code{O_WRONLY}) are defined in this module too (see below).

Note: this function is intended for low-level I/O.  For normal usage,
use the built-in function \code{open}, which returns a ``file object''
with \code{read()} and  \code{write()} methods (and many more).
\end{funcdesc}

\begin{funcdesc}{pipe}{}
Create a pipe.  Return a pair of file descriptors \code{(r, w)}
usable for reading and writing, respectively.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{plock}{op}
Lock program segments into memory.  The value of \var{op}
(defined in \code{<sys/lock.h>}) determines which segments are locked.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{popen}{command\optional{\, mode\optional{\, bufsize}}}
Open a pipe to or from \var{command}.  The return value is an open
file object connected to the pipe, which can be read or written
depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
The \var{bufsize} argument has the same meaning as the corresponding
argument to the built-in \code{open()} function.  The exit status of
the command (encoded in the format specified for \code{wait()}) is
available as the return value of the \code{close()} method of the file
object.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{putenv}{varname\, value}
Set the environment variable named \var{varname} to the string \var{value}.  
Such changes to the environment affect
subprocesses started with \code{os.system()}, \code{os.popen()} or
\code{os.fork()} and \code{os.execv()}.  (Not on all systems.)

When \code{putenv()} is
supported, assignments to items in \code{os.environ} are automatically
translated into corresponding calls to \code{os.putenv()}; however,
calls to \code{os.putenv()} don't update \code{os.environ}, so it is
actually preferable to assign to items of \code{os.environ}.  
\end{funcdesc}

\begin{funcdesc}{strerror}{code}
Return the error message corresponding to the error code in \var{code}.
\end{funcdesc}

\begin{funcdesc}{read}{fd\, n}
Read at most \var{n} bytes from file descriptor \var{fd}.
Return a string containing the bytes read.

Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \code{posix.open()} or
\code{posix.pipe()}.  To read a ``file object'' returned by the
built-in function \code{open} or by \code{posix.popen} or
\code{posix.fdopen}, or \code{sys.stdin}, use its
\code{read()} or \code{readline()} methods.
\end{funcdesc}

\begin{funcdesc}{readlink}{path}
Return a string representing the path to which the symbolic link
points.  (On systems without symbolic links, this always raises
\code{posix.error}.)
\end{funcdesc}

\begin{funcdesc}{remove}{path}
Remove the file \var{path}.  See \code{rmdir} below to remove a directory.
This is identical to the \code{unlink} function documented below.
\end{funcdesc}

\begin{funcdesc}{rename}{src\, dst}
Rename the file or directory \var{src} to \var{dst}.
\end{funcdesc}

\begin{funcdesc}{rmdir}{path}
Remove the directory \var{path}.
\end{funcdesc}

\begin{funcdesc}{setgid}{gid}
Set the current process' group id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{setpgrp}{}
Calls the system call \code{setpgrp()} or \code{setpgrp(0, 0)}
depending on which version is implemented (if any).  See the \UNIX{}
manual for the semantics.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{setpgid}{pid\, pgrp}
Calls the system call \code{setpgid()}.  See the \UNIX{} manual for
the semantics.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{setsid}{}
Calls the system call \code{setsid()}.  See the \UNIX{} manual for the
semantics.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{setuid}{uid}
Set the current process' user id.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{stat}{path}
Perform a \emph{stat} system call on the given path.  The return value
is a tuple of at least 10 integers giving the most important (and
portable) members of the \emph{stat} structure, in the order
\code{st_mode},
\code{st_ino},
\code{st_dev},
\code{st_nlink},
\code{st_uid},
\code{st_gid},
\code{st_size},
\code{st_atime},
\code{st_mtime},
\code{st_ctime}.
More items may be added at the end by some implementations.
(On MS-DOS, some items are filled with dummy values.)

Note: The standard module \code{stat} defines functions and constants
that are useful for extracting information from a stat structure.
\refstmodindex{stat}
\end{funcdesc}

\begin{funcdesc}{symlink}{src\, dst}
Create a symbolic link pointing to \var{src} named \var{dst}.  (On
systems without symbolic links, this always raises
\code{posix.error}.)
\end{funcdesc}

\begin{funcdesc}{system}{command}
Execute the command (a string) in a subshell.  This is implemented by
calling the Standard C function \code{system()}, and has the same
limitations.  Changes to \code{posix.environ}, \code{sys.stdin} etc.\ are
not reflected in the environment of the executed command.  The return
value is the exit status of the process encoded in the format
specified for \code{wait()}.
\end{funcdesc}

\begin{funcdesc}{tcgetpgrp}{fd}
Return the process group associated with the terminal given by
\var{fd} (an open file descriptor as returned by \code{posix.open()}).
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{tcsetpgrp}{fd\, pg}
Set the process group associated with the terminal given by
\var{fd} (an open file descriptor as returned by \code{posix.open()})
to \var{pg}.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{times}{}
Return a 5-tuple of floating point numbers indicating accumulated (CPU
or other)
times, in seconds.  The items are: user time, system time, children's
user time, children's system time, and elapsed real time since a fixed
point in the past, in that order.  See the \UNIX{}
manual page {\it times}(2).  (Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{umask}{mask}
Set the current numeric umask and returns the previous umask.
(Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{uname}{}
Return a 5-tuple containing information identifying the current
operating system.  The tuple contains 5 strings:
\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, \var{machine})}.
Some systems truncate the nodename to 8
characters or to the leading component; a better way to get the
hostname is \code{socket.gethostname()} or even
\code{socket.gethostbyaddr(socket.gethostname())}.
(Not on MS-DOS, nor on older \UNIX{} systems.)
\end{funcdesc}

\begin{funcdesc}{unlink}{path}
Remove the file \var{path}.  This is the same function as \code{remove};
the \code{unlink} name is its traditional \UNIX{} name.
\end{funcdesc}

\begin{funcdesc}{utime}{path\, {\rm (}atime, mtime{\rm )}}
Set the access and modified time of the file to the given values.
(The second argument is a tuple of two items.)
\end{funcdesc}

\begin{funcdesc}{wait}{}
Wait for completion of a child process, and return a tuple containing
its pid and exit status indication: a 16-bit number, whose low byte is
the signal number that killed the process, and whose high byte is the
exit status (if the signal number is zero); the high bit of the low
byte is set if a core file was produced.  (Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{waitpid}{pid\, options}
Wait for completion of a child process given by proces id, and return
a tuple containing its pid and exit status indication (encoded as for
\code{wait()}).  The semantics of the call are affected by the value of
the integer options, which should be 0 for normal operation.  (If the
system does not support \code{waitpid()}, this always raises
\code{posix.error}.  Not on MS-DOS.)
\end{funcdesc}

\begin{funcdesc}{write}{fd\, str}
Write the string \var{str} to file descriptor \var{fd}.
Return the number of bytes actually written.

Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \code{posix.open()} or
\code{posix.pipe()}.  To write a ``file object'' returned by the
built-in function \code{open} or by \code{posix.popen} or
\code{posix.fdopen}, or \code{sys.stdout} or \code{sys.stderr}, use
its \code{write()} method.
\end{funcdesc}

\begin{datadesc}{WNOHANG}
The option for \code{waitpid()} to avoid hanging if no child process
status is available immediately.
\end{datadesc}


\begin{datadesc}{O_RDONLY}
\end{datadesc}
\begin{datadesc}{O_WRONLY}
\end{datadesc}
\begin{datadesc}{O_RDWR}
\end{datadesc}
\begin{datadesc}{O_NDELAY}
\end{datadesc}
\begin{datadesc}{O_NONBLOCK}
\end{datadesc}
\begin{datadesc}{O_APPEND}
\end{datadesc}
\begin{datadesc}{O_DSYNC}
\end{datadesc}
\begin{datadesc}{O_RSYNC}
\end{datadesc}
\begin{datadesc}{O_SYNC}
\end{datadesc}
\begin{datadesc}{O_NOCTTY}
\end{datadesc}
\begin{datadesc}{O_CREAT}
\end{datadesc}
\begin{datadesc}{O_EXCL}
\end{datadesc}
\begin{datadesc}{O_TRUNC}
Options for the \code{flag} argument to the \code{open()} function.
These can be bit-wise OR'd together.
\end{datadesc}