/Doc/library/os.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 2154 lines · 1376 code · 778 blank · 0 comment · 0 complexity · 3f385f38c7506dc5e3ab477140efda3d MD5 · raw file
Large files are truncated click here to view the full file
- :mod:`os` --- Miscellaneous operating system interfaces
- =======================================================
- .. module:: os
- :synopsis: Miscellaneous operating system interfaces.
- This module provides a portable way of using operating system dependent
- functionality. If you just want to read or write a file see :func:`open`, if
- you want to manipulate paths, see the :mod:`os.path` module, and if you want to
- read all the lines in all the files on the command line see the :mod:`fileinput`
- module. For creating temporary files and directories see the :mod:`tempfile`
- module, and for high-level file and directory handling see the :mod:`shutil`
- module.
- The design of all built-in operating system dependent modules of Python is such
- that as long as the same functionality is available, it uses the same interface;
- for example, the function ``os.stat(path)`` returns stat information about
- *path* in the same format (which happens to have originated with the POSIX
- interface).
- Extensions peculiar to a particular operating system are also available through
- the :mod:`os` module, but using them is of course a threat to portability!
- .. note::
- If not separately noted, all functions that claim "Availability: Unix" are
- supported on Mac OS X, which builds on a Unix core.
- .. note::
- All functions in this module raise :exc:`OSError` in the case of invalid or
- inaccessible file names and paths, or other arguments that have the correct
- type, but are not accepted by the operating system.
- .. exception:: error
- An alias for the built-in :exc:`OSError` exception.
- .. data:: name
- The name of the operating system dependent module imported. The following names
- have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
- ``'ce'``, ``'java'``, ``'riscos'``.
- .. _os-procinfo:
- Process Parameters
- ------------------
- These functions and data items provide information and operate on the current
- process and user.
- .. data:: environ
- A mapping object representing the string environment. For example,
- ``environ['HOME']`` is the pathname of your home directory (on some platforms),
- and is equivalent to ``getenv("HOME")`` in C.
- This mapping is captured the first time the :mod:`os` module is imported,
- typically during Python startup as part of processing :file:`site.py`. Changes
- to the environment made after this time are not reflected in ``os.environ``,
- except for changes made by modifying ``os.environ`` directly.
- If the platform supports the :func:`putenv` function, this mapping may be used
- to modify the environment as well as query the environment. :func:`putenv` will
- be called automatically when the mapping is modified.
- .. note::
- Calling :func:`putenv` directly does not change ``os.environ``, so it's better
- to modify ``os.environ``.
- .. note::
- On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
- cause memory leaks. Refer to the system documentation for
- :cfunc:`putenv`.
- If :func:`putenv` is not provided, a modified copy of this mapping may be
- passed to the appropriate process-creation functions to cause child processes
- to use a modified environment.
- If the platform supports the :func:`unsetenv` function, you can delete items in
- this mapping to unset environment variables. :func:`unsetenv` will be called
- automatically when an item is deleted from ``os.environ``, and when
- one of the :meth:`pop` or :meth:`clear` methods is called.
- .. versionchanged:: 2.6
- Also unset environment variables when calling :meth:`os.environ.clear`
- and :meth:`os.environ.pop`.
- .. function:: chdir(path)
- fchdir(fd)
- getcwd()
- :noindex:
- These functions are described in :ref:`os-file-dir`.
- .. function:: ctermid()
- Return the filename corresponding to the controlling terminal of the process.
- Availability: Unix.
- .. function:: getegid()
- Return the effective group id of the current process. This corresponds to the
- "set id" bit on the file being executed in the current process. Availability:
- Unix.
- .. function:: geteuid()
- .. index:: single: user; effective id
- Return the current process's effective user id. Availability: Unix.
- .. function:: getgid()
- .. index:: single: process; group
- Return the real group id of the current process. Availability: Unix.
- .. function:: getgroups()
- Return list of supplemental group ids associated with the current process.
- Availability: Unix.
- .. function:: getlogin()
- Return the name of the user logged in on the controlling terminal of the
- process. For most purposes, it is more useful to use the environment variable
- :envvar:`LOGNAME` to find out who the user is, or
- ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
- effective user id. Availability: Unix.
- .. function:: getpgid(pid)
- Return the process group id of the process with process id *pid*. If *pid* is 0,
- the process group id of the current process is returned. Availability: Unix.
- .. versionadded:: 2.3
- .. function:: getpgrp()
- .. index:: single: process; group
- Return the id of the current process group. Availability: Unix.
- .. function:: getpid()
- .. index:: single: process; id
- Return the current process id. Availability: Unix, Windows.
- .. function:: getppid()
- .. index:: single: process; id of parent
- Return the parent's process id. Availability: Unix.
- .. function:: getuid()
- .. index:: single: user; id
- Return the current process's user id. Availability: Unix.
- .. function:: getenv(varname[, value])
- Return the value of the environment variable *varname* if it exists, or *value*
- if it doesn't. *value* defaults to ``None``. Availability: most flavors of
- Unix, Windows.
- .. function:: putenv(varname, value)
- .. index:: single: environment variables; setting
- Set the environment variable named *varname* to the string *value*. Such
- changes to the environment affect subprocesses started with :func:`os.system`,
- :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
- Unix, Windows.
- .. note::
- On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
- cause memory leaks. Refer to the system documentation for putenv.
- When :func:`putenv` is supported, assignments to items in ``os.environ`` are
- automatically translated into corresponding calls to :func:`putenv`; however,
- calls to :func:`putenv` don't update ``os.environ``, so it is actually
- preferable to assign to items of ``os.environ``.
- .. function:: setegid(egid)
- Set the current process's effective group id. Availability: Unix.
- .. function:: seteuid(euid)
- Set the current process's effective user id. Availability: Unix.
- .. function:: setgid(gid)
- Set the current process' group id. Availability: Unix.
- .. function:: setgroups(groups)
- Set the list of supplemental group ids associated with the current process to
- *groups*. *groups* must be a sequence, and each element must be an integer
- identifying a group. This operation is typically available only to the superuser.
- Availability: Unix.
- .. versionadded:: 2.2
- .. function:: setpgrp()
- Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
- which version is implemented (if any). See the Unix manual for the semantics.
- Availability: Unix.
- .. function:: setpgid(pid, pgrp)
- Call the system call :cfunc:`setpgid` to set the process group id of the
- process with id *pid* to the process group with id *pgrp*. See the Unix manual
- for the semantics. Availability: Unix.
- .. function:: setreuid(ruid, euid)
- Set the current process's real and effective user ids. Availability: Unix.
- .. function:: setregid(rgid, egid)
- Set the current process's real and effective group ids. Availability: Unix.
- .. function:: getsid(pid)
- Call the system call :cfunc:`getsid`. See the Unix manual for the semantics.
- Availability: Unix.
- .. versionadded:: 2.4
- .. function:: setsid()
- Call the system call :cfunc:`setsid`. See the Unix manual for the semantics.
- Availability: Unix.
- .. function:: setuid(uid)
- .. index:: single: user; id, setting
- Set the current process's user id. Availability: Unix.
- .. placed in this section since it relates to errno.... a little weak
- .. function:: strerror(code)
- Return the error message corresponding to the error code in *code*.
- On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
- error number, :exc:`ValueError` is raised. Availability: Unix, Windows.
- .. function:: umask(mask)
- Set the current numeric umask and return the previous umask. Availability:
- Unix, Windows.
- .. function:: uname()
- .. index::
- single: gethostname() (in module socket)
- single: gethostbyaddr() (in module socket)
- Return a 5-tuple containing information identifying the current operating
- system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
- machine)``. Some systems truncate the nodename to 8 characters or to the
- leading component; a better way to get the hostname is
- :func:`socket.gethostname` or even
- ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
- Unix.
- .. function:: unsetenv(varname)
- .. index:: single: environment variables; deleting
- Unset (delete) the environment variable named *varname*. Such changes to the
- environment affect subprocesses started with :func:`os.system`, :func:`popen` or
- :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
- When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
- automatically translated into a corresponding call to :func:`unsetenv`; however,
- calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
- preferable to delete items of ``os.environ``.
- .. _os-newstreams:
- File Object Creation
- --------------------
- These functions create new file objects. (See also :func:`open`.)
- .. function:: fdopen(fd[, mode[, bufsize]])
- .. index:: single: I/O control; buffering
- Return an open file object connected to the file descriptor *fd*. The *mode*
- and *bufsize* arguments have the same meaning as the corresponding arguments to
- the built-in :func:`open` function. Availability: Unix, Windows.
- .. versionchanged:: 2.3
- When specified, the *mode* argument must now start with one of the letters
- ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
- .. versionchanged:: 2.5
- On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
- set on the file descriptor (which the :cfunc:`fdopen` implementation already
- does on most platforms).
- .. function:: popen(command[, mode[, bufsize]])
- Open a pipe to or from *command*. The return value is an open file object
- connected to the pipe, which can be read or written depending on whether *mode*
- is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
- the corresponding argument to the built-in :func:`open` function. The exit
- status of the command (encoded in the format specified for :func:`wait`) is
- available as the return value of the :meth:`~file.close` method of the file object,
- except that when the exit status is zero (termination without errors), ``None``
- is returned. Availability: Unix, Windows.
- .. deprecated:: 2.6
- This function is obsolete. Use the :mod:`subprocess` module. Check
- especially the :ref:`subprocess-replacements` section.
- .. versionchanged:: 2.0
- This function worked unreliably under Windows in earlier versions of Python.
- This was due to the use of the :cfunc:`_popen` function from the libraries
- provided with Windows. Newer versions of Python do not use the broken
- implementation from the Windows libraries.
- .. function:: tmpfile()
- Return a new file object opened in update mode (``w+b``). The file has no
- directory entries associated with it and will be automatically deleted once
- there are no file descriptors for the file. Availability: Unix,
- Windows.
- There are a number of different :func:`popen\*` functions that provide slightly
- different ways to create subprocesses.
- .. deprecated:: 2.6
- All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
- module.
- For each of the :func:`popen\*` variants, if *bufsize* is specified, it
- specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
- string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
- file objects should be opened in binary or text mode. The default value for
- *mode* is ``'t'``.
- Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
- case arguments will be passed directly to the program without shell intervention
- (as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
- (as with :func:`os.system`).
- These methods do not make it possible to retrieve the exit status from the child
- processes. The only way to control the input and output streams and also
- retrieve the return codes is to use the :mod:`subprocess` module; these are only
- available on Unix.
- For a discussion of possible deadlock conditions related to the use of these
- functions, see :ref:`popen2-flow-control`.
- .. function:: popen2(cmd[, mode[, bufsize]])
- Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
- child_stdout)``.
- .. deprecated:: 2.6
- This function is obsolete. Use the :mod:`subprocess` module. Check
- especially the :ref:`subprocess-replacements` section.
- Availability: Unix, Windows.
- .. versionadded:: 2.0
- .. function:: popen3(cmd[, mode[, bufsize]])
- Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
- child_stdout, child_stderr)``.
- .. deprecated:: 2.6
- This function is obsolete. Use the :mod:`subprocess` module. Check
- especially the :ref:`subprocess-replacements` section.
- Availability: Unix, Windows.
- .. versionadded:: 2.0
- .. function:: popen4(cmd[, mode[, bufsize]])
- Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
- child_stdout_and_stderr)``.
- .. deprecated:: 2.6
- This function is obsolete. Use the :mod:`subprocess` module. Check
- especially the :ref:`subprocess-replacements` section.
- Availability: Unix, Windows.
- .. versionadded:: 2.0
- (Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
- point of view of the child process, so *child_stdin* is the child's standard
- input.)
- This functionality is also available in the :mod:`popen2` module using functions
- of the same names, but the return values of those functions have a different
- order.
- .. _os-fd-ops:
- File Descriptor Operations
- --------------------------
- These functions operate on I/O streams referenced using file descriptors.
- File descriptors are small integers corresponding to a file that has been opened
- by the current process. For example, standard input is usually file descriptor
- 0, standard output is 1, and standard error is 2. Further files opened by a
- process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
- is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
- by file descriptors.
- .. function:: close(fd)
- Close file descriptor *fd*. Availability: Unix, Windows.
- .. note::
- This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
- object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, use its :meth:`~file.close` method.
- .. function:: closerange(fd_low, fd_high)
- Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
- ignoring errors. Availability: Unix, Windows. Equivalent to::
- for fd in xrange(fd_low, fd_high):
- try:
- os.close(fd)
- except OSError:
- pass
- .. versionadded:: 2.6
- .. function:: dup(fd)
- Return a duplicate of file descriptor *fd*. Availability: Unix,
- Windows.
- .. function:: dup2(fd, fd2)
- Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
- Availability: Unix, Windows.
- .. function:: fchmod(fd, mode)
- Change the mode of the file given by *fd* to the numeric *mode*. See the docs
- for :func:`chmod` for possible values of *mode*. Availability: Unix.
- .. versionadded:: 2.6
- .. function:: fchown(fd, uid, gid)
- Change the owner and group id of the file given by *fd* to the numeric *uid*
- and *gid*. To leave one of the ids unchanged, set it to -1.
- Availability: Unix.
- .. versionadded:: 2.6
- .. function:: fdatasync(fd)
- Force write of file with filedescriptor *fd* to disk. Does not force update of
- metadata. Availability: Unix.
- .. function:: fpathconf(fd, name)
- Return system configuration information relevant to an open file. *name*
- specifies the configuration value to retrieve; it may be a string which is the
- name of a defined system value; these names are specified in a number of
- standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
- additional names as well. The names known to the host operating system are
- given in the ``pathconf_names`` dictionary. For configuration variables not
- included in that mapping, passing an integer for *name* is also accepted.
- Availability: Unix.
- If *name* is a string and is not known, :exc:`ValueError` is raised. If a
- specific value for *name* is not supported by the host system, even if it is
- included in ``pathconf_names``, an :exc:`OSError` is raised with
- :const:`errno.EINVAL` for the error number.
- .. function:: fstat(fd)
- Return status for file descriptor *fd*, like :func:`stat`. Availability:
- Unix, Windows.
- .. function:: fstatvfs(fd)
- Return information about the filesystem containing the file associated with file
- descriptor *fd*, like :func:`statvfs`. Availability: Unix.
- .. function:: fsync(fd)
- Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
- native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
- If you're starting with a Python file object *f*, first do ``f.flush()``, and
- then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
- with *f* are written to disk. Availability: Unix, and Windows
- starting in 2.2.3.
- .. function:: ftruncate(fd, length)
- Truncate the file corresponding to file descriptor *fd*, so that it is at most
- *length* bytes in size. Availability: Unix.
- .. function:: isatty(fd)
- Return ``True`` if the file descriptor *fd* is open and connected to a
- tty(-like) device, else ``False``. Availability: Unix.
- .. function:: lseek(fd, pos, how)
- Set the current position of file descriptor *fd* to position *pos*, modified
- by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
- beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
- current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
- the file. Availability: Unix, Windows.
- .. function:: open(file, flags[, mode])
- Open the file *file* and set various flags according to *flags* and possibly its
- mode according to *mode*. The default *mode* is ``0777`` (octal), and the
- current umask value is first masked out. Return the file descriptor for the
- newly opened file. Availability: Unix, Windows.
- For a description of the flag and mode values, see the C run-time documentation;
- flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
- this module too (see below).
- .. note::
- This function is intended for low-level I/O. For normal usage, use the built-in
- function :func:`open`, which returns a "file object" with :meth:`~file.read` and
- :meth:`~file.write` methods (and many more). To wrap a file descriptor in a "file
- object", use :func:`fdopen`.
- .. function:: openpty()
- .. index:: module: pty
- Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
- slave)`` for the pty and the tty, respectively. For a (slightly) more portable
- approach, use the :mod:`pty` module. Availability: some flavors of
- Unix.
- .. function:: pipe()
- Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
- and writing, respectively. Availability: Unix, Windows.
- .. function:: read(fd, n)
- Read at most *n* bytes from file descriptor *fd*. Return a string containing the
- bytes read. If the end of the file referred to by *fd* has been reached, an
- empty string is returned. Availability: Unix, Windows.
- .. note::
- This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object"
- returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
- :meth:`~file.readline` methods.
- .. function:: tcgetpgrp(fd)
- Return the process group associated with the terminal given by *fd* (an open
- file descriptor as returned by :func:`os.open`). Availability: Unix.
- .. function:: tcsetpgrp(fd, pg)
- Set the process group associated with the terminal given by *fd* (an open file
- descriptor as returned by :func:`os.open`) to *pg*. Availability: Unix.
- .. function:: ttyname(fd)
- Return a string which specifies the terminal device associated with
- file descriptor *fd*. If *fd* is not associated with a terminal device, an
- exception is raised. Availability: Unix.
- .. function:: write(fd, str)
- Write the string *str* to file descriptor *fd*. Return the number of bytes
- actually written. Availability: Unix, Windows.
- .. note::
- This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
- object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
- :meth:`~file.write` method.
- The following constants are options for the *flags* parameter to the
- :func:`~os.open` function. They can be combined using the bitwise OR operator
- ``|``. Some of them are not available on all platforms. For descriptions of
- their availability and use, consult the :manpage:`open(2)` manual page on Unix
- or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
- .. data:: O_RDONLY
- O_WRONLY
- O_RDWR
- O_APPEND
- O_CREAT
- O_EXCL
- O_TRUNC
- These constants are available on Unix and Windows.
- .. data:: O_DSYNC
- O_RSYNC
- O_SYNC
- O_NDELAY
- O_NONBLOCK
- O_NOCTTY
- O_SHLOCK
- O_EXLOCK
- These constants are only available on Unix.
- .. data:: O_BINARY
- O_NOINHERIT
- O_SHORT_LIVED
- O_TEMPORARY
- O_RANDOM
- O_SEQUENTIAL
- O_TEXT
- These constants are only available on Windows.
- .. data:: O_ASYNC
- O_DIRECT
- O_DIRECTORY
- O_NOFOLLOW
- O_NOATIME
- These constants are GNU extensions and not present if they are not defined by
- the C library.
- .. data:: SEEK_SET
- SEEK_CUR
- SEEK_END
- Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
- respectively. Availability: Windows, Unix.
- .. versionadded:: 2.5
- .. _os-file-dir:
- Files and Directories
- ---------------------
- .. function:: access(path, mode)
- Use the real uid/gid to test for access to *path*. Note that most operations
- will use the effective uid/gid, therefore this routine can be used in a
- suid/sgid environment to test if the invoking user has the specified access to
- *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
- can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
- :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
- :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
- information. Availability: Unix, Windows.
- .. note::
- Using :func:`access` to check if a user is authorized to e.g. open a file before
- actually doing so using :func:`open` creates a security hole, because the user
- might exploit the short time interval between checking and opening the file to
- manipulate it.
- .. note::
- I/O operations may fail even when :func:`access` indicates that they would
- succeed, particularly for operations on network filesystems which may have
- permissions semantics beyond the usual POSIX permission-bit model.
- .. data:: F_OK
- Value to pass as the *mode* parameter of :func:`access` to test the existence of
- *path*.
- .. data:: R_OK
- Value to include in the *mode* parameter of :func:`access` to test the
- readability of *path*.
- .. data:: W_OK
- Value to include in the *mode* parameter of :func:`access` to test the
- writability of *path*.
- .. data:: X_OK
- Value to include in the *mode* parameter of :func:`access` to determine if
- *path* can be executed.
- .. function:: chdir(path)
- .. index:: single: directory; changing
- Change the current working directory to *path*. Availability: Unix,
- Windows.
- .. function:: fchdir(fd)
- Change the current working directory to the directory represented by the file
- descriptor *fd*. The descriptor must refer to an opened directory, not an open
- file. Availability: Unix.
- .. versionadded:: 2.3
- .. function:: getcwd()
- Return a string representing the current working directory. Availability:
- Unix, Windows.
- .. function:: getcwdu()
- Return a Unicode object representing the current working directory.
- Availability: Unix, Windows.
- .. versionadded:: 2.3
- .. function:: chflags(path, flags)
- Set the flags of *path* to the numeric *flags*. *flags* may take a combination
- (bitwise OR) of the following values (as defined in the :mod:`stat` module):
- * ``UF_NODUMP``
- * ``UF_IMMUTABLE``
- * ``UF_APPEND``
- * ``UF_OPAQUE``
- * ``UF_NOUNLINK``
- * ``SF_ARCHIVED``
- * ``SF_IMMUTABLE``
- * ``SF_APPEND``
- * ``SF_NOUNLINK``
- * ``SF_SNAPSHOT``
- Availability: Unix.
- .. versionadded:: 2.6
- .. function:: chroot(path)
- Change the root directory of the current process to *path*. Availability:
- Unix.
- .. versionadded:: 2.2
- .. function:: chmod(path, mode)
- Change the mode of *path* to the numeric *mode*. *mode* may take one of the
- following values (as defined in the :mod:`stat` module) or bitwise ORed
- combinations of them:
- * :data:`stat.S_ISUID`
- * :data:`stat.S_ISGID`
- * :data:`stat.S_ENFMT`
- * :data:`stat.S_ISVTX`
- * :data:`stat.S_IREAD`
- * :data:`stat.S_IWRITE`
- * :data:`stat.S_IEXEC`
- * :data:`stat.S_IRWXU`
- * :data:`stat.S_IRUSR`
- * :data:`stat.S_IWUSR`
- * :data:`stat.S_IXUSR`
- * :data:`stat.S_IRWXG`
- * :data:`stat.S_IRGRP`
- * :data:`stat.S_IWGRP`
- * :data:`stat.S_IXGRP`
- * :data:`stat.S_IRWXO`
- * :data:`stat.S_IROTH`
- * :data:`stat.S_IWOTH`
- * :data:`stat.S_IXOTH`
- Availability: Unix, Windows.
- .. note::
- Although Windows supports :func:`chmod`, you can only set the file's read-only
- flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
- constants or a corresponding integer value). All other bits are
- ignored.
- .. function:: chown(path, uid, gid)
- Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
- one of the ids unchanged, set it to -1. Availability: Unix.
- .. function:: lchflags(path, flags)
- Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
- follow symbolic links. Availability: Unix.
- .. versionadded:: 2.6
- .. function:: lchmod(path, mode)
- Change the mode of *path* to the numeric *mode*. If path is a symlink, this
- affects the symlink rather than the target. See the docs for :func:`chmod`
- for possible values of *mode*. Availability: Unix.
- .. versionadded:: 2.6
- .. function:: lchown(path, uid, gid)
- Change the owner and group id of *path* to the numeric *uid* and *gid*. This
- function will not follow symbolic links. Availability: Unix.
- .. versionadded:: 2.3
- .. function:: link(src, dst)
- Create a hard link pointing to *src* named *dst*. Availability: Unix.
- .. function:: listdir(path)
- Return a list containing the names of the entries in the directory given by
- *path*. The list is in arbitrary order. It does not include the special
- entries ``'.'`` and ``'..'`` even if they are present in the
- directory. Availability: Unix, Windows.
- .. versionchanged:: 2.3
- On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
- a list of Unicode objects. Undecodable filenames will still be returned as
- string objects.
- .. function:: lstat(path)
- Like :func:`stat`, but do not follow symbolic links. This is an alias for
- :func:`stat` on platforms that do not support symbolic links, such as
- Windows.
- .. function:: mkfifo(path[, mode])
- Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default
- *mode* is ``0666`` (octal). The current umask value is first masked out from
- the mode. Availability: Unix.
- FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
- are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
- rendezvous between "client" and "server" type processes: the server opens the
- FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
- doesn't open the FIFO --- it just creates the rendezvous point.
- .. function:: mknod(filename[, mode=0600, device])
- Create a filesystem node (file, device special file or named pipe) named
- *filename*. *mode* specifies both the permissions to use and the type of node to
- be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
- ``stat.S_IFCHR``, ``stat.S_IFBLK``,
- and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
- For ``stat.S_IFCHR`` and
- ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
- :func:`os.makedev`), otherwise it is ignored.
- .. versionadded:: 2.3
- .. function:: major(device)
- Extract the device major number from a raw device number (usually the
- :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
- .. versionadded:: 2.3
- .. function:: minor(device)
- Extract the device minor number from a raw device number (usually the
- :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
- .. versionadded:: 2.3
- .. function:: makedev(major, minor)
- Compose a raw device number from the major and minor device numbers.
- .. versionadded:: 2.3
- .. function:: mkdir(path[, mode])
- Create a directory named *path* with numeric mode *mode*. The default *mode* is
- ``0777`` (octal). On some systems, *mode* is ignored. Where it is used, the
- current umask value is first masked out. Availability: Unix, Windows.
- It is also possible to create temporary directories; see the
- :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
- .. function:: makedirs(path[, mode])
- .. index::
- single: directory; creating
- single: UNC paths; and os.makedirs()
- Recursive directory creation function. Like :func:`mkdir`, but makes all
- intermediate-level directories needed to contain the leaf directory. Throws an
- :exc:`error` exception if the leaf directory already exists or cannot be
- created. The default *mode* is ``0777`` (octal). On some systems, *mode* is
- ignored. Where it is used, the current umask value is first masked out.
- .. note::
- :func:`makedirs` will become confused if the path elements to create include
- :data:`os.pardir`.
- .. versionadded:: 1.5.2
- .. versionchanged:: 2.3
- This function now handles UNC paths correctly.
- .. function:: pathconf(path, name)
- Return system configuration information relevant to a named file. *name*
- specifies the configuration value to retrieve; it may be a string which is the
- name of a defined system value; these names are specified in a number of
- standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
- additional names as well. The names known to the host operating system are
- given in the ``pathconf_names`` dictionary. For configuration variables not
- included in that mapping, passing an integer for *name* is also accepted.
- Availability: Unix.
- If *name* is a string and is not known, :exc:`ValueError` is raised. If a
- specific value for *name* is not supported by the host system, even if it is
- included in ``pathconf_names``, an :exc:`OSError` is raised with
- :const:`errno.EINVAL` for the error number.
- .. data:: pathconf_names
- Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
- the integer values defined for those names by the host operating system. This
- can be used to determine the set of names known to the system. Availability:
- Unix.
- .. function:: readlink(path)
- Return a string representing the path to which the symbolic link points. The
- result may be either an absolute or relative pathname; if it is relative, it may
- be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
- result)``.
- .. versionchanged:: 2.6
- If the *path* is a Unicode object the result will also be a Unicode object.
- Availability: Unix.
- .. function:: remove(path)
- Remove the file *path*. If *path* is a directory, :exc:`OSError` is raised; see
- :func:`rmdir` below to remove a directory. This is identical to the
- :func:`unlink` function documented below. On Windows, attempting to remove a
- file that is in use causes an exception to be raised; on Unix, the directory
- entry is removed but the storage allocated to the file is not made available
- until the original file is no longer in use. Availability: Unix,
- Windows.
- .. function:: removedirs(path)
- .. index:: single: directory; deleting
- Remove directories recursively. Works like :func:`rmdir` except that, if the
- leaf directory is successfully removed, :func:`removedirs` tries to
- successively remove every parent directory mentioned in *path* until an error
- is raised (which is ignored, because it generally means that a parent directory
- is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
- the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
- they are empty. Raises :exc:`OSError` if the leaf directory could not be
- successfully removed.
- .. versionadded:: 1.5.2
- .. function:: rename(src, dst)
- Rename the file or directory *src* to *dst*. If *dst* is a directory,
- :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
- be replaced silently if the user has permission. The operation may fail on some
- Unix flavors if *src* and *dst* are on different filesystems. If successful,
- the renaming will be an atomic operation (this is a POSIX requirement). On
- Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
- file; there may be no way to implement an atomic rename when *dst* names an
- existing file. Availability: Unix, Windows.
- .. function:: renames(old, new)
- Recursive directory or file renaming function. Works like :func:`rename`, except
- creation of any intermediate directories needed to make the new pathname good is
- attempted first. After the rename, directories corresponding to rightmost path
- segments of the old name will be pruned away using :func:`removedirs`.
- .. versionadded:: 1.5.2
- .. note::
- This function can fail with the new directory structure made if you lack
- permissions needed to remove the leaf directory or file.
- .. function:: rmdir(path)
- Remove the directory *path*. Availability: Unix, Windows.
- .. function:: stat(path)
- Perform a :cfunc:`stat` system call on the given path. The return value is an
- object whose attributes correspond to the members of the :ctype:`stat`
- structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
- number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
- :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
- :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
- access), :attr:`st_mtime` (time of most recent content modification),
- :attr:`st_ctime` (platform dependent; time of most recent metadata change on
- Unix, or the time of creation on Windows)::
- >>> import os
- >>> statinfo = os.stat('somefile.txt')
- >>> statinfo
- (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
- >>> statinfo.st_size
- 926L
- >>>
- .. versionchanged:: 2.3
- If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
- seconds. Fractions of a second may be reported if the system supports that. On
- Mac OS, the times are always floats. See :func:`stat_float_times` for further
- discussion.
- On some Unix systems (such as Linux), the following attributes may also be
- available: :attr:`st_blocks` (number of blocks allocated for file),
- :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
- inode device). :attr:`st_flags` (user defined flags for file).
- On other Unix systems (such as FreeBSD), the following attributes may be
- available (but may be only filled out if root tries to use them): :attr:`st_gen`
- (file generation number), :attr:`st_birthtime` (time of file creation).
- On Mac OS systems, the following attributes may also be available:
- :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
- On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
- (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
- .. index:: module: stat
- For backward compatibility, the return value of :func:`stat` is also accessible
- as a tuple of at least 10 integers giving the most important (and portable)
- members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
- :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
- :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
- :attr:`st_ctime`. More items may be added at the end by some implementations.
- The standard module :mod:`stat` defines functions and constants that are useful
- for extracting information from a :ctype:`stat` structure. (On Windows, some
- items are filled with dummy values.)
- .. note::
- The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
- :attr:`st_ctime` members depends on the operating system and the file system.
- For example, on Windows systems using the FAT or FAT32 file systems,
- :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
- resolution. See your operating system documentation for details.
- Availability: Unix, Windows.
- .. versionchanged:: 2.2
- Added access to values as attributes of the returned object.
- .. versionchanged:: 2.5
- Added :attr:`st_gen` and :attr:`st_birthtime`.
- .. function:: stat_float_times([newvalue])
- Determine whether :class:`stat_result` represents time stamps as float objects.
- If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
- ``False``, future calls return ints. If *newvalue* is omitted, return the
- current setting.
- For compatibility with older Python versions, accessing :class:`stat_result` as
- a tuple always returns integers.
- .. versionchanged:: 2.5
- Python now returns float values by default. Applications which do not work
- correctly with floating point time stamps can use this function to restore the
- old behaviour.
- The resolution of the timestamps (that is the smallest possible fraction)
- depends on the system. Some systems only support second resolution; on these
- systems, the fraction will always be zero.
- It is recommended that this setting is only changed at program startup time in
- the *__main__* module; libraries should never change this setting. If an
- application uses a library that works incorrectly if floating point time stamps
- are processed, this application should turn the feature off until the library
- has been corrected.
- .. function:: statvfs(path)
- Perform a :cfunc:`statvfs` system call on the given path. The return value is
- an object whose attributes describe the filesystem on the given path, and
- correspond to the members of the :ctype:`statvfs` structure, namely:
- :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
- :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
- :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.
- .. index:: module: statvfs
- For backward compatibility, the return value is also accessible as a tuple whose
- values correspond to the attributes, in the order given above. The standard
- module :mod:`statvfs` defines constants that are useful for extracting
- information from a :ctype:`statvfs` structure when accessing it as a sequence;
- this remains useful when writing code that needs to work with versions of Python
- that don't support accessing the fields as attributes.
- .. versionchanged:: 2.2
- Added access to values as attributes of the returned object.
- .. function:: symlink(src, dst)
- Create a symbolic link pointing to *src* named *dst*. Availability: Unix.
- .. function:: tempnam([dir[, prefix]])
- Return a unique path name that is reasonable for creating a temporary file.
- This will be an absolute path that names a potential directory entry in the
- directory *dir* or a common location for temporary files if *dir* is omitted or
- ``None``. If given and not ``None``, *prefix* is used to provide a short prefix
- to the filename. Applications are responsible for properly creating and
- managing files created using paths returned by :func:`tempnam`; no automatic
- cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
- overrides *dir*, while on Windows :envvar:`TMP` is used. The specific
- behavior of this function depends on the C library implementation; some aspects
- are underspecified in system documentation.
- .. warning::
- Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
- :func:`tmpfile` (section :ref:`os-newstreams`) instead.
- Availability: Unix, Windows.
- .. function:: tmpnam()
- Return a unique path name that is reasonable for creating a temporary file.
- This will be an absolute path that names a potential directory entry in a common
- location for temporary files. Applications are responsible for properly
- creating and managing files created using paths returned by :func:`tmpnam`; no
- automatic cleanup is provided.
- .. warning::
- Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
- :func:`tmpfile` (section :ref:`os-newstreams`) instead.
- Availability: Unix, Windows. This function probably shouldn't be used on
- Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
- name in the root directory of the current drive, and that's generally a poor
- location for a temp file (depending on privileges, you may not even be able to
- open a file using this name).
- .. data:: TMP_MAX
- The maximum number of unique names that :func:`tmpnam` will generate before
- reusing names.
- .. function:: unlink(path)
- Remove the file *path*. This is the same function as :func:`remove`; the
- :func:`unlink` name is its traditional Unix name. Availability: Unix,
- Windows.
- .. function:: utime(path, times)
- Set the access and modified times of the file specified by *path*. If *times*
- is ``None``, then the file's access and modified times are set to the current
- time. (The effect is similar to running the Unix program :program:`touch` on
- the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
- ``(atime, mtime)`` which is used to set the access and modified times,
- respectively. Whether a directory can be given for *path* depends on whether
- the operating system implements directories as files (for example, Windows
- does not). Note that the exact times you set here may not be returned by a
- subsequent :func:`stat` call, depending on the resolution with which your
- operating system records access and modification times; see :func:`stat`.
- .. versionchanged:: 2.0
- Added support for ``None`` for *times*.
- Availability: Unix, Windows.
- .. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
- .. index::
- single: directory; walking
- single: directory; traversal
- Generate the file names in a directory tree by walking the tree
- either top-down or bottom-up. For each directory in the tree rooted at directory
- *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
- filenames)``.
- *dirpath* is a string, the path to the directory. *dirnames* is a list of the
- names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
- *filenames* is a list of the names of the non-directory files in *dirpath*.
- Note that the names in the lists contain no path components. To get a full path
- (which begins with *top*) to a file or directory in *dirpath*, do
- ``os.path.join(dirpath, name)``.
- If optional argument *topdown* is ``True`` or not specified, the triple for a
- directory is generated before the triples for any of its subdirectories
- (directories are generated top-down). If *topdown* is ``False``, the triple for a
- directory is generated after the triples for all of its subdirectories
- (directories are generated bottom-up).
- When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
- (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
- recurse into the subdirectories whose names remain in *dirnames*; this can be
- used to prune the search, impose a specific order of visiting, or even to inform
- :func:`walk` about directories the caller creates or renames before it resumes
- :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
- ineffective, because in bottom-up mode the directories in *dirnames* are
- generated before *dirpath* itself is generated.
- By default errors from the :func:`listdir` call are ignored. If optional
- argument *onerror* is specified, it should be a function; it will be called with
- one argument, an :exc:`OSError` instance. It can report the error to continue
- with the walk, or raise the exception to abort the walk. Note that the filename
- is available as the ``filename`` attribute of the exception object.
- By default, :func:`walk` will not walk down into symbolic links that resolve to
- directories. Set *followlinks* to ``True`` to visit directories pointed to by
- symlinks, on systems that support them.
- .. versionadded:: 2.6
- The *followlinks* parameter.
- .. note::
- Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
- link points to a parent directory of itself. :func:`walk` does not keep track of
- the directories it visited already.
- .. note::
- If you pass a relative pathname, don't change the current working directory
- between resumptions of :func:`walk`. :func:`walk` never changes the current
- directory, and assumes that its caller doesn't either.
- This example displays the number of bytes taken by non-directory files in each
- directory under the starting directory, except that it doesn't look under any
- CVS subdirectory::
- import os
- from os.path import join, getsize
- for root, dirs, files in os.walk('python/Lib/email'):
- print root, "consumes",
- print sum(getsize(join(root, name)) for name in files),
- print "bytes in", len(files), "non-directory files"
- if 'CVS' in dirs:
- dirs.remove('CVS') # don't visit CVS directories
- In the next example, walking the tree bottom-up is essential: :func:`rmdir`
- doesn't allow deleting a directory before the directory is empty::
- # Delete everything reachable from the directory named in "top",
- # assuming there are no symbolic links.
- # CAUTION: This is dangerous! For example, if top == '/', it
- # could delete all your disk files.
- import os
- for root, dirs, files in os.walk(top, topdown=False):
- for name in files:
- os.remove(os.path.join(root, name))
- for name in dirs:
- os.rmdir(os.path.join(root, name))
- .. versionadded:: 2.3
- .. _os-process:
- Process Management
- ------------------
- These functions may be used to create and manage processes.
- The various :func:`exec\*` functions take a list of arguments for the new
- program loaded into the process. In each case, the first of these arguments is
- passed to the new program as its own name rather than as an argument a user may
- have typed on a command line. For the C programmer, this is the ``argv[0]``
- passed to a program's :cfunc:`main`. Fo…