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.

16.1.1. File Names, Command Line Arguments, and Environment Variables¶

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()).

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.

16.1.2. Process Parameters¶

These functions and data items provide information and operate on the currentprocess and user.

os.ctermid()¶

Return the filename corresponding to the controlling terminal of the process.

Availability: Unix.

os.environ¶

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.

os.environb¶

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.

os.chdir(path)

os.fchdir(fd)

os.getcwd()

These functions are described inFiles and Directories.

os.fsencode(filename)¶

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.

os.fsdecode(filename)¶

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.

os.getenv(key,default=None)¶

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.

os.getenvb(key,default=None)¶

Return the value of the environment variablekey if it exists, ordefault if it doesn’t.key,default and the result are bytes.

getenvb() is only available ifsupports_bytes_environis True.

Availability: most flavors of Unix.

New in version 3.2.

os.get_exec_path(env=None)¶

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 isNone,environ is used.

New in version 3.2.

os.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.

os.geteuid()¶

Return the current process’s effective user id.

Availability: Unix.

os.getgid()¶

Return the real group id of the current process.

Availability: Unix.

os.getgrouplist(user,group)¶

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.

os.getgroups()¶

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().

os.getlogin()¶

Return the name of the user logged in on the controlling terminal of theprocess. For most purposes, it is more useful to use the environmentvariablesLOGNAME orUSERNAME to find out who the useris, orpwd.getpwuid(os.getuid())[0] to get the login name of the currentreal user id.

Availability: Unix, Windows.

os.getpgid(pid)¶

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.

os.getpgrp()¶

Return the id of the current process group.

Availability: Unix.

os.getpid()¶

Return the current process id.

os.getppid()¶

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.

os.getpriority(which,who)¶

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.

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

Parameters for thegetpriority() andsetpriority() functions.

Availability: Unix.

New in version 3.3.

os.getresuid()¶

Return a tuple (ruid, euid, suid) denoting the current process’sreal, effective, and saved user ids.

Availability: Unix.

New in version 3.2.

os.getresgid()¶

Return a tuple (rgid, egid, sgid) denoting the current process’sreal, effective, and saved group ids.

Availability: Unix.

New in version 3.2.

os.getuid()¶

Return the current process’s real user id.

Availability: Unix.

os.initgroups(username,gid)¶

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.

os.putenv(key,value)¶

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.

os.setegid(egid)¶

Set the current process’s effective group id.

Availability: Unix.

os.seteuid(euid)¶

Set the current process’s effective user id.

Availability: Unix.

os.setgid(gid)¶

Set the current process’ group id.

Availability: Unix.

os.setgroups(groups)¶

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().

os.setpgrp()¶

Call the system callsetpgrp() orsetpgrp(0,0) depending onwhich version is implemented (if any). See the Unix manual for the semantics.

Availability: Unix.

os.setpgid(pid,pgrp)¶

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.

os.setpriority(which,who,priority)¶

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.

os.setregid(rgid,egid)¶

Set the current process’s real and effective group ids.

Availability: Unix.

os.setresgid(rgid,egid,sgid)¶

Set the current process’s real, effective, and saved group ids.

Availability: Unix.

New in version 3.2.

os.setresuid(ruid,euid,suid)¶

Set the current process’s real, effective, and saved user ids.

Availability: Unix.

New in version 3.2.

os.setreuid(ruid,euid)¶

Set the current process’s real and effective user ids.

Availability: Unix.

os.getsid(pid)¶

Call the system callgetsid(). See the Unix manual for the semantics.

Availability: Unix.

os.setsid()¶

Call the system callsetsid(). See the Unix manual for the semantics.

Availability: Unix.

os.setuid(uid)¶

Set the current process’s user id.

Availability: Unix.

os.strerror(code)¶

Return the error message corresponding to the error code incode.On platforms wherestrerror() returnsNULL when given an unknownerror number,ValueError is raised.

os.supports_bytes_environ¶

True if the native OS type of the environment is bytes (eg.False onWindows).

New in version 3.2.

os.umask(mask)¶

Set the current numeric umask and return the previous umask.

os.uname()¶

Returns information identifying the current operating system.The return value is an object with five attributes:

• sysname - operating system name
• nodename - name of machine on network (implementation-defined)
• release - operating system release
• version - operating system version
• machine - hardware identifier

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.

os.unsetenv(key)¶

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.

16.1.3. File Object Creation¶

This function creates newfile objects. (See alsoopen() for opening file descriptors.)

os.fdopen(fd,*args,**kwargs)¶

Return an open file object connected to the file descriptorfd. This is analias of theopen() built-in function and accepts the same arguments.The only difference is that the first argument offdopen() must alwaysbe an integer.

16.1.4. File Descriptor Operations¶

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.

os.close(fd)¶

Close file descriptorfd.

Note

This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To close a “fileobject” returned by the built-in functionopen() or bypopen() orfdopen(), use itsclose() method.

os.closerange(fd_low,fd_high)¶

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

os.device_encoding(fd)¶

Return a string describing the encoding of the device associated withfdif it is connected to a terminal; else returnNone.

os.dup(fd)¶

Return a duplicate of file descriptorfd. The new file descriptor isnon-inheritable.

