This module provides a portable way of using operating system dependentfunctionality. If you just want to read or write a file seeopen(), ifyou want to manipulate paths, see theos.path module, and if you want toread all the lines in all the files on the command line see thefileinputmodule. For creating temporary files and directories see thetempfilemodule, and for high-level file and directory handling see theshutilmodule.
Notes on the availability of these functions:
Note
All functions in this module raiseOSError in the case of invalid orinaccessible file names and paths, or other arguments that have the correcttype, but are not accepted by the operating system.
The name of the operating system dependent module imported. The followingnames have currently been registered:'posix','nt','mac','os2','ce','java'.
See also
sys.platform has a finer granularity.os.uname() givessystem-dependent version information.
Theplatform module provides detailed checks for thesystem’s identity.
In Python, file names, command line arguments, and environment variables arerepresented using the string type. On some systems, decoding these strings toand from bytes is necessary before passing them to the operating system. Pythonuses the file system encoding to perform this conversion (seesys.getfilesystemencoding()).
Changed in version 3.1:On some systems, conversion using the file system encoding may fail. In thiscase, Python uses thesurrogateescape encoding error handler, which meansthat undecodable bytes are replaced by a Unicode character U+DCxx ondecoding, and these are again translated to the original byte on encoding.
The file system encoding must guarantee to successfully decode all bytesbelow 128. If the file system encoding fails to provide this guarantee, APIfunctions may raise UnicodeErrors.
These functions and data items provide information and operate on the currentprocess and user.
Return the filename corresponding to the controlling terminal of the process.
Availability: Unix.
Amapping object representing the string environment. For example,environ['HOME'] is the pathname of your home directory (on some platforms),and is equivalent togetenv("HOME") in C.
This mapping is captured the first time theos module is imported,typically during Python startup as part of processingsite.py. Changesto the environment made after this time are not reflected inos.environ,except for changes made by modifyingos.environ directly.
If the platform supports theputenv() function, this mapping may be usedto modify the environment as well as query the environment.putenv() willbe called automatically when the mapping is modified.
On Unix, keys and values usesys.getfilesystemencoding() and'surrogateescape' error handler. Useenvironb if you would liketo use a different encoding.
Note
Callingputenv() directly does not changeos.environ, so it’s betterto modifyos.environ.
Note
On some platforms, including FreeBSD and Mac OS X, settingenviron maycause memory leaks. Refer to the system documentation forputenv().
Ifputenv() is not provided, a modified copy of this mapping may bepassed to the appropriate process-creation functions to cause child processesto use a modified environment.
If the platform supports theunsetenv() function, you can delete items inthis mapping to unset environment variables.unsetenv() will be calledautomatically when an item is deleted fromos.environ, and whenone of thepop() orclear() methods is called.
Bytes version ofenviron: amapping object representing theenvironment as byte strings.environ andenvironb aresynchronized (modifyenvironb updatesenviron, and viceversa).
environb is only available ifsupports_bytes_environ isTrue.
New in version 3.2.
These functions are described inFiles and Directories.
Encodefilename to the filesystem encoding with'surrogateescape'error handler, or'strict' on Windows; returnbytes unchanged.
fsdecode() is the reverse function.
New in version 3.2.
Decodefilename from the filesystem encoding with'surrogateescape'error handler, or'strict' on Windows; returnstr unchanged.
fsencode() is the reverse function.
New in version 3.2.
Return the value of the environment variablekey if it exists, ordefault if it doesn’t.key,default and the result are str.
On Unix, keys and values are decoded withsys.getfilesystemencoding()and'surrogateescape' error handler. Useos.getenvb() if youwould like to use a different encoding.
Availability: most flavors of Unix, Windows.
Return the value of the environment variablekey if it exists, ordefault if it doesn’t.key,default and the result are bytes.
Availability: most flavors of Unix.
New in version 3.2.
Returns the list of directories that will be searched for a namedexecutable, similar to a shell, when launching a process.env, when specified, should be an environment variable dictionaryto lookup the PATH in.By default, whenenv is None,environ is used.
New in version 3.2.
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.
Return the current process’s effective user id.
Availability: Unix.
Return the real group id of the current process.
Availability: Unix.
Return list of group ids thatuser belongs to. Ifgroup is not in thelist, it is included; typically,group is specified as the group IDfield from the password record foruser.
Availability: Unix.
New in version 3.3.
Return list of supplemental group ids associated with the current process.
Availability: Unix.
Note
On Mac OS X,getgroups() behavior differs somewhat fromother Unix platforms. If the Python interpreter was built with adeployment target of10.5 or earlier,getgroups() returnsthe list of effective group ids associated with the current user process;this list is limited to a system-defined number of entries, typically 16,and may be modified by calls tosetgroups() if suitably privileged.If built with a deployment target greater than10.5,getgroups() returns the current group access list for the userassociated with the effective user id of the process; the group accesslist may change over the lifetime of the process, it is not affected bycalls tosetgroups(), and its length is not limited to 16. Thedeployment target value,MACOSX_DEPLOYMENT_TARGET, can beobtained withsysconfig.get_config_var().
Return the name of the user logged in on the controlling terminal of theprocess. For most purposes, it is more useful to use the environment variablesLOGNAME orUSERNAME to find out who the user is, orpwd.getpwuid(os.getuid())[0] to get the login name of the currentlyeffective user id.
Availability: Unix, Windows.
Return the process group id of the process with process idpid. Ifpid is 0,the process group id of the current process is returned.
Availability: Unix.
Return the id of the current process group.
Availability: Unix.
Return the current process id.
Availability: Unix, Windows.
Return the parent’s process id. When the parent process has exited, on Unixthe id returned is the one of the init process (1), on Windows it is stillthe same id, which may be already reused by another process.
Availability: Unix, Windows.
Changed in version 3.2:Added support for Windows.
Get program scheduling priority. The valuewhich is one ofPRIO_PROCESS,PRIO_PGRP, orPRIO_USER, andwhois interpreted relative towhich (a process identifier forPRIO_PROCESS, process group identifier forPRIO_PGRP, and auser ID forPRIO_USER). A zero value forwho denotes(respectively) the calling process, the process group of the calling process,or the real user ID of the calling process.
Availability: Unix.
New in version 3.3.
Parameters for thegetpriority() andsetpriority() functions.
Availability: Unix.
New in version 3.3.
Return a tuple (ruid, euid, suid) denoting the current process’sreal, effective, and saved user ids.
Availability: Unix.
New in version 3.2.
Return a tuple (rgid, egid, sgid) denoting the current process’sreal, effective, and saved group ids.
Availability: Unix.
New in version 3.2.
Return the current process’s user id.
Availability: Unix.
Call the system initgroups() to initialize the group access list with all ofthe groups of which the specified username is a member, plus the specifiedgroup id.
Availability: Unix.
New in version 3.2.
Set the environment variable namedkey to the stringvalue. Suchchanges to the environment affect subprocesses started withos.system(),popen() orfork() andexecv().
Availability: most flavors of Unix, Windows.
Note
On some platforms, including FreeBSD and Mac OS X, settingenviron maycause memory leaks. Refer to the system documentation for putenv.
Whenputenv() is supported, assignments to items inos.environ areautomatically translated into corresponding calls toputenv(); however,calls toputenv() don’t updateos.environ, so it is actuallypreferable to assign to items ofos.environ.
Set the current process’s effective group id.
Availability: Unix.
Set the current process’s effective user id.
Availability: Unix.
Set the current process’ group id.
Availability: Unix.
Set the list of supplemental group ids associated with the current process togroups.groups must be a sequence, and each element must be an integeridentifying a group. This operation is typically available only to the superuser.
Availability: Unix.
Note
On Mac OS X, the length ofgroups may not exceed thesystem-defined maximum number of effective group ids, typically 16.See the documentation forgetgroups() for cases where it may notreturn the same group list set by calling setgroups().
Call the system callsetpgrp() orsetpgrp(0,0) depending onwhich version is implemented (if any). See the Unix manual for the semantics.
Availability: Unix.
Call the system callsetpgid() to set the process group id of theprocess with idpid to the process group with idpgrp. See the Unix manualfor the semantics.
Availability: Unix.
Set program scheduling priority. The valuewhich is one ofPRIO_PROCESS,PRIO_PGRP, orPRIO_USER, andwhois interpreted relative towhich (a process identifier forPRIO_PROCESS, process group identifier forPRIO_PGRP, and auser ID forPRIO_USER). A zero value forwho denotes(respectively) the calling process, the process group of the calling process,or the real user ID of the calling process.priority is a value in the range -20 to 19. The default priority is 0;lower priorities cause more favorable scheduling.
Availability: Unix
New in version 3.3.
Set the current process’s real and effective group ids.
Availability: Unix.
Set the current process’s real, effective, and saved group ids.
Availability: Unix.
New in version 3.2.
Set the current process’s real, effective, and saved user ids.
Availability: Unix.
New in version 3.2.
Set the current process’s real and effective user ids.
Availability: Unix.
Call the system callgetsid(). See the Unix manual for the semantics.
Availability: Unix.
Call the system callsetsid(). See the Unix manual for the semantics.
Availability: Unix.
Set the current process’s user id.
Availability: Unix.
Return the error message corresponding to the error code incode.On platforms wherestrerror() returnsNULL when given an unknownerror number,ValueError is raised.
Availability: Unix, Windows.
True if the native OS type of the environment is bytes (eg.False onWindows).
New in version 3.2.
Set the current numeric umask and return the previous umask.
Availability: Unix, Windows.
Returns information identifying the current operating system.The return value is an object with five attributes:
For backwards compatibility, this object is also iterable, behavinglike a five-tuple containingsysname,nodename,release,version, andmachinein that order.
Some systems truncatenodename to 8 characters or to theleading component; a better way to get the hostname issocket.gethostname() or evensocket.gethostbyaddr(socket.gethostname()).
Availability: recent flavors of Unix.
Changed in version 3.3:Return type changed from a tuple to a tuple-like objectwith named attributes.
Unset (delete) the environment variable namedkey. Such changes to theenvironment affect subprocesses started withos.system(),popen() orfork() andexecv().
Whenunsetenv() is supported, deletion of items inos.environ isautomatically translated into a corresponding call tounsetenv(); however,calls tounsetenv() don’t updateos.environ, so it is actuallypreferable to delete items ofos.environ.
Availability: most flavors of Unix, Windows.
This function creates newfile objects. (See alsoopen() for opening file descriptors.)
These functions operate on I/O streams referenced using file descriptors.
File descriptors are small integers corresponding to a file that has been openedby the current process. For example, standard input is usually file descriptor0, standard output is 1, and standard error is 2. Further files opened by aprocess 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 referencedby file descriptors.
Thefileno() method can be used to obtain the file descriptorassociated with afile object when required. Note that using the filedescriptor directly will bypass the file object methods, ignoring aspects suchas internal buffering of data.
Close file descriptorfd.
Availability: Unix, Windows.
Close all file descriptors fromfd_low (inclusive) tofd_high (exclusive),ignoring errors. Equivalent to (but much faster than):
forfdinrange(fd_low,fd_high):try:os.close(fd)exceptOSError:pass
Availability: Unix, Windows.
Return a string describing the encoding of the device associated withfdif it is connected to a terminal; else returnNone.
Return a duplicate of file descriptorfd.
Availability: Unix, Windows.
Duplicate file descriptorfd tofd2, closing the latter first if necessary.
Availability: Unix, Windows.
Change the mode of the file given byfd to the numericmode. See thedocs forchmod() for possible values ofmode. As of Python 3.3, thisis equivalent toos.chmod(fd,mode).
Availability: Unix.
Change the owner and group id of the file given byfd to the numericuidandgid. To leave one of the ids unchanged, set it to -1. Seechown(). As of Python 3.3, this is equivalent toos.chown(fd,uid,gid).
Availability: Unix.
Force write of file with filedescriptorfd to disk. Does not force update ofmetadata.
Availability: Unix.
Note
This function is not available on MacOS.
Return system configuration information relevant to an open file.namespecifies the configuration value to retrieve; it may be a string which is thename of a defined system value; these names are specified in a number ofstandards (POSIX.1, Unix 95, Unix 98, and others). Some platforms defineadditional names as well. The names known to the host operating system aregiven in thepathconf_names dictionary. For configuration variables notincluded in that mapping, passing an integer forname is also accepted.
Ifname is a string and is not known,ValueError is raised. If aspecific value forname is not supported by the host system, even if it isincluded inpathconf_names, anOSError is raised witherrno.EINVAL for the error number.
As of Python 3.3, this is equivalent toos.pathconf(fd,name).
Availability: Unix.
Return status for file descriptorfd, likestat(). As of Python3.3, this is equivalent toos.stat(fd).
Availability: Unix, Windows.
Return information about the filesystem containing the file associated withfile descriptorfd, likestatvfs(). As of Python 3.3, this isequivalent toos.statvfs(fd).
Availability: Unix.
Force write of file with filedescriptorfd to disk. On Unix, this calls thenativefsync() function; on Windows, the MS_commit() function.
If you’re starting with a buffered Pythonfile objectf, first dof.flush(), and then doos.fsync(f.fileno()), to ensure that all internalbuffers associated withf are written to disk.
Availability: Unix, Windows.
Truncate the file corresponding to file descriptorfd, so that it is atmostlength bytes in size. As of Python 3.3, this is equivalent toos.truncate(fd,length).
Availability: Unix.
ReturnTrue if the file descriptorfd is open and connected to atty(-like) device, elseFalse.
Apply, test or remove a POSIX lock on an open file descriptor.fd is an open file descriptor.cmd specifies the command to use - one ofF_LOCK,F_TLOCK,F_ULOCK orF_TEST.len specifies the section of the file to lock.
Availability: Unix.
New in version 3.3.
Flags that specify what actionlockf() will take.
Availability: Unix.
New in version 3.3.
Set the current position of file descriptorfd to positionpos, modifiedbyhow:SEEK_SET or0 to set the position relative to thebeginning of the file;SEEK_CUR or1 to set it relative to thecurrent position;SEEK_END or2 to set it relative to the end ofthe file. Return the new cursor position in bytes, starting from the beginning.
Availability: Unix, Windows.
Parameters to thelseek() function. Their values are 0, 1, and 2,respectively.
Availability: Unix, Windows.
New in version 3.3:Some operating systems could support additional values, likeos.SEEK_HOLE oros.SEEK_DATA.
Open the filefile and set various flags according toflags and possiblyits mode according tomode. When computingmode, the current umask valueis first masked out. Return the file descriptor for the newly opened file.
For a description of the flag and mode values, see the C run-time documentation;flag constants (likeO_RDONLY andO_WRONLY) are defined inthis module too (seeopen() flag constants). In particular, on Windows addingO_BINARY is needed to open files in binary mode.
This function can supportpaths relative to directory descriptors.
Availability: Unix, Windows.
Note
This function is intended for low-level I/O. For normal usage, use thebuilt-in functionopen(), which returns afile object withread() andwrite() methods (and many more). Towrap a file descriptor in a file object, usefdopen().
New in version 3.3:Thedir_fd argument.
Open a new pseudo-terminal pair. Return a pair of file descriptors(master,slave) for the pty and the tty, respectively. For a (slightly) more portableapproach, use thepty module.
Availability: some flavors of Unix.
Create a pipe. Return a pair of file descriptors(r,w) usable for readingand writing, respectively.
Availability: Unix, Windows.
Create a pipe withflags set atomically.flags can be constructed by ORing together one or more of these values:O_NONBLOCK,O_CLOEXEC.Return a pair of file descriptors(r,w) usable for reading and writing,respectively.
Availability: some flavors of Unix.
New in version 3.3.
Ensures that enough disk space is allocated for the file specified byfdstarting fromoffset and continuing forlen bytes.
Availability: Unix.
New in version 3.3.
Announces an intention to access data in a specific pattern thus allowingthe kernel to make optimizations.The advice applies to the region of the file specified byfd starting atoffset and continuing forlen bytes.advice is one ofPOSIX_FADV_NORMAL,POSIX_FADV_SEQUENTIAL,POSIX_FADV_RANDOM,POSIX_FADV_NOREUSE,POSIX_FADV_WILLNEED orPOSIX_FADV_DONTNEED.
Availability: Unix.
New in version 3.3.
Flags that can be used inadvice inposix_fadvise() that specifythe access pattern that is likely to be used.
Availability: Unix.
New in version 3.3.
Read from a file descriptor,fd, at a position ofoffset. It will read uptobuffersize number of bytes. The file offset remains unchanged.
Availability: Unix.
New in version 3.3.
Writestring to a file descriptor,fd, fromoffset, leaving the fileoffset unchanged.
Availability: Unix.
New in version 3.3.
Read at mostn bytes from file descriptorfd. Return a bytestring containing thebytes read. If the end of the file referred to byfd has been reached, anempty bytes object is returned.
Availability: Unix, Windows.
Copynbytes bytes from file descriptorin to file descriptoroutstarting atoffset.Return the number of bytes sent. When EOF is reached return 0.
The first function notation is supported by all platforms that definesendfile().
On Linux, ifoffset is given asNone, the bytes are read from thecurrent position ofin and the position ofin is updated.
The second case may be used on Mac OS X and FreeBSD whereheaders andtrailers are arbitrary sequences of buffers that are written before andafter the data fromin is written. It returns the same as the first case.
On Mac OS X and FreeBSD, a value of 0 fornbytes specifies to send untilthe end ofin is reached.
All platforms support sockets asout file descriptor, and some platformsallow other types (e.g. regular file, pipe) as well.
Availability: Unix.
New in version 3.3.
Parameters to thesendfile() function, if the implementation supportsthem.
Availability: Unix.
New in version 3.3.
Read from a file descriptorfd into a number of mutablebytes-likeobjectsbuffers.readv() will transfer datainto each buffer until it is full and then move on to the next buffer in thesequence to hold the rest of the data.readv() returns the totalnumber of bytes read (which may be less than the total capacity of all theobjects).
Availability: Unix.
New in version 3.3.
Return the process group associated with the terminal given byfd (an openfile descriptor as returned byos.open()).
Availability: Unix.
Set the process group associated with the terminal given byfd (an open filedescriptor as returned byos.open()) topg.
Availability: Unix.
Return a string which specifies the terminal device associated withfile descriptorfd. Iffd is not associated with a terminal device, anexception is raised.
Availability: Unix.
Write the bytestring instr to file descriptorfd. Return the number ofbytes actually written.
Availability: Unix, Windows.
Note
This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To write a “fileobject” returned by the built-in functionopen() or bypopen() orfdopen(), orsys.stdout orsys.stderr, use itswrite() method.
Write the contents ofbuffers to file descriptorfd.buffers must be asequence ofbytes-like objects.writev() writes the contents of each object to the file descriptorand returns the total number of bytes written.
Availability: Unix.
New in version 3.3.
The following constants are options for theflags parameter to theopen() function. They can be combined using the bitwise OR operator|. Some of them are not available on all platforms. For descriptions oftheir availability and use, consult theopen(2) manual page on Unixorthe MSDN on Windows.
These constants are available on Unix and Windows.
These constants are only available on Unix.
Changed in version 3.3:AddO_CLOEXEC constant.
These constants are only available on Windows.
New in version 3.3.
Return the size of the terminal window as(columns,lines),tuple of typeterminal_size.
The optional argumentfd (defaultSTDOUT_FILENO, or standardoutput) specifies which file descriptor should be queried.
If the file descriptor is not connected to a terminal, anOSErroris raised.
shutil.get_terminal_size() is the high-level function whichshould normally be used,os.get_terminal_size is the low-levelimplementation.
Availability: Unix, Windows.
On some Unix platforms, many of these functions support one or more of thesefeatures:
specifying a file descriptor:For some functions, thepath argument can be not only a string giving a pathname, but also a file descriptor. The function will then operate on the filereferred to by the descriptor. (For POSIX systems, Python will call thef... version of the function.)
You can check whether or notpath can be specified as a file descriptor onyour platform usingos.supports_fd. If it is unavailable, using itwill raise aNotImplementedError.
If the function also supportsdir_fd orfollow_symlinks arguments, it isan error to specify one of those when supplyingpath as a file descriptor.
paths relative to directory descriptors: Ifdir_fd is notNone, itshould be a file descriptor referring to a directory, and the path to operateon should be relative; path will then be relative to that directory. If thepath is absolute,dir_fd is ignored. (For POSIX systems, Python will callthe...at orf...at version of the function.)
You can check whether or notdir_fd is supported on your platform usingos.supports_dir_fd. If it is unavailable, using it will raise aNotImplementedError.
not following symlinks: Iffollow_symlinks isFalse, and the last element of the path to operate on is a symbolic link,the function will operate on the symbolic link itself instead of the file thelink points to. (For POSIX systems, Python will call thel... version ofthe function.)
You can check whether or notfollow_symlinks is supported on your platformusingos.supports_follow_symlinks. If it is unavailable, using itwill raise aNotImplementedError.
Use the real uid/gid to test for access topath. Note that most operationswill use the effective uid/gid, therefore this routine can be used in asuid/sgid environment to test if the invoking user has the specified access topath.mode should beF_OK to test the existence ofpath, or itcan be the inclusive OR of one or more ofR_OK,W_OK, andX_OK to test permissions. ReturnTrue if access is allowed,False if not. See the Unix man pageaccess(2) for moreinformation.
This function can support specifyingpaths relative to directorydescriptors andnot following symlinks.
Ifeffective_ids isTrue,access() will perform its accesschecks using the effective uid/gid instead of the real uid/gid.effective_ids may not be supported on your platform; you can check whetheror not it is available usingos.supports_effective_ids. If it isunavailable, using it will raise aNotImplementedError.
Availability: Unix, Windows.
Note
Usingaccess() to check if a user is authorized to e.g. open a filebefore actually doing so usingopen() creates a security hole,because the user might exploit the short time interval between checkingand opening the file to manipulate it. It’s preferable to useEAFPtechniques. For example:
ifos.access("myfile",os.R_OK):withopen("myfile")asfp:returnfp.read()return"some default data"
is better written as:
try:fp=open("myfile")exceptPermissionError:return"some default data"else:withfp:returnfp.read()
Note
I/O operations may fail even whenaccess() indicates that they wouldsucceed, particularly for operations on network filesystems which may havepermissions semantics beyond the usual POSIX permission-bit model.
Changed in version 3.3:Added thedir_fd,effective_ids, andfollow_symlinks parameters.
Values to pass as themode parameter ofaccess() to test theexistence, readability, writability and executability ofpath,respectively.
Change the current working directory topath.
This function can supportspecifying a file descriptor. Thedescriptor must refer to an opened directory, not an open file.
Availability: Unix, Windows.
New in version 3.3:Added support for specifyingpath as a file descriptoron some platforms.
Set the flags ofpath to the numericflags.flags may take a combination(bitwise OR) of the following values (as defined in thestat module):
This function can supportnot following symlinks.
Availability: Unix.
New in version 3.3:Thefollow_symlinks argument.
Change the mode ofpath to the numericmode.mode may take one of thefollowing values (as defined in thestat module) or bitwise ORedcombinations of them:
This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.
Availability: Unix, Windows.
Note
Although Windows supportschmod(), you can only set the file’sread-only flag with it (via thestat.S_IWRITE andstat.S_IREADconstants or a corresponding integer value). All other bits are ignored.
New in version 3.3:Added support for specifyingpath as an open file descriptor,and thedir_fd andfollow_symlinks arguments.
Change the owner and group id ofpath to the numericuid andgid. Toleave one of the ids unchanged, set it to -1.
This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.
Seeshutil.chown() for a higher-level function that accepts names inaddition to numeric ids.
Availability: Unix.
New in version 3.3:Added support for specifying an open file descriptor forpath,and thedir_fd andfollow_symlinks arguments.
Change the root directory of the current process topath.
Availability: Unix.
Change the current working directory to the directory represented by the filedescriptorfd. The descriptor must refer to an opened directory, not anopen file. As of Python 3.3, this is equivalent toos.chdir(fd).
Availability: Unix.
Return a string representing the current working directory.
Availability: Unix, Windows.
Return a bytestring representing the current working directory.
Availability: Unix, Windows.
Set the flags ofpath to the numericflags, likechflags(), but donot follow symbolic links. As of Python 3.3, this is equivalent toos.chflags(path,flags,follow_symlinks=False).
Availability: Unix.
Change the mode ofpath to the numericmode. If path is a symlink, thisaffects the symlink rather than the target. See the docs forchmod()for possible values ofmode. As of Python 3.3, this is equivalent toos.chmod(path,mode,follow_symlinks=False).
Availability: Unix.
Change the owner and group id ofpath to the numericuid andgid. Thisfunction will not follow symbolic links. As of Python 3.3, this is equivalenttoos.chown(path,uid,gid,follow_symlinks=False).
Availability: Unix.
Create a hard link pointing tosrc nameddst.
This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors, andnotfollowing symlinks.
Availability: Unix, Windows.
Changed in version 3.2:Added Windows support.
New in version 3.3:Added thesrc_dir_fd,dst_dir_fd, andfollow_symlinks arguments.
Return a list containing the names of the entries in the directory given bypath. The list is in arbitrary order, and does not include the specialentries'.' and'..' even if they are present in the directory.
path may be either of typestr or of typebytes. Ifpathis of typebytes, the filenames returned will also be of typebytes;in all other circumstances, they will be of typestr.
This function can also supportspecifying a file descriptor; the file descriptor must refer to a directory.
Note
To encodestr filenames tobytes, usefsencode().
Availability: Unix, Windows.
Changed in version 3.2:Thepath parameter became optional.
New in version 3.3:Added support for specifying an open file descriptor forpath.
Perform the equivalent of anlstat() system call on the given path.Similar tostat(), but does not follow symbolic links. Onplatforms that do not support symbolic links, this is an alias forstat(). As of Python 3.3, this is equivalent toos.stat(path,dir_fd=dir_fd,follow_symlinks=False).
This function can also supportpaths relative to directory descriptors.
Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.
Changed in version 3.3:Added thedir_fd parameter.
Create a directory namedpath with numeric modemode.
On some systems,mode is ignored. Where it is used, the current umaskvalue is first masked out. If the directory already exists,OSErroris raised.
This function can also supportpaths relative to directory descriptors.
It is also possible to create temporary directories; see thetempfile module’stempfile.mkdtemp() function.
Availability: Unix, Windows.
New in version 3.3:Thedir_fd argument.
Recursive directory creation function. Likemkdir(), but makes allintermediate-level directories needed to contain the leaf directory.
The defaultmode is0o777 (octal). On some systems,mode isignored. Where it is used, the current umask value is first masked out.
Ifexist_ok isFalse (the default), anOSError is raised if thetarget directory already exists.
Note
makedirs() will become confused if the path elements to createincludepardir (eg. ”..” on UNIX systems).
This function handles UNC paths correctly.
New in version 3.2:Theexist_ok parameter.
Changed in version 3.3.6:Before Python 3.3.6, ifexist_ok wasTrue and the directory existed,makedirs() would still raise an error ifmode did not match themode of the existing directory. Since this behavior was impossible toimplement safely, it was removed in Python 3.3.6. Seeissue 21082.
Create a FIFO (a named pipe) namedpath with numeric modemode.The current umask value is first masked out from the mode.
This function can also supportpaths relative to directory descriptors.
FIFOs are pipes that can be accessed like regular files. FIFOs exist until theyare deleted (for example withos.unlink()). Generally, FIFOs are used asrendezvous between “client” and “server” type processes: the server opens theFIFO for reading, and the client opens it for writing. Note thatmkfifo()doesn’t open the FIFO — it just creates the rendezvous point.
Availability: Unix.
New in version 3.3:Thedir_fd argument.
Create a filesystem node (file, device special file or named pipe) namedfilename.mode specifies both the permissions to use and the type of nodeto be created, being combined (bitwise OR) with one ofstat.S_IFREG,stat.S_IFCHR,stat.S_IFBLK, andstat.S_IFIFO (those constants areavailable instat). Forstat.S_IFCHR andstat.S_IFBLK,device defines the newly created device special file (probably usingos.makedev()), otherwise it is ignored.
This function can also supportpaths relative to directory descriptors.
New in version 3.3:Thedir_fd argument.
Extract the device major number from a raw device number (usually thest_dev orst_rdev field fromstat).
Extract the device minor number from a raw device number (usually thest_dev orst_rdev field fromstat).
Compose a raw device number from the major and minor device numbers.
Return system configuration information relevant to a named file.namespecifies the configuration value to retrieve; it may be a string which is thename of a defined system value; these names are specified in a number ofstandards (POSIX.1, Unix 95, Unix 98, and others). Some platforms defineadditional names as well. The names known to the host operating system aregiven in thepathconf_names dictionary. For configuration variables notincluded in that mapping, passing an integer forname is also accepted.
Ifname is a string and is not known,ValueError is raised. If aspecific value forname is not supported by the host system, even if it isincluded inpathconf_names, anOSError is raised witherrno.EINVAL for the error number.
This function can supportspecifying a file descriptor.
Availability: Unix.
Dictionary mapping names accepted bypathconf() andfpathconf() tothe integer values defined for those names by the host operating system. Thiscan be used to determine the set of names known to the system.
Availability: Unix.
Return a string representing the path to which the symbolic link points. Theresult may be either an absolute or relative pathname; if it is relative, itmay be converted to an absolute pathname usingos.path.join(os.path.dirname(path),result).
If thepath is a string object, the result will also be a string object,and the call may raise an UnicodeDecodeError. If thepath is a bytesobject, the result will be a bytes object.
This function can also supportpaths relative to directory descriptors.
Availability: Unix, Windows
Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.
New in version 3.3:Thedir_fd argument.
Remove (delete) the filepath. Ifpath is a directory,OSError israised. Usermdir() to remove directories.
This function can supportpaths relative to directory descriptors.
On Windows, attempting to remove a file that is in use causes an exception tobe raised; on Unix, the directory entry is removed but the storage allocatedto the file is not made available until the original file is no longer in use.
This function is identical tounlink().
Availability: Unix, Windows.
New in version 3.3:Thedir_fd argument.
Remove directories recursively. Works likermdir() except that, if theleaf directory is successfully removed,removedirs() tries tosuccessively remove every parent directory mentioned inpath until an erroris raised (which is ignored, because it generally means that a parent directoryis not empty). For example,os.removedirs('foo/bar/baz') will first removethe directory'foo/bar/baz', and then remove'foo/bar' and'foo' ifthey are empty. RaisesOSError if the leaf directory could not besuccessfully removed.
Rename the file or directorysrc todst. Ifdst is a directory,OSError will be raised. On Unix, ifdst exists and is a file, it willbe replaced silently if the user has permission. The operation may fail on someUnix flavors ifsrc anddst are on different filesystems. If successful,the renaming will be an atomic operation (this is a POSIX requirement). OnWindows, ifdst already exists,OSError will be raised even if it is afile.
This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors.
If you want cross-platform overwriting of the destination, usereplace().
Availability: Unix, Windows.
New in version 3.3:Thesrc_dir_fd anddst_dir_fd arguments.
Recursive directory or file renaming function. Works likerename(), exceptcreation of any intermediate directories needed to make the new pathname good isattempted first. After the rename, directories corresponding to rightmost pathsegments of the old name will be pruned away usingremovedirs().
Note
This function can fail with the new directory structure made if you lackpermissions needed to remove the leaf directory or file.
Rename the file or directorysrc todst. Ifdst is a directory,OSError will be raised. Ifdst exists and is a file, it willbe replaced silently if the user has permission. The operation may failifsrc anddst are on different filesystems. If successful,the renaming will be an atomic operation (this is a POSIX requirement).
This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors.
Availability: Unix, Windows.
New in version 3.3.
Remove (delete) the directorypath. Only works when the directory isempty, otherwise,OSError is raised. In order to remove wholedirectory trees,shutil.rmtree() can be used.
This function can supportpaths relative to directory descriptors.
Availability: Unix, Windows.
New in version 3.3:Thedir_fd parameter.
Perform the equivalent of astat() system call on the given path.path may be specified as either a string or as an open file descriptor.(This function normally follows symlinks; to stat a symlink add the argumentfollow_symlinks=False, or uselstat().)
The return value is an object whose attributes correspond roughlyto the members of thestat structure, namely:
On some Unix systems (such as Linux), the following attributes may also beavailable:
On other Unix systems (such as FreeBSD), the following attributes may beavailable (but may be only filled out if root tries to use them):
On Mac OS systems, the following attributes may also be available:
Note
The exact meaning and resolution of thest_atime,st_mtime, andst_ctime attributes depend on the operatingsystem and the file system. For example, on Windows systems using the FATor FAT32 file systems,st_mtime has 2-second resolution, andst_atime has only 1-day resolution. See your operating systemdocumentation for details.Similarly, althoughst_atime_ns,st_mtime_ns,andst_ctime_ns are always expressed in nanoseconds, manysystems do not provide nanosecond precision. On systems that doprovide nanosecond precision, the floating-point object used tostorest_atime,st_mtime, andst_ctimecannot preserve all of it, and as such will be slightly inexact.If you need the exact timestamps you should always usest_atime_ns,st_mtime_ns, andst_ctime_ns.
For backward compatibility, the return value ofstat() is alsoaccessible as a tuple of at least 10 integers giving the most important (andportable) members of thestat structure, in the orderst_mode,st_ino,st_dev,st_nlink,st_uid,st_gid,st_size,st_atime,st_mtime,st_ctime. More items may be added at the end bysome implementations.
This function can supportspecifying a file descriptor andnot following symlinks.
The standard modulestat defines functions and constants that are usefulfor extracting information from astat structure. (On Windows, someitems are filled with dummy values.)
Example:
>>>importos>>>statinfo=os.stat('somefile.txt')>>>statinfoposix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,st_mtime=1297230027, st_ctime=1297230027)>>>statinfo.st_size264
Availability: Unix, Windows.
New in version 3.3:Added thedir_fd andfollow_symlinks arguments,specifying a file descriptor instead of a path,and thest_atime_ns,st_mtime_ns,andst_ctime_ns members.
Determine whetherstat_result represents time stamps as float objects.Ifnewvalue isTrue, future calls tostat() return floats, if it isFalse, future calls return ints. Ifnewvalue is omitted, return thecurrent setting.
For compatibility with older Python versions, accessingstat_result asa tuple always returns integers.
Python now returns float values by default. Applications which do not workcorrectly with floating point time stamps can use this function to restore theold behaviour.
The resolution of the timestamps (that is the smallest possible fraction)depends on the system. Some systems only support second resolution; on thesesystems, the fraction will always be zero.
It is recommended that this setting is only changed at program startup time inthe__main__ module; libraries should never change this setting. If anapplication uses a library that works incorrectly if floating point time stampsare processed, this application should turn the feature off until the libraryhas been corrected.
Deprecated since version 3.3.
Perform astatvfs() system call on the given path. The return value isan object whose attributes describe the filesystem on the given path, andcorrespond to the members of thestatvfs structure, namely:f_bsize,f_frsize,f_blocks,f_bfree,f_bavail,f_files,f_ffree,f_favail,f_flag,f_namemax.
Two module-level constants are defined for thef_flag attribute’sbit-flags: ifST_RDONLY is set, the filesystem is mountedread-only, and ifST_NOSUID is set, the semantics ofsetuid/setgid bits are disabled or not supported.
This function can supportspecifying a file descriptor.
Changed in version 3.2:TheST_RDONLY andST_NOSUID constants were added.
Availability: Unix.
New in version 3.3:Added support for specifying an open file descriptor forpath.
ASet object indicating which functions in theos module permit use of theirdir_fd parameter. Different platformsprovide different functionality, and an option that might work on one mightbe unsupported on another. For consistency’s sakes, functions that supportdir_fd always allow specifying the parameter, but will raise an exceptionif the functionality is not actually available.
To check whether a particular function permits use of itsdir_fdparameter, use thein operator onsupports_dir_fd. As an example,this expression determines whether thedir_fd parameter ofos.stat()is locally available:
os.statinos.supports_dir_fd
Currentlydir_fd parameters only work on Unix platforms; none of them workon Windows.
New in version 3.3.
ASet object indicating which functions in theos module permit use of theeffective_ids parameter foros.access(). If the local platform supports it, the collection willcontainos.access(), otherwise it will be empty.
To check whether you can use theeffective_ids parameter foros.access(), use thein operator onsupports_dir_fd, like so:
os.accessinos.supports_effective_ids
Currentlyeffective_ids only works on Unix platforms; it does not work onWindows.
New in version 3.3.
ASet object indicating which functions in theos module permit specifying theirpath parameter as an open filedescriptor. Different platforms provide different functionality, and anoption that might work on one might be unsupported on another. Forconsistency’s sakes, functions that supportfd always allow specifyingthe parameter, but will raise an exception if the functionality is notactually available.
To check whether a particular function permits specifying an open filedescriptor for itspath parameter, use thein operator onsupports_fd. As an example, this expression determines whetheros.chdir() accepts open file descriptors when called on your localplatform:
os.chdirinos.supports_fd
New in version 3.3.
ASet object indicating which functions in theos module permit use of theirfollow_symlinks parameter. Differentplatforms provide different functionality, and an option that might work onone might be unsupported on another. For consistency’s sakes, functions thatsupportfollow_symlinks always allow specifying the parameter, but willraise an exception if the functionality is not actually available.
To check whether a particular function permits use of itsfollow_symlinksparameter, use thein operator onsupports_follow_symlinks. As anexample, this expression determines whether thefollow_symlinks parameterofos.stat() is locally available:
os.statinos.supports_follow_symlinks
New in version 3.3.
Create a symbolic link pointing tosource namedlink_name.
On Windows, a symlink represents either a file or a directory, and does notmorph to the target dynamically. If the target is present, the type of thesymlink will be created to match. Otherwise, the symlink will be createdas a directory iftarget_is_directory isTrue or a file symlink (thedefault) otherwise. On non-Window platforms,target_is_directory is ignored.
Symbolic link support was introduced in Windows 6.0 (Vista).symlink()will raise aNotImplementedError on Windows versions earlier than 6.0.
This function can supportpaths relative to directory descriptors.
Note
On Windows, theSeCreateSymbolicLinkPrivilege is required in order tosuccessfully create symlinks. This privilege is not typically granted toregular users but is available to accounts which can escalate privilegesto the administrator level. Either obtaining the privilege or running yourapplication as an administrator are ways to successfully create symlinks.
OSError is raised when the function is called by an unprivilegeduser.
Availability: Unix, Windows.
Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.
New in version 3.3:Added thedir_fd argument, and now allowtarget_is_directoryon non-Windows platforms.
Force write of everything to disk.
Availability: Unix.
New in version 3.3.
Truncate the file corresponding topath, so that it is at mostlength bytes in size.
This function can supportspecifying a file descriptor.
Availability: Unix.
New in version 3.3.
Remove (delete) the filepath. This function is identical toremove(); theunlink name is its traditional Unixname. Please see the documentation forremove() forfurther information.
Availability: Unix, Windows.
New in version 3.3:Thedir_fd parameter.
Set the access and modified times of the file specified bypath.
utime() takes two optional parameters,times andns.These specify the times set onpath and are used as follows:
It is an error to specify tuples for bothtimes andns.
Whether a directory can be given forpathdepends on whether the operating system implements directories as files(for example, Windows does not). Note that the exact times you set here maynot be returned by a subsequentstat() call, depending on theresolution with which your operating system records access and modificationtimes; seestat(). The best way to preserve exact times is touse thest_atime_ns andst_mtime_ns fields from theos.stat()result object with thens parameter toutime.
This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.
Availability: Unix, Windows.
New in version 3.3:Added support for specifying an open file descriptor forpath,and thedir_fd,follow_symlinks, andns parameters.
Generate the file names in a directory tree by walking the treeeither top-down or bottom-up. For each directory in the tree rooted at directorytop (includingtop itself), it yields a 3-tuple(dirpath,dirnames,filenames).
dirpath is a string, the path to the directory.dirnames is a list of thenames of the subdirectories indirpath (excluding'.' and'..').filenames is a list of the names of the non-directory files indirpath.Note that the names in the lists contain no path components. To get a full path(which begins withtop) to a file or directory indirpath, doos.path.join(dirpath,name).
If optional argumenttopdown isTrue or not specified, the triple for adirectory is generated before the triples for any of its subdirectories(directories are generated top-down). Iftopdown isFalse, the triple for adirectory is generated after the triples for all of its subdirectories(directories are generated bottom-up).
Whentopdown isTrue, the caller can modify thedirnames list in-place(perhaps usingdel or slice assignment), andwalk() will onlyrecurse into the subdirectories whose names remain indirnames; this can beused to prune the search, impose a specific order of visiting, or even to informwalk() about directories the caller creates or renames before it resumeswalk() again. Modifyingdirnames whentopdown isFalse isineffective, because in bottom-up mode the directories indirnames aregenerated beforedirpath itself is generated.
By default, errors from thelistdir() call are ignored. If optionalargumentonerror is specified, it should be a function; it will be called withone argument, anOSError instance. It can report the error to continuewith the walk, or raise the exception to abort the walk. Note that the filenameis available as thefilename attribute of the exception object.
By default,walk() will not walk down into symbolic links that resolve todirectories. Setfollowlinks toTrue to visit directories pointed to bysymlinks, on systems that support them.
Note
Be aware that settingfollowlinks toTrue can lead to infiniterecursion if a link points to a parent directory of itself.walk()does not keep track of the directories it visited already.
Note
If you pass a relative pathname, don’t change the current working directorybetween resumptions ofwalk().walk() never changes the currentdirectory, and assumes that its caller doesn’t either.
This example displays the number of bytes taken by non-directory files in eachdirectory under the starting directory, except that it doesn’t look under anyCVS subdirectory:
importosfromos.pathimportjoin,getsizeforroot,dirs,filesinos.walk('python/Lib/email'):print(root,"consumes",end=" ")print(sum(getsize(join(root,name))fornameinfiles),end=" ")print("bytes in",len(files),"non-directory files")if'CVS'indirs:dirs.remove('CVS')# don't visit CVS directories
In the next example, walking the tree bottom-up is essential:rmdir()doesn’t allow deleting a directory before the directory is empty:
# 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.importosforroot,dirs,filesinos.walk(top,topdown=False):fornameinfiles:os.remove(os.path.join(root,name))fornameindirs:os.rmdir(os.path.join(root,name))
This behaves exactly likewalk(), except that it yields a 4-tuple(dirpath,dirnames,filenames,dirfd), and it supportsdir_fd.
dirpath,dirnames andfilenames are identical towalk() output,anddirfd is a file descriptor referring to the directorydirpath.
This function always supportspaths relative to directory descriptors andnot following symlinks. Note howeverthat, unlike other functions, thefwalk() default value forfollow_symlinks isFalse.
Note
Sincefwalk() yields file descriptors, those are only valid untilthe next iteration step, so you should duplicate them (e.g. withdup()) if you want to keep them longer.
This example displays the number of bytes taken by non-directory files in eachdirectory under the starting directory, except that it doesn’t look under anyCVS subdirectory:
importosforroot,dirs,files,rootfdinos.fwalk('python/Lib/email'):print(root,"consumes",end="")print(sum([os.stat(name,dir_fd=rootfd).st_sizefornameinfiles]),end="")print("bytes in",len(files),"non-directory files")if'CVS'indirs:dirs.remove('CVS')# don't visit CVS directories
In the next example, walking the tree bottom-up is essential:rmdir() doesn’t allow deleting a directory before the directory isempty:
# 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.importosforroot,dirs,files,rootfdinos.fwalk(top,topdown=False):fornameinfiles:os.unlink(name,dir_fd=rootfd)fornameindirs:os.rmdir(name,dir_fd=rootfd)
Availability: Unix.
New in version 3.3.
New in version 3.3.
These functions are all available on Linux only.
Return the value of the extended filesystem attributeattribute forpath.attribute can be bytes or str. If it is str, it is encodedwith the filesystem encoding.
This function can supportspecifying a file descriptor andnot following symlinks.
Return a list of the extended filesystem attributes onpath. Theattributes in the list are represented as strings decoded with the filesystemencoding. Ifpath isNone,listxattr() will examine the currentdirectory.
This function can supportspecifying a file descriptor andnot following symlinks.
Removes the extended filesystem attributeattribute frompath.attribute should be bytes or str. If it is a string, it is encodedwith the filesystem encoding.
This function can supportspecifying a file descriptor andnot following symlinks.
Set the extended filesystem attributeattribute onpath tovalue.attribute must be a bytes or str with no embedded NULs. If it is a str,it is encoded with the filesystem encoding.flags may beXATTR_REPLACE orXATTR_CREATE. IfXATTR_REPLACE isgiven and the attribute does not exist,EEXISTS will be raised.IfXATTR_CREATE is given and the attribute already exists, theattribute will not be created andENODATA will be raised.
This function can supportspecifying a file descriptor andnot following symlinks.
Note
A bug in Linux kernel versions less than 2.6.39 caused the flags argumentto be ignored on some filesystems.
The maximum size the value of an extended attribute can be. Currently, thisis 64 KiB on Linux.
This is a possible value for the flags argument insetxattr(). Itindicates the operation must create an attribute.
This is a possible value for the flags argument insetxattr(). Itindicates the operation must replace an existing attribute.
These functions may be used to create and manage processes.
The variousexec* functions take a list of arguments for the newprogram loaded into the process. In each case, the first of these arguments ispassed to the new program as its own name rather than as an argument a user mayhave typed on a command line. For the C programmer, this is theargv[0]passed to a program’smain(). For example,os.execv('/bin/echo',['foo','bar']) will only printbar on standard output;foo will seemto be ignored.
Generate aSIGABRT signal to the current process. On Unix, the defaultbehavior is to produce a core dump; on Windows, the process immediately returnsan exit code of3. Be aware that calling this function will not call thePython signal handler registered forSIGABRT withsignal.signal().
Availability: Unix, Windows.
These functions all execute a new program, replacing the current process; theydo 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 asOSError exceptions.
The current process is replaced immediately. Open file objects anddescriptors are not flushed, so if there may be data bufferedon these open files, you should flush them usingsys.stdout.flush() oros.fsync() before calling anexec* function.
The “l” and “v” variants of theexec* functions differ in howcommand-line arguments are passed. The “l” variants are perhaps the easiestto work with if the number of parameters is fixed when the code is written; theindividual parameters simply become additional parameters to theexecl*()functions. The “v” variants are good when the number of parameters isvariable, with the arguments being passed in a list or tuple as theargsparameter. In either case, the arguments to the child process should start withthe name of the command being run, but this is not enforced.
The variants which include a “p” near the end (execlp(),execlpe(),execvp(), andexecvpe()) will use thePATH environment variable to locate the programfile. When theenvironment is being replaced (using one of theexec*e variants,discussed in the next paragraph), the new environment is used as the source ofthePATH variable. The other variants,execl(),execle(),execv(), andexecve(), will not use thePATH variable tolocate the executable;path must contain an appropriate absolute or relativepath.
Forexecle(),execlpe(),execve(), andexecvpe() (notethat these all end in “e”), theenv parameter must be a mapping which isused to define the environment variables for the new process (these are usedinstead of the current process’ environment); the functionsexecl(),execlp(),execv(), andexecvp() all cause the new process toinherit the environment of the current process.
Forexecve() on some platforms,path may also be specified as an openfile descriptor. This functionality may not be supported on your platform;you can check whether or not it is available usingos.supports_fd.If it is unavailable, using it will raise aNotImplementedError.
Availability: Unix, Windows.
New in version 3.3:Added support for specifying an open file descriptor forpathforexecve().
Exit the process with statusn, without calling cleanup handlers, flushingstdio buffers, etc.
Availability: Unix, Windows.
The following exit codes are defined and can be used with_exit(),although they are not required. These are typically used for system programswritten 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 somevariation. These constants are defined where they are defined by the underlyingplatform.
Exit code that means no error occurred.
Availability: Unix.
Exit code that means the command was used incorrectly, such as when the wrongnumber of arguments are given.
Availability: Unix.
Exit code that means the input data was incorrect.
Availability: Unix.
Exit code that means an input file did not exist or was not readable.
Availability: Unix.
Exit code that means a specified user did not exist.
Availability: Unix.
Exit code that means a specified host did not exist.
Availability: Unix.
Exit code that means that a required service is unavailable.
Availability: Unix.
Exit code that means an internal software error was detected.
Availability: Unix.
Exit code that means an operating system error was detected, such as theinability to fork or create a pipe.
Availability: Unix.
Exit code that means some system file did not exist, could not be opened, or hadsome other kind of error.
Availability: Unix.
Exit code that means a user specified output file could not be created.
Availability: Unix.
Exit code that means that an error occurred while doing I/O on some file.
Availability: Unix.
Exit code that means a temporary failure occurred. This indicates somethingthat may not really be an error, such as a network connection that couldn’t bemade during a retryable operation.
Availability: Unix.
Exit code that means that a protocol exchange was illegal, invalid, or notunderstood.
Availability: Unix.
Exit code that means that there were insufficient permissions to perform theoperation (but not intended for file system problems).
Availability: Unix.
Exit code that means that some kind of configuration error occurred.
Availability: Unix.
Exit code that means something like “an entry was not found”.
Availability: Unix.
Fork a child process. Return0 in the child and the child’s process id in theparent. If an error occursOSError is raised.
Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX haveknown issues when using fork() from a thread.
Warning
Seessl for applications that use the SSL module with fork().
Availability: Unix.
Fork a child process, using a new pseudo-terminal as the child’s controllingterminal. Return a pair of(pid,fd), wherepid is0 in the child, thenew child’s process id in the parent, andfd is the file descriptor of themaster end of the pseudo-terminal. For a more portable approach, use thepty module. If an error occursOSError is raised.
Availability: some flavors of Unix.
Send signalsig to the processpid. Constants for the specific signalsavailable on the host platform are defined in thesignal module.
Windows: Thesignal.CTRL_C_EVENT andsignal.CTRL_BREAK_EVENT signals are special signals which canonly be sent to console processes which share a common console window,e.g., some subprocesses. Any other value forsig will cause the processto be unconditionally killed by the TerminateProcess API, and the exit codewill be set tosig. The Windows version ofkill() additionally takesprocess handles to be killed.
See alsosignal.pthread_kill().
New in version 3.2:Windows support.
Send the signalsig to the process grouppgid.
Availability: Unix.
Addincrement to the process’s “niceness”. Return the new niceness.
Availability: Unix.
Lock program segments into memory. The value ofop (defined in<sys/lock.h>) determines which segments are locked.
Availability: Unix.
Run child processes, returning opened pipes for communications. These functionsare described in sectionFile Object Creation.
Execute the programpath in a new process.
(Note that thesubprocess module provides more powerful facilities forspawning new processes and retrieving their results; using that module ispreferable to using these functions. Check especially theReplacing Older Functions with the subprocess Module section.)
Ifmode isP_NOWAIT, this function returns the process id of the newprocess; ifmode isP_WAIT, returns the process’s exit code if itexits normally, or-signal, wheresignal is the signal that killed theprocess. On Windows, the process id will actually be the process handle, so canbe used with thewaitpid() function.
The “l” and “v” variants of thespawn* functions differ in howcommand-line arguments are passed. The “l” variants are perhaps the easiestto work with if the number of parameters is fixed when the code is written; theindividual parameters simply become additional parameters to thespawnl*() functions. The “v” variants are good when the number ofparameters is variable, with the arguments being passed in a list or tuple astheargs parameter. In either case, the arguments to the child process muststart with the name of the command being run.
The variants which include a second “p” near the end (spawnlp(),spawnlpe(),spawnvp(), andspawnvpe()) will use thePATH environment variable to locate the programfile. When theenvironment is being replaced (using one of thespawn*e variants,discussed in the next paragraph), the new environment is used as the source ofthePATH variable. The other variants,spawnl(),spawnle(),spawnv(), andspawnve(), will not use thePATH variable to locate the executable;path must contain anappropriate absolute or relative path.
Forspawnle(),spawnlpe(),spawnve(), andspawnvpe()(note that these all end in “e”), theenv parameter must be a mappingwhich is used to define the environment variables for the new process (they areused instead of the current process’ environment); the functionsspawnl(),spawnlp(),spawnv(), andspawnvp() all causethe new process to inherit the environment of the current process. Note thatkeys and values in theenv dictionary must be strings; invalid keys orvalues will cause the function to fail, with a return value of127.
As an example, the following calls tospawnlp() andspawnvpe() areequivalent:
importosos.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)
Availability: Unix, Windows.spawnlp(),spawnlpe(),spawnvp()andspawnvpe() are not available on Windows.spawnle() andspawnve() are not thread-safe on Windows; we advise you to use thesubprocess module instead.
Possible values for themode parameter to thespawn* family offunctions. If either of these values is given, thespawn*() functionswill return as soon as the new process has been created, with the process id asthe return value.
Availability: Unix, Windows.
Possible value for themode parameter to thespawn* family offunctions. If this is given asmode, thespawn*() functions will notreturn until the new process has run to completion and will return the exit codeof the process the run is successful, or-signal if a signal kills theprocess.
Availability: Unix, Windows.
Possible values for themode parameter to thespawn* family offunctions. These are less portable than those listed above.P_DETACHis similar toP_NOWAIT, but the new process is detached from theconsole of the calling process. IfP_OVERLAY is used, the currentprocess will be replaced; thespawn* function will not return.
Availability: Windows.
Start a file with its associated application.
Whenoperation is not specified or'open', this acts like double-clickingthe file in Windows Explorer, or giving the file name as an argument to thestart command from the interactive command shell: the file is openedwith whatever application (if any) its extension is associated.
When anotheroperation is given, it must be a “command verb” that specifieswhat should be done with the file. Common verbs documented by Microsoft are'print' and'edit' (to be used on files) as well as'explore' and'find' (to be used on directories).
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 retrievethe application’s exit status. Thepath parameter is relative to the currentdirectory. If you want to use an absolute path, make sure the first characteris not a slash ('/'); the underlying Win32ShellExecute() functiondoesn’t work if it is. Use theos.path.normpath() function to ensure thatthe path is properly encoded for Win32.
Availability: Windows.
Execute the command (a string) in a subshell. This is implemented by callingthe Standard C functionsystem(), and has the same limitations.Changes tosys.stdin, etc. are not reflected in the environment ofthe executed command. Ifcommand generates any output, it will be sent tothe interpreter standard output stream.
On Unix, the return value is the exit status of the process encoded in theformat specified forwait(). Note that POSIX does not specify themeaning of the return value of the Csystem() function, so the returnvalue of the Python function is system-dependent.
On Windows, the return value is that returned by the system shell afterrunningcommand. The shell is given by the Windows environment variableCOMSPEC: it is usuallycmd.exe, which returns the exitstatus of the command run; on systems using a non-native shell, consult yourshell documentation.
Thesubprocess module provides more powerful facilities for spawningnew processes and retrieving their results; using that module is preferableto using this function. See theReplacing Older Functions with the subprocess Module section inthesubprocess documentation for some helpful recipes.
Availability: Unix, Windows.
Returns the current global process times.The return value is an object with five attributes:
For backwards compatibility, this object also behaves like a five-tuplecontaininguser,system,children_user,children_system, andelapsed in that order.
See the Unix manual pagetimes(2) or the corresponding Windows Platform API documentation.On Windows, onlyuser andsystem are known; the otherattributes are zero.On OS/2, onlyelapsed is known; the other attributes are zero.
Availability: Unix, Windows.
Changed in version 3.3:Return type changed from a tuple to a tuple-like objectwith named attributes.
Wait for completion of a child process, and return a tuple containing its pidand exit status indication: a 16-bit number, whose low byte is the signal numberthat killed the process, and whose high byte is the exit status (if the signalnumber is zero); the high bit of the low byte is set if a core file wasproduced.
Availability: Unix.
Wait for the completion of one or more child processes.idtype can beP_PID,P_PGID orP_ALL.id specifies the pid to wait on.options is constructed from the ORing of one or more ofWEXITED,WSTOPPED orWCONTINUED and additionally may be ORed withWNOHANG orWNOWAIT. The return value is an objectrepresenting the data contained in thesiginfo_t structure, namely:si_pid,si_uid,si_signo,si_status,si_code orNone ifWNOHANG is specified and there are nochildren in a waitable state.
Availability: Unix.
New in version 3.3.
These are the possible values foridtype inwaitid(). They affecthowid is interpreted.
Availability: Unix.
New in version 3.3.
Flags that can be used inoptions inwaitid() that specify whatchild signal to wait for.
Availability: Unix.
New in version 3.3.
These are the possible values forsi_code in the result returned bywaitid().
Availability: Unix.
New in version 3.3.
The details of this function differ on Unix and Windows.
On Unix: Wait for completion of a child process given by process idpid, andreturn a tuple containing its process id and exit status indication (encoded asforwait()). The semantics of the call are affected by the value of theintegeroptions, which should be0 for normal operation.
Ifpid is greater than0,waitpid() requests status information forthat specific process. Ifpid is0, the request is for the status of anychild in the process group of the current process. Ifpid is-1, therequest pertains to any child of the current process. Ifpid is less than-1, status is requested for any process in the process group-pid (theabsolute value ofpid).
AnOSError is raised with the value of errno when the syscallreturns -1.
On Windows: Wait for completion of a process given by process handlepid, andreturn a tuple containingpid, and its exit status shifted left by 8 bits(shifting makes cross-platform use of the function easier). Apid less than orequal to0 has no special meaning on Windows, and raises an exception. Thevalue of integeroptions has no effect.pid can refer to any process whoseid is known, not necessarily a child process. Thespawn*functions called withP_NOWAIT return suitable process handles.
Similar towaitpid(), except no process id argument is given and a3-element tuple containing the child’s process id, exit status indication, andresource usage information is returned. Refer toresource.getrusage() for details on resource usage information. Theoption argument is the same as that provided towaitpid() andwait4().
Availability: Unix.
Similar towaitpid(), except a 3-element tuple, containing the child’sprocess id, exit status indication, and resource usage information is returned.Refer toresource.getrusage() for details onresource usage information. The arguments towait4() are the sameas those provided towaitpid().
Availability: Unix.
The option forwaitpid() to return immediately if no child process statusis available immediately. The function returns(0,0) in this case.
Availability: Unix.
This option causes child processes to be reported if they have been continuedfrom a job control stop since their status was last reported.
Availability: some Unix systems.
This option causes child processes to be reported if they have been stopped buttheir current state has not been reported since they were stopped.
Availability: Unix.
The following functions take a process status code as returned bysystem(),wait(), orwaitpid() as a parameter. They may beused to determine the disposition of a process.
ReturnTrue if a core dump was generated for the process, otherwisereturnFalse.
Availability: Unix.
ReturnTrue if the process has been continued from a job control stop,otherwise returnFalse.
Availability: Unix.
ReturnTrue if the process has been stopped, otherwise returnFalse.
Availability: Unix.
ReturnTrue if the process exited due to a signal, otherwise returnFalse.
Availability: Unix.
ReturnTrue if the process exited using theexit(2) system call,otherwise returnFalse.
Availability: Unix.
IfWIFEXITED(status) is true, return the integer parameter to theexit(2) system call. Otherwise, the return value is meaningless.
Availability: Unix.
Return the signal which caused the process to stop.
Availability: Unix.
Return the signal which caused the process to exit.
Availability: Unix.
These functions control how a process is allocated CPU time by the operatingsystem. They are only available on some Unix platforms. For more detailedinformation, consult your Unix manpages.
New in version 3.3.
The following scheduling policies are exposed if they are a supported by theoperating system.
The default scheduling policy.
Scheduling policy for CPU-intensive processes that tries to preserveinteractivity on the rest of the computer.
Scheduling policy for extremely low priority background tasks.
Scheduling policy for sporadic server programs.
A First In First Out scheduling policy.
A round-robin scheduling policy.
This flag can OR’ed with any other scheduling policy. When a process withthis flag set forks, its child’s scheduling policy and priority are reset tothe default.
This class represents tunable scheduling parameters used insched_setparam(),sched_setscheduler(), andsched_getparam(). It is immutable.
At the moment, there is only one possible parameter:
The scheduling priority for a scheduling policy.
Get the minimum priority value forpolicy.policy is one of thescheduling policy constants above.
Get the maximum priority value forpolicy.policy is one of thescheduling policy constants above.
Set the scheduling policy for the process with PIDpid. Apid of 0 meansthe calling process.policy is one of the scheduling policy constantsabove.param is asched_param instance.
Return the scheduling policy for the process with PIDpid. Apid of 0means the calling process. The result is one of the scheduling policyconstants above.
Set a scheduling parameters for the process with PIDpid. Apid of 0 meansthe calling process.param is asched_param instance.
Return the scheduling parameters as asched_param instance for theprocess with PIDpid. Apid of 0 means the calling process.
Return the round-robin quantum in seconds for the process with PIDpid. Apid of 0 means the calling process.
Voluntarily relinquish the CPU.
Restrict the process with PIDpid (or the current process if zero) to aset of CPUs.mask is an iterable of integers representing the set ofCPUs to which the process should be restricted.
Return the set of CPUs the process with PIDpid (or the current processif zero) is restricted to.
See also
multiprocessing.cpu_count() returns the number of CPUs in thesystem.
Return string-valued system configuration values.name specifies theconfiguration value to retrieve; it may be a string which is the name of adefined 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 theconfstr_names dictionary. For configuration variables not included in thatmapping, passing an integer forname is also accepted.
If the configuration value specified byname isn’t defined,None isreturned.
Ifname is a string and is not known,ValueError is raised. If aspecific value forname is not supported by the host system, even if it isincluded inconfstr_names, anOSError is raised witherrno.EINVAL for the error number.
Availability: Unix.
Dictionary mapping names accepted byconfstr() to the integer valuesdefined for those names by the host operating system. This can be used todetermine the set of names known to the system.
Availability: Unix.
Return the number of processes in the system run queue averaged over the last1, 5, and 15 minutes or raisesOSError if the load average wasunobtainable.
Availability: Unix.
Return integer-valued system configuration values. If the configuration valuespecified byname isn’t defined,-1 is returned. The comments regardingthename parameter forconfstr() apply here as well; the dictionary thatprovides information on the known names is given bysysconf_names.
Availability: Unix.
Dictionary mapping names accepted bysysconf() to the integer valuesdefined for those names by the host operating system. This can be used todetermine the set of names known to the system.
Availability: Unix.
The following data values are used to support path manipulation operations. Theseare defined for all platforms.
Higher-level operations on pathnames are defined in theos.path module.
The constant string used by the operating system to refer to the currentdirectory. This is'.' for Windows and POSIX. Also available viaos.path.
The constant string used by the operating system to refer to the parentdirectory. This is'..' for Windows and POSIX. Also available viaos.path.
The character used by the operating system to separate pathname components.This is'/' for POSIX and'\\' for Windows. Note that knowing thisis not sufficient to be able to parse or concatenate pathnames — useos.path.split() andos.path.join() — but it is occasionallyuseful. Also available viaos.path.
An alternative character used by the operating system to separate pathnamecomponents, orNone if only one separator character exists. This is set to'/' on Windows systems wheresep is a backslash. Also available viaos.path.
The character which separates the base filename from the extension; for example,the'.' inos.py. Also available viaos.path.
The character conventionally used by the operating system to separate searchpath components (as inPATH), such as':' for POSIX or';' forWindows. Also available viaos.path.
The default search path used byexec*p* andspawn*p* if the environment doesn’t have a'PATH'key. Also available viaos.path.
The string used to separate (or, rather, terminate) lines on the currentplatform. This may be a single character, such as'\n' for POSIX, ormultiple characters, for example,'\r\n' for Windows. Do not useos.linesep as a line terminator when writing files opened in text mode (thedefault); use a single'\n' instead, on all platforms.
Return a string ofn random bytes suitable for cryptographic use.
This function returns random bytes from an OS-specific randomness source. Thereturned data should be unpredictable enough for cryptographic applications,though its exact quality depends on the OS implementation. On a Unix-likesystem this will query/dev/urandom, and on Windows it will useCryptGenRandom(). If a randomness source is not found,NotImplementedError will be raised.
For an easy-to-use interface to the random number generatorprovided by your platform, please seerandom.SystemRandom.
16. Generic Operating System Services
16.2.io — Core tools for working with streams
Enter search terms or a module, class or function name.
