\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 systemdependent functionality than importing a operating system dependentbuilt-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 dataas found there. The design of all Python's built-in operating system dependentmodules 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} inthe same format (which happens to have originated with the\POSIX{} interface). Extensions peculiar to a particular operating system are alsoavailable through the \module{os} module, but using them is of course athreat 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.%\ifhtmlThe \module{os} module contains many functions and data values.The items below and in the following sub-sections are all availabledirectly from the \module{os} module.\fi \begin{excdesc}{error}This exception is raised when a function returns a system-relatederror (not for illegal argument types or other incidental errors).This is also known as the built-in exception \exception{OSError}. Theaccompanying value is a pair containing the numeric error code from\cdata{errno} and the corresponding string, as would be printed by theC function \cfunction{perror()}. See the module\refmodule{errno}\refbimodindex{errno}, which contains names for theerror 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 ofthe C \cdata{errno} variable, and the latter holds the correspondingerror message from \cfunction{strerror()}. For exceptions thatinvolve a file system path (such as \function{chdir()} or\function{unlink()}), the exception instance will contain a thirdattribute, \member{filename}, which is the file name passed to thefunction.\end{excdesc} \begin{datadesc}{name}The name of the operating system dependent module imported. Thefollowing 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 pathnameoperations, such as \module{posixpath} or \module{macpath}. Thus,given the proper imports, \code{os.path.split(\var{file})} isequivalent to but more portable than\code{posixpath.split(\var{file})}. Note that this is also animportable 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 thecurrent 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 someplatforms), and is equivalent to \code{getenv("HOME")} in C. This mapping is captured the first time the \module{os} module isimported, typically during Python startup as part of processing\file{site.py}. Changes to the environment made after this time arenot reflected in \code{os.environ}, except for changes made by modifying\code{os.environ} directly. If the platform supports the \function{putenv()} function, thismapping may be used to modify the environment as well as query theenvironment. \function{putenv()} will be called automatically whenthe 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 documentationfor \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 isdeleted 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 theprocess.Availability: \UNIX.\end{funcdesc} \begin{funcdesc}{getegid}{}Return the effective group id of the current process. Thiscorresponds to the `set id' bit on the file being executed in thecurrent 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 currentprocess.Availability: \UNIX.\end{funcdesc} \begin{funcdesc}{getlogin}{}Return the name of the user logged in on the controlling terminal ofthe process. For most purposes, it is more useful to use theenvironment variable \envvar{LOGNAME} to find out who the user is,or \code{pwd.getpwuid(os.getuid())[0]} to get the login nameof 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 isreturned. 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 itexists, 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 subprocessesstarted 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()} issupported, assignments to items in \code{os.environ} are automaticallytranslated into corresponding calls to \function{putenv()}; however,calls to \function{putenv()} don't update \code{os.environ}, so it isactually 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 currentprocess to \var{groups}. \var{groups} must be a sequence, and eachelement must be an integer identifying a group. This operation istypical 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 withid \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{} manualfor the semantics.Availability: \UNIX. \versionadded{2.4}\end{funcdesc} \begin{funcdesc}{setsid}{}Calls the system call \cfunction{setsid()}. See the \UNIX{} manualfor 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 currentoperating system. The tuple contains 5 strings:\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},\var{machine})}. Some systems truncate the nodename to 8characters or to the leading component; a better way to get thehostname 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}. Suchchanges 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()} issupported, deletion of items in \code{os.environ} is automaticallytranslated into a corresponding call to \function{unsetenv()}; however,calls to \function{unsetenv()} don't update \code{os.environ}, so it isactually 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 asthe 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 openfile object connected to the pipe, which can be read or writtendepending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.The \var{bufsize} argument has the same meaning as the correspondingargument to the built-in \function{open()} function. The exit status ofthe command (encoded in the format specified for \function{wait()}) isavailable as the return value of the \method{close()} method of the fileobject, except that when the exit status is zero (termination withouterrors), \code{None} is returned.Availability: Macintosh, \UNIX, Windows. The \module{subprocess} module provides more powerful facilities forspawning new processes and retrieving their results; using that moduleis preferable to using this function. \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 filehas no directory entries associated with it and will be automaticallydeleted once there are no file descriptors for the file.Availability: Macintosh, \UNIX, Windows.\end{funcdesc} There are a number of different \function{popen*()} functions thatprovide slightly different ways to create subprocesses. Note that the\module{subprocess} module is easier to use and more powerful;consider using that module before writing code using thelower-level \function{popen*()} functions. For each of the \function{popen*()} variants, if \var{bufsize} isspecified, it specifies the buffer size for the I/O pipes.\var{mode}, if provided, should be the string \code{'b'} or\code{'t'}; on Windows this is needed to determine whether the fileobjects should be opened in binary or text mode. The default valuefor \var{mode} is \code{'t'}. Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, inwhich case arguments will be passed directly to the program without shellintervention (as with \function{os.spawnv()}). If \var{cmd} is a string it willbe passed to the shell (as with \function{os.system()}). These methods do not make it possible to retrieve the exit status fromthe child processes. The only way to control the input and outputstreams and also retrieve the return codes is to use the\class{Popen3} and \class{Popen4} classes from the \refmodule{popen2}module; these are only available on \UNIX. For a discussion of possible deadlock conditions related to the useof these functions, see ``\ulink{Flow ControlIssues}{popen2-flow-control.html}''(section~\ref{popen2-flow-control}). \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}Executes \var{cmd} as a sub-process. Returns the file objects\code{(\var{child_stdin}, \var{child_stdout})}.Availability: Macintosh, \UNIX, Windows.\versionadded{2.0}\end{funcdesc} \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}}Executes \var{cmd} as a sub-process. Returns the file objects\code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.Availability: Macintosh, \UNIX, Windows.\versionadded{2.0}\end{funcdesc} \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}Executes \var{cmd} as a sub-process. Returns the file objects\code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.Availability: Macintosh, \UNIX, Windows.\versionadded{2.0}\end{funcdesc} (Note that \code{\var{child_stdin}, \var{child_stdout}, and\var{child_stderr}} are named from the point of view of the childprocess, so \var{child_stdin} is the child's standard input.) This functionality is also available in the \refmodule{popen2} moduleusing functions of the same names, but the return values of thosefunctions have a different order. \subsection{File Descriptor Operations \label{os-fd-ops}} These functions operate on I/O streams referenced using filedescriptors. File descriptors are small integers corresponding to a file that hasbeen opened by the current process. For example, standard input isusually file descriptor 0, standard output is 1, and standard error is2. 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 appliedto a file descriptor as returned by \function{open()} or\function{pipe()}. To close a ``file object'' returned by thebuilt-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 latterfirst 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 astring which is the name of a defined system value; these names arespecified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, andothers). Some platforms define additional names as well. The namesknown to the host operating system are given in the\code{pathconf_names} dictionary. For configuration variables notincluded in that mapping, passing an integer for \var{name} is alsoaccepted.Availability: Macintosh, \UNIX. If \var{name} is a string and is not known, \exception{ValueError} israised. If a specific value for \var{name} is not supported by thehost system, even if it is included in \code{pathconf_names}, an\exception{OSError} is raised with \constant{errno.EINVAL} for theerror number.Lines 1–500 of 2006. Load more
\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. 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. \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} There are a number of different \function{popen*()} functions that provide slightly different ways to create subprocesses. Note that the \module{subprocess} module is easier to use and more powerful; consider using that module before writing code using the lower-level \function{popen*()} functions. For each of the \function{popen*()} variants, if \var{bufsize} is specified, it specifies the buffer size for the I/O pipes. \var{mode}, if provided, should be the string \code{'b'} or \code{'t'}; on Windows this is needed to determine whether the file objects should be opened in binary or text mode. The default value for \var{mode} is \code{'t'}. Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed directly to the program without shell intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will be passed to the shell (as with \function{os.system()}). These methods do not make it possible to retrieve the exit status from the child processes. The only way to control the input and output streams and also retrieve the return codes is to use the \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2} module; these are only available on \UNIX. For a discussion of possible deadlock conditions related to the use of these functions, see ``\ulink{Flow Control Issues}{popen2-flow-control.html}'' (section~\ref{popen2-flow-control}). \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}} Executes \var{cmd} as a sub-process. Returns the file objects \code{(\var{child_stdin}, \var{child_stdout})}. Availability: Macintosh, \UNIX, Windows. \versionadded{2.0} \end{funcdesc} \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}} Executes \var{cmd} as a sub-process. Returns the file objects \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}. Availability: Macintosh, \UNIX, Windows. \versionadded{2.0} \end{funcdesc} \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}} Executes \var{cmd} as a sub-process. Returns the file objects \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}. Availability: Macintosh, \UNIX, Windows. \versionadded{2.0} \end{funcdesc} (Note that \code{\var{child_stdin}, \var{child_stdout}, and \var{child_stderr}} are named from the point of view of the child process, so \var{child_stdin} is the child's standard input.) This functionality is also available in the \refmodule{popen2} module using functions of the same names, but the return values of those functions have a different order. \subsection{File Descriptor Operations \label{os-fd-ops}} These functions operate on I/O streams 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.