On Windows, when duplicating a standard stream (0: stdin, 1: stdout,2: stderr), the new file descriptor isinheritable.

Changed in version 3.4:The new file descriptor is now non-inheritable.

os.dup2(fd,fd2,inheritable=True)¶

Duplicate file descriptorfd tofd2, closing the latter first if necessary.The file descriptorfd2 isinheritable by default,or non-inheritable ifinheritable isFalse.

Changed in version 3.4:Add the optionalinheritable parameter.

os.fchmod(fd,mode)¶

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.

os.fchown(fd,uid,gid)¶

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.

os.fdatasync(fd)¶

Force write of file with filedescriptorfd to disk. Does not force update ofmetadata.

Availability: Unix.

Note

This function is not available on MacOS.

os.fpathconf(fd,name)¶

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.

os.fstat(fd)¶

Get the status of the file descriptorfd. Return astat_resultobject.

As of Python 3.3, this is equivalent toos.stat(fd).

See also

Thestat() function.

os.fstatvfs(fd)¶

Return information about the filesystem containing the file associated withfile descriptorfd, likestatvfs(). As of Python 3.3, this isequivalent toos.statvfs(fd).

Availability: Unix.

os.fsync(fd)¶

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.

os.ftruncate(fd,length)¶

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, Windows.

Changed in version 3.5:Added support for Windows

os.get_blocking(fd)¶

Get the blocking mode of the file descriptor:False if theO_NONBLOCK flag is set,True if the flag is cleared.

See alsoset_blocking() andsocket.socket.setblocking().

Availability: Unix.

New in version 3.5.

os.isatty(fd)¶

ReturnTrue if the file descriptorfd is open and connected to atty(-like) device, elseFalse.

os.lockf(fd,cmd,len)¶

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.

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

Flags that specify what actionlockf() will take.

Availability: Unix.

New in version 3.3.

os.lseek(fd,pos,how)¶

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.

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

Parameters to thelseek() function. Their values are 0, 1, and 2,respectively.

New in version 3.3:Some operating systems could support additional values, likeos.SEEK_HOLE oros.SEEK_DATA.

os.open(path,flags,mode=0o777,*,dir_fd=None)¶

Open the filepath 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.The new file descriptor isnon-inheritable.

For a description of the flag and mode values, see the C run-time documentation;flag constants (likeO_RDONLY andO_WRONLY) are defined intheos module. In particular, on Windows addingO_BINARY is needed to open files in binary mode.

This function can supportpaths relative to directory descriptors with thedir_fd parameter.

Changed in version 3.4:The new file descriptor is now non-inheritable.

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.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

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.

os.O_RDONLY¶

os.O_WRONLY¶

os.O_RDWR¶

os.O_APPEND¶

os.O_CREAT¶

os.O_EXCL¶

os.O_TRUNC¶

The above constants are available on Unix and Windows.

os.O_DSYNC¶

os.O_RSYNC¶

os.O_SYNC¶

os.O_NDELAY¶

os.O_NONBLOCK¶

os.O_NOCTTY¶

os.O_CLOEXEC¶

The above constants are only available on Unix.

Changed in version 3.3:AddO_CLOEXEC constant.

os.O_BINARY¶

os.O_NOINHERIT¶

os.O_SHORT_LIVED¶

os.O_TEMPORARY¶

os.O_RANDOM¶

os.O_SEQUENTIAL¶

os.O_TEXT¶

The above constants are only available on Windows.

os.O_ASYNC¶

os.O_DIRECT¶

os.O_DIRECTORY¶

os.O_NOFOLLOW¶

os.O_NOATIME¶

os.O_PATH¶

os.O_TMPFILE¶

os.O_SHLOCK¶

os.O_EXLOCK¶

The above constants are extensions and not present if they are not defined bythe C library.

Changed in version 3.4:AddO_PATH on systems that support it.AddO_TMPFILE, only available on Linux Kernel 3.11 or newer.

os.openpty()¶

Open a new pseudo-terminal pair. Return a pair of file descriptors(master,slave) for the pty and the tty, respectively. The new filedescriptors arenon-inheritable. For a (slightly) moreportable approach, use thepty module.

Availability: some flavors of Unix.

Changed in version 3.4:The new file descriptors are now non-inheritable.

os.pipe()¶

Create a pipe. Return a pair of file descriptors(r,w) usable forreading and writing, respectively. The new file descriptor isnon-inheritable.

Availability: Unix, Windows.

Changed in version 3.4:The new file descriptors are now non-inheritable.

os.pipe2(flags)¶

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.

os.posix_fallocate(fd,offset,len)¶

Ensures that enough disk space is allocated for the file specified byfdstarting fromoffset and continuing forlen bytes.

Availability: Unix.

New in version 3.3.

os.posix_fadvise(fd,offset,len,advice)¶

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.

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

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.

os.pread(fd,buffersize,offset)¶

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.

os.pwrite(fd,str,offset)¶

Writebytestring to a file descriptor,fd, fromoffset,leaving the file offset unchanged.

Availability: Unix.

New in version 3.3.

os.read(fd,n)¶

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.

Note

This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To read a“file object” returned by the built-in functionopen() or bypopen() orfdopen(), orsys.stdin, use itsread() orreadline() methods.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

os.sendfile(out,in,offset,count)¶

