| \section{\module{posix} --- |
| The most common \POSIX{} system calls.} |
| \declaremodule{builtin}{posix} |
| |
| \modulesynopsis{The most common \POSIX{} system calls (normally used via module |
| \module{os}).} |
| |
| |
| 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 \module{os}, which provides a \emph{portable} version of this |
| interface. On \UNIX{}, the \module{os} module provides a superset of |
| the \module{posix} interface. On non-\UNIX{} operating systems the |
| \module{posix} module is not available, but a subset is always |
| available through the \module{os} interface. Once \module{os} is |
| imported, there is \emph{no} performance penalty in using it instead |
| of \module{posix}. In addition, \module{os} provides some additional |
| functionality, such as automatically calling \function{putenv()} |
| when an entry in \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 |
| \exception{error} (a synonym for the standard exception |
| \exception{OSError}), described |
| below. |
| |
| Module \module{posix} defines the following data items: |
| |
| \begin{datadesc}{environ} |
| A dictionary or dictionary look-alike 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 \function{execv()}, \function{popen()} or |
| \function{system()}; if you need to change the environment, pass |
| \code{environ} to \function{execve()} or add variable assignments and |
| export statements to the command string for \function{system()} or |
| \function{popen()}. |
| |
| \emph{However:} If you are using this module via the \module{os} |
| module (as you should -- see the introduction above), \code{environ} |
| is a a mapping object that behaves almost like a dictionary but |
| invokes \function{putenv()} automatically whenever an item is changed. |
| \end{datadesc} |
| |
| \begin{excdesc}{error} |
| This exception is raised when a \POSIX{} function returns a |
| \POSIX{}-related error (e.g., not for illegal argument types). The |
| accompanying value is a pair containing the numeric error code from |
| \cdata{errno} and the corresponding string, as would be printed by the |
| \C{} function \cfunction{perror()}. See the module |
| \module{errno}\refbimodindex{errno}, which contains names for the |
| error codes defined by the underlying operating system. |
| |
| When exceptions are classes, this exception carries two attributes, |
| \member{errno} and \member{strerror}. The first holds the value of |
| the \C{} \cdata{errno} variable, and the latter holds the |
| corresponding error message from \cfunction{strerror()}. For |
| exceptions that involve a file system path (e.g. \code{chdir} or |
| \code{unlink}), the exception instance will contain a third attribute |
| \member{filename} which is the file name passed to the |
| function. |
| |
| When exceptions are strings, the string for the exception is |
| \code{'OSError'}. |
| \end{excdesc} |
| |
| It defines the following functions and constants: |
| |
| \begin{funcdesc}{access}{path, mode} |
| Check read/write/execute permissions for this process or extance of file |
| \var{path}. Return \code{1} if access is granted, \code{0} if not. |
| See the \UNIX{} manual for the semantics. |
| \end{funcdesc} |
| |
| \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 \function{open()} or |
| \function{pipe()}. To close a ``file object'' returned by the |
| built-in function \function{open()} or by \function{popen()} or |
| \function{fdopen()}, use its \method{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. |
| \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})}. |
| \function{_exit()} should normally only be used in the child process |
| after a \function{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 \function{open()} function. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fork}{} |
| Fork a child process. Return \code{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 \function{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}{} |
| \index{process!group} |
| Return the current process group id. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpid}{} |
| \index{process!id} |
| Return the current process id. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getppid}{} |
| \index{process!id of parent} |
| Return the parent's process id. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getuid}{} |
| \index{user id} |
| Return the current process' user id. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{kill}{pid, sig} |
| \index{process!killing} |
| \index{process!signalling} |
| 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}: \code{0} to set the position |
| relative to the beginning of the file; \code{1} to set it relative to |
| the current position; \code{2} to set it relative to the end of the |
| file. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lstat}{path} |
| Like \function{stat()}, but do not follow symbolic links. (On systems |
| without symbolic links, this is identical to \function{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 \code{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 \function{os.unlink()}). |
| Generally, FIFOs are used as rendezvous between ``client'' and |
| ``server'' type processes: the server opens the FIFO for reading, and |
| the client opens it for writing. Note that \function{mkfifo()} |
| doesn't open the FIFO --- it just creates the rendezvous 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 \code{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{increment} 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 \code{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 \constant{O_RDONLY} and |
| \constant{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 \function{open()}, which returns a ``file |
| object'' with \method{read()} and \method{write()} methods (and many |
| more). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pipe}{} |
| Create a pipe. Return a pair of file descriptors \code{(\var{r}, |
| \var{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 \function{open()} function. The exit status of |
| the command (encoded in the format specified for \function{wait()}) is |
| available as the return value of the \method{close()} method of the file |
| object, except that when the exit status is zero (termination without |
| errors), \code{None} is returned. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{putenv}{varname, value} |
| \index{environment variables!setting} |
| Set the environment variable named \var{varname} to the string |
| \var{value}. Such changes to the environment affect subprocesses |
| started with \function{os.system()}, \function{os.popen()} or |
| \function{os.fork()} and \function{os.execv()}. (Not on all systems.) |
| |
| When \function{putenv()} is |
| supported, assignments to items in \code{os.environ} are automatically |
| translated into corresponding calls to \function{putenv()}; however, |
| calls to \function{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}{ttyname}{fd} |
| Return a string which specifies the terminal device associated with |
| file-descriptor \var{fd}. If \var{fd} is not associated with a terminal |
| device, an exception is raised. |
| \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 \function{open()} or |
| \function{pipe()}. To read a ``file object'' returned by the |
| built-in function \function{open()} or by \function{popen()} or |
| \function{fdopen()}, or \code{sys.stdin}, use its |
| \method{read()} or \method{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 |
| \exception{error}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{remove}{path} |
| Remove the file \var{path}. See \function{rmdir()} below to remove a |
| directory. This is identical to the \function{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 \cfunction{setpgrp()} or \cfunction{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 \cfunction{setpgid()}. See the \UNIX{} manual |
| for the semantics. |
| (Not on MS-DOS.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setsid}{} |
| Calls the system call \cfunction{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 \cfunction{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 \module{stat}\refstmodindex{stat} defines |
| functions and constants that are useful for extracting information |
| from a stat structure. |
| \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 \exception{error}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{system}{command} |
| Execute the command (a string) in a subshell. This is implemented by |
| calling the Standard \C{} function \cfunction{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 \function{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 \function{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 \function{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 \manpage{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 \function{socket.gethostname()}% |
| \withsubitem{(in module socket)}{\ttindex{gethostname()}} |
| or even |
| \code{socket.gethostbyaddr(socket.gethostname())}% |
| \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}. |
| (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, (atime, mtime)} |
| 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 |
| \function{wait()}). The semantics of the call are affected by the |
| value of the integer \var{options}, which should be \code{0} for |
| normal operation. (If the system does not support |
| \function{waitpid()}, this always raises \exception{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 \function{open()} or |
| \function{pipe()}. To write a ``file object'' returned by the |
| built-in function \function{open()} or by \function{popen()} or |
| \function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use |
| its \method{write()} method. |
| \end{funcdesc} |
| |
| \begin{datadesc}{WNOHANG} |
| The option for \function{waitpid()} to avoid hanging if no child |
| process status is available immediately. |
| \end{datadesc} |
| |
| |
| \begin{datadesc}{O_RDONLY} |
| \dataline{O_WRONLY} |
| \dataline{O_RDWR} |
| \dataline{O_NDELAY} |
| \dataline{O_NONBLOCK} |
| \dataline{O_APPEND} |
| \dataline{O_DSYNC} |
| \dataline{O_RSYNC} |
| \dataline{O_SYNC} |
| \dataline{O_NOCTTY} |
| \dataline{O_CREAT} |
| \dataline{O_EXCL} |
| \dataline{O_TRUNC} |
| Options for the \code{flag} argument to the \function{open()} function. |
| These can be bit-wise OR'd together. |
| \end{datadesc} |