Doc/libposix.tex

   1 \section{Built-in Module \module{posix}}
   2 \label{module-posix}
   3 \bimodindex{posix}
   4
   5 This module provides access to operating system functionality that is
   6 standardized by the \C{} Standard and the \POSIX{} standard (a thinly
   7 disguised \UNIX{} interface).
   8
   9 \strong{Do not import this module directly.}  Instead, import the
  10 module \module{os}, which provides a \emph{portable} version of this
  11 interface.  On \UNIX{}, the \module{os} module provides a superset of
  12 the \module{posix} interface.  On non-\UNIX{} operating systems the
  13 \module{posix} module is not available, but a subset is always
  14 available through the \module{os} interface.  Once \module{os} is
  15 imported, there is \emph{no} performance penalty in using it instead
  16 of \module{posix}.  In addition, \module{os} provides some additional
  17 functionality, such as automatically calling \function{putenv()}
  18 when an entry in \code{os.environ} is changed.
  19 \refstmodindex{os}
  20
  21 The descriptions below are very terse; refer to the corresponding
  22 \UNIX{} manual (or \POSIX{} documentation) entry for more information.
  23 Arguments called \var{path} refer to a pathname given as a string.
  24
  25 Errors are reported as exceptions; the usual exceptions are given
  26 for type errors, while errors reported by the system calls raise
  27 \exception{error}, described below.
  28
  29 Module \module{posix} defines the following data items:
  30
  31 \begin{datadesc}{environ}
  32 A dictionary representing the string environment at the time
  33 the interpreter was started.
  34 For example,
  35 \code{posix.environ['HOME']}
  36 is the pathname of your home directory, equivalent to
  37 \code{getenv("HOME")}
  38 in \C{}.
  39
  40 Modifying this dictionary does not affect the string environment
  41 passed on by \function{execv()}, \function{popen()} or
  42 \function{system()}; if you need to change the environment, pass
  43 \code{environ} to \function{execve()} or add variable assignments and
  44 export statements to the command string for \function{system()} or
  45 \function{popen()}.
  46
  47 \emph{However:} If you are using this module via the \module{os}
  48 module (as you should -- see the introduction above), \code{environ}
  49 is a a mapping object that behaves almost like a dictionary but
  50 invokes \function{putenv()} automatically called whenever an item is
  51 changed.
  52 \end{datadesc}
  53
  54 \begin{excdesc}{error}
  55 This exception is raised when a \POSIX{} function returns a
  56 \POSIX{}-related error (e.g., not for illegal argument types).  The
  57 accompanying value is a pair containing the numeric error code from
  58 \cdata{errno} and the corresponding string, as would be printed by the
  59 \C{} function \cfunction{perror()}.  See the module
  60 \module{errno}\refbimodindex{errno}, which contains names for the
  61 error codes defined by the underlying operating system.
  62
  63 When exceptions are classes, this exception carries two attributes,
  64 \member{errno} and \member{strerror}.  The first holds the value of
  65 the \C{} \cdata{errno} variable, and the latter holds the
  66 corresponding error message from \cfunction{strerror()}.
  67
  68 When exceptions are strings, the string for the exception is
  69 \code{'os.error'}; this reflects the more portable access to the
  70 exception through the \module{os} module.
  71 \end{excdesc}
  72
  73 It defines the following functions and constants:
  74
  75 \begin{funcdesc}{chdir}{path}
  76 Change the current working directory to \var{path}.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{chmod}{path, mode}
  80 Change the mode of \var{path} to the numeric \var{mode}.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{chown}{path, uid, gid}
  84 Change the owner and group id of \var{path} to the numeric \var{uid}
  85 and \var{gid}.
  86 (Not on MS-DOS.)
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{close}{fd}
  90 Close file descriptor \var{fd}.
  91
  92 Note: this function is intended for low-level I/O and must be applied
  93 to a file descriptor as returned by \function{open()} or
  94 \function{pipe()}.  To close a ``file object'' returned by the
  95 built-in function \function{open()} or by \function{popen()} or
  96 \function{fdopen()}, use its \method{close()} method.
  97 \end{funcdesc}
  98
  99 \begin{funcdesc}{dup}{fd}
 100 Return a duplicate of file descriptor \var{fd}.
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{dup2}{fd, fd2}
 104 Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
 105 first if necessary.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{execv}{path, args}
 109 Execute the executable \var{path} with argument list \var{args},
 110 replacing the current process (i.e., the Python interpreter).
 111 The argument list may be a tuple or list of strings.
 112 (Not on MS-DOS.)
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{execve}{path, args, env}
 116 Execute the executable \var{path} with argument list \var{args},
 117 and environment \var{env},
 118 replacing the current process (i.e., the Python interpreter).
 119 The argument list may be a tuple or list of strings.
 120 The environment must be a dictionary mapping strings to strings.
 121 (Not on MS-DOS.)
 122 \end{funcdesc}
 123
 124 \begin{funcdesc}{_exit}{n}
 125 Exit to the system with status \var{n}, without calling cleanup
 126 handlers, flushing stdio buffers, etc.
 127 (Not on MS-DOS.)
 128
 129 Note: the standard way to exit is \code{sys.exit(\var{n})}.
 130 \function{_exit()} should normally only be used in the child process
 131 after a \function{fork()}.
 132 \end{funcdesc}
 133
 134 \begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
 135 Return an open file object connected to the file descriptor \var{fd}.
 136 The \var{mode} and \var{bufsize} arguments have the same meaning as
 137 the corresponding arguments to the built-in \function{open()} function.
 138 \end{funcdesc}
 139
 140 \begin{funcdesc}{fork}{}
 141 Fork a child process.  Return \code{0} in the child, the child's
 142 process id in the parent.
 143 (Not on MS-DOS.)
 144 \end{funcdesc}
 145
 146 \begin{funcdesc}{fstat}{fd}
 147 Return status for file descriptor \var{fd}, like \function{stat()}.
 148 \end{funcdesc}
 149
 150 \begin{funcdesc}{ftruncate}{fd, length}
 151 Truncate the file corresponding to file descriptor \var{fd},
 152 so that it is at most \var{length} bytes in size.
 153 \end{funcdesc}
 154
 155 \begin{funcdesc}{getcwd}{}
 156 Return a string representing the current working directory.
 157 \end{funcdesc}
 158
 159 \begin{funcdesc}{getegid}{}
 160 Return the current process' effective group id.
 161 (Not on MS-DOS.)
 162 \end{funcdesc}
 163
 164 \begin{funcdesc}{geteuid}{}
 165 Return the current process' effective user id.
 166 (Not on MS-DOS.)
 167 \end{funcdesc}
 168
 169 \begin{funcdesc}{getgid}{}
 170 Return the current process' group id.
 171 (Not on MS-DOS.)
 172 \end{funcdesc}
 173
 174 \begin{funcdesc}{getpgrp}{}
 175 Return the current process group id.
 176 (Not on MS-DOS.)
 177 \end{funcdesc}
 178
 179 \begin{funcdesc}{getpid}{}
 180 Return the current process id.
 181 (Not on MS-DOS.)
 182 \end{funcdesc}
 183
 184 \begin{funcdesc}{getppid}{}
 185 Return the parent's process id.
 186 (Not on MS-DOS.)
 187 \end{funcdesc}
 188
 189 \begin{funcdesc}{getuid}{}
 190 Return the current process' user id.
 191 (Not on MS-DOS.)
 192 \end{funcdesc}
 193
 194 \begin{funcdesc}{kill}{pid, sig}
 195 Kill the process \var{pid} with signal \var{sig}.
 196 (Not on MS-DOS.)
 197 \end{funcdesc}
 198
 199 \begin{funcdesc}{link}{src, dst}
 200 Create a hard link pointing to \var{src} named \var{dst}.
 201 (Not on MS-DOS.)
 202 \end{funcdesc}
 203
 204 \begin{funcdesc}{listdir}{path}
 205 Return a list containing the names of the entries in the directory.
 206 The list is in arbitrary order.  It does not include the special
 207 entries \code{'.'} and \code{'..'} even if they are present in the
 208 directory.
 209 \end{funcdesc}
 210
 211 \begin{funcdesc}{lseek}{fd, pos, how}
 212 Set the current position of file descriptor \var{fd} to position
 213 \var{pos}, modified by \var{how}: \code{0} to set the position
 214 relative to the beginning of the file; \code{1} to set it relative to
 215 the current position; \code{2} to set it relative to the end of the
 216 file.
 217 \end{funcdesc}
 218
 219 \begin{funcdesc}{lstat}{path}
 220 Like \function{stat()}, but do not follow symbolic links.  (On systems
 221 without symbolic links, this is identical to \function{stat()}.)
 222 \end{funcdesc}
 223
 224 \begin{funcdesc}{mkfifo}{path\optional{, mode}}
 225 Create a FIFO (a \POSIX{} named pipe) named \var{path} with numeric mode
 226 \var{mode}.  The default \var{mode} is \code{0666} (octal).  The current
 227 umask value is first masked out from the mode.
 228 (Not on MS-DOS.)
 229
 230 FIFOs are pipes that can be accessed like regular files.  FIFOs exist
 231 until they are deleted (for example with \function{os.unlink()}).
 232 Generally, FIFOs are used as rendezvous between ``client'' and
 233 ``server'' type processes: the server opens the FIFO for reading, and
 234 the client opens it for writing.  Note that \function{mkfifo()}
 235 doesn't open the FIFO --- it just creates the rendezvous point.
 236 \end{funcdesc}
 237
 238 \begin{funcdesc}{mkdir}{path\optional{, mode}}
 239 Create a directory named \var{path} with numeric mode \var{mode}.
 240 The default \var{mode} is \code{0777} (octal).  On some systems,
 241 \var{mode} is ignored.  Where it is used, the current umask value is
 242 first masked out.
 243 \end{funcdesc}
 244
 245 \begin{funcdesc}{nice}{increment}
 246 Add \var{increment} to the process' ``niceness''.  Return the new
 247 niceness.  (Not on MS-DOS.)
 248 \end{funcdesc}
 249
 250 \begin{funcdesc}{open}{file, flags\optional{, mode}}
 251 Open the file \var{file} and set various flags according to
 252 \var{flags} and possibly its mode according to \var{mode}.
 253 The default \var{mode} is \code{0777} (octal), and the current umask
 254 value is first masked out.  Return the file descriptor for the newly
 255 opened file.
 256
 257 For a description of the flag and mode values, see the \UNIX{} or \C{}
 258 run-time documentation; flag constants (like \constant{O_RDONLY} and
 259 \constant{O_WRONLY}) are defined in this module too (see below).
 260
 261 Note: this function is intended for low-level I/O.  For normal usage,
 262 use the built-in function \function{open()}, which returns a ``file
 263 object'' with \method{read()} and \method{write()} methods (and many
 264 more).
 265 \end{funcdesc}
 266
 267 \begin{funcdesc}{pipe}{}
 268 Create a pipe.  Return a pair of file descriptors \code{(\var{r},
 269 \var{w})} usable for reading and writing, respectively.
 270 (Not on MS-DOS.)
 271 \end{funcdesc}
 272
 273 \begin{funcdesc}{plock}{op}
 274 Lock program segments into memory.  The value of \var{op}
 275 (defined in \code{<sys/lock.h>}) determines which segments are locked.
 276 (Not on MS-DOS.)
 277 \end{funcdesc}
 278
 279 \begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
 280 Open a pipe to or from \var{command}.  The return value is an open
 281 file object connected to the pipe, which can be read or written
 282 depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
 283 The \var{bufsize} argument has the same meaning as the corresponding
 284 argument to the built-in \function{open()} function.  The exit status of
 285 the command (encoded in the format specified for \function{wait()}) is
 286 available as the return value of the \method{close()} method of the file
 287 object.
 288 (Not on MS-DOS.)
 289 \end{funcdesc}
 290
 291 \begin{funcdesc}{putenv}{varname, value}
 292 \index{environment variables!setting}
 293 Set the environment variable named \var{varname} to the string
 294 \var{value}.  Such changes to the environment affect subprocesses
 295 started with \function{os.system()}, \function{os.popen()} or
 296 \function{os.fork()} and \function{os.execv()}.  (Not on all systems.)
 297
 298 When \function{putenv()} is
 299 supported, assignments to items in \code{os.environ} are automatically
 300 translated into corresponding calls to \function{putenv()}; however,
 301 calls to \function{putenv()} don't update \code{os.environ}, so it is
 302 actually preferable to assign to items of \code{os.environ}.
 303 \end{funcdesc}
 304
 305 \begin{funcdesc}{strerror}{code}
 306 Return the error message corresponding to the error code in \var{code}.
 307 \end{funcdesc}
 308
 309 \begin{funcdesc}{read}{fd, n}
 310 Read at most \var{n} bytes from file descriptor \var{fd}.
 311 Return a string containing the bytes read.
 312
 313 Note: this function is intended for low-level I/O and must be applied
 314 to a file descriptor as returned by \function{open()} or
 315 \function{pipe()}.  To read a ``file object'' returned by the
 316 built-in function \function{open()} or by \function{popen()} or
 317 \function{fdopen()}, or \code{sys.stdin}, use its
 318 \method{read()} or \method{readline()} methods.
 319 \end{funcdesc}
 320
 321 \begin{funcdesc}{readlink}{path}
 322 Return a string representing the path to which the symbolic link
 323 points.  (On systems without symbolic links, this always raises
 324 \exception{error}.)
 325 \end{funcdesc}
 326
 327 \begin{funcdesc}{remove}{path}
 328 Remove the file \var{path}.  See \function{rmdir()} below to remove a
 329 directory.  This is identical to the \function{unlink()} function
 330 documented below.
 331 \end{funcdesc}
 332
 333 \begin{funcdesc}{rename}{src, dst}
 334 Rename the file or directory \var{src} to \var{dst}.
 335 \end{funcdesc}
 336
 337 \begin{funcdesc}{rmdir}{path}
 338 Remove the directory \var{path}.
 339 \end{funcdesc}
 340
 341 \begin{funcdesc}{setgid}{gid}
 342 Set the current process' group id.
 343 (Not on MS-DOS.)
 344 \end{funcdesc}
 345
 346 \begin{funcdesc}{setpgrp}{}
 347 Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
 348 0)} depending on which version is implemented (if any).  See the
 349 \UNIX{} manual for the semantics.
 350 (Not on MS-DOS.)
 351 \end{funcdesc}
 352
 353 \begin{funcdesc}{setpgid}{pid, pgrp}
 354 Calls the system call \cfunction{setpgid()}.  See the \UNIX{} manual
 355 for the semantics.
 356 (Not on MS-DOS.)
 357 \end{funcdesc}
 358
 359 \begin{funcdesc}{setsid}{}
 360 Calls the system call \cfunction{setsid()}.  See the \UNIX{} manual
 361 for the semantics.
 362 (Not on MS-DOS.)
 363 \end{funcdesc}
 364
 365 \begin{funcdesc}{setuid}{uid}
 366 Set the current process' user id.
 367 (Not on MS-DOS.)
 368 \end{funcdesc}
 369
 370 \begin{funcdesc}{stat}{path}
 371 Perform a \cfunction{stat()} system call on the given path.  The
 372 return value is a tuple of at least 10 integers giving the most
 373 important (and portable) members of the \emph{stat} structure, in the
 374 order
 375 \code{st_mode},
 376 \code{st_ino},
 377 \code{st_dev},
 378 \code{st_nlink},
 379 \code{st_uid},
 380 \code{st_gid},
 381 \code{st_size},
 382 \code{st_atime},
 383 \code{st_mtime},
 384 \code{st_ctime}.
 385 More items may be added at the end by some implementations.
 386 (On MS-DOS, some items are filled with dummy values.)
 387
 388 Note: The standard module \module{stat}\refstmodindex{stat} defines
 389 functions and constants that are useful for extracting information
 390 from a stat structure.
 391 \end{funcdesc}
 392
 393 \begin{funcdesc}{symlink}{src, dst}
 394 Create a symbolic link pointing to \var{src} named \var{dst}.  (On
 395 systems without symbolic links, this always raises \exception{error}.)
 396 \end{funcdesc}
 397
 398 \begin{funcdesc}{system}{command}
 399 Execute the command (a string) in a subshell.  This is implemented by
 400 calling the Standard \C{} function \cfunction{system()}, and has the
 401 same limitations.  Changes to \code{posix.environ}, \code{sys.stdin}
 402 etc.\ are not reflected in the environment of the executed command.
 403 The return value is the exit status of the process encoded in the
 404 format specified for \function{wait()}.
 405 \end{funcdesc}
 406
 407 \begin{funcdesc}{tcgetpgrp}{fd}
 408 Return the process group associated with the terminal given by
 409 \var{fd} (an open file descriptor as returned by \function{open()}).
 410 (Not on MS-DOS.)
 411 \end{funcdesc}
 412
 413 \begin{funcdesc}{tcsetpgrp}{fd, pg}
 414 Set the process group associated with the terminal given by
 415 \var{fd} (an open file descriptor as returned by \function{open()})
 416 to \var{pg}.
 417 (Not on MS-DOS.)
 418 \end{funcdesc}
 419
 420 \begin{funcdesc}{times}{}
 421 Return a 5-tuple of floating point numbers indicating accumulated (CPU
 422 or other)
 423 times, in seconds.  The items are: user time, system time, children's
 424 user time, children's system time, and elapsed real time since a fixed
 425 point in the past, in that order.  See the \UNIX{}
 426 manual page \manpage{times}{2}.  (Not on MS-DOS.)
 427 \end{funcdesc}
 428
 429 \begin{funcdesc}{umask}{mask}
 430 Set the current numeric umask and returns the previous umask.
 431 (Not on MS-DOS.)
 432 \end{funcdesc}
 433
 434 \begin{funcdesc}{uname}{}
 435 Return a 5-tuple containing information identifying the current
 436 operating system.  The tuple contains 5 strings:
 437 \code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
 438 \var{machine})}.  Some systems truncate the nodename to 8
 439 characters or to the leading component; a better way to get the
 440 hostname is \function{socket.gethostname()}%
 441 \withsubitem{(in module socket)}{\ttindex{gethostname()}}
 442 or even
 443 \code{socket.gethostbyaddr(socket.gethostname())}%
 444 \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}.
 445 (Not on MS-DOS, nor on older \UNIX{} systems.)
 446 \end{funcdesc}
 447
 448 \begin{funcdesc}{unlink}{path}
 449 Remove the file \var{path}.  This is the same function as \code{remove};
 450 the \code{unlink} name is its traditional \UNIX{} name.
 451 \end{funcdesc}
 452
 453 \begin{funcdesc}{utime}{path, {\rm (}atime, mtime{\rm )}}
 454 Set the access and modified time of the file to the given values.
 455 (The second argument is a tuple of two items.)
 456 \end{funcdesc}
 457
 458 \begin{funcdesc}{wait}{}
 459 Wait for completion of a child process, and return a tuple containing
 460 its pid and exit status indication: a 16-bit number, whose low byte is
 461 the signal number that killed the process, and whose high byte is the
 462 exit status (if the signal number is zero); the high bit of the low
 463 byte is set if a core file was produced.  (Not on MS-DOS.)
 464 \end{funcdesc}
 465
 466 \begin{funcdesc}{waitpid}{pid, options}
 467 Wait for completion of a child process given by proces id, and return
 468 a tuple containing its pid and exit status indication (encoded as for
 469 \function{wait()}).  The semantics of the call are affected by the
 470 value of the integer \var{options}, which should be \code{0} for
 471 normal operation.  (If the system does not support
 472 \function{waitpid()}, this always raises \exception{error}.  Not on
 473 MS-DOS.)
 474 \end{funcdesc}
 475
 476 \begin{funcdesc}{write}{fd, str}
 477 Write the string \var{str} to file descriptor \var{fd}.
 478 Return the number of bytes actually written.
 479
 480 Note: this function is intended for low-level I/O and must be applied
 481 to a file descriptor as returned by \function{open()} or
 482 \function{pipe()}.  To write a ``file object'' returned by the
 483 built-in function \function{open()} or by \function{popen()} or
 484 \function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
 485 its \method{write()} method.
 486 \end{funcdesc}
 487
 488 \begin{datadesc}{WNOHANG}
 489 The option for \function{waitpid()} to avoid hanging if no child
 490 process status is available immediately.
 491 \end{datadesc}
 492
 493
 494 \begin{datadesc}{O_RDONLY}
 495 \dataline{O_WRONLY}
 496 \dataline{O_RDWR}
 497 \dataline{O_NDELAY}
 498 \dataline{O_NONBLOCK}
 499 \dataline{O_APPEND}
 500 \dataline{O_DSYNC}
 501 \dataline{O_RSYNC}
 502 \dataline{O_SYNC}
 503 \dataline{O_NOCTTY}
 504 \dataline{O_CREAT}
 505 \dataline{O_EXCL}
 506 \dataline{O_TRUNC}
 507 Options for the \code{flag} argument to the \function{open()} function.
 508 These can be bit-wise OR'd together.
 509 \end{datadesc}