os.sendfile(out,in,offset,count,[headers,][trailers,]flags=0)

Copycount 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 forcount 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.

Cross-platform applications should not useheaders,trailers andflagsarguments.

Availability: Unix.

Note

For a higher-level wrapper ofsendfile(), seesocket.socket.sendfile().

New in version 3.3.

os.set_blocking(fd,blocking)¶

Set the blocking mode of the specified file descriptor. Set theO_NONBLOCK flag if blocking isFalse, clear the flag otherwise.

See alsoget_blocking() andsocket.socket.setblocking().

Availability: Unix.

New in version 3.5.

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

Parameters to thesendfile() function, if the implementation supportsthem.

Availability: Unix.

New in version 3.3.

os.readv(fd,buffers)¶

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.

os.tcgetpgrp(fd)¶

Return the process group associated with the terminal given byfd (an openfile descriptor as returned byos.open()).

Availability: Unix.

os.tcsetpgrp(fd,pg)¶

Set the process group associated with the terminal given byfd (an open filedescriptor as returned byos.open()) topg.

Availability: Unix.

os.ttyname(fd)¶

Return a string which specifies the terminal device associated withfile descriptorfd. Iffd is not associated with a terminal device, anexception is raised.

Availability: Unix.

os.write(fd,str)¶

Write the bytestring instr to file descriptorfd. Return the number ofbytes actually written.

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.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

os.writev(fd,buffers)¶

Write the contents ofbuffers to file descriptorfd.buffers must be asequence ofbytes-like objects. Buffers areprocessed in array order. Entire contents of first buffer is written beforeproceeding to second, and so on. The operating system may set a limit(sysconf() value SC_IOV_MAX) on the number of buffers that can be used.

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.

16.1.5. Files and Directories¶

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.

os.access(path,mode,*,dir_fd=None,effective_ids=False,follow_symlinks=True)¶

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.

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.

os.F_OK¶

os.R_OK¶

os.W_OK¶

os.X_OK¶

Values to pass as themode parameter ofaccess() to test theexistence, readability, writability and executability ofpath,respectively.

os.chdir(path)¶

Change the current working directory topath.

This function can supportspecifying a file descriptor. Thedescriptor must refer to an opened directory, not an open file.

New in version 3.3:Added support for specifyingpath as a file descriptoron some platforms.

os.chflags(path,flags,*,follow_symlinks=True)¶

Set the flags ofpath to the numericflags.flags may take a combination(bitwise OR) of the following values (as defined in thestat module):

• stat.UF_NODUMP
• stat.UF_IMMUTABLE
• stat.UF_APPEND
• stat.UF_OPAQUE
• stat.UF_NOUNLINK
• stat.UF_COMPRESSED
• stat.UF_HIDDEN
• stat.SF_ARCHIVED
• stat.SF_IMMUTABLE
• stat.SF_APPEND
• stat.SF_NOUNLINK
• stat.SF_SNAPSHOT

This function can supportnot following symlinks.

Availability: Unix.

New in version 3.3:Thefollow_symlinks argument.

os.chmod(path,mode,*,dir_fd=None,follow_symlinks=True)¶

Change the mode ofpath to the numericmode.mode may take one of thefollowing values (as defined in thestat module) or bitwise ORedcombinations of them:

• stat.S_ISUID
• stat.S_ISGID
• stat.S_ENFMT
• stat.S_ISVTX
• stat.S_IREAD
• stat.S_IWRITE
• stat.S_IEXEC
• stat.S_IRWXU
• stat.S_IRUSR
• stat.S_IWUSR
• stat.S_IXUSR
• stat.S_IRWXG
• stat.S_IRGRP
• stat.S_IWGRP
• stat.S_IXGRP
• stat.S_IRWXO
• stat.S_IROTH
• stat.S_IWOTH
• stat.S_IXOTH

This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.

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.

os.chown(path,uid,gid,*,dir_fd=None,follow_symlinks=True)¶

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.

os.chroot(path)¶

Change the root directory of the current process topath.

Availability: Unix.

os.fchdir(fd)¶

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.

os.getcwd()¶

Return a string representing the current working directory.

os.getcwdb()¶

Return a bytestring representing the current working directory.

os.lchflags(path,flags)¶

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.

os.lchmod(path,mode)¶

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.

os.lchown(path,uid,gid)¶

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.

os.link(src,dst,*,src_dir_fd=None,dst_dir_fd=None,follow_symlinks=True)¶

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.

os.listdir(path='.')¶

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().

See also

Thescandir() function returns directory entries along withfile attribute information, giving better performance for manycommon use cases.

Changed in version 3.2:Thepath parameter became optional.

New in version 3.3:Added support for specifying an open file descriptor forpath.

os.lstat(path,*,dir_fd=None)¶

Perform the equivalent of anlstat() system call on the given path.Similar tostat(), but does not follow symbolic links. Return astat_result object.

On platforms 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.

See also

Thestat() function.

Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.

Changed in version 3.3:Added thedir_fd parameter.

os.mkdir(path,mode=0o777,*,dir_fd=None)¶

Create a directory namedpath with numeric modemode.

If the directory already exists,FileExistsError is raised.

