Doc/libposix.tex

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