| \section{\module{os} --- |
| Miscellaneous operating system interfaces} |
| |
| \declaremodule{standard}{os} |
| \modulesynopsis{Miscellaneous operating system interfaces.} |
| |
| |
| This module provides a more portable way of using operating system |
| dependent functionality than importing a operating system dependent |
| built-in module like \refmodule{posix} or \module{nt}. |
| |
| This module searches for an operating system dependent built-in module like |
| \module{mac} or \refmodule{posix} and exports the same functions and data |
| as found there. The design of all Python's built-in operating system dependent |
| modules is such that as long as the same functionality is available, |
| it uses the same interface; for example, the function |
| \code{os.stat(\var{path})} returns stat information about \var{path} in |
| the same format (which happens to have originated with the |
| \POSIX{} interface). |
| |
| Extensions peculiar to a particular operating system are also |
| available through the \module{os} module, but using them is of course a |
| threat to portability! |
| |
| Note that after the first time \module{os} is imported, there is |
| \emph{no} performance penalty in using functions from \module{os} |
| instead of directly from the operating system dependent built-in module, |
| so there should be \emph{no} reason not to use \module{os}! |
| |
| |
| % Frank Stajano <fstajano@uk.research.att.com> complained that it |
| % wasn't clear that the entries described in the subsections were all |
| % available at the module level (most uses of subsections are |
| % different); I think this is only a problem for the HTML version, |
| % where the relationship may not be as clear. |
| % |
| \ifhtml |
| The \module{os} module contains many functions and data values. |
| The items below and in the following sub-sections are all available |
| directly from the \module{os} module. |
| \fi |
| |
| |
| \begin{excdesc}{error} |
| This exception is raised when a function returns a system-related |
| error (not for illegal argument types or other incidental errors). |
| This is also known as the built-in exception \exception{OSError}. 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 |
| \refmodule{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 (such as \function{chdir()} or |
| \function{unlink()}), the exception instance will contain a third |
| attribute, \member{filename}, which is the file name passed to the |
| function. |
| \end{excdesc} |
| |
| \begin{datadesc}{name} |
| The name of the operating system dependent module imported. The |
| following names have currently been registered: \code{'posix'}, |
| \code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, |
| \code{'java'}, \code{'riscos'}. |
| \end{datadesc} |
| |
| \begin{datadesc}{path} |
| The corresponding operating system dependent standard module for pathname |
| operations, such as \module{posixpath} or \module{macpath}. Thus, |
| given the proper imports, \code{os.path.split(\var{file})} is |
| equivalent to but more portable than |
| \code{posixpath.split(\var{file})}. Note that this is also an |
| importable module: it may be imported directly as |
| \refmodule{os.path}. |
| \end{datadesc} |
| |
| |
| |
| \subsection{Process Parameters \label{os-procinfo}} |
| |
| These functions and data items provide information and operate on the |
| current process and user. |
| |
| \begin{datadesc}{environ} |
| A mapping object representing the string environment. For example, |
| \code{environ['HOME']} is the pathname of your home directory (on some |
| platforms), and is equivalent to \code{getenv("HOME")} in C. |
| |
| If the platform supports the \function{putenv()} function, this |
| mapping may be used to modify the environment as well as query the |
| environment. \function{putenv()} will be called automatically when |
| the mapping is modified. \note{On some platforms, including |
| FreeBSD and Mac OS X, setting \code{environ} may cause memory leaks. |
| Refer to the system documentation for putenv.} |
| |
| If \function{putenv()} is not provided, this mapping may be passed to |
| the appropriate process-creation functions to cause child processes to |
| use a modified environment. |
| \end{datadesc} |
| |
| \begin{funcdescni}{chdir}{path} |
| \funclineni{fchdir}{fd} |
| \funclineni{getcwd}{} |
| These functions are described in ``Files and Directories'' (section |
| \ref{os-file-dir}). |
| \end{funcdescni} |
| |
| \begin{funcdesc}{ctermid}{} |
| Return the filename corresponding to the controlling terminal of the |
| process. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getegid}{} |
| Return the effective group id of the current process. This |
| corresponds to the `set id' bit on the file being executed in the |
| current process. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{geteuid}{} |
| \index{user!effective id} |
| Return the current process' effective user id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getgid}{} |
| \index{process!group} |
| Return the real group id of the current process. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getgroups}{} |
| Return list of supplemental group ids associated with the current |
| process. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getlogin}{} |
| Return the name of the user logged in on the controlling terminal of |
| the process. For most purposes, it is more useful to use the |
| environment variable \envvar{LOGNAME} to find out who the user is, |
| or \code{pwd.getpwuid(os.getuid())[0]} to get the login name |
| of the currently effective user ID. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpgid}{pid} |
| Return the process group id of the process with process id \var{pid}. |
| If \var{pid} is 0, the process group id of the current process is |
| returned. Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpgrp}{} |
| \index{process!group} |
| Return the id of the current process group. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpid}{} |
| \index{process!id} |
| Return the current process id. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getppid}{} |
| \index{process!id of parent} |
| Return the parent's process id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getuid}{} |
| \index{user!id} |
| Return the current process' user id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getenv}{varname\optional{, value}} |
| Return the value of the environment variable \var{varname} if it |
| exists, or \var{value} if it doesn't. \var{value} defaults to |
| \code{None}. |
| Availability: most flavors of \UNIX, Windows. |
| \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{popen()} or |
| \function{fork()} and \function{execv()}. |
| Availability: most flavors of \UNIX, Windows. |
| |
| \note{On some platforms, including FreeBSD and Mac OS X, |
| setting \code{environ} may cause memory leaks. |
| Refer to the system documentation for putenv.} |
| |
| 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}{setegid}{egid} |
| Set the current process's effective group id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{seteuid}{euid} |
| Set the current process's effective user id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setgid}{gid} |
| Set the current process' group id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setgroups}{groups} |
| Set the list of supplemental group ids associated with the current |
| process to \var{groups}. \var{groups} must be a sequence, and each |
| element must be an integer identifying a group. This operation is |
| typical available only to the superuser. |
| Availability: \UNIX. |
| \versionadded{2.2} |
| \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. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call |
| \cfunction{setpgid()} to set the process group id of the process with |
| id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{} |
| manual for the semantics. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setreuid}{ruid, euid} |
| Set the current process's real and effective user ids. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setregid}{rgid, egid} |
| Set the current process's real and effective group ids. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setsid}{} |
| Calls the system call \cfunction{setsid()}. See the \UNIX{} manual |
| for the semantics. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setuid}{uid} |
| \index{user!id, setting} |
| Set the current process' user id. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| % placed in this section since it relates to errno.... a little weak ;-( |
| \begin{funcdesc}{strerror}{code} |
| Return the error message corresponding to the error code in |
| \var{code}. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{umask}{mask} |
| Set the current numeric umask and returns the previous umask. |
| Availability: \UNIX, Windows. |
| \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 |
| \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}} |
| \code{socket.gethostbyaddr(socket.gethostname())}. |
| Availability: recent flavors of \UNIX. |
| \end{funcdesc} |
| |
| |
| |
| \subsection{File Object Creation \label{os-newstreams}} |
| |
| These functions create new file objects. |
| |
| |
| \begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}} |
| Return an open file object connected to the file descriptor \var{fd}. |
| \index{I/O control!buffering} |
| The \var{mode} and \var{bufsize} arguments have the same meaning as |
| the corresponding arguments to the built-in \function{open()} |
| function. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| \versionchanged[When specified, the \var{mode} argument must now start |
| with one of the letters \character{r}, \character{w}, or \character{a}, |
| otherwise a \exception{ValueError} is raised]{2.3} |
| \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. |
| Availability: \UNIX, Windows. |
| |
| \versionchanged[This function worked unreliably under Windows in |
| earlier versions of Python. This was due to the use of the |
| \cfunction{_popen()} function from the libraries provided with |
| Windows. Newer versions of Python do not use the broken |
| implementation from the Windows libraries]{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{tmpfile}{} |
| Return a new file object opened in update mode (\samp{w+b}). The file |
| has no directory entries associated with it and will be automatically |
| deleted once there are no file descriptors for the file. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| |
| For each of these \function{popen()} variants, if \var{bufsize} is |
| specified, it specifies the buffer size for the I/O pipes. |
| \var{mode}, if provided, should be the string \code{'b'} or |
| \code{'t'}; on Windows this is needed to determine whether the file |
| objects should be opened in binary or text mode. The default value |
| for \var{mode} is \code{'t'}. |
| |
| These methods do not make it possible to retrieve the return code from |
| the child processes. The only way to control the input and output |
| streams and also retrieve the return codes is to use the |
| \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2} |
| module; these are only available on \UNIX. |
| |
| For a discussion of possible deadlock conditions related to the use |
| of these functions, see ``\ulink{Flow Control |
| Issues}{popen2-flow-control.html}'' |
| (section~\ref{popen2-flow-control}). |
| |
| \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}} |
| Executes \var{cmd} as a sub-process. Returns the file objects |
| \code{(\var{child_stdin}, \var{child_stdout})}. |
| Availability: \UNIX, Windows. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}} |
| Executes \var{cmd} as a sub-process. Returns the file objects |
| \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}. |
| Availability: \UNIX, Windows. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}} |
| Executes \var{cmd} as a sub-process. Returns the file objects |
| \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}. |
| Availability: \UNIX, Windows. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| This functionality is also available in the \refmodule{popen2} module |
| using functions of the same names, but the return values of those |
| functions have a different order. |
| |
| |
| \subsection{File Descriptor Operations \label{os-fd-ops}} |
| |
| These functions operate on I/O streams referred to |
| using file descriptors. |
| |
| |
| \begin{funcdesc}{close}{fd} |
| Close file descriptor \var{fd}. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| 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}. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{dup2}{fd, fd2} |
| Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter |
| first if necessary. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fdatasync}{fd} |
| Force write of file with filedescriptor \var{fd} to disk. |
| Does not force update of metadata. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fpathconf}{fd, name} |
| Return system configuration information relevant to an open file. |
| \var{name} specifies the configuration value to retrieve; it may be a |
| string which is the name of a defined system value; these names are |
| specified in a number of standards (\POSIX.1, \UNIX 95, \UNIX 98, and |
| others). Some platforms define additional names as well. The names |
| known to the host operating system are given in the |
| \code{pathconf_names} dictionary. For configuration variables not |
| included in that mapping, passing an integer for \var{name} is also |
| accepted. |
| Availability: \UNIX. |
| |
| If \var{name} is a string and is not known, \exception{ValueError} is |
| raised. If a specific value for \var{name} is not supported by the |
| host system, even if it is included in \code{pathconf_names}, an |
| \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| error number. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fstat}{fd} |
| Return status for file descriptor \var{fd}, like \function{stat()}. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fstatvfs}{fd} |
| Return information about the filesystem containing the file associated |
| with file descriptor \var{fd}, like \function{statvfs()}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fsync}{fd} |
| Force write of file with filedescriptor \var{fd} to disk. On \UNIX, |
| this calls the native \cfunction{fsync()} function; on Windows, the |
| MS \cfunction{_commit()} function. |
| |
| If you're starting with a Python file object \var{f}, first do |
| \code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())}, |
| to ensure that all internal buffers associated with \var{f} are written |
| to disk. |
| Availability: \UNIX, and Windows starting in 2.2.3. |
| \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. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{isatty}{fd} |
| Return \code{True} if the file descriptor \var{fd} is open and |
| connected to a tty(-like) device, else \code{False}. |
| Availability: \UNIX. |
| \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. |
| Availability: Macintosh, \UNIX, Windows. |
| \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. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| For a description of the flag and mode values, see the 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}{openpty}{} |
| Open a new pseudo-terminal pair. Return a pair of file descriptors |
| \code{(\var{master}, \var{slave})} for the pty and the tty, |
| respectively. For a (slightly) more portable approach, use the |
| \refmodule{pty}\refstmodindex{pty} module. |
| Availability: Some flavors of \UNIX. |
| \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. |
| Availability: \UNIX, Windows. |
| \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. If the end of the file |
| referred to by \var{fd} has been reached, an empty string is |
| returned. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| 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}{tcgetpgrp}{fd} |
| Return the process group associated with the terminal given by |
| \var{fd} (an open file descriptor as returned by \function{open()}). |
| Availability: \UNIX. |
| \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}. |
| Availability: \UNIX. |
| \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. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{write}{fd, str} |
| Write the string \var{str} to file descriptor \var{fd}. |
| Return the number of bytes actually written. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| 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} |
| |
| |
| The following data items are available for use in constructing the |
| \var{flags} parameter to the \function{open()} function. |
| |
| \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 \var{flag} argument to the \function{open()} function. |
| These can be bit-wise OR'd together. |
| Availability: Macintosh, \UNIX, Windows. |
| % XXX O_NDELAY, O_NONBLOCK, O_DSYNC, O_RSYNC, O_SYNC, O_NOCTTY are not on Windows. |
| \end{datadesc} |
| |
| \begin{datadesc}{O_BINARY} |
| Option for the \var{flag} argument to the \function{open()} function. |
| This can be bit-wise OR'd together with those listed above. |
| Availability: Macintosh, Windows. |
| % XXX need to check on the availability of this one. |
| \end{datadesc} |
| |
| \begin{datadesc}{O_NOINHERIT} |
| \dataline{O_SHORT_LIVED} |
| \dataline{O_TEMPORARY} |
| \dataline{O_RANDOM} |
| \dataline{O_SEQUENTIAL} |
| \dataline{O_TEXT} |
| Options for the \var{flag} argument to the \function{open()} function. |
| These can be bit-wise OR'd together. |
| Availability: Windows. |
| \end{datadesc} |
| |
| \subsection{Files and Directories \label{os-file-dir}} |
| |
| \begin{funcdesc}{access}{path, mode} |
| Use the real uid/gid to test for access to \var{path}. Note that most |
| operations will use the effective uid/gid, therefore this routine can |
| be used in a suid/sgid environment to test if the invoking user has the |
| specified access to \var{path}. \var{mode} should be \constant{F_OK} |
| to test the existence of \var{path}, or it can be the inclusive OR of |
| one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to |
| test permissions. Return \code{1} if access is allowed, \code{0} if not. |
| See the \UNIX{} man page \manpage{access}{2} for more information. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{datadesc}{F_OK} |
| Value to pass as the \var{mode} parameter of \function{access()} to |
| test the existence of \var{path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{R_OK} |
| Value to include in the \var{mode} parameter of \function{access()} |
| to test the readability of \var{path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{W_OK} |
| Value to include in the \var{mode} parameter of \function{access()} |
| to test the writability of \var{path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{X_OK} |
| Value to include in the \var{mode} parameter of \function{access()} |
| to determine if \var{path} can be executed. |
| \end{datadesc} |
| |
| \begin{funcdesc}{chdir}{path} |
| \index{directory!changing} |
| Change the current working directory to \var{path}. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fchdir}{fd} |
| Change the current working directory to the directory represented by |
| the file descriptor \var{fd}. The descriptor must refer to an opened |
| directory, not an open file. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getcwd}{} |
| Return a string representing the current working directory. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getcwdu}{} |
| Return a Unicode object representing the current working directory. |
| Availability: \UNIX, Windows. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{chroot}{path} |
| Change the root directory of the current process to \var{path}. |
| Availability: \UNIX. |
| \versionadded{2.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{chmod}{path, mode} |
| Change the mode of \var{path} to the numeric \var{mode}. |
| \var{mode} may take one of the following values: |
| \begin{itemize} |
| \item \code{S_ISUID} |
| \item \code{S_ISGID} |
| \item \code{S_ENFMT} |
| \item \code{S_ISVTX} |
| \item \code{S_IREAD} |
| \item \code{S_IWRITE} |
| \item \code{S_IEXEC} |
| \item \code{S_IRWXU} |
| \item \code{S_IRUSR} |
| \item \code{S_IWUSR} |
| \item \code{S_IXUSR} |
| \item \code{S_IRWXG} |
| \item \code{S_IRGRP} |
| \item \code{S_IWGRP} |
| \item \code{S_IXGRP} |
| \item \code{S_IRWXO} |
| \item \code{S_IROTH} |
| \item \code{S_IWOTH} |
| \item \code{S_IXOTH} |
| \end{itemize} |
| Availability: \UNIX, Windows. |
| \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}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lchown}{path, uid, gid} |
| Change the owner and group id of \var{path} to the numeric \var{uid} |
| and gid. This function will not follow symbolic links. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{link}{src, dst} |
| Create a hard link pointing to \var{src} named \var{dst}. |
| Availability: \UNIX. |
| \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. |
| Availability: Macintosh, \UNIX, Windows. |
| |
| \versionchanged[On Windows NT/2k/XP and Unix, if \var{path} is a Unicode |
| object, the result will be a list of Unicode objects.]{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lstat}{path} |
| Like \function{stat()}, but do not follow symbolic links. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mkfifo}{path\optional{, mode}} |
| Create a FIFO (a 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. |
| Availability: \UNIX. |
| |
| 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}{mknod}{path\optional{, mode=0600, device}} |
| Create a filesystem node (file, device special file or named pipe) |
| named filename. \var{mode} specifies both the permissions to use and |
| the type of node to be created, being combined (bitwise OR) with one |
| of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are |
| available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device} |
| defines the newly created device special file (probably using |
| \function{os.makedev()}), otherwise it is ignored. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{major}{device} |
| Extracts a device major number from a raw device number. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{minor}{device} |
| Extracts a device minor number from a raw device number. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{makedev}{major, minor} |
| Composes a raw device number from the major and minor device numbers. |
| \versionadded{2.3} |
| \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. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{makedirs}{path\optional{, mode}} |
| Recursive directory creation function.\index{directory!creating} |
| \index{UNC paths!and \function{os.makedirs()}} |
| Like \function{mkdir()}, |
| but makes all intermediate-level directories needed to contain the |
| leaf directory. Throws an \exception{error} exception if the leaf |
| directory already exists or cannot be created. The default \var{mode} |
| is \code{0777} (octal). This function does not properly handle UNC |
| paths (only relevant on Windows systems; Universal Naming Convention |
| paths are those that use the `\code{\e\e host\e path}' syntax). |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pathconf}{path, name} |
| Return system configuration information relevant to a named file. |
| \var{name} specifies the configuration value to retrieve; it may be a |
| string which is the name of a defined system value; these names are |
| specified in a number of standards (\POSIX.1, \UNIX 95, \UNIX 98, and |
| others). Some platforms define additional names as well. The names |
| known to the host operating system are given in the |
| \code{pathconf_names} dictionary. For configuration variables not |
| included in that mapping, passing an integer for \var{name} is also |
| accepted. |
| Availability: \UNIX. |
| |
| If \var{name} is a string and is not known, \exception{ValueError} is |
| raised. If a specific value for \var{name} is not supported by the |
| host system, even if it is included in \code{pathconf_names}, an |
| \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| error number. |
| \end{funcdesc} |
| |
| \begin{datadesc}{pathconf_names} |
| Dictionary mapping names accepted by \function{pathconf()} and |
| \function{fpathconf()} to the integer values defined for those names |
| by the host operating system. This can be used to determine the set |
| of names known to the system. |
| Availability: \UNIX. |
| \end{datadesc} |
| |
| \begin{funcdesc}{readlink}{path} |
| Return a string representing the path to which the symbolic link |
| points. The result may be either an absolute or relative pathname; if |
| it is relative, it may be converted to an absolute pathname using |
| \code{os.path.join(os.path.dirname(\var{path}), \var{result})}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{remove}{path} |
| Remove the file \var{path}. If \var{path} is a directory, |
| \exception{OSError} is raised; see \function{rmdir()} below to remove |
| a directory. This is identical to the \function{unlink()} function |
| documented below. On Windows, attempting to remove a file that is in |
| use causes an exception to be raised; on \UNIX, the directory entry is |
| removed but the storage allocated to the file is not made available |
| until the original file is no longer in use. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{removedirs}{path} |
| \index{directory!deleting} |
| Removes directories recursively. Works like |
| \function{rmdir()} except that, if the leaf directory is |
| successfully removed, directories corresponding to rightmost path |
| segments will be pruned way until either the whole path is consumed or |
| an error is raised (which is ignored, because it generally means that |
| a parent directory is not empty). Throws an \exception{error} |
| exception if the leaf directory could not be successfully removed. |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rename}{src, dst} |
| Rename the file or directory \var{src} to \var{dst}. If \var{dst} is |
| a directory, \exception{OSError} will be raised. On \UNIX, if |
| \var{dst} exists and is a file, it will be removed silently if the |
| user has permission. The operation may fail on some \UNIX{} flavors |
| if \var{src} and \var{dst} are on different filesystems. If |
| successful, the renaming will be an atomic operation (this is a |
| \POSIX{} requirement). On Windows, if \var{dst} already exists, |
| \exception{OSError} will be raised even if it is a file; there may be |
| no way to implement an atomic rename when \var{dst} names an existing |
| file. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{renames}{old, new} |
| Recursive directory or file renaming function. |
| Works like \function{rename()}, except creation of any intermediate |
| directories needed to make the new pathname good is attempted first. |
| After the rename, directories corresponding to rightmost path segments |
| of the old name will be pruned away using \function{removedirs()}. |
| |
| Note: this function can fail with the new directory structure made if |
| you lack permissions needed to remove the leaf directory or file. |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rmdir}{path} |
| Remove the directory \var{path}. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{stat}{path} |
| Perform a \cfunction{stat()} system call on the given path. The |
| return value is an object whose attributes correspond to the members of |
| the \ctype{stat} structure, namely: |
| \member{st_mode} (protection bits), |
| \member{st_ino} (inode number), |
| \member{st_dev} (device), |
| \member{st_nlink} (number of hard links), |
| \member{st_uid} (user ID of owner), |
| \member{st_gid} (group ID of owner), |
| \member{st_size} (size of file, in bytes), |
| \member{st_atime} (time of most recent access), |
| \member{st_mtime} (time of most recent content modification), |
| \member{st_ctime} |
| (time of most recent content modification or metadata change). |
| |
| \versionchanged [If \function{stat_float_times} returns true, the time |
| values are floats, measuring seconds. Fractions of a second may be |
| reported if the system supports that. On Mac OS, the times are always |
| floats. See \function{stat_float_times} for further discussion. ]{2.3} |
| |
| On some Unix systems (such as Linux), the following attributes may |
| also be available: |
| \member{st_blocks} (number of blocks allocated for file), |
| \member{st_blksize} (filesystem blocksize), |
| \member{st_rdev} (type of device if an inode device). |
| |
| On Mac OS systems, the following attributes may also be available: |
| \member{st_rsize}, |
| \member{st_creator}, |
| \member{st_type}. |
| |
| On RISCOS systems, the following attributes are also available: |
| \member{st_ftype} (file type), |
| \member{st_attrs} (attributes), |
| \member{st_obtype} (object type). |
| |
| For backward compatibility, the return value of \function{stat()} is |
| also accessible as a tuple of at least 10 integers giving the most |
| important (and portable) members of the \ctype{stat} structure, in the |
| order |
| \member{st_mode}, |
| \member{st_ino}, |
| \member{st_dev}, |
| \member{st_nlink}, |
| \member{st_uid}, |
| \member{st_gid}, |
| \member{st_size}, |
| \member{st_atime}, |
| \member{st_mtime}, |
| \member{st_ctime}. |
| More items may be added at the end by some implementations. |
| The standard module \refmodule{stat}\refstmodindex{stat} defines |
| functions and constants that are useful for extracting information |
| from a \ctype{stat} structure. |
| (On Windows, some items are filled with dummy values.) |
| Availability: Macintosh, \UNIX, Windows. |
| |
| \versionchanged |
| [Added access to values as attributes of the returned object]{2.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{stat_float_times}{\optional{newvalue}} |
| Determine whether \class{stat_result} represents time stamps as float |
| objects. If newval is True, future calls to stat() return floats, if |
| it is False, future calls return ints. If newval is omitted, return |
| the current setting. |
| |
| For compatibility with older Python versions, accessing |
| \class{stat_result} as a tuple always returns integers. For |
| compatibility with Python 2.2, accessing the time stamps by field name |
| also returns integers. Applications that want to determine the |
| fractions of a second in a time stamp can use this function to have |
| time stamps represented as floats. Whether they will actually observe |
| non-zero fractions depends on the system. |
| |
| Future Python releases will change the default of this setting; |
| applications that cannot deal with floating point time stamps can then |
| use this function to turn the feature off. |
| |
| It is recommended that this setting is only changed at program startup |
| time in the \var{__main__} module; libraries should never change this |
| setting. If an application uses a library that works incorrectly if |
| floating point time stamps are processed, this application should turn |
| the feature off until the library has been corrected. |
| |
| \end{funcdesc} |
| |
| \begin{funcdesc}{statvfs}{path} |
| Perform a \cfunction{statvfs()} system call on the given path. The |
| return value is an object whose attributes describe the filesystem on |
| the given path, and correspond to the members of the |
| \ctype{statvfs} structure, namely: |
| \member{f_frsize}, |
| \member{f_blocks}, |
| \member{f_bfree}, |
| \member{f_bavail}, |
| \member{f_files}, |
| \member{f_ffree}, |
| \member{f_favail}, |
| \member{f_flag}, |
| \member{f_namemax}. |
| Availability: \UNIX. |
| |
| For backward compatibility, the return value is also accessible as a |
| tuple whose values correspond to the attributes, in the order given above. |
| The standard module \refmodule{statvfs}\refstmodindex{statvfs} |
| defines constants that are useful for extracting information |
| from a \ctype{statvfs} structure when accessing it as a sequence; this |
| remains useful when writing code that needs to work with versions of |
| Python that don't support accessing the fields as attributes. |
| |
| \versionchanged |
| [Added access to values as attributes of the returned object]{2.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{symlink}{src, dst} |
| Create a symbolic link pointing to \var{src} named \var{dst}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}} |
| Return a unique path name that is reasonable for creating a temporary |
| file. This will be an absolute path that names a potential directory |
| entry in the directory \var{dir} or a common location for temporary |
| files if \var{dir} is omitted or \code{None}. If given and not |
| \code{None}, \var{prefix} is used to provide a short prefix to the |
| filename. Applications are responsible for properly creating and |
| managing files created using paths returned by \function{tempnam()}; |
| no automatic cleanup is provided. |
| On \UNIX, the environment variable \envvar{TMPDIR} overrides |
| \var{dir}, while on Windows the \envvar{TMP} is used. The specific |
| behavior of this function depends on the C library implementation; |
| some aspects are underspecified in system documentation. |
| \warning{Use of \function{tempnam()} is vulnerable to symlink attacks; |
| consider using \function{tmpfile()} instead.} |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{tmpnam}{} |
| Return a unique path name that is reasonable for creating a temporary |
| file. This will be an absolute path that names a potential directory |
| entry in a common location for temporary files. Applications are |
| responsible for properly creating and managing files created using |
| paths returned by \function{tmpnam()}; no automatic cleanup is |
| provided. |
| \warning{Use of \function{tmpnam()} is vulnerable to symlink attacks; |
| consider using \function{tmpfile()} instead.} |
| Availability: \UNIX, Windows. This function probably shouldn't be used |
| on Windows, though: Microsoft's implementation of \function{tmpnam()} |
| always creates a name in the root directory of the current drive, and |
| that's generally a poor location for a temp file (depending on |
| privileges, you may not even be able to open a file using this name). |
| \end{funcdesc} |
| |
| \begin{datadesc}{TMP_MAX} |
| The maximum number of unique names that \function{tmpnam()} will |
| generate before reusing names. |
| \end{datadesc} |
| |
| \begin{funcdesc}{unlink}{path} |
| Remove the file \var{path}. This is the same function as |
| \function{remove()}; the \function{unlink()} name is its traditional |
| \UNIX{} name. |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{utime}{path, times} |
| Set the access and modified times of the file specified by \var{path}. |
| If \var{times} is \code{None}, then the file's access and modified |
| times are set to the current time. Otherwise, \var{times} must be a |
| 2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})} |
| which is used to set the access and modified times, respectively. |
| \versionchanged[Added support for \code{None} for \var{times}]{2.0} |
| Availability: Macintosh, \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{walk}{top\optional{, topdown\code{=True}}} |
| \index{directory!walking} |
| \index{directory!traversal} |
| \function{walk()} generates the file names in a directory tree, by |
| walking the tree either top down or bottom up. |
| For each directory in the tree rooted at directory \var{top} (including |
| \var{top} itself), it yields a 3-tuple |
| \code{(\var{dirpath}, \var{dirnames}, \var{filenames})}. |
| |
| \var{dirpath} is a string, the path to the directory. \var{dirnames} is |
| a list of the names of the subdirectories in \var{dirpath} |
| (excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of |
| the names of the non-directory files in \var{dirpath}. Note that the |
| names in the lists contain no path components. To get a full |
| path (which begins with \var{top}) to a file or directory in |
| \var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}. |
| |
| If optional argument \var{topdown} is true or not specified, the triple |
| for a directory is generated before the triples for any of its |
| subdirectories (directories are generated top down). If \var{topdown} is |
| false, the triple for a directory is generated after the triples for all |
| of its subdirectories (directories are generated bottom up). |
| |
| When \var{topdown} is true, the caller can modify the \var{dirnames} list |
| in-place (e.g., via \keyword{del} or slice assignment), and |
| \function{walk()} will only recurse into the subdirectories whose names |
| remain in \var{dirnames}; this can be used to prune the search, |
| impose a specific order of visiting, or even to inform \function{walk()} |
| about directories the caller creates or renames before it resumes |
| \function{walk()} again. Modifying \var{dirnames} when \var{topdown} is |
| false is ineffective, because in bottom-up mode the directories in |
| \var{dirnames} are generated before \var{dirnames} itself is generated. |
| |
| \begin{notice} |
| If you pass a relative pathname, don't change the current working |
| directory between resumptions of \function{walk()}. \function{walk()} |
| never changes the current directory, and assumes that its caller |
| doesn't either. |
| \end{notice} |
| |
| \begin{notice} |
| On systems that support symbolic links, links to subdirectories appear |
| in \var{dirnames} lists, but \function{walk()} will not visit them |
| (infinite loops are hard to avoid when following symbolic links). |
| To visit linked directories, you can identify them with |
| \code{os.path.islink(\var{path})}, and invoke \code{walk(\var{path})} |
| on each directly. |
| \end{notice} |
| |
| This example displays the number of bytes taken by non-directory files |
| in each directory under the starting directory, except that it doesn't |
| look under any CVS subdirectory: |
| |
| \begin{verbatim} |
| import os |
| from os.path import join, getsize |
| for root, dirs, files in os.walk('python/Lib/email'): |
| print root, "consumes", |
| print sum([getsize(join(root, name)) for name in files]), |
| print "bytes in", len(files), "non-directory files" |
| if 'CVS' in dirs: |
| dirs.remove('CVS') # don't visit CVS directories |
| \end{verbatim} |
| |
| In the next example, walking the tree bottom up is essential: |
| \function{rmdir()} doesn't allow deleting a directory before the |
| directory is empty: |
| |
| \begin{verbatim} |
| import os |
| from os.path import join |
| # Delete everything reachable from the directory named in 'top'. |
| # CAUTION: This is dangerous! For example, if top == '/', it |
| # could delete all your disk files. |
| for root, dirs, files in os.walk(top, topdown=False): |
| for name in files: |
| os.remove(join(root, name)) |
| for name in dirs: |
| os.rmdir(join(root, name)) |
| \end{verbatim} |
| |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \subsection{Process Management \label{os-process}} |
| |
| These functions may be used to create and manage processes. |
| |
| The various \function{exec*()} functions take a list of arguments for |
| the new program loaded into the process. In each case, the first of |
| these arguments is passed to the new program as its own name rather |
| than as an argument a user may have typed on a command line. For the |
| C programmer, this is the \code{argv[0]} passed to a program's |
| \cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo', |
| 'bar'])} will only print \samp{bar} on standard output; \samp{foo} |
| will seem to be ignored. |
| |
| |
| \begin{funcdesc}{abort}{} |
| Generate a \constant{SIGABRT} signal to the current process. On |
| \UNIX, the default behavior is to produce a core dump; on Windows, the |
| process immediately returns an exit code of \code{3}. Be aware that |
| programs which use \function{signal.signal()} to register a handler |
| for \constant{SIGABRT} will behave differently. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{execl}{path, arg0, arg1, \moreargs} |
| \funcline{execle}{path, arg0, arg1, \moreargs, env} |
| \funcline{execlp}{file, arg0, arg1, \moreargs} |
| \funcline{execlpe}{file, arg0, arg1, \moreargs, env} |
| \funcline{execv}{path, args} |
| \funcline{execve}{path, args, env} |
| \funcline{execvp}{file, args} |
| \funcline{execvpe}{file, args, env} |
| These functions all execute a new program, replacing the current |
| process; they do not return. On \UNIX, the new executable is loaded |
| into the current process, and will have the same process ID as the |
| caller. Errors will be reported as \exception{OSError} exceptions. |
| |
| The \character{l} and \character{v} variants of the |
| \function{exec*()} functions differ in how command-line arguments are |
| passed. The \character{l} variants are perhaps the easiest to work |
| with if the number of parameters is fixed when the code is written; |
| the individual parameters simply become additional parameters to the |
| \function{execl*()} functions. The \character{v} variants are good |
| when the number of parameters is variable, with the arguments being |
| passed in a list or tuple as the \var{args} parameter. In either |
| case, the arguments to the child process must start with the name of |
| the command being run. |
| |
| The variants which include a \character{p} near the end |
| (\function{execlp()}, \function{execlpe()}, \function{execvp()}, |
| and \function{execvpe()}) will use the \envvar{PATH} environment |
| variable to locate the program \var{file}. When the environment is |
| being replaced (using one of the \function{exec*e()} variants, |
| discussed in the next paragraph), the |
| new environment is used as the source of the \envvar{PATH} variable. |
| The other variants, \function{execl()}, \function{execle()}, |
| \function{execv()}, and \function{execve()}, will not use the |
| \envvar{PATH} variable to locate the executable; \var{path} must |
| contain an appropriate absolute or relative path. |
| |
| For \function{execle()}, \function{execlpe()}, \function{execve()}, |
| and \function{execvpe()} (note that these all end in \character{e}), |
| the \var{env} parameter must be a mapping which is used to define the |
| environment variables for the new process; the \function{execl()}, |
| \function{execlp()}, \function{execv()}, and \function{execvp()} |
| all cause the new process to inherit the environment of the current |
| process. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{_exit}{n} |
| Exit to the system with status \var{n}, without calling cleanup |
| handlers, flushing stdio buffers, etc. |
| Availability: \UNIX, Windows. |
| |
| 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} |
| |
| The following exit codes are a defined, and can be used with |
| \function{_exit()}, although they are not required. These are |
| typically used for system programs written in Python, such as a |
| mail server's external command delivery program. |
| |
| \begin{datadesc}{EX_OK} |
| Exit code that means no error occurred. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_USAGE} |
| Exit code that means the command was used incorrectly, such as when |
| the wrong number of arguments are given. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_DATAERR} |
| Exit code that means the input data was incorrect. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_NOINPUT} |
| Exit code that means an input file did not exist or was not readable. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_NOUSER} |
| Exit code that means a specified user did not exist. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_NOHOST} |
| Exit code that means a specified host did not exist. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_UNAVAILABLE} |
| Exit code that means that a required service is unavailable. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_SOFTWARE} |
| Exit code that means an internal software error was detected. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_OSERR} |
| Exit code that means an operating system error was detected, such as |
| the inability to fork or create a pipe. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_OSFILE} |
| Exit code that means some system file did not exist, could not be |
| opened, or had some other kind of error. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_CANTCREAT} |
| Exit code that means a user specified output file could not be created. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_IOERR} |
| Exit code that means that an error occurred while doing I/O on some file. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_TEMPFAIL} |
| Exit code that means a temporary failure occurred. This indicates |
| something that may not really be an error, such as a network |
| connection that couldn't be made during a retryable operation. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_PROTOCOL} |
| Exit code that means that a protocol exchange was illegal, invalid, or |
| not understood. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_NOPERM} |
| Exit code that means that there were insufficient permissions to |
| perform the operation (but not intended for file system problems). |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_CONFIG} |
| Exit code that means that some kind of configuration error occurred. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{EX_NOTFOUND} |
| Exit code that means something like ``an entry was not found''. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{funcdesc}{fork}{} |
| Fork a child process. Return \code{0} in the child, the child's |
| process id in the parent. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{forkpty}{} |
| Fork a child process, using a new pseudo-terminal as the child's |
| controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})}, |
| where \var{pid} is \code{0} in the child, the new child's process id |
| in the parent, and \var{fd} is the file descriptor of the master end |
| of the pseudo-terminal. For a more portable approach, use the |
| \refmodule{pty} module. |
| Availability: Some flavors of \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{kill}{pid, sig} |
| \index{process!killing} |
| \index{process!signalling} |
| Kill the process \var{pid} with signal \var{sig}. Constants for the |
| specific signals available on the host platform are defined in the |
| \refmodule{signal} module. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{killpg}{pgid, sig} |
| \index{process!killing} |
| \index{process!signalling} |
| Kill the process group \var{pgid} with the signal \var{sig}. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{nice}{increment} |
| Add \var{increment} to the process's ``niceness''. Return the new |
| niceness. |
| Availability: \UNIX. |
| \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. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdescni}{popen}{\unspecified} |
| \funclineni{popen2}{\unspecified} |
| \funclineni{popen3}{\unspecified} |
| \funclineni{popen4}{\unspecified} |
| Run child processes, returning opened pipes for communications. These |
| functions are described in section \ref{os-newstreams}. |
| \end{funcdescni} |
| |
| \begin{funcdesc}{spawnl}{mode, path, \moreargs} |
| \funcline{spawnle}{mode, path, \moreargs, env} |
| \funcline{spawnlp}{mode, file, \moreargs} |
| \funcline{spawnlpe}{mode, file, \moreargs, env} |
| \funcline{spawnv}{mode, path, args} |
| \funcline{spawnve}{mode, path, args, env} |
| \funcline{spawnvp}{mode, file, args} |
| \funcline{spawnvpe}{mode, file, args, env} |
| Execute the program \var{path} in a new process. If \var{mode} is |
| \constant{P_NOWAIT}, this function returns the process ID of the new |
| process; if \var{mode} is \constant{P_WAIT}, returns the process's |
| exit code if it exits normally, or \code{-\var{signal}}, where |
| \var{signal} is the signal that killed the process. On Windows, the |
| process ID will actually be the process handle, so can be used with |
| the \function{waitpid()} function. |
| |
| The \character{l} and \character{v} variants of the |
| \function{spawn*()} functions differ in how command-line arguments are |
| passed. The \character{l} variants are perhaps the easiest to work |
| with if the number of parameters is fixed when the code is written; |
| the individual parameters simply become additional parameters to the |
| \function{spawnl*()} functions. The \character{v} variants are good |
| when the number of parameters is variable, with the arguments being |
| passed in a list or tuple as the \var{args} parameter. In either |
| case, the arguments to the child process must start with the name of |
| the command being run. |
| |
| The variants which include a second \character{p} near the end |
| (\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()}, |
| and \function{spawnvpe()}) will use the \envvar{PATH} environment |
| variable to locate the program \var{file}. When the environment is |
| being replaced (using one of the \function{spawn*e()} variants, |
| discussed in the next paragraph), the new environment is used as the |
| source of the \envvar{PATH} variable. The other variants, |
| \function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and |
| \function{spawnve()}, will not use the \envvar{PATH} variable to |
| locate the executable; \var{path} must contain an appropriate absolute |
| or relative path. |
| |
| For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()}, |
| and \function{spawnvpe()} (note that these all end in \character{e}), |
| the \var{env} parameter must be a mapping which is used to define the |
| environment variables for the new process; the \function{spawnl()}, |
| \function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()} |
| all cause the new process to inherit the environment of the current |
| process. |
| |
| As an example, the following calls to \function{spawnlp()} and |
| \function{spawnvpe()} are equivalent: |
| |
| \begin{verbatim} |
| import os |
| os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') |
| |
| L = ['cp', 'index.html', '/dev/null'] |
| os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) |
| \end{verbatim} |
| |
| Availability: \UNIX, Windows. \function{spawnlp()}, |
| \function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()} |
| are not available on Windows. |
| \versionadded{1.6} |
| \end{funcdesc} |
| |
| \begin{datadesc}{P_NOWAIT} |
| \dataline{P_NOWAITO} |
| Possible values for the \var{mode} parameter to the \function{spawn*()} |
| family of functions. If either of these values is given, the |
| \function{spawn*()} functions will return as soon as the new process |
| has been created, with the process ID as the return value. |
| Availability: \UNIX, Windows. |
| \versionadded{1.6} |
| \end{datadesc} |
| |
| \begin{datadesc}{P_WAIT} |
| Possible value for the \var{mode} parameter to the \function{spawn*()} |
| family of functions. If this is given as \var{mode}, the |
| \function{spawn*()} functions will not return until the new process |
| has run to completion and will return the exit code of the process the |
| run is successful, or \code{-\var{signal}} if a signal kills the |
| process. |
| Availability: \UNIX, Windows. |
| \versionadded{1.6} |
| \end{datadesc} |
| |
| \begin{datadesc}{P_DETACH} |
| \dataline{P_OVERLAY} |
| Possible values for the \var{mode} parameter to the |
| \function{spawn*()} family of functions. These are less portable than |
| those listed above. |
| \constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new |
| process is detached from the console of the calling process. |
| If \constant{P_OVERLAY} is used, the current process will be replaced; |
| the \function{spawn*()} function will not return. |
| Availability: Windows. |
| \versionadded{1.6} |
| \end{datadesc} |
| |
| \begin{funcdesc}{startfile}{path} |
| Start a file with its associated application. This acts like |
| double-clicking the file in Windows Explorer, or giving the file name |
| as an argument to the \program{start} command from the interactive |
| command shell: the file is opened with whatever application (if any) |
| its extension is associated. |
| |
| \function{startfile()} returns as soon as the associated application |
| is launched. There is no option to wait for the application to close, |
| and no way to retrieve the application's exit status. The \var{path} |
| parameter is relative to the current directory. If you want to use an |
| absolute path, make sure the first character is not a slash |
| (\character{/}); the underlying Win32 \cfunction{ShellExecute()} |
| function doesn't work if it is. Use the \function{os.path.normpath()} |
| function to ensure that the path is properly encoded for Win32. |
| Availability: Windows. |
| \versionadded{2.0} |
| \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()}, except on Windows 95 and 98, |
| where it is always \code{0}. Note that \POSIX{} does not specify the |
| meaning of the return value of the C \cfunction{system()} function, |
| so the return value of the Python function is system-dependent. |
| Availability: \UNIX, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{times}{} |
| Return a 5-tuple of floating point numbers indicating accumulated |
| (processor 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} or the corresponding Windows Platform API |
| documentation. |
| Availability: \UNIX, Windows. |
| \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. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{waitpid}{pid, options} |
| The details of this function differ on \UNIX{} and Windows. |
| |
| On \UNIX: |
| Wait for completion of a child process given by process id \var{pid}, |
| and return a tuple containing its process id 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 \var{pid} is greater than \code{0}, \function{waitpid()} requests |
| status information for that specific process. If \var{pid} is |
| \code{0}, the request is for the status of any child in the process |
| group of the current process. If \var{pid} is \code{-1}, the request |
| pertains to any child of the current process. If \var{pid} is less |
| than \code{-1}, status is requested for any process in the process |
| group \code{-\var{pid}} (the absolute value of \var{pid}). |
| |
| On Windows: |
| Wait for completion of a process given by process handle \var{pid}, |
| and return a tuple containing \var{pid}, |
| and its exit status shifted left by 8 bits (shifting makes cross-platform |
| use of the function easier). |
| A \var{pid} less than or equal to \code{0} has no special meaning on |
| Windows, and raises an exception. |
| The value of integer \var{options} has no effect. |
| \var{pid} can refer to any process whose id is known, not necessarily a |
| child process. |
| The \function{spawn()} functions called with \constant{P_NOWAIT} |
| return suitable process handles. |
| \end{funcdesc} |
| |
| \begin{datadesc}{WNOHANG} |
| The option for \function{waitpid()} to avoid hanging if no child |
| process status is available immediately. |
| Availability: \UNIX. |
| \end{datadesc} |
| |
| \begin{datadesc}{WCONTINUED} |
| This option causes child processes to be reported if they have been |
| continued from a job control stop since their status was last |
| reported. |
| Availability: Some \UNIX{} systems. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{datadesc}{WUNTRACED} |
| This option causes child processes to be reported if they have been |
| stopped but their current state has not been reported since they were |
| stopped. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| The following functions take a process status code as returned by |
| \function{system()}, \function{wait()}, or \function{waitpid()} as a |
| parameter. They may be used to determine the disposition of a |
| process. |
| |
| \begin{funcdesc}{WCOREDUMP}{status} |
| Returns \code{True} if a core dump was generated for the process, |
| otherwise it returns \code{False}. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFCONTINUED}{status} |
| Returns \code{True} if the process has been continued from a job |
| control stop, otherwise it returns \code{False}. |
| Availability: \UNIX. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFSTOPPED}{status} |
| Returns \code{True} if the process has been stopped, otherwise it |
| returns \code{False}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFSIGNALED}{status} |
| Returns \code{True} if the process exited due to a signal, otherwise |
| it returns \code{False}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFEXITED}{status} |
| Returns \code{True} if the process exited using the \manpage{exit}{2} |
| system call, otherwise it returns \code{False}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WEXITSTATUS}{status} |
| If \code{WIFEXITED(\var{status})} is true, return the integer |
| parameter to the \manpage{exit}{2} system call. Otherwise, the return |
| value is meaningless. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WSTOPSIG}{status} |
| Return the signal which caused the process to stop. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WTERMSIG}{status} |
| Return the signal which caused the process to exit. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| |
| \subsection{Miscellaneous System Information \label{os-path}} |
| |
| |
| \begin{funcdesc}{confstr}{name} |
| Return string-valued system configuration values. |
| \var{name} specifies the configuration value to retrieve; it may be a |
| string which is the name of a defined system value; these names are |
| specified in a number of standards (\POSIX, \UNIX 95, \UNIX 98, and |
| others). Some platforms define additional names as well. The names |
| known to the host operating system are given in the |
| \code{confstr_names} dictionary. For configuration variables not |
| included in that mapping, passing an integer for \var{name} is also |
| accepted. |
| Availability: \UNIX. |
| |
| If the configuration value specified by \var{name} isn't defined, the |
| empty string is returned. |
| |
| If \var{name} is a string and is not known, \exception{ValueError} is |
| raised. If a specific value for \var{name} is not supported by the |
| host system, even if it is included in \code{confstr_names}, an |
| \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| error number. |
| \end{funcdesc} |
| |
| \begin{datadesc}{confstr_names} |
| Dictionary mapping names accepted by \function{confstr()} to the |
| integer values defined for those names by the host operating system. |
| This can be used to determine the set of names known to the system. |
| Availability: \UNIX. |
| \end{datadesc} |
| |
| \begin{funcdesc}{getloadavg}{} |
| Return the number of processes in the system run queue averaged over |
| the last 1, 5, and 15 minutes or raises OSError if the load average |
| was unobtainable. |
| |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{sysconf}{name} |
| Return integer-valued system configuration values. |
| If the configuration value specified by \var{name} isn't defined, |
| \code{-1} is returned. The comments regarding the \var{name} |
| parameter for \function{confstr()} apply here as well; the dictionary |
| that provides information on the known names is given by |
| \code{sysconf_names}. |
| Availability: \UNIX. |
| \end{funcdesc} |
| |
| \begin{datadesc}{sysconf_names} |
| Dictionary mapping names accepted by \function{sysconf()} to the |
| integer values defined for those names by the host operating system. |
| This can be used to determine the set of names known to the system. |
| Availability: \UNIX. |
| \end{datadesc} |
| |
| |
| The follow data values are used to support path manipulation |
| operations. These are defined for all platforms. |
| |
| Higher-level operations on pathnames are defined in the |
| \refmodule{os.path} module. |
| |
| |
| \begin{datadesc}{curdir} |
| The constant string used by the operating system to refer to the current |
| directory. |
| For example: \code{'.'} for \POSIX{} or \code{':'} for the Macintosh. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{pardir} |
| The constant string used by the operating system to refer to the parent |
| directory. |
| For example: \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{sep} |
| The character used by the operating system to separate pathname components, |
| for example, \character{/} for \POSIX{} or \character{:} for the |
| Macintosh. Note that knowing this is not sufficient to be able to |
| parse or concatenate pathnames --- use \function{os.path.split()} and |
| \function{os.path.join()} --- but it is occasionally useful. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{altsep} |
| An alternative character used by the operating system to separate pathname |
| components, or \code{None} if only one separator character exists. This is |
| set to \character{/} on Windows systems where \code{sep} is a |
| backslash. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{extsep} |
| The character which separates the base filename from the extension; |
| for example, the \character{.} in \file{os.py}. |
| Also available via \module{os.path}. |
| \versionadded{2.2} |
| \end{datadesc} |
| |
| \begin{datadesc}{pathsep} |
| The character conventionally used by the operating system to separate |
| search patch components (as in \envvar{PATH}), such as \character{:} for |
| \POSIX{} or \character{;} for Windows. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{defpath} |
| The default search path used by \function{exec*p*()} and |
| \function{spawn*p*()} if the environment doesn't have a \code{'PATH'} |
| key. |
| Also available via \module{os.path}. |
| \end{datadesc} |
| |
| \begin{datadesc}{linesep} |
| The string used to separate (or, rather, terminate) lines on the |
| current platform. This may be a single character, such as \code{'\e |
| n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters, |
| for example, \code{'\e r\e n'} for Windows. |
| \end{datadesc} |