diff options
Diffstat (limited to 'Doc/lib/libos.tex')
| -rw-r--r-- | Doc/lib/libos.tex | 1980 |
1 files changed, 0 insertions, 1980 deletions
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex deleted file mode 100644 index 826e9fa..0000000 --- a/Doc/lib/libos.tex +++ /dev/null @@ -1,1980 +0,0 @@ -\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. - -This mapping is captured the first time the \module{os} module is -imported, typically during Python startup as part of processing -\file{site.py}. Changes to the environment made after this time are -not reflected in \code{os.environ}, except for changes made by modifying -\code{os.environ} directly. - -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{Calling \function{putenv()} directly does not change -\code{os.environ}, so it's better to modify \code{os.environ}.} -\note{On some platforms, including FreeBSD and Mac OS X, setting -\code{environ} may cause memory leaks. Refer to the system documentation -for \cfunction{putenv()}.} - -If \function{putenv()} is not provided, a modified copy of this mapping -may be passed to the appropriate process-creation functions to cause -child processes to use a modified environment. - -If the platform supports the \function{unsetenv()} function, you can -delete items in this mapping to unset environment variables. -\function{unsetenv()} will be called automatically when an item is -deleted from \code{os.environ}. - -\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}{getsid}{pid} -Calls the system call \cfunction{getsid()}. See the \UNIX{} manual -for the semantics. -Availability: \UNIX. \versionadded{2.4} -\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} - -\begin{funcdesc}{unsetenv}{varname} -\index{environment variables!deleting} -Unset (delete) the environment variable named \var{varname}. 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{unsetenv()} is -supported, deletion of items in \code{os.environ} is automatically -translated into a corresponding call to \function{unsetenv()}; however, -calls to \function{unsetenv()} don't update \code{os.environ}, so it is -actually preferable to delete items of \code{os.environ}. -\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} -\versionchanged[On \UNIX, when the \var{mode} argument starts with - \character{a}, the \var{O_APPEND} flag is set on the file descriptor - (which the \cfunction{fdopen()} implementation already does on most - platforms)]{2.5} -\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: Macintosh, \UNIX, Windows. - -\deprecated{2.6}{This function is obsolete. Use the - \module{subprocess} module.} - -\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: Macintosh, \UNIX, Windows. -\end{funcdesc} - - -\subsection{File Descriptor Operations \label{os-fd-ops}} - -These functions operate on I/O streams referenced using file -descriptors. - -File descriptors are small integers corresponding to a file that has -been opened by the current process. For example, standard input is -usually file descriptor 0, standard output is 1, and standard error is -2. Further files opened by a process will then be assigned 3, 4, 5, -and so forth. The name ``file descriptor'' is slightly deceptive; on -{\UNIX} platforms, sockets and pipes are also referenced by file descriptors. - - -\begin{funcdesc}{close}{fd} -Close file descriptor \var{fd}. -Availability: Macintosh, \UNIX, Windows. - -\begin{notice} -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{notice} -\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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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). - -\begin{notice} -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). To wrap a file descriptor in a ``file object'', use -\function{fdopen()}. -\end{notice} -\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: Macintosh, 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: Macintosh, \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. - -\begin{notice} -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{notice} -\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: Macintosh, \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: Macintosh, \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:Macintosh, \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. - -\begin{notice} -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{notice} -\end{funcdesc} - - -The following data items are available for use in constructing the -\var{flags} parameter to the \function{open()} function. Some items will -not be available on all platforms. For descriptions of their availability -and use, consult \manpage{open}{2}. - -\begin{datadesc}{O_RDONLY} -\dataline{O_WRONLY} -\dataline{O_RDWR} -\dataline{O_APPEND} -\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_DSYNC} -\dataline{O_RSYNC} -\dataline{O_SYNC} -\dataline{O_NDELAY} -\dataline{O_NONBLOCK} -\dataline{O_NOCTTY} -\dataline{O_SHLOCK} -\dataline{O_EXLOCK} -More options for the \var{flag} argument to the \function{open()} function. -Availability: Macintosh, \UNIX. -\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: 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} - -\begin{datadesc}{SEEK_SET} -\dataline{SEEK_CUR} -\dataline{SEEK_END} -Parameters to the \function{lseek()} function. -Their values are 0, 1, and 2, respectively. -Availability: Windows, Macintosh, \UNIX. -\versionadded{2.5} -\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 \constant{True} if access is allowed, -\constant{False} if not. -See the \UNIX{} man page \manpage{access}{2} for more information. -Availability: Macintosh, \UNIX, Windows. - -\note{Using \function{access()} to check if a user is authorized to e.g. -open a file before actually doing so using \function{open()} creates a -security hole, because the user might exploit the short time interval -between checking and opening the file to manipulate it.} - -\note{I/O operations may fail even when \function{access()} -indicates that they would succeed, particularly for operations -on network filesystems which may have permissions semantics -beyond the usual \POSIX{} permission-bit model.} -\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: Macintosh, \UNIX, Windows. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{chflags}{path, flags} -Set the flags of \var{path} to the numeric \var{flags}. -\var{flags} may take a combination (bitwise OR) of the following values -(as defined in the \module{stat} module): -\begin{itemize} - \item \code{UF_NODUMP} - \item \code{UF_IMMUTABLE} - \item \code{UF_APPEND} - \item \code{UF_OPAQUE} - \item \code{UF_NOUNLINK} - \item \code{SF_ARCHIVED} - \item \code{SF_IMMUTABLE} - \item \code{SF_APPEND} - \item \code{SF_NOUNLINK} - \item \code{SF_SNAPSHOT} -\end{itemize} -Availability: Macintosh, \UNIX. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{chroot}{path} -Change the root directory of the current process to \var{path}. -Availability: Macintosh, \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 -(as defined in the \module{stat} module) or bitwise or-ed -combinations of them: -\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: Macintosh, \UNIX, Windows. - -\note{Although Windows supports \function{chmod()}, you can only -set the file's read-only flag with it (via the \code{S_IWRITE} -and \code{S_IREAD} constants or a corresponding integer value). -All other bits are ignored.} -\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}. To leave one of the ids unchanged, set it to -1. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{lchflags}{path, flags} -Set the flags of \var{path} to the numeric \var{flags}, like -\function{chflags()}, but do not follow symbolic links. -Availability: \UNIX. -\versionadded{2.6} -\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: Macintosh, \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{link}{src, dst} -Create a hard link pointing to \var{src} named \var{dst}. -Availability: Macintosh, \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: Macintosh, \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: Macintosh, \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}{filename\optional{, mode=0600, device}} -Create a filesystem node (file, device special file or named pipe) -named \var{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 the device major number from a raw device number (usually -the \member{st_dev} or \member{st_rdev} field from \ctype{stat}). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{minor}{device} -Extracts the device minor number from a raw device number (usually -the \member{st_dev} or \member{st_rdev} field from \ctype{stat}). -\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). On some systems, \var{mode} is ignored. -Where it is used, the current umask value is first masked out. -\note{\function{makedirs()} will become confused if the path elements -to create include \var{os.pardir}.} -\versionadded{1.5.2} -\versionchanged[This function now handles UNC paths correctly]{2.3} -\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: Macintosh, \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: Macintosh, \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})}. -\versionchanged [If the \var{path} is a Unicode object the result will also -be a Unicode object]{2.6} -Availability: Macintosh, \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, \function{removedirs()} -tries to successively remove every parent directory mentioned in -\var{path} until an error is raised (which is ignored, because -it generally means that a parent directory is not empty). -For example, \samp{os.removedirs('foo/bar/baz')} will first remove -the directory \samp{'foo/bar/baz'}, and then remove \samp{'foo/bar'} -and \samp{'foo'} if they are empty. -Raises \exception{OSError} 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()}. -\versionadded{1.5.2} - -\begin{notice} -This function can fail with the new directory structure made if -you lack permissions needed to remove the leaf directory or file. -\end{notice} -\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} -(platform dependent; time of most recent metadata change on \UNIX, or -the time of creation on Windows): - -\begin{verbatim} ->>> import os ->>> statinfo = os.stat('somefile.txt') ->>> statinfo -(33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732) ->>> statinfo.st_size -926L ->>> -\end{verbatim} - -\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). -\member{st_flags} (user defined flags for file). - -On other \UNIX{} systems (such as FreeBSD), the following attributes -may be available (but may be only filled out if root tries to -use them): -\member{st_gen} (file generation number), -\member{st_birthtime} (time of file creation). - -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.) - -\note{The exact meaning and resolution of the \member{st_atime}, - \member{st_mtime}, and \member{st_ctime} members depends on the - operating system and the file system. For example, on Windows systems - using the FAT or FAT32 file systems, \member{st_mtime} has 2-second - resolution, and \member{st_atime} has only 1-day resolution. See - your operating system documentation for details.} - -Availability: Macintosh, \UNIX, Windows. - -\versionchanged -[Added access to values as attributes of the returned object]{2.2} -\versionchanged[Added st_gen, st_birthtime]{2.5} -\end{funcdesc} - -\begin{funcdesc}{stat_float_times}{\optional{newvalue}} -Determine whether \class{stat_result} represents time stamps as float -objects. If \var{newvalue} is \code{True}, future calls to \function{stat()} -return floats, if it is \code{False}, future calls return ints. -If \var{newvalue} is omitted, return the current setting. - -For compatibility with older Python versions, accessing -\class{stat_result} as a tuple always returns integers. - -\versionchanged[Python now returns float values by default. Applications -which do not work correctly with floating point time stamps can use -this function to restore the old behaviour]{2.5} - -The resolution of the timestamps (that is the smallest possible fraction) -depends on the system. Some systems only support second resolution; -on these systems, the fraction will always be zero. - -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_bsize}, -\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()} (section \ref{os-newstreams}) -instead.} Availability: Macintosh, \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()} (section \ref{os-newstreams}) -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. -Whether a directory can be given for \var{path} depends on whether the -operating system implements directories as files (for example, Windows -does not). Note that the exact times you set here may not be returned -by a subsequent \function{stat()} call, depending on the resolution -with which your operating system records access and modification times; -see \function{stat()}. -\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} - \optional{, onerror\code{=None}\optional{, - followlinks\code{=False}}}}} -\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 (perhaps using \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{dirpath} itself is generated. - -By default errors from the \code{os.listdir()} call are ignored. If -optional argument \var{onerror} is specified, it should be a function; -it will be called with one argument, an \exception{OSError} instance. It can -report the error to continue with the walk, or raise the exception -to abort the walk. Note that the filename is available as the -\code{filename} attribute of the exception object. - -By default, \function{walk()} will not walk down into symbolic links that -resolve to directories. Set \var{followlinks} to True to visit directories -pointed to by symlinks, on systems that support them. - -\versionadded[The \var{followlinks} parameter]{2.6} - -\begin{notice} -Be aware that setting \var{followlinks} to true can lead to infinite recursion -if a link points to a parent directory of itself. \function{walk()} does not -keep track of the directories it visited already. -\end{notice} - -\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} - -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} -# Delete everything reachable from the directory named in 'top', -# assuming there are no symbolic links. -# CAUTION: This is dangerous! For example, if top == '/', it -# could delete all your disk files. -import os -for root, dirs, files in os.walk(top, topdown=False): - for name in files: - os.remove(os.path.join(root, name)) - for name in dirs: - os.rmdir(os.path.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: Macintosh, \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 should start with the name of -the command being run, but this is not enforced. - -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: Macintosh, \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: Macintosh, \UNIX, Windows. - -\begin{notice} -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{notice} -\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. -\note{Some of these may not be available on all \UNIX{} platforms, -since there is some variation. These constants are defined where they -are defined by the underlying platform.} - -\begin{datadesc}{EX_OK} -Exit code that means no error occurred. -Availability: Macintosh, \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: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_DATAERR} -Exit code that means the input data was incorrect. -Availability: Macintosh, \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: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOUSER} -Exit code that means a specified user did not exist. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOHOST} -Exit code that means a specified host did not exist. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_UNAVAILABLE} -Exit code that means that a required service is unavailable. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_SOFTWARE} -Exit code that means an internal software error was detected. -Availability: Macintosh, \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: Macintosh, \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: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_CANTCREAT} -Exit code that means a user specified output file could not be created. -Availability: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_CONFIG} -Exit code that means that some kind of configuration error occurred. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOTFOUND} -Exit code that means something like ``an entry was not found''. -Availability: Macintosh, \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: Macintosh, \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: Macintosh, Some flavors of \UNIX. -\end{funcdesc} - -\begin{funcdesc}{kill}{pid, sig} -\index{process!killing} -\index{process!signalling} -Send signal \var{sig} to the process \var{pid}. Constants for the -specific signals available on the host platform are defined in the -\refmodule{signal} module. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{killpg}{pgid, sig} -\index{process!killing} -\index{process!signalling} -Send the signal \var{sig} to the process group \var{pgid}. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{nice}{increment} -Add \var{increment} to the process's ``niceness''. Return the new -niceness. -Availability: Macintosh, \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: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdescni}{popen}{\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. - -(Note that the \module{subprocess} module provides more powerful -facilities for spawning new processes and retrieving their results; -using that module is preferable to using these functions.) - -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: Macintosh, \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: Macintosh, \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\optional{, operation}} -Start a file with its associated application. - -When \var{operation} is not specified or \code{'open'}, 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. - -When another \var{operation} is given, it must be a ``command verb'' -that specifies what should be done with the file. -Common verbs documented by Microsoft are \code{'print'} and -\code{'edit'} (to be used on files) as well as \code{'explore'} and -\code{'find'} (to be used on directories). - -\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} -\versionadded[The \var{operation} parameter]{2.5} -\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. - -On \UNIX, the return value is the exit status of the process encoded in the -format specified for \function{wait()}. 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. - -On Windows, the return value is that returned by the system shell after -running \var{command}, given by the Windows environment variable -\envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME) -this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000 -and XP) this is the exit status of the command run; on systems using -a non-native shell, consult your shell documentation. - -Availability: Macintosh, \UNIX, Windows. - -The \module{subprocess} module provides more powerful facilities for -spawning new processes and retrieving their results; using that module -is preferable to using this function. -\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: Macintosh, \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: Macintosh, \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{funcdesc}{wait3}{\optional{options}} -Similar to \function{waitpid()}, except no process id argument is given and -a 3-element tuple containing the child's process id, exit status indication, -and resource usage information is returned. Refer to -\module{resource}.\function{getrusage()} -for details on resource usage information. The option argument is the same -as that provided to \function{waitpid()} and \function{wait4()}. -Availability: \UNIX. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{wait4}{pid, options} -Similar to \function{waitpid()}, except a 3-element tuple, containing the -child's process id, exit status indication, and resource usage information -is returned. Refer to \module{resource}.\function{getrusage()} for details -on resource usage information. The arguments to \function{wait4()} are -the same as those provided to \function{waitpid()}. -Availability: \UNIX. -\versionadded{2.5} -\end{funcdesc} - -\begin{datadesc}{WNOHANG} -The option for \function{waitpid()} to return immediately if no child -process status is available immediately. The function returns -\code{(0, 0)} in this case. -Availability: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \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: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WSTOPSIG}{status} -Return the signal which caused the process to stop. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WTERMSIG}{status} -Return the signal which caused the process to exit. -Availability: Macintosh, \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 as the keys of the -\code{confstr_names} dictionary. For configuration variables not -included in that mapping, passing an integer for \var{name} is also -accepted. -Availability: Macintosh, \UNIX. - -If the configuration value specified by \var{name} isn't defined, -\code{None} 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: Macintosh, \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 \exception{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: Macintosh, \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: Macintosh, \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 Mac OS 9. -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 Mac OS 9. -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 -Mac OS 9. 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 path 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. -Do not use \var{os.linesep} as a line terminator when writing files -opened in text mode (the default); use a single \code{'\e n'} instead, -on all platforms. -\end{datadesc} - -\begin{datadesc}{devnull} -The file path of the null device. -For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for -Mac OS 9. -Also available via \module{os.path}. -\versionadded{2.4} -\end{datadesc} - - -\subsection{Miscellaneous Functions \label{os-miscfunc}} - -\begin{funcdesc}{urandom}{n} -Return a string of \var{n} random bytes suitable for cryptographic use. - -This function returns random bytes from an OS-specific -randomness source. The returned data should be unpredictable enough for -cryptographic applications, though its exact quality depends on the OS -implementation. On a UNIX-like system this will query /dev/urandom, and -on Windows it will use CryptGenRandom. If a randomness source is not -found, \exception{NotImplementedError} will be raised. -\versionadded{2.4} -\end{funcdesc} - - - - |