| \section{\module{os} --- |
| Miscellaneous OS interfaces} |
| |
| \declaremodule{standard}{os} |
| \modulesynopsis{Miscellaneous OS interfaces.} |
| |
| |
| This module provides a more portable way of using operating system |
| (OS) dependent functionality than importing an OS dependent built-in |
| module like \refmodule{posix} or \module{nt}. |
| |
| This module searches for an OS 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 OS dependent |
| modules is such that as long as the same functionality is available, |
| it uses the same interface; e.g., 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 OS 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 OS 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 (e.g., not for illegal argument types). 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 (e.g. \function{chdir()} or |
| \function{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} |
| |
| \begin{datadesc}{name} |
| The name of the OS dependent module imported. The following names |
| have currently been registered: \code{'posix'}, \code{'nt'}, |
| \code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, \code{'java'}. |
| \end{datadesc} |
| |
| \begin{datadesc}{path} |
| The corresponding OS dependent standard module for pathname |
| operations, e.g., \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 a valid 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. |
| |
| 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{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 current process' effective group id. |
| 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 current process' group id. |
| 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 actual login name for the current process, even if there |
| are multiple login names which map to the same user id. |
| Availability: \UNIX{}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpgrp}{} |
| \index{process!group} |
| Return the current process group id. |
| 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}{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. |
| |
| 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}{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()}. 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. |
| \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. \strong{Note:} This function |
| behaves unreliably under Windows due to the native implementation of |
| \cfunction{popen()}. |
| Availability: \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{tmpfile}{} |
| Return a new file object opened in update mode (\samp{w+}). 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{}. |
| \end{funcdesc} |
| |
| |
| \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}{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, Unix95, Unix98, 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}{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{1} if the file descriptor \var{fd} is open and connected to a |
| tty(-like) device, else \code{0}. |
| 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. |
| 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. |
| \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} |
| |
| |
| \subsection{Files and Directories \label{os-file-dir}} |
| |
| \begin{funcdesc}{access}{path, mode} |
| Check read/write/execute permissions for this process or existence of |
| file \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}{getcwd}{} |
| Return a string representing the current working directory. |
| Availability: Macintosh, \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{chmod}{path, mode} |
| Change the mode of \var{path} to the numeric \var{mode}. |
| 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}{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. |
| \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}{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}} |
| \index{directory!creating} |
| Recursive directory creation function. 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). |
| \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, Unix95, Unix98, 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. |
| Availability: \UNIX{}. |
| \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. |
| Availability: Macintosh, \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{removedirs}{path} |
| \index{directory!deleting} |
| Recursive directory removal function. 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}. |
| 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 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 Windows, some items are filled with dummy values.) |
| Availability: Macintosh, \UNIX{}, Windows. |
| |
| Note: The standard module \refmodule{stat}\refstmodindex{stat} defines |
| functions and constants that are useful for extracting information |
| from a \ctype{stat} structure. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{statvfs}{path} |
| Perform a \cfunction{statvfs()} system call on the given path. The |
| return value is a tuple of 10 integers giving the most common |
| members of the \ctype{statvfs} structure, in the order |
| \code{f_bsize}, |
| \code{f_frsize}, |
| \code{f_blocks}, |
| \code{f_bfree}, |
| \code{f_bavail}, |
| \code{f_files}, |
| \code{f_ffree}, |
| \code{f_favail}, |
| \code{f_flag}, |
| \code{f_namemax}. |
| Availability: \UNIX{}. |
| |
| Note: The standard module \module{statvfs}\refstmodindex{statvfs} |
| defines constants that are useful for extracting information |
| from a \ctype{statvfs} structure. |
| \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. |
| \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. |
| \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} |
| |
| |
| \subsection{Process Management \label{os-process}} |
| |
| These functions may be used to create and manage processes. |
| |
| |
| \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, ...} |
| This is equivalent to |
| \samp{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}. |
| Availability: \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{execle}{path, arg0, arg1, ..., env} |
| This is equivalent to |
| \samp{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}. |
| Availability: \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{execlp}{path, arg0, arg1, ...} |
| This is equivalent to |
| \samp{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}. |
| Availability: \UNIX{}, Windows. |
| \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. |
| Availability: \UNIX{}, Windows. |
| \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. |
| Availability: \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{execvp}{path, args} |
| This is like \samp{execv(\var{path}, \var{args})} but duplicates |
| the shell's actions in searching for an executable file in a list of |
| directories. The directory list is obtained from |
| \code{environ['PATH']}. |
| Availability: \UNIX{}, Windows. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{execvpe}{path, args, env} |
| This is a cross between \function{execve()} and \function{execvp()}. |
| The directory list is obtained from \code{\var{env}['PATH']}. |
| 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} |
| |
| \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 \code{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}. |
| Availability: \UNIX{}. |
| \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{funcdesc}{spawnv}{mode, path, args} |
| Execute the program \var{path} in a new process, passing the arguments |
| specified in \var{args} as command-line parameters. \var{args} may be |
| a list or a tuple. \var{mode} is a magic operational constant. See |
| the Visual \Cpp{} Runtime Library documentation for further |
| information; the constants are exposed to the Python programmer as |
| listed below. |
| Availability: \UNIX{}, Windows. |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{spawnve}{mode, path, args, env} |
| Execute the program \var{path} in a new process, passing the arguments |
| specified in \var{args} as command-line parameters and the contents of |
| the mapping \var{env} as the environment. \var{args} may be a list or |
| a tuple. \var{mode} is a magic operational constant. See the Visual |
| \Cpp{} Runtime Library documentation for further information; the |
| constants are exposed to the Python programmer as listed below. |
| Availability: \UNIX{}, Windows. |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{datadesc}{P_WAIT} |
| \dataline{P_NOWAIT} |
| \dataline{P_NOWAITO} |
| Possible values for the \var{mode} parameter to \function{spawnv()} |
| and \function{spawnve()}. |
| Availability: \UNIX{}, Windows. |
| \versionadded{1.5.2} |
| \end{datadesc} |
| |
| \begin{datadesc}{P_OVERLAY} |
| \dataline{P_DETACH} |
| Possible values for the \var{mode} parameter to \function{spawnv()} |
| and \function{spawnve()}. These are less portable than those listed |
| above. |
| Availability: Windows. |
| \versionadded{1.5.2} |
| \end{datadesc} |
| |
| \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 (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} 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} |
| 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. |
| Availability: \UNIX{}. |
| |
| 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}). |
| \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} |
| |
| 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}{WIFSTOPPED}{status} |
| Return true if the process has been stopped. |
| Availability: \UNIX{}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFSIGNALED}{status} |
| Return true if the process exited due to a signal. |
| Availability: \UNIX{}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WIFEXITED}{status} |
| Return true if the process exited using the \manpage{exit}{2} system |
| call. |
| 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, Unix95, Unix98, 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}{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 OS to refer to the current directory, |
| e.g.\ \code{'.'} for \POSIX{} or \code{':'} for the Macintosh. |
| \end{datadesc} |
| |
| \begin{datadesc}{pardir} |
| The constant string used by the OS to refer to the parent directory, |
| e.g.\ \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh. |
| \end{datadesc} |
| |
| \begin{datadesc}{sep} |
| The character used by the OS to separate pathname components, |
| e.g.\ \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. |
| \end{datadesc} |
| |
| \begin{datadesc}{altsep} |
| An alternative character used by the OS to separate pathname components, |
| or \code{None} if only one separator character exists. This is set to |
| \character{/} on DOS and Windows systems where \code{sep} is a backslash. |
| \end{datadesc} |
| |
| \begin{datadesc}{pathsep} |
| The character conventionally used by the OS to separate search patch |
| components (as in \envvar{PATH}), e.g.\ \character{:} for \POSIX{} or |
| \character{;} for DOS and Windows. |
| \end{datadesc} |
| |
| \begin{datadesc}{defpath} |
| The default search path used by \function{exec*p*()} if the environment |
| doesn't have a \code{'PATH'} key. |
| \end{datadesc} |
| |
| \begin{datadesc}{linesep} |
| The string used to separate (or, rather, terminate) lines on the |
| current platform. This may be a single character, |
| e.g.\ \code{'\e n'} for \POSIX{} or \code{'\e r'} for MacOS, or multiple |
| characters, e.g.\ \code{'\e r\e n'} for MS-DOS and MS Windows. |
| \end{datadesc} |