Doc/lib/libposix.tex

   1 \section{Built-in Module \sectcode{posix}}
   2 \bimodindex{posix}
   3
   4 This module provides access to operating system functionality that is
   5 standardized by the C Standard and the POSIX standard (a thinly disguised
   6 \UNIX{} interface).
   7
   8 \strong{Do not import this module directly.}  Instead, import the
   9 module \code{os}, which provides a \emph{portable} version of this
  10 interface.  On \UNIX{}, the \code{os} module provides a superset of
  11 the \code{posix} interface.  On non-\UNIX{} operating systems the
  12 \code{posix} module is not available, but a subset is always available
  13 through the \code{os} interface.  Once \code{os} is imported, there is
  14 \emph{no} performance penalty in using it instead of
  15 \code{posix}.
  16 \stmodindex{os}
  17
  18 The descriptions below are very terse; refer to the
  19 corresponding \UNIX{} manual entry for more information.  Arguments
  20 called \var{path} refer to a pathname given as a string.
  21
  22 Errors are reported as exceptions; the usual exceptions are given
  23 for type errors, while errors reported by the system calls raise
  24 \code{posix.error}, described below.
  25
  26 Module \code{posix} defines the following data items:
  27
  28 \renewcommand{\indexsubitem}{(data in module posix)}
  29 \begin{datadesc}{environ}
  30 A dictionary representing the string environment at the time
  31 the interpreter was started.
  32 For example,
  33 \code{posix.environ['HOME']}
  34 is the pathname of your home directory, equivalent to
  35 \code{getenv("HOME")}
  36 in C.
  37 Modifying this dictionary does not affect the string environment
  38 passed on by \code{execv()}, \code{popen()} or \code{system()}; if you
  39 need to change the environment, pass \code{environ} to \code{execve()}
  40 or add variable assignments and export statements to the command
  41 string for \code{system()} or \code{popen()}.%
  42 \footnote{The problem with automatically passing on \code{environ} is
  43 that there is no portable way of changing the environment.}
  44 \end{datadesc}
  45
  46 \renewcommand{\indexsubitem}{(exception in module posix)}
  47 \begin{excdesc}{error}
  48 This exception is raised when a POSIX function returns a
  49 POSIX-related error (e.g., not for illegal argument types).  Its
  50 string value is \code{'posix.error'}.  The accompanying value is a
  51 pair containing the numeric error code from \code{errno} and the
  52 corresponding string, as would be printed by the C function
  53 \code{perror()}.
  54 \end{excdesc}
  55
  56 It defines the following functions and constants:
  57
  58 \renewcommand{\indexsubitem}{(in module posix)}
  59 \begin{funcdesc}{chdir}{path}
  60 Change the current working directory to \var{path}.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{chmod}{path\, mode}
  64 Change the mode of \var{path} to the numeric \var{mode}.
  65 \end{funcdesc}
  66
  67 \begin{funcdesc}{chown}{path\, uid, gid}
  68 Change the owner and group id of \var{path} to the numeric \var{uid}
  69 and \var{gid}.
  70 (Not on MS-DOS.)
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{close}{fd}
  74 Close file descriptor \var{fd}.
  75
  76 Note: this function is intended for low-level I/O and must be applied
  77 to a file descriptor as returned by \code{posix.open()} or
  78 \code{posix.pipe()}.  To close a ``file object'' returned by the
  79 built-in function \code{open} or by \code{posix.popen} or
  80 \code{posix.fdopen}, use its \code{close()} method.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{dup}{fd}
  84 Return a duplicate of file descriptor \var{fd}.
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{dup2}{fd\, fd2}
  88 Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
  89 first if necessary.  Return \code{None}.
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{execv}{path\, args}
  93 Execute the executable \var{path} with argument list \var{args},
  94 replacing the current process (i.e., the Python interpreter).
  95 The argument list may be a tuple or list of strings.
  96 (Not on MS-DOS.)
  97 \end{funcdesc}
  98
  99 \begin{funcdesc}{execve}{path\, args\, env}
 100 Execute the executable \var{path} with argument list \var{args},
 101 and environment \var{env},
 102 replacing the current process (i.e., the Python interpreter).
 103 The argument list may be a tuple or list of strings.
 104 The environment must be a dictionary mapping strings to strings.
 105 (Not on MS-DOS.)
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{_exit}{n}
 109 Exit to the system with status \var{n}, without calling cleanup
 110 handlers, flushing stdio buffers, etc.
 111 (Not on MS-DOS.)
 112
 113 Note: the standard way to exit is \code{sys.exit(\var{n})}.
 114 \code{posix._exit()} should normally only be used in the child process
 115 after a \code{fork()}.
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{fdopen}{fd\optional{\, mode\optional{\, bufsize}}}
 119 Return an open file object connected to the file descriptor \var{fd}.
 120 The \var{mode} and \var{bufsize} arguments have the same meaning as
 121 the corresponding arguments to the built-in \code{open()} function.
 122 \end{funcdesc}
 123
 124 \begin{funcdesc}{fork}{}
 125 Fork a child process.  Return 0 in the child, the child's process id
 126 in the parent.
 127 (Not on MS-DOS.)
 128 \end{funcdesc}
 129
 130 \begin{funcdesc}{fstat}{fd}
 131 Return status for file descriptor \var{fd}, like \code{stat()}.
 132 \end{funcdesc}
 133
 134 \begin{funcdesc}{getcwd}{}
 135 Return a string representing the current working directory.
 136 \end{funcdesc}
 137
 138 \begin{funcdesc}{getegid}{}
 139 Return the current process's effective group id.
 140 (Not on MS-DOS.)
 141 \end{funcdesc}
 142
 143 \begin{funcdesc}{geteuid}{}
 144 Return the current process's effective user id.
 145 (Not on MS-DOS.)
 146 \end{funcdesc}
 147
 148 \begin{funcdesc}{getgid}{}
 149 Return the current process's group id.
 150 (Not on MS-DOS.)
 151 \end{funcdesc}
 152
 153 \begin{funcdesc}{getpid}{}
 154 Return the current process id.
 155 (Not on MS-DOS.)
 156 \end{funcdesc}
 157
 158 \begin{funcdesc}{getppid}{}
 159 Return the parent's process id.
 160 (Not on MS-DOS.)
 161 \end{funcdesc}
 162
 163 \begin{funcdesc}{getuid}{}
 164 Return the current process's user id.
 165 (Not on MS-DOS.)
 166 \end{funcdesc}
 167
 168 \begin{funcdesc}{kill}{pid\, sig}
 169 Kill the process \var{pid} with signal \var{sig}.
 170 (Not on MS-DOS.)
 171 \end{funcdesc}
 172
 173 \begin{funcdesc}{link}{src\, dst}
 174 Create a hard link pointing to \var{src} named \var{dst}.
 175 (Not on MS-DOS.)
 176 \end{funcdesc}
 177
 178 \begin{funcdesc}{listdir}{path}
 179 Return a list containing the names of the entries in the directory.
 180 The list is in arbitrary order.  It does not include the special
 181 entries \code{'.'} and \code{'..'} even if they are present in the
 182 directory.
 183 \end{funcdesc}
 184
 185 \begin{funcdesc}{lseek}{fd\, pos\, how}
 186 Set the current position of file descriptor \var{fd} to position
 187 \var{pos}, modified by \var{how}: 0 to set the position relative to
 188 the beginning of the file; 1 to set it relative to the current
 189 position; 2 to set it relative to the end of the file.
 190 \end{funcdesc}
 191
 192 \begin{funcdesc}{lstat}{path}
 193 Like \code{stat()}, but do not follow symbolic links.  (On systems
 194 without symbolic links, this is identical to \code{posix.stat}.)
 195 \end{funcdesc}
 196
 197 \begin{funcdesc}{mkdir}{path\, mode}
 198 Create a directory named \var{path} with numeric mode \var{mode}.
 199 \end{funcdesc}
 200
 201 \begin{funcdesc}{nice}{increment}
 202 Add \var{incr} to the process' ``niceness''.  Return the new niceness.
 203 (Not on MS-DOS.)
 204 \end{funcdesc}
 205
 206 \begin{funcdesc}{open}{file\, flags\, mode}
 207 Open the file \var{file} and set various flags according to
 208 \var{flags} and possibly its mode according to \var{mode}.
 209 Return the file descriptor for the newly opened file.
 210
 211 Note: this function is intended for low-level I/O.  For normal usage,
 212 use the built-in function \code{open}, which returns a ``file object''
 213 with \code{read()} and  \code{write()} methods (and many more).
 214 \end{funcdesc}
 215
 216 \begin{funcdesc}{pipe}{}
 217 Create a pipe.  Return a pair of file descriptors \code{(r, w)}
 218 usable for reading and writing, respectively.
 219 (Not on MS-DOS.)
 220 \end{funcdesc}
 221
 222 \begin{funcdesc}{popen}{command\optional{\, mode\optional{\, bufsize}}}
 223 Open a pipe to or from \var{command}.  The return value is an open
 224 file object connected to the pipe, which can be read or written
 225 depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
 226 The \var{bufsize} argument has the same meaning as the corresponding
 227 argument to the built-in \code{open()} function.
 228 (Not on MS-DOS.)
 229 \end{funcdesc}
 230
 231 \begin{funcdesc}{read}{fd\, n}
 232 Read at most \var{n} bytes from file descriptor \var{fd}.
 233 Return a string containing the bytes read.
 234
 235 Note: this function is intended for low-level I/O and must be applied
 236 to a file descriptor as returned by \code{posix.open()} or
 237 \code{posix.pipe()}.  To read a ``file object'' returned by the
 238 built-in function \code{open} or by \code{posix.popen} or
 239 \code{posix.fdopen}, or \code{sys.stdin}, use its
 240 \code{read()} or \code{readline()} methods.
 241 \end{funcdesc}
 242
 243 \begin{funcdesc}{readlink}{path}
 244 Return a string representing the path to which the symbolic link
 245 points.  (On systems without symbolic links, this always raises
 246 \code{posix.error}.)
 247 \end{funcdesc}
 248
 249 \begin{funcdesc}{remove}{path}
 250 Remove the file \var{path}.  See \code{rmdir} below to remove a directory.
 251 \end{funcdesc}
 252
 253 \begin{funcdesc}{rename}{src\, dst}
 254 Rename the file or directory \var{src} to \var{dst}.
 255 \end{funcdesc}
 256
 257 \begin{funcdesc}{rmdir}{path}
 258 Remove the directory \var{path}.
 259 \end{funcdesc}
 260
 261 \begin{funcdesc}{setgid}{gid}
 262 Set the current process's group id.
 263 (Not on MS-DOS.)
 264 \end{funcdesc}
 265
 266 \begin{funcdesc}{setuid}{uid}
 267 Set the current process's user id.
 268 (Not on MS-DOS.)
 269 \end{funcdesc}
 270
 271 \begin{funcdesc}{stat}{path}
 272 Perform a {\em stat} system call on the given path.  The return value
 273 is a tuple of at least 10 integers giving the most important (and
 274 portable) members of the {\em stat} structure, in the order
 275 \code{st_mode},
 276 \code{st_ino},
 277 \code{st_dev},
 278 \code{st_nlink},
 279 \code{st_uid},
 280 \code{st_gid},
 281 \code{st_size},
 282 \code{st_atime},
 283 \code{st_mtime},
 284 \code{st_ctime}.
 285 More items may be added at the end by some implementations.
 286 (On MS-DOS, some items are filled with dummy values.)
 287
 288 Note: The standard module \code{stat} defines functions and constants
 289 that are useful for extracting information from a stat structure.
 290 \end{funcdesc}
 291
 292 \begin{funcdesc}{symlink}{src\, dst}
 293 Create a symbolic link pointing to \var{src} named \var{dst}.  (On
 294 systems without symbolic links, this always raises
 295 \code{posix.error}.)
 296 \end{funcdesc}
 297
 298 \begin{funcdesc}{system}{command}
 299 Execute the command (a string) in a subshell.  This is implemented by
 300 calling the Standard C function \code{system()}, and has the same
 301 limitations.  Changes to \code{posix.environ}, \code{sys.stdin} etc.\ are
 302 not reflected in the environment of the executed command.  The return
 303 value is the exit status of the process as returned by Standard C
 304 \code{system()}.
 305 \end{funcdesc}
 306
 307 \begin{funcdesc}{times}{}
 308 Return a 5-tuple of floating point numbers indicating accumulated (CPU
 309 or other)
 310 times, in seconds.  The items are: user time, system time, children's
 311 user time, children's system time, and elapsed real time since a fixed
 312 point in the past, in that order.  See the \UNIX{}
 313 manual page {\it times}(2).  (Not on MS-DOS.)
 314 \end{funcdesc}
 315
 316 \begin{funcdesc}{umask}{mask}
 317 Set the current numeric umask and returns the previous umask.
 318 (Not on MS-DOS.)
 319 \end{funcdesc}
 320
 321 \begin{funcdesc}{uname}{}
 322 Return a 5-tuple containing information identifying the current
 323 operating system.  The tuple contains 5 strings:
 324 \code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, \var{machine})}.
 325 Some systems truncate the nodename to 8
 326 characters or to the leading component; a better way to get the
 327 hostname is \code{socket.gethostname()}.  (Not on MS-DOS, nor on older
 328 \UNIX{} systems.)
 329 \end{funcdesc}
 330
 331 \begin{funcdesc}{unlink}{path}
 332 Remove the file \var{path}.  This is the same function as \code{remove};
 333 the \code{unlink} name is its traditional \UNIX{} name.
 334 \end{funcdesc}
 335
 336 \begin{funcdesc}{utime}{path\, \(atime\, mtime\)}
 337 Set the access and modified time of the file to the given values.
 338 (The second argument is a tuple of two items.)
 339 \end{funcdesc}
 340
 341 \begin{funcdesc}{wait}{}
 342 Wait for completion of a child process, and return a tuple containing
 343 its pid and exit status indication (encoded as by \UNIX{}).
 344 (Not on MS-DOS.)
 345 \end{funcdesc}
 346
 347 \begin{funcdesc}{waitpid}{pid\, options}
 348 Wait for completion of a child process given by proces id, and return
 349 a tuple containing its pid and exit status indication (encoded as by
 350 \UNIX{}).  The semantics of the call are affected by the value of
 351 the integer options, which should be 0 for normal operation.  (If the
 352 system does not support \code{waitpid()}, this always raises
 353 \code{posix.error}.  Not on MS-DOS.)
 354 \end{funcdesc}
 355
 356 \begin{funcdesc}{write}{fd\, str}
 357 Write the string \var{str} to file descriptor \var{fd}.
 358 Return the number of bytes actually written.
 359
 360 Note: this function is intended for low-level I/O and must be applied
 361 to a file descriptor as returned by \code{posix.open()} or
 362 \code{posix.pipe()}.  To write a ``file object'' returned by the
 363 built-in function \code{open} or by \code{posix.popen} or
 364 \code{posix.fdopen}, or \code{sys.stdout} or \code{sys.stderr}, use
 365 its \code{write()} method.
 366 \end{funcdesc}
 367
 368 \begin{datadesc}{WNOHANG}
 369 The option for \code{waitpid()} to avoid hanging if no child process
 370 status is available immediately.
 371 \end{datadesc}