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'``.
51 The corresponding operating system dependent standard module for pathname
52 operations, such as :mod:`posixpath` or :mod:`ntpath`. Thus, given the proper
53 imports, ``os.path.split(file)`` is equivalent to but more portable than
54 ``posixpath.split(file)``. Note that this is also an importable module: it may
55 be imported directly as :mod:`os.path`.
63 These functions and data items provide information and operate on the current
69 A mapping object representing the string environment. For example,
70 ``environ['HOME']`` is the pathname of your home directory (on some platforms),
71 and is equivalent to ``getenv("HOME")`` in C.
73 This mapping is captured the first time the :mod:`os` module is imported,
74 typically during Python startup as part of processing :file:`site.py`. Changes
75 to the environment made after this time are not reflected in ``os.environ``,
76 except for changes made by modifying ``os.environ`` directly.
78 If the platform supports the :func:`putenv` function, this mapping may be used
79 to modify the environment as well as query the environment. :func:`putenv` will
80 be called automatically when the mapping is modified.
84 Calling :func:`putenv` directly does not change ``os.environ``, so it's better
85 to modify ``os.environ``.
89 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
90 cause memory leaks. Refer to the system documentation for
93 If :func:`putenv` is not provided, a modified copy of this mapping may be
94 passed to the appropriate process-creation functions to cause child processes
95 to use a modified environment.
97 If the platform supports the :func:`unsetenv` function, you can delete items in
98 this mapping to unset environment variables. :func:`unsetenv` will be called
99 automatically when an item is deleted from ``os.environ``, and when
100 one of the :meth:`pop` or :meth:`clear` methods is called.
102 .. versionchanged:: 2.6
103 Also unset environment variables when calling :meth:`os.environ.clear`
104 and :meth:`os.environ.pop`.
107 .. function:: chdir(path)
112 These functions are described in :ref:`os-file-dir`.
115 .. function:: ctermid()
117 Return the filename corresponding to the controlling terminal of the process.
121 .. function:: getegid()
123 Return the effective group id of the current process. This corresponds to the
124 "set id" bit on the file being executed in the current process. Availability:
128 .. function:: geteuid()
130 .. index:: single: user; effective id
132 Return the current process's effective user id. Availability: Unix.
135 .. function:: getgid()
137 .. index:: single: process; group
139 Return the real group id of the current process. Availability: Unix.
142 .. function:: getgroups()
144 Return list of supplemental group ids associated with the current process.
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:: getuid()
188 .. index:: single: user; id
190 Return the current process's user id. Availability: Unix.
193 .. function:: getenv(varname[, value])
195 Return the value of the environment variable *varname* if it exists, or *value*
196 if it doesn't. *value* defaults to ``None``. Availability: most flavors of
200 .. function:: putenv(varname, value)
202 .. index:: single: environment variables; setting
204 Set the environment variable named *varname* to the string *value*. Such
205 changes to the environment affect subprocesses started with :func:`os.system`,
206 :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
211 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
212 cause memory leaks. Refer to the system documentation for putenv.
214 When :func:`putenv` is supported, assignments to items in ``os.environ`` are
215 automatically translated into corresponding calls to :func:`putenv`; however,
216 calls to :func:`putenv` don't update ``os.environ``, so it is actually
217 preferable to assign to items of ``os.environ``.
220 .. function:: setegid(egid)
222 Set the current process's effective group id. Availability: Unix.
225 .. function:: seteuid(euid)
227 Set the current process's effective user id. Availability: Unix.
230 .. function:: setgid(gid)
232 Set the current process' group id. Availability: Unix.
235 .. function:: setgroups(groups)
237 Set the list of supplemental group ids associated with the current process to
238 *groups*. *groups* must be a sequence, and each element must be an integer
239 identifying a group. This operation is typically available only to the superuser.
242 .. versionadded:: 2.2
245 .. function:: setpgrp()
247 Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
248 which version is implemented (if any). See the Unix manual for the semantics.
252 .. function:: setpgid(pid, pgrp)
254 Call the system call :cfunc:`setpgid` to set the process group id of the
255 process with id *pid* to the process group with id *pgrp*. See the Unix manual
256 for the semantics. Availability: Unix.
259 .. function:: setreuid(ruid, euid)
261 Set the current process's real and effective user ids. Availability: Unix.
264 .. function:: setregid(rgid, egid)
266 Set the current process's real and effective group ids. Availability: Unix.
269 .. function:: getsid(pid)
271 Call the system call :cfunc:`getsid`. See the Unix manual for the semantics.
274 .. versionadded:: 2.4
277 .. function:: setsid()
279 Call the system call :cfunc:`setsid`. See the Unix manual for the semantics.
283 .. function:: setuid(uid)
285 .. index:: single: user; id, setting
287 Set the current process's user id. Availability: Unix.
290 .. placed in this section since it relates to errno.... a little weak
291 .. function:: strerror(code)
293 Return the error message corresponding to the error code in *code*.
294 On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
295 error number, :exc:`ValueError` is raised. Availability: Unix, Windows.
298 .. function:: umask(mask)
300 Set the current numeric umask and return the previous umask. Availability:
304 .. function:: uname()
307 single: gethostname() (in module socket)
308 single: gethostbyaddr() (in module socket)
310 Return a 5-tuple containing information identifying the current operating
311 system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
312 machine)``. Some systems truncate the nodename to 8 characters or to the
313 leading component; a better way to get the hostname is
314 :func:`socket.gethostname` or even
315 ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
319 .. function:: unsetenv(varname)
321 .. index:: single: environment variables; deleting
323 Unset (delete) the environment variable named *varname*. Such changes to the
324 environment affect subprocesses started with :func:`os.system`, :func:`popen` or
325 :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
327 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
328 automatically translated into a corresponding call to :func:`unsetenv`; however,
329 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
330 preferable to delete items of ``os.environ``.
338 These functions create new file objects. (See also :func:`open`.)
341 .. function:: fdopen(fd[, mode[, bufsize]])
343 .. index:: single: I/O control; buffering
345 Return an open file object connected to the file descriptor *fd*. The *mode*
346 and *bufsize* arguments have the same meaning as the corresponding arguments to
347 the built-in :func:`open` function. Availability: Unix, Windows.
349 .. versionchanged:: 2.3
350 When specified, the *mode* argument must now start with one of the letters
351 ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
353 .. versionchanged:: 2.5
354 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
355 set on the file descriptor (which the :cfunc:`fdopen` implementation already
356 does on most platforms).
359 .. function:: popen(command[, mode[, bufsize]])
361 Open a pipe to or from *command*. The return value is an open file object
362 connected to the pipe, which can be read or written depending on whether *mode*
363 is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
364 the corresponding argument to the built-in :func:`open` function. The exit
365 status of the command (encoded in the format specified for :func:`wait`) is
366 available as the return value of the :meth:`close` method of the file object,
367 except that when the exit status is zero (termination without errors), ``None``
368 is returned. Availability: Unix, Windows.
371 This function is obsolete. Use the :mod:`subprocess` module. Check
372 especially the :ref:`subprocess-replacements` section.
374 .. versionchanged:: 2.0
375 This function worked unreliably under Windows in earlier versions of Python.
376 This was due to the use of the :cfunc:`_popen` function from the libraries
377 provided with Windows. Newer versions of Python do not use the broken
378 implementation from the Windows libraries.
381 .. function:: tmpfile()
383 Return a new file object opened in update mode (``w+b``). The file has no
384 directory entries associated with it and will be automatically deleted once
385 there are no file descriptors for the file. Availability: Unix,
388 There are a number of different :func:`popen\*` functions that provide slightly
389 different ways to create subprocesses.
392 All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
395 For each of the :func:`popen\*` variants, if *bufsize* is specified, it
396 specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
397 string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
398 file objects should be opened in binary or text mode. The default value for
401 Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
402 case arguments will be passed directly to the program without shell intervention
403 (as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
404 (as with :func:`os.system`).
406 These methods do not make it possible to retrieve the exit status from the child
407 processes. The only way to control the input and output streams and also
408 retrieve the return codes is to use the :mod:`subprocess` module; these are only
411 For a discussion of possible deadlock conditions related to the use of these
412 functions, see :ref:`popen2-flow-control`.
415 .. function:: popen2(cmd[, mode[, bufsize]])
417 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
421 This function is obsolete. Use the :mod:`subprocess` module. Check
422 especially the :ref:`subprocess-replacements` section.
424 Availability: Unix, Windows.
426 .. versionadded:: 2.0
429 .. function:: popen3(cmd[, mode[, bufsize]])
431 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
432 child_stdout, child_stderr)``.
435 This function is obsolete. Use the :mod:`subprocess` module. Check
436 especially the :ref:`subprocess-replacements` section.
438 Availability: Unix, Windows.
440 .. versionadded:: 2.0
443 .. function:: popen4(cmd[, mode[, bufsize]])
445 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
446 child_stdout_and_stderr)``.
449 This function is obsolete. Use the :mod:`subprocess` module. Check
450 especially the :ref:`subprocess-replacements` section.
452 Availability: Unix, Windows.
454 .. versionadded:: 2.0
456 (Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
457 point of view of the child process, so *child_stdin* is the child's standard
460 This functionality is also available in the :mod:`popen2` module using functions
461 of the same names, but the return values of those functions have a different
467 File Descriptor Operations
468 --------------------------
470 These functions operate on I/O streams referenced using file descriptors.
472 File descriptors are small integers corresponding to a file that has been opened
473 by the current process. For example, standard input is usually file descriptor
474 0, standard output is 1, and standard error is 2. Further files opened by a
475 process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
476 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
480 .. function:: close(fd)
482 Close file descriptor *fd*. Availability: Unix, Windows.
486 This function is intended for low-level I/O and must be applied to a file
487 descriptor as returned by :func:`open` or :func:`pipe`. To close a "file
488 object" returned by the built-in function :func:`open` or by :func:`popen` or
489 :func:`fdopen`, use its :meth:`close` method.
492 .. function:: closerange(fd_low, fd_high)
494 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
495 ignoring errors. Availability: Unix, Windows. Equivalent to::
497 for fd in xrange(fd_low, fd_high):
503 .. versionadded:: 2.6
506 .. function:: dup(fd)
508 Return a duplicate of file descriptor *fd*. Availability: Unix,
512 .. function:: dup2(fd, fd2)
514 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
515 Availability: Unix, Windows.
518 .. function:: fchmod(fd, mode)
520 Change the mode of the file given by *fd* to the numeric *mode*. See the docs
521 for :func:`chmod` for possible values of *mode*. Availability: Unix.
523 .. versionadded:: 2.6
526 .. function:: fchown(fd, uid, gid)
528 Change the owner and group id of the file given by *fd* to the numeric *uid*
529 and *gid*. To leave one of the ids unchanged, set it to -1.
532 .. versionadded:: 2.6
535 .. function:: fdatasync(fd)
537 Force write of file with filedescriptor *fd* to disk. Does not force update of
538 metadata. Availability: Unix.
541 .. function:: fpathconf(fd, name)
543 Return system configuration information relevant to an open file. *name*
544 specifies the configuration value to retrieve; it may be a string which is the
545 name of a defined system value; these names are specified in a number of
546 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
547 additional names as well. The names known to the host operating system are
548 given in the ``pathconf_names`` dictionary. For configuration variables not
549 included in that mapping, passing an integer for *name* is also accepted.
552 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
553 specific value for *name* is not supported by the host system, even if it is
554 included in ``pathconf_names``, an :exc:`OSError` is raised with
555 :const:`errno.EINVAL` for the error number.
558 .. function:: fstat(fd)
560 Return status for file descriptor *fd*, like :func:`stat`. Availability:
564 .. function:: fstatvfs(fd)
566 Return information about the filesystem containing the file associated with file
567 descriptor *fd*, like :func:`statvfs`. Availability: Unix.
570 .. function:: fsync(fd)
572 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
573 native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
575 If you're starting with a Python file object *f*, first do ``f.flush()``, and
576 then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
577 with *f* are written to disk. Availability: Unix, and Windows
581 .. function:: ftruncate(fd, length)
583 Truncate the file corresponding to file descriptor *fd*, so that it is at most
584 *length* bytes in size. Availability: Unix.
587 .. function:: isatty(fd)
589 Return ``True`` if the file descriptor *fd* is open and connected to a
590 tty(-like) device, else ``False``. Availability: Unix.
593 .. function:: lseek(fd, pos, how)
595 Set the current position of file descriptor *fd* to position *pos*, modified
596 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
597 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
598 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
599 the file. Availability: Unix, Windows.
602 .. function:: open(file, flags[, mode])
604 Open the file *file* and set various flags according to *flags* and possibly its
605 mode according to *mode*. The default *mode* is ``0777`` (octal), and the
606 current umask value is first masked out. Return the file descriptor for the
607 newly opened file. Availability: Unix, Windows.
609 For a description of the flag and mode values, see the C run-time documentation;
610 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
611 this module too (see below).
615 This function is intended for low-level I/O. For normal usage, use the built-in
616 function :func:`open`, which returns a "file object" with :meth:`read` and
617 :meth:`write` methods (and many more). To wrap a file descriptor in a "file
618 object", use :func:`fdopen`.
621 .. function:: openpty()
623 .. index:: module: pty
625 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
626 slave)`` for the pty and the tty, respectively. For a (slightly) more portable
627 approach, use the :mod:`pty` module. Availability: some flavors of
633 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
634 and writing, respectively. Availability: Unix, Windows.
637 .. function:: read(fd, n)
639 Read at most *n* bytes from file descriptor *fd*. Return a string containing the
640 bytes read. If the end of the file referred to by *fd* has been reached, an
641 empty string is returned. Availability: Unix, Windows.
645 This function is intended for low-level I/O and must be applied to a file
646 descriptor as returned by :func:`open` or :func:`pipe`. To read a "file object"
647 returned by the built-in function :func:`open` or by :func:`popen` or
648 :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
652 .. function:: tcgetpgrp(fd)
654 Return the process group associated with the terminal given by *fd* (an open
655 file descriptor as returned by :func:`open`). Availability: Unix.
658 .. function:: tcsetpgrp(fd, pg)
660 Set the process group associated with the terminal given by *fd* (an open file
661 descriptor as returned by :func:`open`) to *pg*. Availability: Unix.
664 .. function:: ttyname(fd)
666 Return a string which specifies the terminal device associated with
667 file descriptor *fd*. If *fd* is not associated with a terminal device, an
668 exception is raised. Availability: Unix.
671 .. function:: write(fd, str)
673 Write the string *str* to file descriptor *fd*. Return the number of bytes
674 actually written. Availability: Unix, Windows.
678 This function is intended for low-level I/O and must be applied to a file
679 descriptor as returned by :func:`open` or :func:`pipe`. To write a "file
680 object" returned by the built-in function :func:`open` or by :func:`popen` or
681 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
684 The following constants are options for the *flags* parameter to the
685 :func:`open` function. They can be combined using the bitwise OR operator
686 ``|``. Some of them are not available on all platforms. For descriptions of
687 their availability and use, consult the :manpage:`open(2)` manual page on Unix
688 or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
699 These constants are available on Unix and Windows.
711 These constants are only available on Unix.
722 These constants are only available on Windows.
731 These constants are GNU extensions and not present if they are not defined by
739 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
740 respectively. Availability: Windows, Unix.
742 .. versionadded:: 2.5
747 Files and Directories
748 ---------------------
750 .. function:: access(path, mode)
752 Use the real uid/gid to test for access to *path*. Note that most operations
753 will use the effective uid/gid, therefore this routine can be used in a
754 suid/sgid environment to test if the invoking user has the specified access to
755 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
756 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
757 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
758 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
759 information. Availability: Unix, Windows.
763 Using :func:`access` to check if a user is authorized to e.g. open a file before
764 actually doing so using :func:`open` creates a security hole, because the user
765 might exploit the short time interval between checking and opening the file to
770 I/O operations may fail even when :func:`access` indicates that they would
771 succeed, particularly for operations on network filesystems which may have
772 permissions semantics beyond the usual POSIX permission-bit model.
777 Value to pass as the *mode* parameter of :func:`access` to test the existence of
783 Value to include in the *mode* parameter of :func:`access` to test the
784 readability of *path*.
789 Value to include in the *mode* parameter of :func:`access` to test the
790 writability of *path*.
795 Value to include in the *mode* parameter of :func:`access` to determine if
796 *path* can be executed.
799 .. function:: chdir(path)
801 .. index:: single: directory; changing
803 Change the current working directory to *path*. Availability: Unix,
807 .. function:: fchdir(fd)
809 Change the current working directory to the directory represented by the file
810 descriptor *fd*. The descriptor must refer to an opened directory, not an open
811 file. Availability: Unix.
813 .. versionadded:: 2.3
816 .. function:: getcwd()
818 Return a string representing the current working directory. Availability:
822 .. function:: getcwdu()
824 Return a Unicode object representing the current working directory.
825 Availability: Unix, Windows.
827 .. versionadded:: 2.3
830 .. function:: chflags(path, flags)
832 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
833 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
848 .. versionadded:: 2.6
851 .. function:: chroot(path)
853 Change the root directory of the current process to *path*. Availability:
856 .. versionadded:: 2.2
859 .. function:: chmod(path, mode)
861 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
862 following values (as defined in the :mod:`stat` module) or bitwise ORed
863 combinations of them:
886 Availability: Unix, Windows.
890 Although Windows supports :func:`chmod`, you can only set the file's read-only
891 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
892 constants or a corresponding integer value). All other bits are
896 .. function:: chown(path, uid, gid)
898 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
899 one of the ids unchanged, set it to -1. Availability: Unix.
902 .. function:: lchflags(path, flags)
904 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
905 follow symbolic links. Availability: Unix.
907 .. versionadded:: 2.6
910 .. function:: lchmod(path, mode)
912 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
913 affects the symlink rather than the target. See the docs for :func:`chmod`
914 for possible values of *mode*. Availability: Unix.
916 .. versionadded:: 2.6
919 .. function:: lchown(path, uid, gid)
921 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
922 function will not follow symbolic links. Availability: Unix.
924 .. versionadded:: 2.3
927 .. function:: link(src, dst)
929 Create a hard link pointing to *src* named *dst*. Availability: Unix.
932 .. function:: listdir(path)
934 Return a list containing the names of the entries in the directory given by
935 *path*. The list is in arbitrary order. It does not include the special
936 entries ``'.'`` and ``'..'`` even if they are present in the
937 directory. Availability: Unix, Windows.
939 .. versionchanged:: 2.3
940 On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
941 a list of Unicode objects.
944 .. function:: lstat(path)
946 Like :func:`stat`, but do not follow symbolic links. This is an alias for
947 :func:`stat` on platforms that do not support symbolic links, such as
951 .. function:: mkfifo(path[, mode])
953 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default
954 *mode* is ``0666`` (octal). The current umask value is first masked out from
955 the mode. Availability: Unix.
957 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
958 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
959 rendezvous between "client" and "server" type processes: the server opens the
960 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
961 doesn't open the FIFO --- it just creates the rendezvous point.
964 .. function:: mknod(filename[, mode=0600, device])
966 Create a filesystem node (file, device special file or named pipe) named
967 *filename*. *mode* specifies both the permissions to use and the type of node to
968 be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
969 ``stat.S_IFCHR``, ``stat.S_IFBLK``,
970 and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
971 For ``stat.S_IFCHR`` and
972 ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
973 :func:`os.makedev`), otherwise it is ignored.
975 .. versionadded:: 2.3
978 .. function:: major(device)
980 Extract the device major number from a raw device number (usually the
981 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
983 .. versionadded:: 2.3
986 .. function:: minor(device)
988 Extract the device minor number from a raw device number (usually the
989 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
991 .. versionadded:: 2.3
994 .. function:: makedev(major, minor)
996 Compose a raw device number from the major and minor device numbers.
998 .. versionadded:: 2.3
1001 .. function:: mkdir(path[, mode])
1003 Create a directory named *path* with numeric mode *mode*. The default *mode* is
1004 ``0777`` (octal). On some systems, *mode* is ignored. Where it is used, the
1005 current umask value is first masked out. Availability: Unix, Windows.
1007 It is also possible to create temporary directories; see the
1008 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1011 .. function:: makedirs(path[, mode])
1014 single: directory; creating
1015 single: UNC paths; and os.makedirs()
1017 Recursive directory creation function. Like :func:`mkdir`, but makes all
1018 intermediate-level directories needed to contain the leaf directory. Throws an
1019 :exc:`error` exception if the leaf directory already exists or cannot be
1020 created. The default *mode* is ``0777`` (octal). On some systems, *mode* is
1021 ignored. Where it is used, the current umask value is first masked out.
1025 :func:`makedirs` will become confused if the path elements to create include
1028 .. versionadded:: 1.5.2
1030 .. versionchanged:: 2.3
1031 This function now handles UNC paths correctly.
1034 .. function:: pathconf(path, name)
1036 Return system configuration information relevant to a named file. *name*
1037 specifies the configuration value to retrieve; it may be a string which is the
1038 name of a defined system value; these names are specified in a number of
1039 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1040 additional names as well. The names known to the host operating system are
1041 given in the ``pathconf_names`` dictionary. For configuration variables not
1042 included in that mapping, passing an integer for *name* is also accepted.
1045 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1046 specific value for *name* is not supported by the host system, even if it is
1047 included in ``pathconf_names``, an :exc:`OSError` is raised with
1048 :const:`errno.EINVAL` for the error number.
1051 .. data:: pathconf_names
1053 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1054 the integer values defined for those names by the host operating system. This
1055 can be used to determine the set of names known to the system. Availability:
1059 .. function:: readlink(path)
1061 Return a string representing the path to which the symbolic link points. The
1062 result may be either an absolute or relative pathname; if it is relative, it may
1063 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
1066 .. versionchanged:: 2.6
1067 If the *path* is a Unicode object the result will also be a Unicode object.
1072 .. function:: remove(path)
1074 Remove the file *path*. If *path* is a directory, :exc:`OSError` is raised; see
1075 :func:`rmdir` below to remove a directory. This is identical to the
1076 :func:`unlink` function documented below. On Windows, attempting to remove a
1077 file that is in use causes an exception to be raised; on Unix, the directory
1078 entry is removed but the storage allocated to the file is not made available
1079 until the original file is no longer in use. Availability: Unix,
1083 .. function:: removedirs(path)
1085 .. index:: single: directory; deleting
1087 Remove directories recursively. Works like :func:`rmdir` except that, if the
1088 leaf directory is successfully removed, :func:`removedirs` tries to
1089 successively remove every parent directory mentioned in *path* until an error
1090 is raised (which is ignored, because it generally means that a parent directory
1091 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1092 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1093 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1094 successfully removed.
1096 .. versionadded:: 1.5.2
1099 .. function:: rename(src, dst)
1101 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1102 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
1103 be replaced silently if the user has permission. The operation may fail on some
1104 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1105 the renaming will be an atomic operation (this is a POSIX requirement). On
1106 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1107 file; there may be no way to implement an atomic rename when *dst* names an
1108 existing file. Availability: Unix, Windows.
1111 .. function:: renames(old, new)
1113 Recursive directory or file renaming function. Works like :func:`rename`, except
1114 creation of any intermediate directories needed to make the new pathname good is
1115 attempted first. After the rename, directories corresponding to rightmost path
1116 segments of the old name will be pruned away using :func:`removedirs`.
1118 .. versionadded:: 1.5.2
1122 This function can fail with the new directory structure made if you lack
1123 permissions needed to remove the leaf directory or file.
1126 .. function:: rmdir(path)
1128 Remove the directory *path*. Availability: Unix, Windows.
1131 .. function:: stat(path)
1133 Perform a :cfunc:`stat` system call on the given path. The return value is an
1134 object whose attributes correspond to the members of the :ctype:`stat`
1135 structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
1136 number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
1137 :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
1138 :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
1139 access), :attr:`st_mtime` (time of most recent content modification),
1140 :attr:`st_ctime` (platform dependent; time of most recent metadata change on
1141 Unix, or the time of creation on Windows)::
1144 >>> statinfo = os.stat('somefile.txt')
1146 (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
1147 >>> statinfo.st_size
1151 .. versionchanged:: 2.3
1152 If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
1153 seconds. Fractions of a second may be reported if the system supports that. On
1154 Mac OS, the times are always floats. See :func:`stat_float_times` for further
1157 On some Unix systems (such as Linux), the following attributes may also be
1158 available: :attr:`st_blocks` (number of blocks allocated for file),
1159 :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
1160 inode device). :attr:`st_flags` (user defined flags for file).
1162 On other Unix systems (such as FreeBSD), the following attributes may be
1163 available (but may be only filled out if root tries to use them): :attr:`st_gen`
1164 (file generation number), :attr:`st_birthtime` (time of file creation).
1166 On Mac OS systems, the following attributes may also be available:
1167 :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
1169 On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
1170 (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
1172 .. index:: module: stat
1174 For backward compatibility, the return value of :func:`stat` is also accessible
1175 as a tuple of at least 10 integers giving the most important (and portable)
1176 members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
1177 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
1178 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
1179 :attr:`st_ctime`. More items may be added at the end by some implementations.
1180 The standard module :mod:`stat` defines functions and constants that are useful
1181 for extracting information from a :ctype:`stat` structure. (On Windows, some
1182 items are filled with dummy values.)
1186 The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1187 :attr:`st_ctime` members depends on the operating system and the file system.
1188 For example, on Windows systems using the FAT or FAT32 file systems,
1189 :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1190 resolution. See your operating system documentation for details.
1192 Availability: Unix, Windows.
1194 .. versionchanged:: 2.2
1195 Added access to values as attributes of the returned object.
1197 .. versionchanged:: 2.5
1198 Added :attr:`st_gen` and :attr:`st_birthtime`.
1201 .. function:: stat_float_times([newvalue])
1203 Determine whether :class:`stat_result` represents time stamps as float objects.
1204 If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
1205 ``False``, future calls return ints. If *newvalue* is omitted, return the
1208 For compatibility with older Python versions, accessing :class:`stat_result` as
1209 a tuple always returns integers.
1211 .. versionchanged:: 2.5
1212 Python now returns float values by default. Applications which do not work
1213 correctly with floating point time stamps can use this function to restore the
1216 The resolution of the timestamps (that is the smallest possible fraction)
1217 depends on the system. Some systems only support second resolution; on these
1218 systems, the fraction will always be zero.
1220 It is recommended that this setting is only changed at program startup time in
1221 the *__main__* module; libraries should never change this setting. If an
1222 application uses a library that works incorrectly if floating point time stamps
1223 are processed, this application should turn the feature off until the library
1227 .. function:: statvfs(path)
1229 Perform a :cfunc:`statvfs` system call on the given path. The return value is
1230 an object whose attributes describe the filesystem on the given path, and
1231 correspond to the members of the :ctype:`statvfs` structure, namely:
1232 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1233 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
1234 :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.
1236 .. index:: module: statvfs
1238 For backward compatibility, the return value is also accessible as a tuple whose
1239 values correspond to the attributes, in the order given above. The standard
1240 module :mod:`statvfs` defines constants that are useful for extracting
1241 information from a :ctype:`statvfs` structure when accessing it as a sequence;
1242 this remains useful when writing code that needs to work with versions of Python
1243 that don't support accessing the fields as attributes.
1245 .. versionchanged:: 2.2
1246 Added access to values as attributes of the returned object.
1249 .. function:: symlink(src, dst)
1251 Create a symbolic link pointing to *src* named *dst*. Availability: Unix.
1254 .. function:: tempnam([dir[, prefix]])
1256 Return a unique path name that is reasonable for creating a temporary file.
1257 This will be an absolute path that names a potential directory entry in the
1258 directory *dir* or a common location for temporary files if *dir* is omitted or
1259 ``None``. If given and not ``None``, *prefix* is used to provide a short prefix
1260 to the filename. Applications are responsible for properly creating and
1261 managing files created using paths returned by :func:`tempnam`; no automatic
1262 cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
1263 overrides *dir*, while on Windows :envvar:`TMP` is used. The specific
1264 behavior of this function depends on the C library implementation; some aspects
1265 are underspecified in system documentation.
1269 Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
1270 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1272 Availability: Unix, Windows.
1275 .. function:: tmpnam()
1277 Return a unique path name that is reasonable for creating a temporary file.
1278 This will be an absolute path that names a potential directory entry in a common
1279 location for temporary files. Applications are responsible for properly
1280 creating and managing files created using paths returned by :func:`tmpnam`; no
1281 automatic cleanup is provided.
1285 Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
1286 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1288 Availability: Unix, Windows. This function probably shouldn't be used on
1289 Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
1290 name in the root directory of the current drive, and that's generally a poor
1291 location for a temp file (depending on privileges, you may not even be able to
1292 open a file using this name).
1297 The maximum number of unique names that :func:`tmpnam` will generate before
1301 .. function:: unlink(path)
1303 Remove the file *path*. This is the same function as :func:`remove`; the
1304 :func:`unlink` name is its traditional Unix name. Availability: Unix,
1308 .. function:: utime(path, times)
1310 Set the access and modified times of the file specified by *path*. If *times*
1311 is ``None``, then the file's access and modified times are set to the current
1312 time. (The effect is similar to running the Unix program :program:`touch` on
1313 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
1314 ``(atime, mtime)`` which is used to set the access and modified times,
1315 respectively. Whether a directory can be given for *path* depends on whether
1316 the operating system implements directories as files (for example, Windows
1317 does not). Note that the exact times you set here may not be returned by a
1318 subsequent :func:`stat` call, depending on the resolution with which your
1319 operating system records access and modification times; see :func:`stat`.
1321 .. versionchanged:: 2.0
1322 Added support for ``None`` for *times*.
1324 Availability: Unix, Windows.
1327 .. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
1330 single: directory; walking
1331 single: directory; traversal
1333 Generate the file names in a directory tree by walking the tree
1334 either top-down or bottom-up. For each directory in the tree rooted at directory
1335 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1338 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
1339 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1340 *filenames* is a list of the names of the non-directory files in *dirpath*.
1341 Note that the names in the lists contain no path components. To get a full path
1342 (which begins with *top*) to a file or directory in *dirpath*, do
1343 ``os.path.join(dirpath, name)``.
1345 If optional argument *topdown* is ``True`` or not specified, the triple for a
1346 directory is generated before the triples for any of its subdirectories
1347 (directories are generated top-down). If *topdown* is ``False``, the triple for a
1348 directory is generated after the triples for all of its subdirectories
1349 (directories are generated bottom-up).
1351 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
1352 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1353 recurse into the subdirectories whose names remain in *dirnames*; this can be
1354 used to prune the search, impose a specific order of visiting, or even to inform
1355 :func:`walk` about directories the caller creates or renames before it resumes
1356 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
1357 ineffective, because in bottom-up mode the directories in *dirnames* are
1358 generated before *dirpath* itself is generated.
1360 By default errors from the :func:`listdir` call are ignored. If optional
1361 argument *onerror* is specified, it should be a function; it will be called with
1362 one argument, an :exc:`OSError` instance. It can report the error to continue
1363 with the walk, or raise the exception to abort the walk. Note that the filename
1364 is available as the ``filename`` attribute of the exception object.
1366 By default, :func:`walk` will not walk down into symbolic links that resolve to
1367 directories. Set *followlinks* to ``True`` to visit directories pointed to by
1368 symlinks, on systems that support them.
1370 .. versionadded:: 2.6
1371 The *followlinks* parameter.
1375 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
1376 link points to a parent directory of itself. :func:`walk` does not keep track of
1377 the directories it visited already.
1381 If you pass a relative pathname, don't change the current working directory
1382 between resumptions of :func:`walk`. :func:`walk` never changes the current
1383 directory, and assumes that its caller doesn't either.
1385 This example displays the number of bytes taken by non-directory files in each
1386 directory under the starting directory, except that it doesn't look under any
1390 from os.path import join, getsize
1391 for root, dirs, files in os.walk('python/Lib/email'):
1392 print root, "consumes",
1393 print sum(getsize(join(root, name)) for name in files),
1394 print "bytes in", len(files), "non-directory files"
1396 dirs.remove('CVS') # don't visit CVS directories
1398 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
1399 doesn't allow deleting a directory before the directory is empty::
1401 # Delete everything reachable from the directory named in "top",
1402 # assuming there are no symbolic links.
1403 # CAUTION: This is dangerous! For example, if top == '/', it
1404 # could delete all your disk files.
1406 for root, dirs, files in os.walk(top, topdown=False):
1408 os.remove(os.path.join(root, name))
1410 os.rmdir(os.path.join(root, name))
1412 .. versionadded:: 2.3
1420 These functions may be used to create and manage processes.
1422 The various :func:`exec\*` functions take a list of arguments for the new
1423 program loaded into the process. In each case, the first of these arguments is
1424 passed to the new program as its own name rather than as an argument a user may
1425 have typed on a command line. For the C programmer, this is the ``argv[0]``
1426 passed to a program's :cfunc:`main`. For example, ``os.execv('/bin/echo',
1427 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
1431 .. function:: abort()
1433 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
1434 behavior is to produce a core dump; on Windows, the process immediately returns
1435 an exit code of ``3``. Be aware that programs which use :func:`signal.signal`
1436 to register a handler for :const:`SIGABRT` will behave differently.
1437 Availability: Unix, Windows.
1440 .. function:: execl(path, arg0, arg1, ...)
1441 execle(path, arg0, arg1, ..., env)
1442 execlp(file, arg0, arg1, ...)
1443 execlpe(file, arg0, arg1, ..., env)
1445 execve(path, args, env)
1447 execvpe(file, args, env)
1449 These functions all execute a new program, replacing the current process; they
1450 do not return. On Unix, the new executable is loaded into the current process,
1451 and will have the same process id as the caller. Errors will be reported as
1452 :exc:`OSError` exceptions.
1454 The current process is replaced immediately. Open file objects and
1455 descriptors are not flushed, so if there may be data buffered
1456 on these open files, you should flush them using
1457 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1458 :func:`exec\*` function.
1460 The "l" and "v" variants of the :func:`exec\*` functions differ in how
1461 command-line arguments are passed. The "l" variants are perhaps the easiest
1462 to work with if the number of parameters is fixed when the code is written; the
1463 individual parameters simply become additional parameters to the :func:`execl\*`
1464 functions. The "v" variants are good when the number of parameters is
1465 variable, with the arguments being passed in a list or tuple as the *args*
1466 parameter. In either case, the arguments to the child process should start with
1467 the name of the command being run, but this is not enforced.
1469 The variants which include a "p" near the end (:func:`execlp`,
1470 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1471 :envvar:`PATH` environment variable to locate the program *file*. When the
1472 environment is being replaced (using one of the :func:`exec\*e` variants,
1473 discussed in the next paragraph), the new environment is used as the source of
1474 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1475 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1476 locate the executable; *path* must contain an appropriate absolute or relative
1479 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
1480 that these all end in "e"), the *env* parameter must be a mapping which is
1481 used to define the environment variables for the new process (these are used
1482 instead of the current process' environment); the functions :func:`execl`,
1483 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
1484 inherit the environment of the current process.
1486 Availability: Unix, Windows.
1489 .. function:: _exit(n)
1491 Exit to the system with status *n*, without calling cleanup handlers, flushing
1492 stdio buffers, etc. Availability: Unix, Windows.
1496 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
1497 be used in the child process after a :func:`fork`.
1499 The following exit codes are defined and can be used with :func:`_exit`,
1500 although they are not required. These are typically used for system programs
1501 written in Python, such as a mail server's external command delivery program.
1505 Some of these may not be available on all Unix platforms, since there is some
1506 variation. These constants are defined where they are defined by the underlying
1512 Exit code that means no error occurred. Availability: Unix.
1514 .. versionadded:: 2.3
1519 Exit code that means the command was used incorrectly, such as when the wrong
1520 number of arguments are given. Availability: Unix.
1522 .. versionadded:: 2.3
1525 .. data:: EX_DATAERR
1527 Exit code that means the input data was incorrect. Availability: Unix.
1529 .. versionadded:: 2.3
1532 .. data:: EX_NOINPUT
1534 Exit code that means an input file did not exist or was not readable.
1537 .. versionadded:: 2.3
1542 Exit code that means a specified user did not exist. Availability: Unix.
1544 .. versionadded:: 2.3
1549 Exit code that means a specified host did not exist. Availability: Unix.
1551 .. versionadded:: 2.3
1554 .. data:: EX_UNAVAILABLE
1556 Exit code that means that a required service is unavailable. Availability:
1559 .. versionadded:: 2.3
1562 .. data:: EX_SOFTWARE
1564 Exit code that means an internal software error was detected. Availability:
1567 .. versionadded:: 2.3
1572 Exit code that means an operating system error was detected, such as the
1573 inability to fork or create a pipe. Availability: Unix.
1575 .. versionadded:: 2.3
1580 Exit code that means some system file did not exist, could not be opened, or had
1581 some other kind of error. Availability: Unix.
1583 .. versionadded:: 2.3
1586 .. data:: EX_CANTCREAT
1588 Exit code that means a user specified output file could not be created.
1591 .. versionadded:: 2.3
1596 Exit code that means that an error occurred while doing I/O on some file.
1599 .. versionadded:: 2.3
1602 .. data:: EX_TEMPFAIL
1604 Exit code that means a temporary failure occurred. This indicates something
1605 that may not really be an error, such as a network connection that couldn't be
1606 made during a retryable operation. Availability: Unix.
1608 .. versionadded:: 2.3
1611 .. data:: EX_PROTOCOL
1613 Exit code that means that a protocol exchange was illegal, invalid, or not
1614 understood. Availability: Unix.
1616 .. versionadded:: 2.3
1621 Exit code that means that there were insufficient permissions to perform the
1622 operation (but not intended for file system problems). Availability: Unix.
1624 .. versionadded:: 2.3
1629 Exit code that means that some kind of configuration error occurred.
1632 .. versionadded:: 2.3
1635 .. data:: EX_NOTFOUND
1637 Exit code that means something like "an entry was not found". Availability:
1640 .. versionadded:: 2.3
1643 .. function:: fork()
1645 Fork a child process. Return ``0`` in the child and the child's process id in the
1646 parent. If an error occurs :exc:`OSError` is raised.
1648 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1649 known issues when using fork() from a thread.
1654 .. function:: forkpty()
1656 Fork a child process, using a new pseudo-terminal as the child's controlling
1657 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1658 new child's process id in the parent, and *fd* is the file descriptor of the
1659 master end of the pseudo-terminal. For a more portable approach, use the
1660 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
1661 Availability: some flavors of Unix.
1664 .. function:: kill(pid, sig)
1667 single: process; killing
1668 single: process; signalling
1670 Send signal *sig* to the process *pid*. Constants for the specific signals
1671 available on the host platform are defined in the :mod:`signal` module.
1675 .. function:: killpg(pgid, sig)
1678 single: process; killing
1679 single: process; signalling
1681 Send the signal *sig* to the process group *pgid*. Availability: Unix.
1683 .. versionadded:: 2.3
1686 .. function:: nice(increment)
1688 Add *increment* to the process's "niceness". Return the new niceness.
1692 .. function:: plock(op)
1694 Lock program segments into memory. The value of *op* (defined in
1695 ``<sys/lock.h>``) determines which segments are locked. Availability: Unix.
1698 .. function:: popen(...)
1704 Run child processes, returning opened pipes for communications. These functions
1705 are described in section :ref:`os-newstreams`.
1708 .. function:: spawnl(mode, path, ...)
1709 spawnle(mode, path, ..., env)
1710 spawnlp(mode, file, ...)
1711 spawnlpe(mode, file, ..., env)
1712 spawnv(mode, path, args)
1713 spawnve(mode, path, args, env)
1714 spawnvp(mode, file, args)
1715 spawnvpe(mode, file, args, env)
1717 Execute the program *path* in a new process.
1719 (Note that the :mod:`subprocess` module provides more powerful facilities for
1720 spawning new processes and retrieving their results; using that module is
1721 preferable to using these functions. Check specially the *Replacing Older
1722 Functions with the subprocess Module* section in that documentation page.)
1724 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
1725 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1726 exits normally, or ``-signal``, where *signal* is the signal that killed the
1727 process. On Windows, the process id will actually be the process handle, so can
1728 be used with the :func:`waitpid` function.
1730 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1731 command-line arguments are passed. The "l" variants are perhaps the easiest
1732 to work with if the number of parameters is fixed when the code is written; the
1733 individual parameters simply become additional parameters to the
1734 :func:`spawnl\*` functions. The "v" variants are good when the number of
1735 parameters is variable, with the arguments being passed in a list or tuple as
1736 the *args* parameter. In either case, the arguments to the child process must
1737 start with the name of the command being run.
1739 The variants which include a second "p" near the end (:func:`spawnlp`,
1740 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1741 :envvar:`PATH` environment variable to locate the program *file*. When the
1742 environment is being replaced (using one of the :func:`spawn\*e` variants,
1743 discussed in the next paragraph), the new environment is used as the source of
1744 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
1745 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1746 :envvar:`PATH` variable to locate the executable; *path* must contain an
1747 appropriate absolute or relative path.
1749 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
1750 (note that these all end in "e"), the *env* parameter must be a mapping
1751 which is used to define the environment variables for the new process (they are
1752 used instead of the current process' environment); the functions
1753 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
1754 the new process to inherit the environment of the current process.
1756 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1760 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1762 L = ['cp', 'index.html', '/dev/null']
1763 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
1765 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
1766 and :func:`spawnvpe` are not available on Windows.
1768 .. versionadded:: 1.6
1774 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1775 functions. If either of these values is given, the :func:`spawn\*` functions
1776 will return as soon as the new process has been created, with the process id as
1777 the return value. Availability: Unix, Windows.
1779 .. versionadded:: 1.6
1784 Possible value for the *mode* parameter to the :func:`spawn\*` family of
1785 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
1786 return until the new process has run to completion and will return the exit code
1787 of the process the run is successful, or ``-signal`` if a signal kills the
1788 process. Availability: Unix, Windows.
1790 .. versionadded:: 1.6
1796 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1797 functions. These are less portable than those listed above. :const:`P_DETACH`
1798 is similar to :const:`P_NOWAIT`, but the new process is detached from the
1799 console of the calling process. If :const:`P_OVERLAY` is used, the current
1800 process will be replaced; the :func:`spawn\*` function will not return.
1801 Availability: Windows.
1803 .. versionadded:: 1.6
1806 .. function:: startfile(path[, operation])
1808 Start a file with its associated application.
1810 When *operation* is not specified or ``'open'``, this acts like double-clicking
1811 the file in Windows Explorer, or giving the file name as an argument to the
1812 :program:`start` command from the interactive command shell: the file is opened
1813 with whatever application (if any) its extension is associated.
1815 When another *operation* is given, it must be a "command verb" that specifies
1816 what should be done with the file. Common verbs documented by Microsoft are
1817 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
1818 ``'find'`` (to be used on directories).
1820 :func:`startfile` returns as soon as the associated application is launched.
1821 There is no option to wait for the application to close, and no way to retrieve
1822 the application's exit status. The *path* parameter is relative to the current
1823 directory. If you want to use an absolute path, make sure the first character
1824 is not a slash (``'/'``); the underlying Win32 :cfunc:`ShellExecute` function
1825 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
1826 the path is properly encoded for Win32. Availability: Windows.
1828 .. versionadded:: 2.0
1830 .. versionadded:: 2.5
1831 The *operation* parameter.
1834 .. function:: system(command)
1836 Execute the command (a string) in a subshell. This is implemented by calling
1837 the Standard C function :cfunc:`system`, and has the same limitations. Changes
1838 to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
1839 environment of the executed command.
1841 On Unix, the return value is the exit status of the process encoded in the
1842 format specified for :func:`wait`. Note that POSIX does not specify the meaning
1843 of the return value of the C :cfunc:`system` function, so the return value of
1844 the Python function is system-dependent.
1846 On Windows, the return value is that returned by the system shell after running
1847 *command*, given by the Windows environment variable :envvar:`COMSPEC`: on
1848 :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
1849 :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
1850 the command run; on systems using a non-native shell, consult your shell
1853 Availability: Unix, Windows.
1855 The :mod:`subprocess` module provides more powerful facilities for spawning new
1856 processes and retrieving their results; using that module is preferable to using
1857 this function. Use the :mod:`subprocess` module. Check especially the
1858 :ref:`subprocess-replacements` section.
1861 .. function:: times()
1863 Return a 5-tuple of floating point numbers indicating accumulated (processor or
1864 other) times, in seconds. The items are: user time, system time, children's
1865 user time, children's system time, and elapsed real time since a fixed point in
1866 the past, in that order. See the Unix manual page :manpage:`times(2)` or the
1867 corresponding Windows Platform API documentation. Availability: Unix,
1868 Windows. On Windows, only the first two items are filled, the others are zero.
1871 .. function:: wait()
1873 Wait for completion of a child process, and return a tuple containing its pid
1874 and exit status indication: a 16-bit number, whose low byte is the signal number
1875 that killed the process, and whose high byte is the exit status (if the signal
1876 number is zero); the high bit of the low byte is set if a core file was
1877 produced. Availability: Unix.
1880 .. function:: waitpid(pid, options)
1882 The details of this function differ on Unix and Windows.
1884 On Unix: Wait for completion of a child process given by process id *pid*, and
1885 return a tuple containing its process id and exit status indication (encoded as
1886 for :func:`wait`). The semantics of the call are affected by the value of the
1887 integer *options*, which should be ``0`` for normal operation.
1889 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
1890 that specific process. If *pid* is ``0``, the request is for the status of any
1891 child in the process group of the current process. If *pid* is ``-1``, the
1892 request pertains to any child of the current process. If *pid* is less than
1893 ``-1``, status is requested for any process in the process group ``-pid`` (the
1894 absolute value of *pid*).
1896 An :exc:`OSError` is raised with the value of errno when the syscall
1899 On Windows: Wait for completion of a process given by process handle *pid*, and
1900 return a tuple containing *pid*, and its exit status shifted left by 8 bits
1901 (shifting makes cross-platform use of the function easier). A *pid* less than or
1902 equal to ``0`` has no special meaning on Windows, and raises an exception. The
1903 value of integer *options* has no effect. *pid* can refer to any process whose
1904 id is known, not necessarily a child process. The :func:`spawn` functions called
1905 with :const:`P_NOWAIT` return suitable process handles.
1908 .. function:: wait3([options])
1910 Similar to :func:`waitpid`, except no process id argument is given and a
1911 3-element tuple containing the child's process id, exit status indication, and
1912 resource usage information is returned. Refer to :mod:`resource`.\
1913 :func:`getrusage` for details on resource usage information. The option
1914 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
1917 .. versionadded:: 2.5
1920 .. function:: wait4(pid, options)
1922 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
1923 process id, exit status indication, and resource usage information is returned.
1924 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
1925 information. The arguments to :func:`wait4` are the same as those provided to
1926 :func:`waitpid`. Availability: Unix.
1928 .. versionadded:: 2.5
1933 The option for :func:`waitpid` to return immediately if no child process status
1934 is available immediately. The function returns ``(0, 0)`` in this case.
1938 .. data:: WCONTINUED
1940 This option causes child processes to be reported if they have been continued
1941 from a job control stop since their status was last reported. Availability: Some
1944 .. versionadded:: 2.3
1949 This option causes child processes to be reported if they have been stopped but
1950 their current state has not been reported since they were stopped. Availability:
1953 .. versionadded:: 2.3
1955 The following functions take a process status code as returned by
1956 :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
1957 used to determine the disposition of a process.
1960 .. function:: WCOREDUMP(status)
1962 Return ``True`` if a core dump was generated for the process, otherwise
1963 return ``False``. Availability: Unix.
1965 .. versionadded:: 2.3
1968 .. function:: WIFCONTINUED(status)
1970 Return ``True`` if the process has been continued from a job control stop,
1971 otherwise return ``False``. Availability: Unix.
1973 .. versionadded:: 2.3
1976 .. function:: WIFSTOPPED(status)
1978 Return ``True`` if the process has been stopped, otherwise return
1979 ``False``. Availability: Unix.
1982 .. function:: WIFSIGNALED(status)
1984 Return ``True`` if the process exited due to a signal, otherwise return
1985 ``False``. Availability: Unix.
1988 .. function:: WIFEXITED(status)
1990 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
1991 otherwise return ``False``. Availability: Unix.
1994 .. function:: WEXITSTATUS(status)
1996 If ``WIFEXITED(status)`` is true, return the integer parameter to the
1997 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
2001 .. function:: WSTOPSIG(status)
2003 Return the signal which caused the process to stop. Availability: Unix.
2006 .. function:: WTERMSIG(status)
2008 Return the signal which caused the process to exit. Availability: Unix.
2013 Miscellaneous System Information
2014 --------------------------------
2017 .. function:: confstr(name)
2019 Return string-valued system configuration values. *name* specifies the
2020 configuration value to retrieve; it may be a string which is the name of a
2021 defined system value; these names are specified in a number of standards (POSIX,
2022 Unix 95, Unix 98, and others). Some platforms define additional names as well.
2023 The names known to the host operating system are given as the keys of the
2024 ``confstr_names`` dictionary. For configuration variables not included in that
2025 mapping, passing an integer for *name* is also accepted. Availability:
2028 If the configuration value specified by *name* isn't defined, ``None`` is
2031 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
2032 specific value for *name* is not supported by the host system, even if it is
2033 included in ``confstr_names``, an :exc:`OSError` is raised with
2034 :const:`errno.EINVAL` for the error number.
2037 .. data:: confstr_names
2039 Dictionary mapping names accepted by :func:`confstr` to the integer values
2040 defined for those names by the host operating system. This can be used to
2041 determine the set of names known to the system. Availability: Unix.
2044 .. function:: getloadavg()
2046 Return the number of processes in the system run queue averaged over the last
2047 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
2048 unobtainable. Availability: Unix.
2050 .. versionadded:: 2.3
2053 .. function:: sysconf(name)
2055 Return integer-valued system configuration values. If the configuration value
2056 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
2057 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
2058 provides information on the known names is given by ``sysconf_names``.
2062 .. data:: sysconf_names
2064 Dictionary mapping names accepted by :func:`sysconf` to the integer values
2065 defined for those names by the host operating system. This can be used to
2066 determine the set of names known to the system. Availability: Unix.
2068 The following data values are used to support path manipulation operations. These
2069 are defined for all platforms.
2071 Higher-level operations on pathnames are defined in the :mod:`os.path` module.
2076 The constant string used by the operating system to refer to the current
2077 directory. This is ``'.'`` for Windows and POSIX. Also available via
2083 The constant string used by the operating system to refer to the parent
2084 directory. This is ``'..'`` for Windows and POSIX. Also available via
2090 The character used by the operating system to separate pathname components.
2091 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
2092 is not sufficient to be able to parse or concatenate pathnames --- use
2093 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
2094 useful. Also available via :mod:`os.path`.
2099 An alternative character used by the operating system to separate pathname
2100 components, or ``None`` if only one separator character exists. This is set to
2101 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
2107 The character which separates the base filename from the extension; for example,
2108 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
2110 .. versionadded:: 2.2
2115 The character conventionally used by the operating system to separate search
2116 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
2117 Windows. Also available via :mod:`os.path`.
2122 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2123 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2128 The string used to separate (or, rather, terminate) lines on the current
2129 platform. This may be a single character, such as ``'\n'`` for POSIX, or
2130 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2131 *os.linesep* as a line terminator when writing files opened in text mode (the
2132 default); use a single ``'\n'`` instead, on all platforms.
2137 The file path of the null device. For example: ``'/dev/null'`` for POSIX.
2138 Also available via :mod:`os.path`.
2140 .. versionadded:: 2.4
2145 Miscellaneous Functions
2146 -----------------------
2149 .. function:: urandom(n)
2151 Return a string of *n* random bytes suitable for cryptographic use.
2153 This function returns random bytes from an OS-specific randomness source. The
2154 returned data should be unpredictable enough for cryptographic applications,
2155 though its exact quality depends on the OS implementation. On a UNIX-like
2156 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
2157 If a randomness source is not found, :exc:`NotImplementedError` will be raised.
2159 .. versionadded:: 2.4