On some systems,mode is ignored. Where it is used, the current umaskvalue is first masked out. If bits other than the last 9 (i.e. the last 3digits of the octal representation of themode) are set, their meaning isplatform-dependent. On some platforms, they are ignored and you should callchmod() explicitly to set them.

This function can also supportpaths relative to directory descriptors.

It is also possible to create temporary directories; see thetempfile module’stempfile.mkdtemp() function.

New in version 3.3:Thedir_fd argument.

os.makedirs(name,mode=0o777,exist_ok=False)¶

Recursive directory creation function. Likemkdir(), but makes allintermediate-level directories needed to contain the leaf directory.

Themode parameter is passed tomkdir(); seethe mkdir()description for how it is interpreted.

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.4.1:Before Python 3.4.1, 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.4.1. Seebpo-21082.

os.mkfifo(path,mode=0o666,*,dir_fd=None)¶

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.

os.mknod(path,mode=0o600,device=0,*,dir_fd=None)¶

Create a filesystem node (file, device special file or named pipe) namedpath.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.

Availability: Unix.

New in version 3.3:Thedir_fd argument.

os.major(device)¶

Extract the device major number from a raw device number (usually thest_dev orst_rdev field fromstat).

os.minor(device)¶

Extract the device minor number from a raw device number (usually thest_dev orst_rdev field fromstat).

os.makedev(major,minor)¶

Compose a raw device number from the major and minor device numbers.

os.pathconf(path,name)¶

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.

os.pathconf_names¶

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.

os.readlink(path,*,dir_fd=None)¶

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 a 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.

os.remove(path,*,dir_fd=None)¶

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 semantically identical tounlink().

New in version 3.3:Thedir_fd argument.

os.removedirs(name)¶

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.

os.rename(src,dst,*,src_dir_fd=None,dst_dir_fd=None)¶

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().

New in version 3.3:Thesrc_dir_fd anddst_dir_fd arguments.

os.renames(old,new)¶

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.

os.replace(src,dst,*,src_dir_fd=None,dst_dir_fd=None)¶

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.

New in version 3.3.

os.rmdir(path,*,dir_fd=None)¶

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.

New in version 3.3:Thedir_fd parameter.

os.scandir(path='.')¶

Return an iterator ofDirEntry objects corresponding to the entriesin the directory given bypath. The entries are yielded in arbitraryorder, and the special entries'.' and'..' are not included.

Usingscandir() instead oflistdir() can significantlyincrease the performance of code that also needs file type or fileattribute information, becauseDirEntry objects expose thisinformation if the operating system provides it when scanning a directory.AllDirEntry methods may perform a system call, butis_dir() andis_file() usually onlyrequire a system call for symbolic links;DirEntry.stat()always requires a system call on Unix but only requires one forsymbolic links on Windows.

On Unix,path can be of typestr orbytes (usefsencode() andfsdecode() to encode and decodebytes paths). On Windows,path must be of typestr.On both systems, the type of thename andpath attributes of eachDirEntry will be ofthe same type aspath.

The following example shows a simple use ofscandir() to display allthe files (excluding directories) in the givenpath that don’t start with'.'. Theentry.is_file() call will generally not make an additionalsystem call:

forentryinos.scandir(path):ifnotentry.name.startswith('.')andentry.is_file():print(entry.name)

Note

On Unix-based systems,scandir() uses the system’sopendir()andreaddir()functions. On Windows, it uses the Win32FindFirstFileWandFindNextFileWfunctions.

New in version 3.5.

classos.DirEntry¶

Object yielded byscandir() to expose the file path and other fileattributes of a directory entry.

scandir() will provide as much of this information as possible withoutmaking additional system calls. When astat() orlstat() system callis made, theDirEntry object will cache the result.

DirEntry instances are not intended to be stored in long-lived datastructures; if you know the file metadata has changed or if a long time haselapsed since callingscandir(), callos.stat(entry.path) to fetchup-to-date information.

Because theDirEntry methods can make operating system calls, they mayalso raiseOSError. If you need very fine-grainedcontrol over errors, you can catchOSError when calling one of theDirEntry methods and handle as appropriate.

Attributes and methods on aDirEntry instance are as follows:

name¶

The entry’s base filename, relative to thescandir()pathargument.

Thename attribute will be of the same type (str orbytes) as thescandir()path argument. Usefsdecode() to decode byte filenames.

path¶

The entry’s full path name: equivalent toos.path.join(scandir_path,entry.name) wherescandir_path is thescandir()pathargument. The path is only absolute if thescandir()pathargument was absolute.

Thepath attribute will be of the same type (str orbytes) as thescandir()path argument. Usefsdecode() to decode byte filenames.

inode()¶

Return the inode number of the entry.

The result is cached on theDirEntry object. Useos.stat(entry.path,follow_symlinks=False).st_ino to fetch up-to-date information.

On the first, uncached call, a system call is required on Windows butnot on Unix.

is_dir(*,follow_symlinks=True)¶

ReturnTrue if this entry is a directory or a symbolic link pointingto a directory; returnFalse if the entry is or points to any otherkind of file, or if it doesn’t exist anymore.

Iffollow_symlinks isFalse, returnTrue only if this entryis a directory (without following symlinks); returnFalse if theentry is any other kind of file or if it doesn’t exist anymore.

