1 :mod:`os` --- Miscellaneous operating system interfaces
2 =======================================================
5 :synopsis: Miscellaneous operating system interfaces.
8 This module provides a portable way of using operating system dependent
9 functionality. If you just want to read or write a file see :func:`open`, if
10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
11 read all the lines in all the files on the command line see the :mod:`fileinput`
12 module. For creating temporary files and directories see the :mod:`tempfile`
13 module, and for high-level file and directory handling see the :mod:`shutil`
16 The design of all built-in operating system dependent modules of Python is such
17 that as long as the same functionality is available, it uses the same interface;
18 for example, the function ``os.stat(path)`` returns stat information about
19 *path* in the same format (which happens to have originated with the POSIX
22 Extensions peculiar to a particular operating system are also available through
23 the :mod:`os` module, but using them is of course a threat to portability!
27 If not separately noted, all functions that claim "Availability: Unix" are
28 supported on Mac OS X, which builds on a Unix core.
32 All functions in this module raise :exc:`OSError` in the case of invalid or
33 inaccessible file names and paths, or other arguments that have the correct
34 type, but are not accepted by the operating system.
39 An alias for the built-in :exc:`OSError` exception.
44 The name of the operating system dependent module imported. The following names
45 have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
46 ``'ce'``, ``'java'``, ``'riscos'``.
54 These functions and data items provide information and operate on the current
60 A mapping object representing the string environment. For example,
61 ``environ['HOME']`` is the pathname of your home directory (on some platforms),
62 and is equivalent to ``getenv("HOME")`` in C.
64 This mapping is captured the first time the :mod:`os` module is imported,
65 typically during Python startup as part of processing :file:`site.py`. Changes
66 to the environment made after this time are not reflected in ``os.environ``,
67 except for changes made by modifying ``os.environ`` directly.
69 If the platform supports the :func:`putenv` function, this mapping may be used
70 to modify the environment as well as query the environment. :func:`putenv` will
71 be called automatically when the mapping is modified.
75 Calling :func:`putenv` directly does not change ``os.environ``, so it's better
76 to modify ``os.environ``.
80 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
81 cause memory leaks. Refer to the system documentation for
84 If :func:`putenv` is not provided, a modified copy of this mapping may be
85 passed to the appropriate process-creation functions to cause child processes
86 to use a modified environment.
88 If the platform supports the :func:`unsetenv` function, you can delete items in
89 this mapping to unset environment variables. :func:`unsetenv` will be called
90 automatically when an item is deleted from ``os.environ``, and when
91 one of the :meth:`pop` or :meth:`clear` methods is called.
93 .. versionchanged:: 2.6
94 Also unset environment variables when calling :meth:`os.environ.clear`
95 and :meth:`os.environ.pop`.
98 .. function:: chdir(path)
103 These functions are described in :ref:`os-file-dir`.
106 .. function:: ctermid()
108 Return the filename corresponding to the controlling terminal of the process.
112 .. function:: getegid()
114 Return the effective group id of the current process. This corresponds to the
115 "set id" bit on the file being executed in the current process. Availability:
119 .. function:: geteuid()
121 .. index:: single: user; effective id
123 Return the current process's effective user id. Availability: Unix.
126 .. function:: getgid()
128 .. index:: single: process; group
130 Return the real group id of the current process. Availability: Unix.
133 .. function:: getgroups()
135 Return list of supplemental group ids associated with the current process.
139 .. function:: initgroups(username, gid)
141 Call the system initgroups() to initialize the group access list with all of
142 the groups of which the specified username is a member, plus the specified
143 group id. Availability: Unix.
145 .. versionadded:: 2.7
148 .. function:: getlogin()
150 Return the name of the user logged in on the controlling terminal of the
151 process. For most purposes, it is more useful to use the environment variable
152 :envvar:`LOGNAME` to find out who the user is, or
153 ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
154 effective user id. Availability: Unix.
157 .. function:: getpgid(pid)
159 Return the process group id of the process with process id *pid*. If *pid* is 0,
160 the process group id of the current process is returned. Availability: Unix.
162 .. versionadded:: 2.3
165 .. function:: getpgrp()
167 .. index:: single: process; group
169 Return the id of the current process group. Availability: Unix.
172 .. function:: getpid()
174 .. index:: single: process; id
176 Return the current process id. Availability: Unix, Windows.
179 .. function:: getppid()
181 .. index:: single: process; id of parent
183 Return the parent's process id. Availability: Unix.
186 .. function:: getresuid()
188 Return a tuple (ruid, euid, suid) denoting the current process's
189 real, effective, and saved user ids. Availability: Unix.
191 .. versionadded:: 2.7
194 .. function:: getresgid()
196 Return a tuple (rgid, egid, sgid) denoting the current process's
197 real, effective, and saved user ids. Availability: Unix.
199 .. versionadded:: 2.7
202 .. function:: getuid()
204 .. index:: single: user; id
206 Return the current process's user id. Availability: Unix.
209 .. function:: getenv(varname[, value])
211 Return the value of the environment variable *varname* if it exists, or *value*
212 if it doesn't. *value* defaults to ``None``. Availability: most flavors of
216 .. function:: putenv(varname, value)
218 .. index:: single: environment variables; setting
220 Set the environment variable named *varname* to the string *value*. Such
221 changes to the environment affect subprocesses started with :func:`os.system`,
222 :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
227 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
228 cause memory leaks. Refer to the system documentation for putenv.
230 When :func:`putenv` is supported, assignments to items in ``os.environ`` are
231 automatically translated into corresponding calls to :func:`putenv`; however,
232 calls to :func:`putenv` don't update ``os.environ``, so it is actually
233 preferable to assign to items of ``os.environ``.
236 .. function:: setegid(egid)
238 Set the current process's effective group id. Availability: Unix.
241 .. function:: seteuid(euid)
243 Set the current process's effective user id. Availability: Unix.
246 .. function:: setgid(gid)
248 Set the current process' group id. Availability: Unix.
251 .. function:: setgroups(groups)
253 Set the list of supplemental group ids associated with the current process to
254 *groups*. *groups* must be a sequence, and each element must be an integer
255 identifying a group. This operation is typically available only to the superuser.
258 .. versionadded:: 2.2
261 .. function:: setpgrp()
263 Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
264 which version is implemented (if any). See the Unix manual for the semantics.
268 .. function:: setpgid(pid, pgrp)
270 Call the system call :cfunc:`setpgid` to set the process group id of the
271 process with id *pid* to the process group with id *pgrp*. See the Unix manual
272 for the semantics. Availability: Unix.
275 .. function:: setregid(rgid, egid)
277 Set the current process's real and effective group ids. Availability: Unix.
280 .. function:: setresgid(rgid, egid, sgid)
282 Set the current process's real, effective, and saved group ids.
285 .. versionadded:: 2.7
288 .. function:: setresuid(ruid, euid, suid)
290 Set the current process's real, effective, and saved user ids.
293 .. versionadded:: 2.7
296 .. function:: setreuid(ruid, euid)
298 Set the current process's real and effective user ids. Availability: Unix.
301 .. function:: getsid(pid)
303 Call the system call :cfunc:`getsid`. See the Unix manual for the semantics.
306 .. versionadded:: 2.4
309 .. function:: setsid()
311 Call the system call :cfunc:`setsid`. See the Unix manual for the semantics.
315 .. function:: setuid(uid)
317 .. index:: single: user; id, setting
319 Set the current process's user id. Availability: Unix.
322 .. placed in this section since it relates to errno.... a little weak
323 .. function:: strerror(code)
325 Return the error message corresponding to the error code in *code*.
326 On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
327 error number, :exc:`ValueError` is raised. Availability: Unix, Windows.
330 .. function:: umask(mask)
332 Set the current numeric umask and return the previous umask. Availability:
336 .. function:: uname()
339 single: gethostname() (in module socket)
340 single: gethostbyaddr() (in module socket)
342 Return a 5-tuple containing information identifying the current operating
343 system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
344 machine)``. Some systems truncate the nodename to 8 characters or to the
345 leading component; a better way to get the hostname is
346 :func:`socket.gethostname` or even
347 ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
351 .. function:: unsetenv(varname)
353 .. index:: single: environment variables; deleting
355 Unset (delete) the environment variable named *varname*. Such changes to the
356 environment affect subprocesses started with :func:`os.system`, :func:`popen` or
357 :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
359 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
360 automatically translated into a corresponding call to :func:`unsetenv`; however,
361 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
362 preferable to delete items of ``os.environ``.
370 These functions create new file objects. (See also :func:`open`.)
373 .. function:: fdopen(fd[, mode[, bufsize]])
375 .. index:: single: I/O control; buffering
377 Return an open file object connected to the file descriptor *fd*. The *mode*
378 and *bufsize* arguments have the same meaning as the corresponding arguments to
379 the built-in :func:`open` function. Availability: Unix, Windows.
381 .. versionchanged:: 2.3
382 When specified, the *mode* argument must now start with one of the letters
383 ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
385 .. versionchanged:: 2.5
386 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
387 set on the file descriptor (which the :cfunc:`fdopen` implementation already
388 does on most platforms).
391 .. function:: popen(command[, mode[, bufsize]])
393 Open a pipe to or from *command*. The return value is an open file object
394 connected to the pipe, which can be read or written depending on whether *mode*
395 is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
396 the corresponding argument to the built-in :func:`open` function. The exit
397 status of the command (encoded in the format specified for :func:`wait`) is
398 available as the return value of the :meth:`~file.close` method of the file object,
399 except that when the exit status is zero (termination without errors), ``None``
400 is returned. Availability: Unix, Windows.
403 This function is obsolete. Use the :mod:`subprocess` module. Check
404 especially the :ref:`subprocess-replacements` section.
406 .. versionchanged:: 2.0
407 This function worked unreliably under Windows in earlier versions of Python.
408 This was due to the use of the :cfunc:`_popen` function from the libraries
409 provided with Windows. Newer versions of Python do not use the broken
410 implementation from the Windows libraries.
413 .. function:: tmpfile()
415 Return a new file object opened in update mode (``w+b``). The file has no
416 directory entries associated with it and will be automatically deleted once
417 there are no file descriptors for the file. Availability: Unix,
420 There are a number of different :func:`popen\*` functions that provide slightly
421 different ways to create subprocesses.
424 All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
427 For each of the :func:`popen\*` variants, if *bufsize* is specified, it
428 specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
429 string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
430 file objects should be opened in binary or text mode. The default value for
433 Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
434 case arguments will be passed directly to the program without shell intervention
435 (as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
436 (as with :func:`os.system`).
438 These methods do not make it possible to retrieve the exit status from the child
439 processes. The only way to control the input and output streams and also
440 retrieve the return codes is to use the :mod:`subprocess` module; these are only
443 For a discussion of possible deadlock conditions related to the use of these
444 functions, see :ref:`popen2-flow-control`.
447 .. function:: popen2(cmd[, mode[, bufsize]])
449 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
453 This function is obsolete. Use the :mod:`subprocess` module. Check
454 especially the :ref:`subprocess-replacements` section.
456 Availability: Unix, Windows.
458 .. versionadded:: 2.0
461 .. function:: popen3(cmd[, mode[, bufsize]])
463 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
464 child_stdout, child_stderr)``.
467 This function is obsolete. Use the :mod:`subprocess` module. Check
468 especially the :ref:`subprocess-replacements` section.
470 Availability: Unix, Windows.
472 .. versionadded:: 2.0
475 .. function:: popen4(cmd[, mode[, bufsize]])
477 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
478 child_stdout_and_stderr)``.
481 This function is obsolete. Use the :mod:`subprocess` module. Check
482 especially the :ref:`subprocess-replacements` section.
484 Availability: Unix, Windows.
486 .. versionadded:: 2.0
488 (Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
489 point of view of the child process, so *child_stdin* is the child's standard
492 This functionality is also available in the :mod:`popen2` module using functions
493 of the same names, but the return values of those functions have a different
499 File Descriptor Operations
500 --------------------------
502 These functions operate on I/O streams referenced using file descriptors.
504 File descriptors are small integers corresponding to a file that has been opened
505 by the current process. For example, standard input is usually file descriptor
506 0, standard output is 1, and standard error is 2. Further files opened by a
507 process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
508 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
512 .. function:: close(fd)
514 Close file descriptor *fd*. Availability: Unix, Windows.
518 This function is intended for low-level I/O and must be applied to a file
519 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
520 object" returned by the built-in function :func:`open` or by :func:`popen` or
521 :func:`fdopen`, use its :meth:`~file.close` method.
524 .. function:: closerange(fd_low, fd_high)
526 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
527 ignoring errors. Availability: Unix, Windows. Equivalent to::
529 for fd in xrange(fd_low, fd_high):
535 .. versionadded:: 2.6
538 .. function:: dup(fd)
540 Return a duplicate of file descriptor *fd*. Availability: Unix,
544 .. function:: dup2(fd, fd2)
546 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
547 Availability: Unix, Windows.
550 .. function:: fchmod(fd, mode)
552 Change the mode of the file given by *fd* to the numeric *mode*. See the docs
553 for :func:`chmod` for possible values of *mode*. Availability: Unix.
555 .. versionadded:: 2.6
558 .. function:: fchown(fd, uid, gid)
560 Change the owner and group id of the file given by *fd* to the numeric *uid*
561 and *gid*. To leave one of the ids unchanged, set it to -1.
564 .. versionadded:: 2.6
567 .. function:: fdatasync(fd)
569 Force write of file with filedescriptor *fd* to disk. Does not force update of
570 metadata. Availability: Unix.
573 This function is not available on MacOS.
576 .. function:: fpathconf(fd, name)
578 Return system configuration information relevant to an open file. *name*
579 specifies the configuration value to retrieve; it may be a string which is the
580 name of a defined system value; these names are specified in a number of
581 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
582 additional names as well. The names known to the host operating system are
583 given in the ``pathconf_names`` dictionary. For configuration variables not
584 included in that mapping, passing an integer for *name* is also accepted.
587 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
588 specific value for *name* is not supported by the host system, even if it is
589 included in ``pathconf_names``, an :exc:`OSError` is raised with
590 :const:`errno.EINVAL` for the error number.
593 .. function:: fstat(fd)
595 Return status for file descriptor *fd*, like :func:`stat`. Availability:
599 .. function:: fstatvfs(fd)
601 Return information about the filesystem containing the file associated with file
602 descriptor *fd*, like :func:`statvfs`. Availability: Unix.
605 .. function:: fsync(fd)
607 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
608 native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
610 If you're starting with a Python file object *f*, first do ``f.flush()``, and
611 then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
612 with *f* are written to disk. Availability: Unix, and Windows
616 .. function:: ftruncate(fd, length)
618 Truncate the file corresponding to file descriptor *fd*, so that it is at most
619 *length* bytes in size. Availability: Unix.
622 .. function:: isatty(fd)
624 Return ``True`` if the file descriptor *fd* is open and connected to a
625 tty(-like) device, else ``False``. Availability: Unix.
628 .. function:: lseek(fd, pos, how)
630 Set the current position of file descriptor *fd* to position *pos*, modified
631 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
632 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
633 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
634 the file. Availability: Unix, Windows.
637 .. function:: open(file, flags[, mode])
639 Open the file *file* and set various flags according to *flags* and possibly its
640 mode according to *mode*. The default *mode* is ``0777`` (octal), and the
641 current umask value is first masked out. Return the file descriptor for the
642 newly opened file. Availability: Unix, Windows.
644 For a description of the flag and mode values, see the C run-time documentation;
645 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
646 this module too (see below).
650 This function is intended for low-level I/O. For normal usage, use the
651 built-in function :func:`open`, which returns a "file object" with
652 :meth:`~file.read` and :meth:`~file.write` methods (and many more). To
653 wrap a file descriptor in a "file object", use :func:`fdopen`.
656 .. function:: openpty()
658 .. index:: module: pty
660 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
661 slave)`` for the pty and the tty, respectively. For a (slightly) more portable
662 approach, use the :mod:`pty` module. Availability: some flavors of
668 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
669 and writing, respectively. Availability: Unix, Windows.
672 .. function:: read(fd, n)
674 Read at most *n* bytes from file descriptor *fd*. Return a string containing the
675 bytes read. If the end of the file referred to by *fd* has been reached, an
676 empty string is returned. Availability: Unix, Windows.
680 This function is intended for low-level I/O and must be applied to a file
681 descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object"
682 returned by the built-in function :func:`open` or by :func:`popen` or
683 :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
684 :meth:`~file.readline` methods.
687 .. function:: tcgetpgrp(fd)
689 Return the process group associated with the terminal given by *fd* (an open
690 file descriptor as returned by :func:`os.open`). Availability: Unix.
693 .. function:: tcsetpgrp(fd, pg)
695 Set the process group associated with the terminal given by *fd* (an open file
696 descriptor as returned by :func:`os.open`) to *pg*. Availability: Unix.
699 .. function:: ttyname(fd)
701 Return a string which specifies the terminal device associated with
702 file descriptor *fd*. If *fd* is not associated with a terminal device, an
703 exception is raised. Availability: Unix.
706 .. function:: write(fd, str)
708 Write the string *str* to file descriptor *fd*. Return the number of bytes
709 actually written. Availability: Unix, Windows.
713 This function is intended for low-level I/O and must be applied to a file
714 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
715 object" returned by the built-in function :func:`open` or by :func:`popen` or
716 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
717 :meth:`~file.write` method.
719 The following constants are options for the *flags* parameter to the
720 :func:`~os.open` function. They can be combined using the bitwise OR operator
721 ``|``. Some of them are not available on all platforms. For descriptions of
722 their availability and use, consult the :manpage:`open(2)` manual page on Unix
723 or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
734 These constants are available on Unix and Windows.
746 These constants are only available on Unix.
757 These constants are only available on Windows.
766 These constants are GNU extensions and not present if they are not defined by
774 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
775 respectively. Availability: Windows, Unix.
777 .. versionadded:: 2.5
782 Files and Directories
783 ---------------------
785 .. function:: access(path, mode)
787 Use the real uid/gid to test for access to *path*. Note that most operations
788 will use the effective uid/gid, therefore this routine can be used in a
789 suid/sgid environment to test if the invoking user has the specified access to
790 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
791 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
792 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
793 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
794 information. Availability: Unix, Windows.
798 Using :func:`access` to check if a user is authorized to e.g. open a file
799 before actually doing so using :func:`open` creates a security hole,
800 because the user might exploit the short time interval between checking
801 and opening the file to manipulate it.
805 I/O operations may fail even when :func:`access` indicates that they would
806 succeed, particularly for operations on network filesystems which may have
807 permissions semantics beyond the usual POSIX permission-bit model.
812 Value to pass as the *mode* parameter of :func:`access` to test the existence of
818 Value to include in the *mode* parameter of :func:`access` to test the
819 readability of *path*.
824 Value to include in the *mode* parameter of :func:`access` to test the
825 writability of *path*.
830 Value to include in the *mode* parameter of :func:`access` to determine if
831 *path* can be executed.
834 .. function:: chdir(path)
836 .. index:: single: directory; changing
838 Change the current working directory to *path*. Availability: Unix,
842 .. function:: fchdir(fd)
844 Change the current working directory to the directory represented by the file
845 descriptor *fd*. The descriptor must refer to an opened directory, not an open
846 file. Availability: Unix.
848 .. versionadded:: 2.3
851 .. function:: getcwd()
853 Return a string representing the current working directory. Availability:
857 .. function:: getcwdu()
859 Return a Unicode object representing the current working directory.
860 Availability: Unix, Windows.
862 .. versionadded:: 2.3
865 .. function:: chflags(path, flags)
867 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
868 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
883 .. versionadded:: 2.6
886 .. function:: chroot(path)
888 Change the root directory of the current process to *path*. Availability:
891 .. versionadded:: 2.2
894 .. function:: chmod(path, mode)
896 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
897 following values (as defined in the :mod:`stat` module) or bitwise ORed
898 combinations of them:
901 * :data:`stat.S_ISUID`
902 * :data:`stat.S_ISGID`
903 * :data:`stat.S_ENFMT`
904 * :data:`stat.S_ISVTX`
905 * :data:`stat.S_IREAD`
906 * :data:`stat.S_IWRITE`
907 * :data:`stat.S_IEXEC`
908 * :data:`stat.S_IRWXU`
909 * :data:`stat.S_IRUSR`
910 * :data:`stat.S_IWUSR`
911 * :data:`stat.S_IXUSR`
912 * :data:`stat.S_IRWXG`
913 * :data:`stat.S_IRGRP`
914 * :data:`stat.S_IWGRP`
915 * :data:`stat.S_IXGRP`
916 * :data:`stat.S_IRWXO`
917 * :data:`stat.S_IROTH`
918 * :data:`stat.S_IWOTH`
919 * :data:`stat.S_IXOTH`
921 Availability: Unix, Windows.
925 Although Windows supports :func:`chmod`, you can only set the file's read-only
926 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
927 constants or a corresponding integer value). All other bits are
931 .. function:: chown(path, uid, gid)
933 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
934 one of the ids unchanged, set it to -1. Availability: Unix.
937 .. function:: lchflags(path, flags)
939 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
940 follow symbolic links. Availability: Unix.
942 .. versionadded:: 2.6
945 .. function:: lchmod(path, mode)
947 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
948 affects the symlink rather than the target. See the docs for :func:`chmod`
949 for possible values of *mode*. Availability: Unix.
951 .. versionadded:: 2.6
954 .. function:: lchown(path, uid, gid)
956 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
957 function will not follow symbolic links. Availability: Unix.
959 .. versionadded:: 2.3
962 .. function:: link(source, link_name)
964 Create a hard link pointing to *source* named *link_name*. Availability:
968 .. function:: listdir(path)
970 Return a list containing the names of the entries in the directory given by
971 *path*. The list is in arbitrary order. It does not include the special
972 entries ``'.'`` and ``'..'`` even if they are present in the
973 directory. Availability: Unix, Windows.
975 .. versionchanged:: 2.3
976 On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
977 a list of Unicode objects. Undecodable filenames will still be returned as
981 .. function:: lstat(path)
983 Like :func:`stat`, but do not follow symbolic links. This is an alias for
984 :func:`stat` on platforms that do not support symbolic links, such as
988 .. function:: mkfifo(path[, mode])
990 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default
991 *mode* is ``0666`` (octal). The current umask value is first masked out from
992 the mode. Availability: Unix.
994 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
995 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
996 rendezvous between "client" and "server" type processes: the server opens the
997 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
998 doesn't open the FIFO --- it just creates the rendezvous point.
1001 .. function:: mknod(filename[, mode=0600, device])
1003 Create a filesystem node (file, device special file or named pipe) named
1004 *filename*. *mode* specifies both the permissions to use and the type of node to
1005 be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
1006 ``stat.S_IFCHR``, ``stat.S_IFBLK``,
1007 and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
1008 For ``stat.S_IFCHR`` and
1009 ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
1010 :func:`os.makedev`), otherwise it is ignored.
1012 .. versionadded:: 2.3
1015 .. function:: major(device)
1017 Extract the device major number from a raw device number (usually the
1018 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
1020 .. versionadded:: 2.3
1023 .. function:: minor(device)
1025 Extract the device minor number from a raw device number (usually the
1026 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
1028 .. versionadded:: 2.3
1031 .. function:: makedev(major, minor)
1033 Compose a raw device number from the major and minor device numbers.
1035 .. versionadded:: 2.3
1038 .. function:: mkdir(path[, mode])
1040 Create a directory named *path* with numeric mode *mode*. The default *mode* is
1041 ``0777`` (octal). On some systems, *mode* is ignored. Where it is used, the
1042 current umask value is first masked out. Availability: Unix, Windows.
1044 It is also possible to create temporary directories; see the
1045 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1048 .. function:: makedirs(path[, mode])
1051 single: directory; creating
1052 single: UNC paths; and os.makedirs()
1054 Recursive directory creation function. Like :func:`mkdir`, but makes all
1055 intermediate-level directories needed to contain the leaf directory. Throws an
1056 :exc:`error` exception if the leaf directory already exists or cannot be
1057 created. The default *mode* is ``0777`` (octal). On some systems, *mode* is
1058 ignored. Where it is used, the current umask value is first masked out.
1062 :func:`makedirs` will become confused if the path elements to create include
1065 .. versionadded:: 1.5.2
1067 .. versionchanged:: 2.3
1068 This function now handles UNC paths correctly.
1071 .. function:: pathconf(path, name)
1073 Return system configuration information relevant to a named file. *name*
1074 specifies the configuration value to retrieve; it may be a string which is the
1075 name of a defined system value; these names are specified in a number of
1076 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1077 additional names as well. The names known to the host operating system are
1078 given in the ``pathconf_names`` dictionary. For configuration variables not
1079 included in that mapping, passing an integer for *name* is also accepted.
1082 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1083 specific value for *name* is not supported by the host system, even if it is
1084 included in ``pathconf_names``, an :exc:`OSError` is raised with
1085 :const:`errno.EINVAL` for the error number.
1088 .. data:: pathconf_names
1090 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1091 the integer values defined for those names by the host operating system. This
1092 can be used to determine the set of names known to the system. Availability:
1096 .. function:: readlink(path)
1098 Return a string representing the path to which the symbolic link points. The
1099 result may be either an absolute or relative pathname; if it is relative, it may
1100 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
1103 .. versionchanged:: 2.6
1104 If the *path* is a Unicode object the result will also be a Unicode object.
1109 .. function:: remove(path)
1111 Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
1112 raised; see :func:`rmdir` below to remove a directory. This is identical to
1113 the :func:`unlink` function documented below. On Windows, attempting to
1114 remove a file that is in use causes an exception to be raised; on Unix, the
1115 directory entry is removed but the storage allocated to the file is not made
1116 available until the original file is no longer in use. Availability: Unix,
1120 .. function:: removedirs(path)
1122 .. index:: single: directory; deleting
1124 Remove directories recursively. Works like :func:`rmdir` except that, if the
1125 leaf directory is successfully removed, :func:`removedirs` tries to
1126 successively remove every parent directory mentioned in *path* until an error
1127 is raised (which is ignored, because it generally means that a parent directory
1128 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1129 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1130 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1131 successfully removed.
1133 .. versionadded:: 1.5.2
1136 .. function:: rename(src, dst)
1138 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1139 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
1140 be replaced silently if the user has permission. The operation may fail on some
1141 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1142 the renaming will be an atomic operation (this is a POSIX requirement). On
1143 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1144 file; there may be no way to implement an atomic rename when *dst* names an
1145 existing file. Availability: Unix, Windows.
1148 .. function:: renames(old, new)
1150 Recursive directory or file renaming function. Works like :func:`rename`, except
1151 creation of any intermediate directories needed to make the new pathname good is
1152 attempted first. After the rename, directories corresponding to rightmost path
1153 segments of the old name will be pruned away using :func:`removedirs`.
1155 .. versionadded:: 1.5.2
1159 This function can fail with the new directory structure made if you lack
1160 permissions needed to remove the leaf directory or file.
1163 .. function:: rmdir(path)
1165 Remove (delete) the directory *path*. Only works when the directory is
1166 empty, otherwise, :exc:`OSError` is raised. In order to remove whole
1167 directory trees, :func:`shutil.rmtree` can be used. Availability: Unix,
1171 .. function:: stat(path)
1173 Perform a :cfunc:`stat` system call on the given path. The return value is an
1174 object whose attributes correspond to the members of the :ctype:`stat`
1175 structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
1176 number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
1177 :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
1178 :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
1179 access), :attr:`st_mtime` (time of most recent content modification),
1180 :attr:`st_ctime` (platform dependent; time of most recent metadata change on
1181 Unix, or the time of creation on Windows)::
1184 >>> statinfo = os.stat('somefile.txt')
1186 (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
1187 >>> statinfo.st_size
1191 .. versionchanged:: 2.3
1192 If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
1193 seconds. Fractions of a second may be reported if the system supports that. On
1194 Mac OS, the times are always floats. See :func:`stat_float_times` for further
1197 On some Unix systems (such as Linux), the following attributes may also be
1198 available: :attr:`st_blocks` (number of blocks allocated for file),
1199 :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
1200 inode device). :attr:`st_flags` (user defined flags for file).
1202 On other Unix systems (such as FreeBSD), the following attributes may be
1203 available (but may be only filled out if root tries to use them): :attr:`st_gen`
1204 (file generation number), :attr:`st_birthtime` (time of file creation).
1206 On Mac OS systems, the following attributes may also be available:
1207 :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
1209 On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
1210 (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
1212 .. index:: module: stat
1214 For backward compatibility, the return value of :func:`stat` is also accessible
1215 as a tuple of at least 10 integers giving the most important (and portable)
1216 members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
1217 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
1218 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
1219 :attr:`st_ctime`. More items may be added at the end by some implementations.
1220 The standard module :mod:`stat` defines functions and constants that are useful
1221 for extracting information from a :ctype:`stat` structure. (On Windows, some
1222 items are filled with dummy values.)
1226 The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1227 :attr:`st_ctime` members depends on the operating system and the file system.
1228 For example, on Windows systems using the FAT or FAT32 file systems,
1229 :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1230 resolution. See your operating system documentation for details.
1232 Availability: Unix, Windows.
1234 .. versionchanged:: 2.2
1235 Added access to values as attributes of the returned object.
1237 .. versionchanged:: 2.5
1238 Added :attr:`st_gen` and :attr:`st_birthtime`.
1241 .. function:: stat_float_times([newvalue])
1243 Determine whether :class:`stat_result` represents time stamps as float objects.
1244 If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
1245 ``False``, future calls return ints. If *newvalue* is omitted, return the
1248 For compatibility with older Python versions, accessing :class:`stat_result` as
1249 a tuple always returns integers.
1251 .. versionchanged:: 2.5
1252 Python now returns float values by default. Applications which do not work
1253 correctly with floating point time stamps can use this function to restore the
1256 The resolution of the timestamps (that is the smallest possible fraction)
1257 depends on the system. Some systems only support second resolution; on these
1258 systems, the fraction will always be zero.
1260 It is recommended that this setting is only changed at program startup time in
1261 the *__main__* module; libraries should never change this setting. If an
1262 application uses a library that works incorrectly if floating point time stamps
1263 are processed, this application should turn the feature off until the library
1267 .. function:: statvfs(path)
1269 Perform a :cfunc:`statvfs` system call on the given path. The return value is
1270 an object whose attributes describe the filesystem on the given path, and
1271 correspond to the members of the :ctype:`statvfs` structure, namely:
1272 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1273 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
1274 :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.
1276 .. index:: module: statvfs
1278 For backward compatibility, the return value is also accessible as a tuple whose
1279 values correspond to the attributes, in the order given above. The standard
1280 module :mod:`statvfs` defines constants that are useful for extracting
1281 information from a :ctype:`statvfs` structure when accessing it as a sequence;
1282 this remains useful when writing code that needs to work with versions of Python
1283 that don't support accessing the fields as attributes.
1285 .. versionchanged:: 2.2
1286 Added access to values as attributes of the returned object.
1289 .. function:: symlink(source, link_name)
1291 Create a symbolic link pointing to *source* named *link_name*. Availability:
1295 .. function:: tempnam([dir[, prefix]])
1297 Return a unique path name that is reasonable for creating a temporary file.
1298 This will be an absolute path that names a potential directory entry in the
1299 directory *dir* or a common location for temporary files if *dir* is omitted or
1300 ``None``. If given and not ``None``, *prefix* is used to provide a short prefix
1301 to the filename. Applications are responsible for properly creating and
1302 managing files created using paths returned by :func:`tempnam`; no automatic
1303 cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
1304 overrides *dir*, while on Windows :envvar:`TMP` is used. The specific
1305 behavior of this function depends on the C library implementation; some aspects
1306 are underspecified in system documentation.
1310 Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
1311 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1313 Availability: Unix, Windows.
1316 .. function:: tmpnam()
1318 Return a unique path name that is reasonable for creating a temporary file.
1319 This will be an absolute path that names a potential directory entry in a common
1320 location for temporary files. Applications are responsible for properly
1321 creating and managing files created using paths returned by :func:`tmpnam`; no
1322 automatic cleanup is provided.
1326 Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
1327 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1329 Availability: Unix, Windows. This function probably shouldn't be used on
1330 Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
1331 name in the root directory of the current drive, and that's generally a poor
1332 location for a temp file (depending on privileges, you may not even be able to
1333 open a file using this name).
1338 The maximum number of unique names that :func:`tmpnam` will generate before
1342 .. function:: unlink(path)
1344 Remove (delete) the file *path*. This is the same function as
1345 :func:`remove`; the :func:`unlink` name is its traditional Unix
1346 name. Availability: Unix, Windows.
1349 .. function:: utime(path, times)
1351 Set the access and modified times of the file specified by *path*. If *times*
1352 is ``None``, then the file's access and modified times are set to the current
1353 time. (The effect is similar to running the Unix program :program:`touch` on
1354 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
1355 ``(atime, mtime)`` which is used to set the access and modified times,
1356 respectively. Whether a directory can be given for *path* depends on whether
1357 the operating system implements directories as files (for example, Windows
1358 does not). Note that the exact times you set here may not be returned by a
1359 subsequent :func:`stat` call, depending on the resolution with which your
1360 operating system records access and modification times; see :func:`stat`.
1362 .. versionchanged:: 2.0
1363 Added support for ``None`` for *times*.
1365 Availability: Unix, Windows.
1368 .. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
1371 single: directory; walking
1372 single: directory; traversal
1374 Generate the file names in a directory tree by walking the tree
1375 either top-down or bottom-up. For each directory in the tree rooted at directory
1376 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1379 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
1380 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1381 *filenames* is a list of the names of the non-directory files in *dirpath*.
1382 Note that the names in the lists contain no path components. To get a full path
1383 (which begins with *top*) to a file or directory in *dirpath*, do
1384 ``os.path.join(dirpath, name)``.
1386 If optional argument *topdown* is ``True`` or not specified, the triple for a
1387 directory is generated before the triples for any of its subdirectories
1388 (directories are generated top-down). If *topdown* is ``False``, the triple for a
1389 directory is generated after the triples for all of its subdirectories
1390 (directories are generated bottom-up).
1392 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
1393 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1394 recurse into the subdirectories whose names remain in *dirnames*; this can be
1395 used to prune the search, impose a specific order of visiting, or even to inform
1396 :func:`walk` about directories the caller creates or renames before it resumes
1397 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
1398 ineffective, because in bottom-up mode the directories in *dirnames* are
1399 generated before *dirpath* itself is generated.
1401 By default errors from the :func:`listdir` call are ignored. If optional
1402 argument *onerror* is specified, it should be a function; it will be called with
1403 one argument, an :exc:`OSError` instance. It can report the error to continue
1404 with the walk, or raise the exception to abort the walk. Note that the filename
1405 is available as the ``filename`` attribute of the exception object.
1407 By default, :func:`walk` will not walk down into symbolic links that resolve to
1408 directories. Set *followlinks* to ``True`` to visit directories pointed to by
1409 symlinks, on systems that support them.
1411 .. versionadded:: 2.6
1412 The *followlinks* parameter.
1416 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
1417 link points to a parent directory of itself. :func:`walk` does not keep track of
1418 the directories it visited already.
1422 If you pass a relative pathname, don't change the current working directory
1423 between resumptions of :func:`walk`. :func:`walk` never changes the current
1424 directory, and assumes that its caller doesn't either.
1426 This example displays the number of bytes taken by non-directory files in each
1427 directory under the starting directory, except that it doesn't look under any
1431 from os.path import join, getsize
1432 for root, dirs, files in os.walk('python/Lib/email'):
1433 print root, "consumes",
1434 print sum(getsize(join(root, name)) for name in files),
1435 print "bytes in", len(files), "non-directory files"
1437 dirs.remove('CVS') # don't visit CVS directories
1439 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
1440 doesn't allow deleting a directory before the directory is empty::
1442 # Delete everything reachable from the directory named in "top",
1443 # assuming there are no symbolic links.
1444 # CAUTION: This is dangerous! For example, if top == '/', it
1445 # could delete all your disk files.
1447 for root, dirs, files in os.walk(top, topdown=False):
1449 os.remove(os.path.join(root, name))
1451 os.rmdir(os.path.join(root, name))
1453 .. versionadded:: 2.3
1461 These functions may be used to create and manage processes.
1463 The various :func:`exec\*` functions take a list of arguments for the new
1464 program loaded into the process. In each case, the first of these arguments is
1465 passed to the new program as its own name rather than as an argument a user may
1466 have typed on a command line. For the C programmer, this is the ``argv[0]``
1467 passed to a program's :cfunc:`main`. For example, ``os.execv('/bin/echo',
1468 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
1472 .. function:: abort()
1474 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
1475 behavior is to produce a core dump; on Windows, the process immediately returns
1476 an exit code of ``3``. Be aware that programs which use :func:`signal.signal`
1477 to register a handler for :const:`SIGABRT` will behave differently.
1478 Availability: Unix, Windows.
1481 .. function:: execl(path, arg0, arg1, ...)
1482 execle(path, arg0, arg1, ..., env)
1483 execlp(file, arg0, arg1, ...)
1484 execlpe(file, arg0, arg1, ..., env)
1486 execve(path, args, env)
1488 execvpe(file, args, env)
1490 These functions all execute a new program, replacing the current process; they
1491 do not return. On Unix, the new executable is loaded into the current process,
1492 and will have the same process id as the caller. Errors will be reported as
1493 :exc:`OSError` exceptions.
1495 The current process is replaced immediately. Open file objects and
1496 descriptors are not flushed, so if there may be data buffered
1497 on these open files, you should flush them using
1498 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1499 :func:`exec\*` function.
1501 The "l" and "v" variants of the :func:`exec\*` functions differ in how
1502 command-line arguments are passed. The "l" variants are perhaps the easiest
1503 to work with if the number of parameters is fixed when the code is written; the
1504 individual parameters simply become additional parameters to the :func:`execl\*`
1505 functions. The "v" variants are good when the number of parameters is
1506 variable, with the arguments being passed in a list or tuple as the *args*
1507 parameter. In either case, the arguments to the child process should start with
1508 the name of the command being run, but this is not enforced.
1510 The variants which include a "p" near the end (:func:`execlp`,
1511 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1512 :envvar:`PATH` environment variable to locate the program *file*. When the
1513 environment is being replaced (using one of the :func:`exec\*e` variants,
1514 discussed in the next paragraph), the new environment is used as the source of
1515 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1516 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1517 locate the executable; *path* must contain an appropriate absolute or relative
1520 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
1521 that these all end in "e"), the *env* parameter must be a mapping which is
1522 used to define the environment variables for the new process (these are used
1523 instead of the current process' environment); the functions :func:`execl`,
1524 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
1525 inherit the environment of the current process.
1527 Availability: Unix, Windows.
1530 .. function:: _exit(n)
1532 Exit to the system with status *n*, without calling cleanup handlers, flushing
1533 stdio buffers, etc. Availability: Unix, Windows.
1537 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
1538 be used in the child process after a :func:`fork`.
1540 The following exit codes are defined and can be used with :func:`_exit`,
1541 although they are not required. These are typically used for system programs
1542 written in Python, such as a mail server's external command delivery program.
1546 Some of these may not be available on all Unix platforms, since there is some
1547 variation. These constants are defined where they are defined by the underlying
1553 Exit code that means no error occurred. Availability: Unix.
1555 .. versionadded:: 2.3
1560 Exit code that means the command was used incorrectly, such as when the wrong
1561 number of arguments are given. Availability: Unix.
1563 .. versionadded:: 2.3
1566 .. data:: EX_DATAERR
1568 Exit code that means the input data was incorrect. Availability: Unix.
1570 .. versionadded:: 2.3
1573 .. data:: EX_NOINPUT
1575 Exit code that means an input file did not exist or was not readable.
1578 .. versionadded:: 2.3
1583 Exit code that means a specified user did not exist. Availability: Unix.
1585 .. versionadded:: 2.3
1590 Exit code that means a specified host did not exist. Availability: Unix.
1592 .. versionadded:: 2.3
1595 .. data:: EX_UNAVAILABLE
1597 Exit code that means that a required service is unavailable. Availability:
1600 .. versionadded:: 2.3
1603 .. data:: EX_SOFTWARE
1605 Exit code that means an internal software error was detected. Availability:
1608 .. versionadded:: 2.3
1613 Exit code that means an operating system error was detected, such as the
1614 inability to fork or create a pipe. Availability: Unix.
1616 .. versionadded:: 2.3
1621 Exit code that means some system file did not exist, could not be opened, or had
1622 some other kind of error. Availability: Unix.
1624 .. versionadded:: 2.3
1627 .. data:: EX_CANTCREAT
1629 Exit code that means a user specified output file could not be created.
1632 .. versionadded:: 2.3
1637 Exit code that means that an error occurred while doing I/O on some file.
1640 .. versionadded:: 2.3
1643 .. data:: EX_TEMPFAIL
1645 Exit code that means a temporary failure occurred. This indicates something
1646 that may not really be an error, such as a network connection that couldn't be
1647 made during a retryable operation. Availability: Unix.
1649 .. versionadded:: 2.3
1652 .. data:: EX_PROTOCOL
1654 Exit code that means that a protocol exchange was illegal, invalid, or not
1655 understood. Availability: Unix.
1657 .. versionadded:: 2.3
1662 Exit code that means that there were insufficient permissions to perform the
1663 operation (but not intended for file system problems). Availability: Unix.
1665 .. versionadded:: 2.3
1670 Exit code that means that some kind of configuration error occurred.
1673 .. versionadded:: 2.3
1676 .. data:: EX_NOTFOUND
1678 Exit code that means something like "an entry was not found". Availability:
1681 .. versionadded:: 2.3
1684 .. function:: fork()
1686 Fork a child process. Return ``0`` in the child and the child's process id in the
1687 parent. If an error occurs :exc:`OSError` is raised.
1689 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1690 known issues when using fork() from a thread.
1695 .. function:: forkpty()
1697 Fork a child process, using a new pseudo-terminal as the child's controlling
1698 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1699 new child's process id in the parent, and *fd* is the file descriptor of the
1700 master end of the pseudo-terminal. For a more portable approach, use the
1701 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
1702 Availability: some flavors of Unix.
1705 .. function:: kill(pid, sig)
1708 single: process; killing
1709 single: process; signalling
1711 Send signal *sig* to the process *pid*. Constants for the specific signals
1712 available on the host platform are defined in the :mod:`signal` module.
1716 .. function:: killpg(pgid, sig)
1719 single: process; killing
1720 single: process; signalling
1722 Send the signal *sig* to the process group *pgid*. Availability: Unix.
1724 .. versionadded:: 2.3
1727 .. function:: nice(increment)
1729 Add *increment* to the process's "niceness". Return the new niceness.
1733 .. function:: plock(op)
1735 Lock program segments into memory. The value of *op* (defined in
1736 ``<sys/lock.h>``) determines which segments are locked. Availability: Unix.
1739 .. function:: popen(...)
1745 Run child processes, returning opened pipes for communications. These functions
1746 are described in section :ref:`os-newstreams`.
1749 .. function:: spawnl(mode, path, ...)
1750 spawnle(mode, path, ..., env)
1751 spawnlp(mode, file, ...)
1752 spawnlpe(mode, file, ..., env)
1753 spawnv(mode, path, args)
1754 spawnve(mode, path, args, env)
1755 spawnvp(mode, file, args)
1756 spawnvpe(mode, file, args, env)
1758 Execute the program *path* in a new process.
1760 (Note that the :mod:`subprocess` module provides more powerful facilities for
1761 spawning new processes and retrieving their results; using that module is
1762 preferable to using these functions. Check especially the
1763 :ref:`subprocess-replacements` section.)
1765 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
1766 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1767 exits normally, or ``-signal``, where *signal* is the signal that killed the
1768 process. On Windows, the process id will actually be the process handle, so can
1769 be used with the :func:`waitpid` function.
1771 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1772 command-line arguments are passed. The "l" variants are perhaps the easiest
1773 to work with if the number of parameters is fixed when the code is written; the
1774 individual parameters simply become additional parameters to the
1775 :func:`spawnl\*` functions. The "v" variants are good when the number of
1776 parameters is variable, with the arguments being passed in a list or tuple as
1777 the *args* parameter. In either case, the arguments to the child process must
1778 start with the name of the command being run.
1780 The variants which include a second "p" near the end (:func:`spawnlp`,
1781 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1782 :envvar:`PATH` environment variable to locate the program *file*. When the
1783 environment is being replaced (using one of the :func:`spawn\*e` variants,
1784 discussed in the next paragraph), the new environment is used as the source of
1785 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
1786 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1787 :envvar:`PATH` variable to locate the executable; *path* must contain an
1788 appropriate absolute or relative path.
1790 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
1791 (note that these all end in "e"), the *env* parameter must be a mapping
1792 which is used to define the environment variables for the new process (they are
1793 used instead of the current process' environment); the functions
1794 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
1795 the new process to inherit the environment of the current process. Note that
1796 keys and values in the *env* dictionary must be strings; invalid keys or
1797 values will cause the function to fail, with a return value of ``127``.
1799 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1803 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1805 L = ['cp', 'index.html', '/dev/null']
1806 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
1808 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
1809 and :func:`spawnvpe` are not available on Windows.
1811 .. versionadded:: 1.6
1817 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1818 functions. If either of these values is given, the :func:`spawn\*` functions
1819 will return as soon as the new process has been created, with the process id as
1820 the return value. Availability: Unix, Windows.
1822 .. versionadded:: 1.6
1827 Possible value for the *mode* parameter to the :func:`spawn\*` family of
1828 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
1829 return until the new process has run to completion and will return the exit code
1830 of the process the run is successful, or ``-signal`` if a signal kills the
1831 process. Availability: Unix, Windows.
1833 .. versionadded:: 1.6
1839 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1840 functions. These are less portable than those listed above. :const:`P_DETACH`
1841 is similar to :const:`P_NOWAIT`, but the new process is detached from the
1842 console of the calling process. If :const:`P_OVERLAY` is used, the current
1843 process will be replaced; the :func:`spawn\*` function will not return.
1844 Availability: Windows.
1846 .. versionadded:: 1.6
1849 .. function:: startfile(path[, operation])
1851 Start a file with its associated application.
1853 When *operation* is not specified or ``'open'``, this acts like double-clicking
1854 the file in Windows Explorer, or giving the file name as an argument to the
1855 :program:`start` command from the interactive command shell: the file is opened
1856 with whatever application (if any) its extension is associated.
1858 When another *operation* is given, it must be a "command verb" that specifies
1859 what should be done with the file. Common verbs documented by Microsoft are
1860 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
1861 ``'find'`` (to be used on directories).
1863 :func:`startfile` returns as soon as the associated application is launched.
1864 There is no option to wait for the application to close, and no way to retrieve
1865 the application's exit status. The *path* parameter is relative to the current
1866 directory. If you want to use an absolute path, make sure the first character
1867 is not a slash (``'/'``); the underlying Win32 :cfunc:`ShellExecute` function
1868 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
1869 the path is properly encoded for Win32. Availability: Windows.
1871 .. versionadded:: 2.0
1873 .. versionadded:: 2.5
1874 The *operation* parameter.
1877 .. function:: system(command)
1879 Execute the command (a string) in a subshell. This is implemented by calling
1880 the Standard C function :cfunc:`system`, and has the same limitations.
1881 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the
1884 On Unix, the return value is the exit status of the process encoded in the
1885 format specified for :func:`wait`. Note that POSIX does not specify the meaning
1886 of the return value of the C :cfunc:`system` function, so the return value of
1887 the Python function is system-dependent.
1889 On Windows, the return value is that returned by the system shell after running
1890 *command*, given by the Windows environment variable :envvar:`COMSPEC`: on
1891 :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
1892 :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
1893 the command run; on systems using a non-native shell, consult your shell
1896 Availability: Unix, Windows.
1898 The :mod:`subprocess` module provides more powerful facilities for spawning new
1899 processes and retrieving their results; using that module is preferable to using
1900 this function. Use the :mod:`subprocess` module. Check especially the
1901 :ref:`subprocess-replacements` section.
1904 .. function:: times()
1906 Return a 5-tuple of floating point numbers indicating accumulated (processor or
1907 other) times, in seconds. The items are: user time, system time, children's
1908 user time, children's system time, and elapsed real time since a fixed point in
1909 the past, in that order. See the Unix manual page :manpage:`times(2)` or the
1910 corresponding Windows Platform API documentation. Availability: Unix,
1911 Windows. On Windows, only the first two items are filled, the others are zero.
1914 .. function:: wait()
1916 Wait for completion of a child process, and return a tuple containing its pid
1917 and exit status indication: a 16-bit number, whose low byte is the signal number
1918 that killed the process, and whose high byte is the exit status (if the signal
1919 number is zero); the high bit of the low byte is set if a core file was
1920 produced. Availability: Unix.
1923 .. function:: waitpid(pid, options)
1925 The details of this function differ on Unix and Windows.
1927 On Unix: Wait for completion of a child process given by process id *pid*, and
1928 return a tuple containing its process id and exit status indication (encoded as
1929 for :func:`wait`). The semantics of the call are affected by the value of the
1930 integer *options*, which should be ``0`` for normal operation.
1932 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
1933 that specific process. If *pid* is ``0``, the request is for the status of any
1934 child in the process group of the current process. If *pid* is ``-1``, the
1935 request pertains to any child of the current process. If *pid* is less than
1936 ``-1``, status is requested for any process in the process group ``-pid`` (the
1937 absolute value of *pid*).
1939 An :exc:`OSError` is raised with the value of errno when the syscall
1942 On Windows: Wait for completion of a process given by process handle *pid*, and
1943 return a tuple containing *pid*, and its exit status shifted left by 8 bits
1944 (shifting makes cross-platform use of the function easier). A *pid* less than or
1945 equal to ``0`` has no special meaning on Windows, and raises an exception. The
1946 value of integer *options* has no effect. *pid* can refer to any process whose
1947 id is known, not necessarily a child process. The :func:`spawn` functions called
1948 with :const:`P_NOWAIT` return suitable process handles.
1951 .. function:: wait3([options])
1953 Similar to :func:`waitpid`, except no process id argument is given and a
1954 3-element tuple containing the child's process id, exit status indication, and
1955 resource usage information is returned. Refer to :mod:`resource`.\
1956 :func:`getrusage` for details on resource usage information. The option
1957 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
1960 .. versionadded:: 2.5
1963 .. function:: wait4(pid, options)
1965 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
1966 process id, exit status indication, and resource usage information is returned.
1967 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
1968 information. The arguments to :func:`wait4` are the same as those provided to
1969 :func:`waitpid`. Availability: Unix.
1971 .. versionadded:: 2.5
1976 The option for :func:`waitpid` to return immediately if no child process status
1977 is available immediately. The function returns ``(0, 0)`` in this case.
1981 .. data:: WCONTINUED
1983 This option causes child processes to be reported if they have been continued
1984 from a job control stop since their status was last reported. Availability: Some
1987 .. versionadded:: 2.3
1992 This option causes child processes to be reported if they have been stopped but
1993 their current state has not been reported since they were stopped. Availability:
1996 .. versionadded:: 2.3
1998 The following functions take a process status code as returned by
1999 :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
2000 used to determine the disposition of a process.
2003 .. function:: WCOREDUMP(status)
2005 Return ``True`` if a core dump was generated for the process, otherwise
2006 return ``False``. Availability: Unix.
2008 .. versionadded:: 2.3
2011 .. function:: WIFCONTINUED(status)
2013 Return ``True`` if the process has been continued from a job control stop,
2014 otherwise return ``False``. Availability: Unix.
2016 .. versionadded:: 2.3
2019 .. function:: WIFSTOPPED(status)
2021 Return ``True`` if the process has been stopped, otherwise return
2022 ``False``. Availability: Unix.
2025 .. function:: WIFSIGNALED(status)
2027 Return ``True`` if the process exited due to a signal, otherwise return
2028 ``False``. Availability: Unix.
2031 .. function:: WIFEXITED(status)
2033 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
2034 otherwise return ``False``. Availability: Unix.
2037 .. function:: WEXITSTATUS(status)
2039 If ``WIFEXITED(status)`` is true, return the integer parameter to the
2040 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
2044 .. function:: WSTOPSIG(status)
2046 Return the signal which caused the process to stop. Availability: Unix.
2049 .. function:: WTERMSIG(status)
2051 Return the signal which caused the process to exit. Availability: Unix.
2056 Miscellaneous System Information
2057 --------------------------------
2060 .. function:: confstr(name)
2062 Return string-valued system configuration values. *name* specifies the
2063 configuration value to retrieve; it may be a string which is the name of a
2064 defined system value; these names are specified in a number of standards (POSIX,
2065 Unix 95, Unix 98, and others). Some platforms define additional names as well.
2066 The names known to the host operating system are given as the keys of the
2067 ``confstr_names`` dictionary. For configuration variables not included in that
2068 mapping, passing an integer for *name* is also accepted. Availability:
2071 If the configuration value specified by *name* isn't defined, ``None`` is
2074 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
2075 specific value for *name* is not supported by the host system, even if it is
2076 included in ``confstr_names``, an :exc:`OSError` is raised with
2077 :const:`errno.EINVAL` for the error number.
2080 .. data:: confstr_names
2082 Dictionary mapping names accepted by :func:`confstr` to the integer values
2083 defined for those names by the host operating system. This can be used to
2084 determine the set of names known to the system. Availability: Unix.
2087 .. function:: getloadavg()
2089 Return the number of processes in the system run queue averaged over the last
2090 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
2091 unobtainable. Availability: Unix.
2093 .. versionadded:: 2.3
2096 .. function:: sysconf(name)
2098 Return integer-valued system configuration values. If the configuration value
2099 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
2100 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
2101 provides information on the known names is given by ``sysconf_names``.
2105 .. data:: sysconf_names
2107 Dictionary mapping names accepted by :func:`sysconf` to the integer values
2108 defined for those names by the host operating system. This can be used to
2109 determine the set of names known to the system. Availability: Unix.
2111 The following data values are used to support path manipulation operations. These
2112 are defined for all platforms.
2114 Higher-level operations on pathnames are defined in the :mod:`os.path` module.
2119 The constant string used by the operating system to refer to the current
2120 directory. This is ``'.'`` for Windows and POSIX. Also available via
2126 The constant string used by the operating system to refer to the parent
2127 directory. This is ``'..'`` for Windows and POSIX. Also available via
2133 The character used by the operating system to separate pathname components.
2134 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
2135 is not sufficient to be able to parse or concatenate pathnames --- use
2136 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
2137 useful. Also available via :mod:`os.path`.
2142 An alternative character used by the operating system to separate pathname
2143 components, or ``None`` if only one separator character exists. This is set to
2144 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
2150 The character which separates the base filename from the extension; for example,
2151 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
2153 .. versionadded:: 2.2
2158 The character conventionally used by the operating system to separate search
2159 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
2160 Windows. Also available via :mod:`os.path`.
2165 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2166 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2171 The string used to separate (or, rather, terminate) lines on the current
2172 platform. This may be a single character, such as ``'\n'`` for POSIX, or
2173 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2174 *os.linesep* as a line terminator when writing files opened in text mode (the
2175 default); use a single ``'\n'`` instead, on all platforms.
2180 The file path of the null device. For example: ``'/dev/null'`` for POSIX.
2181 Also available via :mod:`os.path`.
2183 .. versionadded:: 2.4
2188 Miscellaneous Functions
2189 -----------------------
2192 .. function:: urandom(n)
2194 Return a string of *n* random bytes suitable for cryptographic use.
2196 This function returns random bytes from an OS-specific randomness source. The
2197 returned data should be unpredictable enough for cryptographic applications,
2198 though its exact quality depends on the OS implementation. On a UNIX-like
2199 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
2200 If a randomness source is not found, :exc:`NotImplementedError` will be raised.
2202 .. versionadded:: 2.4