The result is cached on theDirEntry object, with a separate cacheforfollow_symlinksTrue andFalse. Callos.stat() alongwithstat.S_ISDIR() to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.Specifically, for non-symlinks, neither Windows or Unix require a systemcall, except on certain Unix file systems, such as network file systems,that returndirent.d_type==DT_UNKNOWN. If the entry is a symlink,a system call will be required to follow the symlink unlessfollow_symlinks isFalse.

This method can raiseOSError, such asPermissionError,butFileNotFoundError is caught and not raised.

is_file(*,follow_symlinks=True)¶

ReturnTrue if this entry is a file or a symbolic link pointing to afile; returnFalse if the entry is or points to a directory or othernon-file entry, or if it doesn’t exist anymore.

Iffollow_symlinks isFalse, returnTrue only if this entryis a file (without following symlinks); returnFalse if the entry isa directory or other non-file entry, or if it doesn’t exist anymore.

The result is cached on theDirEntry object. Caching, system callsmade, and exceptions raised are as peris_dir().

is_symlink()¶

ReturnTrue if this entry is a symbolic link (even if broken);returnFalse if the entry points to a directory or any kind of file,or if it doesn’t exist anymore.

The result is cached on theDirEntry object. Callos.path.islink() to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.Specifically, neither Windows or Unix require a system call, except oncertain Unix file systems, such as network file systems, that returndirent.d_type==DT_UNKNOWN.

This method can raiseOSError, such asPermissionError,butFileNotFoundError is caught and not raised.

stat(*,follow_symlinks=True)¶

Return astat_result object for this entry. This methodfollows symbolic links by default; to stat a symbolic link add thefollow_symlinks=False argument.

On Unix, this method always requires a system call. On Windows, itonly requires a system call iffollow_symlinks isTrue and theentry is a symbolic link.

On Windows, thest_ino,st_dev andst_nlink attributes of thestat_result are always set to zero. Callos.stat() toget these attributes.

The result is cached on theDirEntry object, with a separate cacheforfollow_symlinksTrue andFalse. Callos.stat() tofetch up-to-date information.

Note that there is a nice correspondence between several attributesand methods ofDirEntry and ofpathlib.Path. Inparticular, thename attribute has the same meaning, as do theis_dir(),is_file(),is_symlink() andstat() methods.

New in version 3.5.

os.stat(path,*,dir_fd=None,follow_symlinks=True)¶

Get the status of a file or a file descriptor. Perform the equivalent of astat() system call on the given path.path may be specified aseither a string, a bytes or as an open file descriptor. Return astat_resultobject.

This function normally follows symlinks; to stat a symlink add the argumentfollow_symlinks=False, or uselstat().

This function can supportspecifying a file descriptor andnot following symlinks.

Example:

>>>importos>>>statinfo=os.stat('somefile.txt')>>>statinfoos.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

See also

fstat() andlstat() functions.

New in version 3.3:Added thedir_fd andfollow_symlinks arguments, specifying a filedescriptor instead of a path.

classos.stat_result¶

Object whose attributes correspond roughly to the members of thestat structure. It is used for the result ofos.stat(),os.fstat() andos.lstat().

Attributes:

st_mode¶

File mode: file type and file mode bits (permissions).

st_ino¶

Inode number.

st_dev¶

Identifier of the device on which this file resides.

st_nlink¶

Number of hard links.

st_uid¶

User identifier of the file owner.

st_gid¶

Group identifier of the file owner.

st_size¶

Size of the file in bytes, if it is a regular file or a symbolic link.The size of a symbolic link is the length of the pathname it contains,without a terminating null byte.

Timestamps:

st_atime¶

Time of most recent access expressed in seconds.

st_mtime¶

Time of most recent content modification expressed in seconds.

st_ctime¶

Platform dependent:

• the time of most recent metadata change on Unix,
• the time of creation on Windows, expressed in seconds.

st_atime_ns¶

Time of most recent access expressed in nanoseconds as an integer.

st_mtime_ns¶

Time of most recent content modification expressed in nanoseconds as aninteger.

st_ctime_ns¶

Platform dependent:

• the time of most recent metadata change on Unix,
• the time of creation on Windows, expressed in nanoseconds as aninteger.

See also thestat_float_times() function.

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.

On some Unix systems (such as Linux), the following attributes may also beavailable:

st_blocks¶

Number of 512-byte blocks allocated for file.This may be smaller thanst_size/512 when the file has holes.

st_blksize¶

“Preferred” blocksize for efficient file system I/O. Writing to a file insmaller chunks may cause an inefficient read-modify-rewrite.

st_rdev¶

Type of device if an inode device.

st_flags¶

User defined flags for file.

On other Unix systems (such as FreeBSD), the following attributes may beavailable (but may be only filled out if root tries to use them):

st_gen¶

File generation number.

st_birthtime¶

Time of file creation.

On Mac OS systems, the following attributes may also be available:

st_rsize¶

Real size of the file.

st_creator¶

Creator of the file.

st_type¶

File type.

On Windows systems, the following attribute is also available:

st_file_attributes¶

Windows file attributes:dwFileAttributes member of theBY_HANDLE_FILE_INFORMATION structure returned byGetFileInformationByHandle(). See theFILE_ATTRIBUTE_*constants in thestat module.

The standard modulestat defines functions and constants that areuseful for extracting information from astat structure. (OnWindows, some items are filled with dummy values.)

For backward compatibility, astat_result instance 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. For compatibility with older Python versions,accessingstat_result as a tuple always returns integers.

New in version 3.3:Added thest_atime_ns,st_mtime_ns, andst_ctime_ns members.

New in version 3.5:Added thest_file_attributes member on Windows.

os.stat_float_times([newvalue])¶

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.

os.statvfs(path)¶

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.

Additional module-level constants are defined for GNU/glibc based systems.These areST_NODEV (disallow access to device special files),ST_NOEXEC (disallow program execution),ST_SYNCHRONOUS(writes are synced at once),ST_MANDLOCK (allow mandatory locks on an FS),ST_WRITE (write on file/directory/symlink),ST_APPEND(append-only file),ST_IMMUTABLE (immutable file),ST_NOATIME(do not update access times),ST_NODIRATIME (do not update directory accesstimes),ST_RELATIME (update atime relative to mtime/ctime).

This function can supportspecifying a file descriptor.

Changed in version 3.2:TheST_RDONLY andST_NOSUID constants were added.

Changed in version 3.4:TheST_NODEV,ST_NOEXEC,ST_SYNCHRONOUS,ST_MANDLOCK,ST_WRITE,ST_APPEND,ST_IMMUTABLE,ST_NOATIME,ST_NODIRATIME,andST_RELATIME constants were added.

Availability: Unix.

New in version 3.3:Added support for specifying an open file descriptor forpath.

os.supports_dir_fd¶

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.

os.supports_effective_ids¶

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_effective_ids,like so:

os.accessinos.supports_effective_ids

Currentlyeffective_ids only works on Unix platforms; it does not work onWindows.

New in version 3.3.

os.supports_fd¶

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.

os.supports_follow_symlinks¶

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.

os.symlink(src,dst,target_is_directory=False,*,dir_fd=None)¶

Create a symbolic link pointing tosrc nameddst.

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.

os.sync()¶

Force write of everything to disk.

Availability: Unix.

New in version 3.3.

os.truncate(path,length)¶

Truncate the file corresponding topath, so that it is at mostlength bytes in size.

This function can supportspecifying a file descriptor.

Availability: Unix, Windows.

New in version 3.3.

Changed in version 3.5:Added support for Windows

os.unlink(path,*,dir_fd=None)¶

Remove (delete) the filepath. This function is semanticallyidentical toremove(); theunlink name is itstraditional Unix name. Please see the documentation forremove() for further information.

New in version 3.3:Thedir_fd parameter.

os.utime(path,times=None,*,[ns,]dir_fd=None,follow_symlinks=True)¶

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:

• Ifns is specified,it must be a 2-tuple of the form(atime_ns,mtime_ns)where each member is an int expressing nanoseconds.
• Iftimes is notNone,it must be a 2-tuple of the form(atime,mtime)where each member is an int or float expressing seconds.
• Iftimes isNone andns is unspecified,this is equivalent to specifyingns=(atime_ns,mtime_ns)where both times are the current time.

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.

New in version 3.3:Added support for specifying an open file descriptor forpath,and thedir_fd,follow_symlinks, andns parameters.

os.walk(top,topdown=True,onerror=None,followlinks=False)¶

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 triplefor a directory is generated after the triples for all of its subdirectories(directories are generated bottom-up). No matter the value oftopdown, thelist of subdirectories is retrieved before the tuples for the directory andits subdirectories are generated.

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 hasno effect on the behavior of the walk, because in bottom-up mode the directoriesindirnames are generated 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 (simple implementation ofshutil.rmtree()),walking the tree bottom-up is essential,rmdir() doesn’t allowdeleting 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))

Changed in version 3.5:This function now callsos.scandir() instead ofos.listdir(),making it faster by reducing the number of calls toos.stat().

os.fwalk(top='.',topdown=True,onerror=None,*,follow_symlinks=False,dir_fd=None)¶

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.

16.1.6. Process Management¶

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.

os.abort()¶

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().

os.execl(path,arg0,arg1,...)¶

os.execle(path,arg0,arg1,...,env)¶

os.execlp(file,arg0,arg1,...)¶

os.execlpe(file,arg0,arg1,...,env)¶

os.execv(path,args)¶

os.execve(path,args,env)¶

os.execvp(file,args)¶

os.execvpe(file,args,env)¶

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().

os._exit(n)¶

Exit the process with statusn, without calling cleanup handlers, flushingstdio buffers, etc.

Note

The standard way to exit issys.exit(n)._exit() shouldnormally only be used in the child process after afork().

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.

os.EX_OK¶

Exit code that means no error occurred.

Availability: Unix.

os.EX_USAGE¶

Exit code that means the command was used incorrectly, such as when the wrongnumber of arguments are given.

Availability: Unix.

os.EX_DATAERR¶

Exit code that means the input data was incorrect.

Availability: Unix.

os.EX_NOINPUT¶

Exit code that means an input file did not exist or was not readable.

Availability: Unix.

os.EX_NOUSER¶

Exit code that means a specified user did not exist.

Availability: Unix.

os.EX_NOHOST¶

Exit code that means a specified host did not exist.

Availability: Unix.

os.EX_UNAVAILABLE¶

Exit code that means that a required service is unavailable.

Availability: Unix.

os.EX_SOFTWARE¶

Exit code that means an internal software error was detected.

Availability: Unix.

os.EX_OSERR¶

Exit code that means an operating system error was detected, such as theinability to fork or create a pipe.

Availability: Unix.

os.EX_OSFILE¶

Exit code that means some system file did not exist, could not be opened, or hadsome other kind of error.

Availability: Unix.

os.EX_CANTCREAT¶

Exit code that means a user specified output file could not be created.

Availability: Unix.

os.EX_IOERR¶

Exit code that means that an error occurred while doing I/O on some file.

Availability: Unix.

os.EX_TEMPFAIL¶

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.

os.EX_PROTOCOL¶

Exit code that means that a protocol exchange was illegal, invalid, or notunderstood.

Availability: Unix.

os.EX_NOPERM¶

Exit code that means that there were insufficient permissions to perform theoperation (but not intended for file system problems).

Availability: Unix.

os.EX_CONFIG¶

Exit code that means that some kind of configuration error occurred.

Availability: Unix.

os.EX_NOTFOUND¶

Exit code that means something like “an entry was not found”.

Availability: Unix.

os.fork()¶

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 and Cygwin haveknown issues when using fork() from a thread.

Warning

Seessl for applications that use the SSL module with fork().

Availability: Unix.

os.forkpty()¶

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.

os.kill(pid,sig)¶

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.

os.killpg(pgid,sig)¶

Send the signalsig to the process grouppgid.

Availability: Unix.

os.nice(increment)¶

Addincrement to the process’s “niceness”. Return the new niceness.

Availability: Unix.

os.plock(op)¶

Lock program segments into memory. The value ofop (defined in<sys/lock.h>) determines which segments are locked.

Availability: Unix.

os.popen(cmd,mode='r',buffering=-1)¶

Open a pipe to or from commandcmd.The return value is an open file objectconnected to the pipe, which can be read or written depending on whethermodeis'r' (default) or'w'. Thebuffering argument has the same meaning asthe corresponding argument to the built-inopen() function. Thereturned file object reads or writes text strings rather than bytes.

Theclose method returnsNone if the subprocess exitedsuccessfully, or the subprocess’s return code if there was anerror. On POSIX systems, if the return code is positive itrepresents the return value of the process left-shifted by onebyte. If the return code is negative, the process was terminatedby the signal given by the negated value of the return code. (Forexample, the return value might be-signal.SIGKILL if thesubprocess was killed.) On Windows systems, the return valuecontains the signed integer return code from the child process.

This is implemented usingsubprocess.Popen; see that class’sdocumentation for more powerful ways to manage and communicate withsubprocesses.

os.spawnl(mode,path,...)¶

os.spawnle(mode,path,...,env)¶

os.spawnlp(mode,file,...)¶

os.spawnlpe(mode,file,...,env)¶

os.spawnv(mode,path,args)¶

os.spawnve(mode,path,args,env)¶

os.spawnvp(mode,file,args)¶

os.spawnvpe(mode,file,args,env)¶

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.

os.P_NOWAIT¶

os.P_NOWAITO¶

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.

os.P_WAIT¶

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.

os.P_DETACH¶

os.P_OVERLAY¶

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.

os.startfile(path[,operation])¶

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.

To reduce interpreter startup overhead, the Win32ShellExecute()function is not resolved until this function is first called. If the functioncannot be resolved,NotImplementedError will be raised.

Availability: Windows.

os.system(command)¶

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.

os.times()¶

Returns the current global process times.The return value is an object with five attributes:

• user - user time
• system - system time
• children_user - user time of all child processes
• children_system - system time of all child processes
• elapsed - elapsed real time since a fixed point in the past

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.

Availability: Unix, Windows.

Changed in version 3.3:Return type changed from a tuple to a tuple-like objectwith named attributes.

os.wait()¶

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.

os.waitid(idtype,id,options)¶

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.

os.P_PID¶

os.P_PGID¶

os.P_ALL¶

These are the possible values foridtype inwaitid(). They affecthowid is interpreted.

Availability: Unix.

New in version 3.3.

os.WEXITED¶

os.WSTOPPED¶

os.WNOWAIT¶

Flags that can be used inoptions inwaitid() that specify whatchild signal to wait for.

Availability: Unix.

New in version 3.3.

os.CLD_EXITED¶

os.CLD_DUMPED¶

os.CLD_TRAPPED¶

os.CLD_CONTINUED¶

These are the possible values forsi_code in the result returned bywaitid().

Availability: Unix.

New in version 3.3.

os.waitpid(pid,options)¶

The details of this function differ on Unix and Windows.

On Unix: Wait for completion of a child process given by process 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.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

os.wait3(options)¶

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.

os.wait4(pid,options)¶

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.

os.WNOHANG¶

The option forwaitpid() to return immediately if no child process statusis available immediately. The function returns(0,0) in this case.

Availability: Unix.

os.WCONTINUED¶

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.

os.WUNTRACED¶

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.

os.WCOREDUMP(status)¶

ReturnTrue if a core dump was generated for the process, otherwisereturnFalse.

Availability: Unix.

os.WIFCONTINUED(status)¶

ReturnTrue if the process has been continued from a job control stop,otherwise returnFalse.

Availability: Unix.

os.WIFSTOPPED(status)¶

ReturnTrue if the process has been stopped, otherwise returnFalse.

Availability: Unix.

os.WIFSIGNALED(status)¶

ReturnTrue if the process exited due to a signal, otherwise returnFalse.

Availability: Unix.

os.WIFEXITED(status)¶

ReturnTrue if the process exited using theexit(2) system call,otherwise returnFalse.

Availability: Unix.

os.WEXITSTATUS(status)¶

IfWIFEXITED(status) is true, return the integer parameter to theexit(2) system call. Otherwise, the return value is meaningless.

Availability: Unix.

os.WSTOPSIG(status)¶

Return the signal which caused the process to stop.

Availability: Unix.

os.WTERMSIG(status)¶

Return the signal which caused the process to exit.

Availability: Unix.

16.1.7. Interface to the scheduler¶

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.

The following scheduling policies are exposed if they are supported by theoperating system.

os.SCHED_OTHER¶

The default scheduling policy.

os.SCHED_BATCH¶

Scheduling policy for CPU-intensive processes that tries to preserveinteractivity on the rest of the computer.

os.SCHED_IDLE¶

Scheduling policy for extremely low priority background tasks.

os.SCHED_SPORADIC¶

Scheduling policy for sporadic server programs.

os.SCHED_FIFO¶

A First In First Out scheduling policy.

os.SCHED_RR¶

A round-robin scheduling policy.

os.SCHED_RESET_ON_FORK¶

This flag can be 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.

classos.sched_param(sched_priority)¶

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:

sched_priority¶

The scheduling priority for a scheduling policy.

os.sched_get_priority_min(policy)¶

Get the minimum priority value forpolicy.policy is one of thescheduling policy constants above.

os.sched_get_priority_max(policy)¶

Get the maximum priority value forpolicy.policy is one of thescheduling policy constants above.

os.sched_setscheduler(pid,policy,param)¶

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.

os.sched_getscheduler(pid)¶

Return the scheduling policy for the process with PIDpid. Apid of 0means the calling process. The result is one of the scheduling policyconstants above.

os.sched_setparam(pid,param)¶

Set a scheduling parameters for the process with PIDpid. Apid of 0 meansthe calling process.param is asched_param instance.

os.sched_getparam(pid)¶

Return the scheduling parameters as asched_param instance for theprocess with PIDpid. Apid of 0 means the calling process.

os.sched_rr_get_interval(pid)¶

Return the round-robin quantum in seconds for the process with PIDpid. Apid of 0 means the calling process.

os.sched_yield()¶

Voluntarily relinquish the CPU.

os.sched_setaffinity(pid,mask)¶

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.

os.sched_getaffinity(pid)¶

Return the set of CPUs the process with PIDpid (or the current processif zero) is restricted to.

16.1.8. Miscellaneous System Information¶

os.confstr(name)¶

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.

os.confstr_names¶

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.

os.cpu_count()¶

Return the number of CPUs in the system. ReturnsNone if undetermined.

New in version 3.4.

os.getloadavg()¶

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.

os.sysconf(name)¶

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.

os.sysconf_names¶

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.

os.curdir¶

The constant string used by the operating system to refer to the currentdirectory. This is'.' for Windows and POSIX. Also available viaos.path.

os.pardir¶

The constant string used by the operating system to refer to the parentdirectory. This is'..' for Windows and POSIX. Also available viaos.path.

os.sep¶

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.

os.altsep¶

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.

os.extsep¶

The character which separates the base filename from the extension; for example,the'.' inos.py. Also available viaos.path.

os.pathsep¶

The character conventionally used by the operating system to separate searchpath components (as inPATH), such as':' for POSIX or';' forWindows. Also available viaos.path.

os.defpath¶

The default search path used byexec*p* andspawn*p* if the environment doesn’t have a'PATH'key. Also available viaos.path.

os.linesep¶

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.

os.devnull¶

The file path of the null device. For example:'/dev/null' forPOSIX,'nul' for Windows. Also available viaos.path.

os.RTLD_LAZY¶

os.RTLD_NOW¶

os.RTLD_GLOBAL¶

os.RTLD_LOCAL¶

os.RTLD_NODELETE¶

os.RTLD_NOLOAD¶

os.RTLD_DEEPBIND¶

Flags for use with thesetdlopenflags() andgetdlopenflags() functions. See the Unix manual pagedlopen(3) for what the different flags mean.

New in version 3.3.

16.1.9. Miscellaneous Functions¶

os.urandom(n)¶

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 Linux,getrandom() syscall is used if available and the urandomentropy pool is initialized (getrandom() does not block).On a Unix-like system this will query/dev/urandom. On Windows, itwill 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.

Changed in version 3.5.2:On Linux, ifgetrandom() blocks (the urandom entropy pool is notinitialized yet), fall back on reading/dev/urandom.

Changed in version 3.5:On Linux 3.17 and newer, thegetrandom() syscall is now usedwhen available. On OpenBSD 5.6 and newer, the Cgetentropy()function is now used. These functions avoid the usage of an internal filedescriptor.