1 :mod:`os` --- Miscellaneous operating system interfaces 2 ======================================================= 3 4 .. module:: os 5 :synopsis: Miscellaneous operating system interfaces. 6 7 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` 14 module. 15 16 Notes on the availability of these functions: 17 18 * The design of all built-in operating system dependent modules of Python is 19 such that as long as the same functionality is available, it uses the same 20 interface; for example, the function ``os.stat(path)`` returns stat 21 information about *path* in the same format (which happens to have originated 22 with the POSIX interface). 23 24 * Extensions peculiar to a particular operating system are also available 25 through the :mod:`os` module, but using them is of course a threat to 26 portability. 27 28 * An "Availability: Unix" note means that this function is commonly found on 29 Unix systems. It does not make any claims about its existence on a specific 30 operating system. 31 32 * If not separately noted, all functions that claim "Availability: Unix" are 33 supported on Mac OS X, which builds on a Unix core. 34 35 .. Availability notes get their own line and occur at the end of the function 36 .. documentation. 37 38 .. note:: 39 40 All functions in this module raise :exc:`OSError` in the case of invalid or 41 inaccessible file names and paths, or other arguments that have the correct 42 type, but are not accepted by the operating system. 43 44 45 .. exception:: error 46 47 An alias for the built-in :exc:`OSError` exception. 48 49 50 .. data:: name 51 52 The name of the operating system dependent module imported. The following 53 names have currently been registered: ``'posix'``, ``'nt'``, 54 ``'os2'``, ``'ce'``, ``'java'``, ``'riscos'``. 55 56 .. seealso:: 57 :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives 58 system-dependent version information. 59 60 The :mod:`platform` module provides detailed checks for the 61 system's identity. 62 63 64 .. _os-procinfo: 65 66 Process Parameters 67 ------------------ 68 69 These functions and data items provide information and operate on the current 70 process and user. 71 72 73 .. data:: environ 74 75 A :term:`mapping` object representing the string environment. For example, 76 ``environ['HOME']`` is the pathname of your home directory (on some platforms), 77 and is equivalent to ``getenv("HOME")`` in C. 78 79 This mapping is captured the first time the :mod:`os` module is imported, 80 typically during Python startup as part of processing :file:`site.py`. Changes 81 to the environment made after this time are not reflected in ``os.environ``, 82 except for changes made by modifying ``os.environ`` directly. 83 84 If the platform supports the :func:`putenv` function, this mapping may be used 85 to modify the environment as well as query the environment. :func:`putenv` will 86 be called automatically when the mapping is modified. 87 88 .. note:: 89 90 Calling :func:`putenv` directly does not change ``os.environ``, so it's better 91 to modify ``os.environ``. 92 93 .. note:: 94 95 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may 96 cause memory leaks. Refer to the system documentation for 97 :c:func:`putenv`. 98 99 If :func:`putenv` is not provided, a modified copy of this mapping may be 100 passed to the appropriate process-creation functions to cause child processes 101 to use a modified environment. 102 103 If the platform supports the :func:`unsetenv` function, you can delete items in 104 this mapping to unset environment variables. :func:`unsetenv` will be called 105 automatically when an item is deleted from ``os.environ``, and when 106 one of the :meth:`pop` or :meth:`clear` methods is called. 107 108 .. versionchanged:: 2.6 109 Also unset environment variables when calling :meth:`os.environ.clear` 110 and :meth:`os.environ.pop`. 111 112 113 .. function:: chdir(path) 114 fchdir(fd) 115 getcwd() 116 :noindex: 117 118 These functions are described in :ref:`os-file-dir`. 119 120 121 .. function:: ctermid() 122 123 Return the filename corresponding to the controlling terminal of the process. 124 125 Availability: Unix. 126 127 128 .. function:: getegid() 129 130 Return the effective group id of the current process. This corresponds to the 131 "set id" bit on the file being executed in the current process. 132 133 Availability: Unix. 134 135 136 .. function:: geteuid() 137 138 .. index:: single: user; effective id 139 140 Return the current process's effective user id. 141 142 Availability: Unix. 143 144 145 .. function:: getgid() 146 147 .. index:: single: process; group 148 149 Return the real group id of the current process. 150 151 Availability: Unix. 152 153 154 .. function:: getgroups() 155 156 Return list of supplemental group ids associated with the current process. 157 158 Availability: Unix. 159 160 .. note:: 161 162 On Mac OS X, :func:`getgroups` behavior differs somewhat from 163 other Unix platforms. If the Python interpreter was built with a 164 deployment target of :const:`10.5` or earlier, :func:`getgroups` returns 165 the list of effective group ids associated with the current user process; 166 this list is limited to a system-defined number of entries, typically 16, 167 and may be modified by calls to :func:`setgroups` if suitably privileged. 168 If built with a deployment target greater than :const:`10.5`, 169 :func:`getgroups` returns the current group access list for the user 170 associated with the effective user id of the process; the group access 171 list may change over the lifetime of the process, it is not affected by 172 calls to :func:`setgroups`, and its length is not limited to 16. The 173 deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be 174 obtained with :func:`sysconfig.get_config_var`. 175 176 177 .. function:: initgroups(username, gid) 178 179 Call the system initgroups() to initialize the group access list with all of 180 the groups of which the specified username is a member, plus the specified 181 group id. 182 183 Availability: Unix. 184 185 .. versionadded:: 2.7 186 187 188 .. function:: getlogin() 189 190 Return the name of the user logged in on the controlling terminal of the 191 process. For most purposes, it is more useful to use the environment 192 variable :envvar:`LOGNAME` to find out who the user is, or 193 ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the process's real 194 user id. 195 196 Availability: Unix. 197 198 199 .. function:: getpgid(pid) 200 201 Return the process group id of the process with process id *pid*. If *pid* is 0, 202 the process group id of the current process is returned. 203 204 Availability: Unix. 205 206 .. versionadded:: 2.3 207 208 209 .. function:: getpgrp() 210 211 .. index:: single: process; group 212 213 Return the id of the current process group. 214 215 Availability: Unix. 216 217 218 .. function:: getpid() 219 220 .. index:: single: process; id 221 222 Return the current process id. 223 224 Availability: Unix, Windows. 225 226 227 .. function:: getppid() 228 229 .. index:: single: process; id of parent 230 231 Return the parent's process id. 232 233 Availability: Unix. 234 235 236 .. function:: getresuid() 237 238 Return a tuple (ruid, euid, suid) denoting the current process's 239 real, effective, and saved user ids. 240 241 Availability: Unix. 242 243 .. versionadded:: 2.7 244 245 246 .. function:: getresgid() 247 248 Return a tuple (rgid, egid, sgid) denoting the current process's 249 real, effective, and saved group ids. 250 251 Availability: Unix. 252 253 .. versionadded:: 2.7 254 255 256 .. function:: getuid() 257 258 .. index:: single: user; id 259 260 Return the current process's real user id. 261 262 Availability: Unix. 263 264 265 .. function:: getenv(varname[, value]) 266 267 Return the value of the environment variable *varname* if it exists, or *value* 268 if it doesn't. *value* defaults to ``None``. 269 270 Availability: most flavors of Unix, Windows. 271 272 273 .. function:: putenv(varname, value) 274 275 .. index:: single: environment variables; setting 276 277 Set the environment variable named *varname* to the string *value*. Such 278 changes to the environment affect subprocesses started with :func:`os.system`, 279 :func:`popen` or :func:`fork` and :func:`execv`. 280 281 Availability: most flavors of Unix, Windows. 282 283 .. note:: 284 285 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may 286 cause memory leaks. Refer to the system documentation for putenv. 287 288 When :func:`putenv` is supported, assignments to items in ``os.environ`` are 289 automatically translated into corresponding calls to :func:`putenv`; however, 290 calls to :func:`putenv` don't update ``os.environ``, so it is actually 291 preferable to assign to items of ``os.environ``. 292 293 294 .. function:: setegid(egid) 295 296 Set the current process's effective group id. 297 298 Availability: Unix. 299 300 301 .. function:: seteuid(euid) 302 303 Set the current process's effective user id. 304 305 Availability: Unix. 306 307 308 .. function:: setgid(gid) 309 310 Set the current process' group id. 311 312 Availability: Unix. 313 314 315 .. function:: setgroups(groups) 316 317 Set the list of supplemental group ids associated with the current process to 318 *groups*. *groups* must be a sequence, and each element must be an integer 319 identifying a group. This operation is typically available only to the superuser. 320 321 Availability: Unix. 322 323 .. versionadded:: 2.2 324 325 .. note:: On Mac OS X, the length of *groups* may not exceed the 326 system-defined maximum number of effective group ids, typically 16. 327 See the documentation for :func:`getgroups` for cases where it may not 328 return the same group list set by calling setgroups(). 329 330 .. function:: setpgrp() 331 332 Call the system call :c:func:`setpgrp` or :c:func:`setpgrp(0, 0)` depending on 333 which version is implemented (if any). See the Unix manual for the semantics. 334 335 Availability: Unix. 336 337 338 .. function:: setpgid(pid, pgrp) 339 340 Call the system call :c:func:`setpgid` to set the process group id of the 341 process with id *pid* to the process group with id *pgrp*. See the Unix manual 342 for the semantics. 343 344 Availability: Unix. 345 346 347 .. function:: setregid(rgid, egid) 348 349 Set the current process's real and effective group ids. 350 351 Availability: Unix. 352 353 354 .. function:: setresgid(rgid, egid, sgid) 355 356 Set the current process's real, effective, and saved group ids. 357 358 Availability: Unix. 359 360 .. versionadded:: 2.7 361 362 363 .. function:: setresuid(ruid, euid, suid) 364 365 Set the current process's real, effective, and saved user ids. 366 367 Availability: Unix. 368 369 .. versionadded:: 2.7 370 371 372 .. function:: setreuid(ruid, euid) 373 374 Set the current process's real and effective user ids. 375 376 Availability: Unix. 377 378 379 .. function:: getsid(pid) 380 381 Call the system call :c:func:`getsid`. See the Unix manual for the semantics. 382 383 Availability: Unix. 384 385 .. versionadded:: 2.4 386 387 388 .. function:: setsid() 389 390 Call the system call :c:func:`setsid`. See the Unix manual for the semantics. 391 392 Availability: Unix. 393 394 395 .. function:: setuid(uid) 396 397 .. index:: single: user; id, setting 398 399 Set the current process's user id. 400 401 Availability: Unix. 402 403 404 .. placed in this section since it relates to errno.... a little weak 405 .. function:: strerror(code) 406 407 Return the error message corresponding to the error code in *code*. 408 On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown 409 error number, :exc:`ValueError` is raised. 410 411 Availability: Unix, Windows. 412 413 414 .. function:: umask(mask) 415 416 Set the current numeric umask and return the previous umask. 417 418 Availability: Unix, Windows. 419 420 421 .. function:: uname() 422 423 .. index:: 424 single: gethostname() (in module socket) 425 single: gethostbyaddr() (in module socket) 426 427 Return a 5-tuple containing information identifying the current operating 428 system. The tuple contains 5 strings: ``(sysname, nodename, release, version, 429 machine)``. Some systems truncate the nodename to 8 characters or to the 430 leading component; a better way to get the hostname is 431 :func:`socket.gethostname` or even 432 ``socket.gethostbyaddr(socket.gethostname())``. 433 434 Availability: recent flavors of Unix. 435 436 437 .. function:: unsetenv(varname) 438 439 .. index:: single: environment variables; deleting 440 441 Unset (delete) the environment variable named *varname*. Such changes to the 442 environment affect subprocesses started with :func:`os.system`, :func:`popen` or 443 :func:`fork` and :func:`execv`. 444 445 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is 446 automatically translated into a corresponding call to :func:`unsetenv`; however, 447 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually 448 preferable to delete items of ``os.environ``. 449 450 Availability: most flavors of Unix, Windows. 451 452 453 .. _os-newstreams: 454 455 File Object Creation 456 -------------------- 457 458 These functions create new file objects. (See also :func:`open`.) 459 460 461 .. function:: fdopen(fd[, mode[, bufsize]]) 462 463 .. index:: single: I/O control; buffering 464 465 Return an open file object connected to the file descriptor *fd*. The *mode* 466 and *bufsize* arguments have the same meaning as the corresponding arguments 467 to the built-in :func:`open` function. If :func:`fdopen` raises an 468 exception, it leaves *fd* untouched (unclosed). 469 470 Availability: Unix, Windows. 471 472 .. versionchanged:: 2.3 473 When specified, the *mode* argument must now start with one of the letters 474 ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised. 475 476 .. versionchanged:: 2.5 477 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is 478 set on the file descriptor (which the :c:func:`fdopen` implementation already 479 does on most platforms). 480 481 482 .. function:: popen(command[, mode[, bufsize]]) 483 484 Open a pipe to or from *command*. The return value is an open file object 485 connected to the pipe, which can be read or written depending on whether *mode* 486 is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as 487 the corresponding argument to the built-in :func:`open` function. The exit 488 status of the command (encoded in the format specified for :func:`wait`) is 489 available as the return value of the :meth:`~file.close` method of the file object, 490 except that when the exit status is zero (termination without errors), ``None`` 491 is returned. 492 493 Availability: Unix, Windows. 494 495 .. deprecated:: 2.6 496 This function is obsolete. Use the :mod:`subprocess` module. Check 497 especially the :ref:`subprocess-replacements` section. 498 499 .. versionchanged:: 2.0 500 This function worked unreliably under Windows in earlier versions of Python. 501 This was due to the use of the :c:func:`_popen` function from the libraries 502 provided with Windows. Newer versions of Python do not use the broken 503 implementation from the Windows libraries. 504 505 506 .. function:: tmpfile() 507 508 Return a new file object opened in update mode (``w+b``). The file has no 509 directory entries associated with it and will be automatically deleted once 510 there are no file descriptors for the file. 511 512 Availability: Unix, Windows. 513 514 There are a number of different :func:`popen\*` functions that provide slightly 515 different ways to create subprocesses. 516 517 .. deprecated:: 2.6 518 All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess` 519 module. 520 521 For each of the :func:`popen\*` variants, if *bufsize* is specified, it 522 specifies the buffer size for the I/O pipes. *mode*, if provided, should be the 523 string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the 524 file objects should be opened in binary or text mode. The default value for 525 *mode* is ``'t'``. 526 527 Also, for each of these variants, on Unix, *cmd* may be a sequence, in which 528 case arguments will be passed directly to the program without shell intervention 529 (as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell 530 (as with :func:`os.system`). 531 532 These methods do not make it possible to retrieve the exit status from the child 533 processes. The only way to control the input and output streams and also 534 retrieve the return codes is to use the :mod:`subprocess` module; these are only 535 available on Unix. 536 537 For a discussion of possible deadlock conditions related to the use of these 538 functions, see :ref:`popen2-flow-control`. 539 540 541 .. function:: popen2(cmd[, mode[, bufsize]]) 542 543 Execute *cmd* as a sub-process and return the file objects ``(child_stdin, 544 child_stdout)``. 545 546 .. deprecated:: 2.6 547 This function is obsolete. Use the :mod:`subprocess` module. Check 548 especially the :ref:`subprocess-replacements` section. 549 550 Availability: Unix, Windows. 551 552 .. versionadded:: 2.0 553 554 555 .. function:: popen3(cmd[, mode[, bufsize]]) 556 557 Execute *cmd* as a sub-process and return the file objects ``(child_stdin, 558 child_stdout, child_stderr)``. 559 560 .. deprecated:: 2.6 561 This function is obsolete. Use the :mod:`subprocess` module. Check 562 especially the :ref:`subprocess-replacements` section. 563 564 Availability: Unix, Windows. 565 566 .. versionadded:: 2.0 567 568 569 .. function:: popen4(cmd[, mode[, bufsize]]) 570 571 Execute *cmd* as a sub-process and return the file objects ``(child_stdin, 572 child_stdout_and_stderr)``. 573 574 .. deprecated:: 2.6 575 This function is obsolete. Use the :mod:`subprocess` module. Check 576 especially the :ref:`subprocess-replacements` section. 577 578 Availability: Unix, Windows. 579 580 .. versionadded:: 2.0 581 582 (Note that ``child_stdin, child_stdout, and child_stderr`` are named from the 583 point of view of the child process, so *child_stdin* is the child's standard 584 input.) 585 586 This functionality is also available in the :mod:`popen2` module using functions 587 of the same names, but the return values of those functions have a different 588 order. 589 590 591 .. _os-fd-ops: 592 593 File Descriptor Operations 594 -------------------------- 595 596 These functions operate on I/O streams referenced using file descriptors. 597 598 File descriptors are small integers corresponding to a file that has been opened 599 by the current process. For example, standard input is usually file descriptor 600 0, standard output is 1, and standard error is 2. Further files opened by a 601 process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" 602 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced 603 by file descriptors. 604 605 The :meth:`~file.fileno` method can be used to obtain the file descriptor 606 associated with a file object when required. Note that using the file 607 descriptor directly will bypass the file object methods, ignoring aspects such 608 as internal buffering of data. 609 610 .. function:: close(fd) 611 612 Close file descriptor *fd*. 613 614 Availability: Unix, Windows. 615 616 .. note:: 617 618 This function is intended for low-level I/O and must be applied to a file 619 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file 620 object" returned by the built-in function :func:`open` or by :func:`popen` or 621 :func:`fdopen`, use its :meth:`~io.IOBase.close` method. 622 623 624 .. function:: closerange(fd_low, fd_high) 625 626 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), 627 ignoring errors. Equivalent to:: 628 629 for fd in xrange(fd_low, fd_high): 630 try: 631 os.close(fd) 632 except OSError: 633 pass 634 635 Availability: Unix, Windows. 636 637 .. versionadded:: 2.6 638 639 640 .. function:: dup(fd) 641 642 Return a duplicate of file descriptor *fd*. 643 644 Availability: Unix, Windows. 645 646 647 .. function:: dup2(fd, fd2) 648 649 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary. 650 651 Availability: Unix, Windows. 652 653 654 .. function:: fchmod(fd, mode) 655 656 Change the mode of the file given by *fd* to the numeric *mode*. See the docs 657 for :func:`chmod` for possible values of *mode*. 658 659 Availability: Unix. 660 661 .. versionadded:: 2.6 662 663 664 .. function:: fchown(fd, uid, gid) 665 666 Change the owner and group id of the file given by *fd* to the numeric *uid* 667 and *gid*. To leave one of the ids unchanged, set it to -1. 668 669 Availability: Unix. 670 671 .. versionadded:: 2.6 672 673 674 .. function:: fdatasync(fd) 675 676 Force write of file with filedescriptor *fd* to disk. Does not force update of 677 metadata. 678 679 Availability: Unix. 680 681 .. note:: 682 This function is not available on MacOS. 683 684 685 .. function:: fpathconf(fd, name) 686 687 Return system configuration information relevant to an open file. *name* 688 specifies the configuration value to retrieve; it may be a string which is the 689 name of a defined system value; these names are specified in a number of 690 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define 691 additional names as well. The names known to the host operating system are 692 given in the ``pathconf_names`` dictionary. For configuration variables not 693 included in that mapping, passing an integer for *name* is also accepted. 694 695 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 696 specific value for *name* is not supported by the host system, even if it is 697 included in ``pathconf_names``, an :exc:`OSError` is raised with 698 :const:`errno.EINVAL` for the error number. 699 700 Availability: Unix. 701 702 703 .. function:: fstat(fd) 704 705 Return status for file descriptor *fd*, like :func:`~os.stat`. 706 707 Availability: Unix, Windows. 708 709 710 .. function:: fstatvfs(fd) 711 712 Return information about the filesystem containing the file associated with file 713 descriptor *fd*, like :func:`statvfs`. 714 715 Availability: Unix. 716 717 718 .. function:: fsync(fd) 719 720 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the 721 native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function. 722 723 If you're starting with a Python file object *f*, first do ``f.flush()``, and 724 then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated 725 with *f* are written to disk. 726 727 Availability: Unix, and Windows starting in 2.2.3. 728 729 730 .. function:: ftruncate(fd, length) 731 732 Truncate the file corresponding to file descriptor *fd*, so that it is at most 733 *length* bytes in size. 734 735 Availability: Unix. 736 737 738 .. function:: isatty(fd) 739 740 Return ``True`` if the file descriptor *fd* is open and connected to a 741 tty(-like) device, else ``False``. 742 743 744 .. function:: lseek(fd, pos, how) 745 746 Set the current position of file descriptor *fd* to position *pos*, modified 747 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the 748 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the 749 current position; :const:`SEEK_END` or ``2`` to set it relative to the end of 750 the file. Return the new cursor position in bytes, starting from the beginning. 751 752 Availability: Unix, Windows. 753 754 755 .. data:: SEEK_SET 756 SEEK_CUR 757 SEEK_END 758 759 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, 760 respectively. 761 762 Availability: Windows, Unix. 763 764 .. versionadded:: 2.5 765 766 767 .. function:: open(file, flags[, mode]) 768 769 Open the file *file* and set various flags according to *flags* and possibly its 770 mode according to *mode*. The default *mode* is ``0777`` (octal), and the 771 current umask value is first masked out. Return the file descriptor for the 772 newly opened file. 773 774 For a description of the flag and mode values, see the C run-time documentation; 775 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in 776 this module too (see :ref:`open-constants`). In particular, on Windows adding 777 :const:`O_BINARY` is needed to open files in binary mode. 778 779 Availability: Unix, Windows. 780 781 .. note:: 782 783 This function is intended for low-level I/O. For normal usage, use the 784 built-in function :func:`open`, which returns a "file object" with 785 :meth:`~file.read` and :meth:`~file.write` methods (and many more). To 786 wrap a file descriptor in a "file object", use :func:`fdopen`. 787 788 789 .. function:: openpty() 790 791 .. index:: module: pty 792 793 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master, 794 slave)`` for the pty and the tty, respectively. For a (slightly) more portable 795 approach, use the :mod:`pty` module. 796 797 Availability: some flavors of Unix. 798 799 800 .. function:: pipe() 801 802 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading 803 and writing, respectively. 804 805 Availability: Unix, Windows. 806 807 808 .. function:: read(fd, n) 809 810 Read at most *n* bytes from file descriptor *fd*. Return a string containing the 811 bytes read. If the end of the file referred to by *fd* has been reached, an 812 empty string is returned. 813 814 Availability: Unix, Windows. 815 816 .. note:: 817 818 This function is intended for low-level I/O and must be applied to a file 819 descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object" 820 returned by the built-in function :func:`open` or by :func:`popen` or 821 :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or 822 :meth:`~file.readline` methods. 823 824 825 .. function:: tcgetpgrp(fd) 826 827 Return the process group associated with the terminal given by *fd* (an open 828 file descriptor as returned by :func:`os.open`). 829 830 Availability: Unix. 831 832 833 .. function:: tcsetpgrp(fd, pg) 834 835 Set the process group associated with the terminal given by *fd* (an open file 836 descriptor as returned by :func:`os.open`) to *pg*. 837 838 Availability: Unix. 839 840 841 .. function:: ttyname(fd) 842 843 Return a string which specifies the terminal device associated with 844 file descriptor *fd*. If *fd* is not associated with a terminal device, an 845 exception is raised. 846 847 Availability: Unix. 848 849 850 .. function:: write(fd, str) 851 852 Write the string *str* to file descriptor *fd*. Return the number of bytes 853 actually written. 854 855 Availability: Unix, Windows. 856 857 .. note:: 858 859 This function is intended for low-level I/O and must be applied to a file 860 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file 861 object" returned by the built-in function :func:`open` or by :func:`popen` or 862 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its 863 :meth:`~file.write` method. 864 865 866 .. _open-constants: 867 868 ``open()`` flag constants 869 ~~~~~~~~~~~~~~~~~~~~~~~~~ 870 871 The following constants are options for the *flags* parameter to the 872 :func:`~os.open` function. They can be combined using the bitwise OR operator 873 ``|``. Some of them are not available on all platforms. For descriptions of 874 their availability and use, consult the :manpage:`open(2)` manual page on Unix 875 or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. 876 877 878 .. data:: O_RDONLY 879 O_WRONLY 880 O_RDWR 881 O_APPEND 882 O_CREAT 883 O_EXCL 884 O_TRUNC 885 886 The above constants are available on Unix and Windows. 887 888 889 .. data:: O_DSYNC 890 O_RSYNC 891 O_SYNC 892 O_NDELAY 893 O_NONBLOCK 894 O_NOCTTY 895 896 The above constants are only available on Unix. 897 898 899 .. data:: O_BINARY 900 O_NOINHERIT 901 O_SHORT_LIVED 902 O_TEMPORARY 903 O_RANDOM 904 O_SEQUENTIAL 905 O_TEXT 906 907 The above constants are only available on Windows. 908 909 910 .. data:: O_ASYNC 911 O_DIRECT 912 O_DIRECTORY 913 O_NOFOLLOW 914 O_NOATIME 915 O_SHLOCK 916 O_EXLOCK 917 918 The above constants are extensions and not present if they are not 919 defined by the C library. 920 921 922 .. _os-file-dir: 923 924 Files and Directories 925 --------------------- 926 927 .. function:: access(path, mode) 928 929 Use the real uid/gid to test for access to *path*. Note that most operations 930 will use the effective uid/gid, therefore this routine can be used in a 931 suid/sgid environment to test if the invoking user has the specified access to 932 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it 933 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and 934 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed, 935 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more 936 information. 937 938 Availability: Unix, Windows. 939 940 .. note:: 941 942 Using :func:`access` to check if a user is authorized to e.g. open a file 943 before actually doing so using :func:`open` creates a security hole, 944 because the user might exploit the short time interval between checking 945 and opening the file to manipulate it. It's preferable to use :term:`EAFP` 946 techniques. For example:: 947 948 if os.access("myfile", os.R_OK): 949 with open("myfile") as fp: 950 return fp.read() 951 return "some default data" 952 953 is better written as:: 954 955 try: 956 fp = open("myfile") 957 except IOError as e: 958 if e.errno == errno.EACCES: 959 return "some default data" 960 # Not a permission error. 961 raise 962 else: 963 with fp: 964 return fp.read() 965 966 .. note:: 967 968 I/O operations may fail even when :func:`access` indicates that they would 969 succeed, particularly for operations on network filesystems which may have 970 permissions semantics beyond the usual POSIX permission-bit model. 971 972 973 .. data:: F_OK 974 975 Value to pass as the *mode* parameter of :func:`access` to test the existence of 976 *path*. 977 978 979 .. data:: R_OK 980 981 Value to include in the *mode* parameter of :func:`access` to test the 982 readability of *path*. 983 984 985 .. data:: W_OK 986 987 Value to include in the *mode* parameter of :func:`access` to test the 988 writability of *path*. 989 990 991 .. data:: X_OK 992 993 Value to include in the *mode* parameter of :func:`access` to determine if 994 *path* can be executed. 995 996 997 .. function:: chdir(path) 998 999 .. index:: single: directory; changing 1000 1001 Change the current working directory to *path*. 1002 1003 Availability: Unix, Windows. 1004 1005 1006 .. function:: fchdir(fd) 1007 1008 Change the current working directory to the directory represented by the file 1009 descriptor *fd*. The descriptor must refer to an opened directory, not an open 1010 file. 1011 1012 Availability: Unix. 1013 1014 .. versionadded:: 2.3 1015 1016 1017 .. function:: getcwd() 1018 1019 Return a string representing the current working directory. 1020 1021 Availability: Unix, Windows. 1022 1023 1024 .. function:: getcwdu() 1025 1026 Return a Unicode object representing the current working directory. 1027 1028 Availability: Unix, Windows. 1029 1030 .. versionadded:: 2.3 1031 1032 1033 .. function:: chflags(path, flags) 1034 1035 Set the flags of *path* to the numeric *flags*. *flags* may take a combination 1036 (bitwise OR) of the following values (as defined in the :mod:`stat` module): 1037 1038 * :data:`stat.UF_NODUMP` 1039 * :data:`stat.UF_IMMUTABLE` 1040 * :data:`stat.UF_APPEND` 1041 * :data:`stat.UF_OPAQUE` 1042 * :data:`stat.UF_NOUNLINK` 1043 * :data:`stat.UF_COMPRESSED` 1044 * :data:`stat.UF_HIDDEN` 1045 * :data:`stat.SF_ARCHIVED` 1046 * :data:`stat.SF_IMMUTABLE` 1047 * :data:`stat.SF_APPEND` 1048 * :data:`stat.SF_NOUNLINK` 1049 * :data:`stat.SF_SNAPSHOT` 1050 1051 Availability: Unix. 1052 1053 .. versionadded:: 2.6 1054 1055 1056 .. function:: chroot(path) 1057 1058 Change the root directory of the current process to *path*. Availability: 1059 Unix. 1060 1061 .. versionadded:: 2.2 1062 1063 1064 .. function:: chmod(path, mode) 1065 1066 Change the mode of *path* to the numeric *mode*. *mode* may take one of the 1067 following values (as defined in the :mod:`stat` module) or bitwise ORed 1068 combinations of them: 1069 1070 1071 * :data:`stat.S_ISUID` 1072 * :data:`stat.S_ISGID` 1073 * :data:`stat.S_ENFMT` 1074 * :data:`stat.S_ISVTX` 1075 * :data:`stat.S_IREAD` 1076 * :data:`stat.S_IWRITE` 1077 * :data:`stat.S_IEXEC` 1078 * :data:`stat.S_IRWXU` 1079 * :data:`stat.S_IRUSR` 1080 * :data:`stat.S_IWUSR` 1081 * :data:`stat.S_IXUSR` 1082 * :data:`stat.S_IRWXG` 1083 * :data:`stat.S_IRGRP` 1084 * :data:`stat.S_IWGRP` 1085 * :data:`stat.S_IXGRP` 1086 * :data:`stat.S_IRWXO` 1087 * :data:`stat.S_IROTH` 1088 * :data:`stat.S_IWOTH` 1089 * :data:`stat.S_IXOTH` 1090 1091 Availability: Unix, Windows. 1092 1093 .. note:: 1094 1095 Although Windows supports :func:`chmod`, you can only set the file's read-only 1096 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` 1097 constants or a corresponding integer value). All other bits are 1098 ignored. 1099 1100 1101 .. function:: chown(path, uid, gid) 1102 1103 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave 1104 one of the ids unchanged, set it to -1. 1105 1106 Availability: Unix. 1107 1108 1109 .. function:: lchflags(path, flags) 1110 1111 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not 1112 follow symbolic links. 1113 1114 Availability: Unix. 1115 1116 .. versionadded:: 2.6 1117 1118 1119 .. function:: lchmod(path, mode) 1120 1121 Change the mode of *path* to the numeric *mode*. If path is a symlink, this 1122 affects the symlink rather than the target. See the docs for :func:`chmod` 1123 for possible values of *mode*. 1124 1125 Availability: Unix. 1126 1127 .. versionadded:: 2.6 1128 1129 1130 .. function:: lchown(path, uid, gid) 1131 1132 Change the owner and group id of *path* to the numeric *uid* and *gid*. This 1133 function will not follow symbolic links. 1134 1135 Availability: Unix. 1136 1137 .. versionadded:: 2.3 1138 1139 1140 .. function:: link(source, link_name) 1141 1142 Create a hard link pointing to *source* named *link_name*. 1143 1144 Availability: Unix. 1145 1146 1147 .. function:: listdir(path) 1148 1149 Return a list containing the names of the entries in the directory given by 1150 *path*. The list is in arbitrary order. It does not include the special 1151 entries ``'.'`` and ``'..'`` even if they are present in the 1152 directory. 1153 1154 Availability: Unix, Windows. 1155 1156 .. versionchanged:: 2.3 1157 On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be 1158 a list of Unicode objects. Undecodable filenames will still be returned as 1159 string objects. 1160 1161 1162 .. function:: lstat(path) 1163 1164 Perform the equivalent of an :c:func:`lstat` system call on the given path. 1165 Similar to :func:`~os.stat`, but does not follow symbolic links. On 1166 platforms that do not support symbolic links, this is an alias for 1167 :func:`~os.stat`. 1168 1169 1170 .. function:: mkfifo(path[, mode]) 1171 1172 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default 1173 *mode* is ``0666`` (octal). The current umask value is first masked out from 1174 the mode. 1175 1176 Availability: Unix. 1177 1178 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they 1179 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as 1180 rendezvous between "client" and "server" type processes: the server opens the 1181 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo` 1182 doesn't open the FIFO --- it just creates the rendezvous point. 1183 1184 1185 .. function:: mknod(filename[, mode=0600[, device=0]]) 1186 1187 Create a filesystem node (file, device special file or named pipe) named 1188 *filename*. *mode* specifies both the permissions to use and the type of node to 1189 be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, 1190 ``stat.S_IFCHR``, ``stat.S_IFBLK``, 1191 and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`). 1192 For ``stat.S_IFCHR`` and 1193 ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using 1194 :func:`os.makedev`), otherwise it is ignored. 1195 1196 .. versionadded:: 2.3 1197 1198 1199 .. function:: major(device) 1200 1201 Extract the device major number from a raw device number (usually the 1202 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). 1203 1204 .. versionadded:: 2.3 1205 1206 1207 .. function:: minor(device) 1208 1209 Extract the device minor number from a raw device number (usually the 1210 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). 1211 1212 .. versionadded:: 2.3 1213 1214 1215 .. function:: makedev(major, minor) 1216 1217 Compose a raw device number from the major and minor device numbers. 1218 1219 .. versionadded:: 2.3 1220 1221 1222 .. function:: mkdir(path[, mode]) 1223 1224 Create a directory named *path* with numeric mode *mode*. The default *mode* is 1225 ``0777`` (octal). If the directory already exists, 1226 :exc:`OSError` is raised. 1227 1228 .. _mkdir_modebits: 1229 1230 On some systems, *mode* is ignored. Where it is used, the current umask 1231 value is first masked out. If bits other than the last 9 (i.e. the last 3 1232 digits of the octal representation of the *mode*) are set, their meaning is 1233 platform-dependent. On some platforms, they are ignored and you should call 1234 :func:`chmod` explicitly to set them. 1235 1236 It is also possible to create temporary directories; see the 1237 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function. 1238 1239 Availability: Unix, Windows. 1240 1241 1242 .. function:: makedirs(path[, mode]) 1243 1244 .. index:: 1245 single: directory; creating 1246 single: UNC paths; and os.makedirs() 1247 1248 Recursive directory creation function. Like :func:`mkdir`, but makes all 1249 intermediate-level directories needed to contain the leaf directory. Raises an 1250 :exc:`error` exception if the leaf directory already exists or cannot be 1251 created. The default *mode* is ``0777`` (octal). 1252 1253 The *mode* parameter is passed to :func:`mkdir`; see :ref:`the mkdir() 1254 description <mkdir_modebits>` for how it is interpreted. 1255 1256 .. note:: 1257 1258 :func:`makedirs` will become confused if the path elements to create include 1259 :data:`os.pardir`. 1260 1261 .. versionadded:: 1.5.2 1262 1263 .. versionchanged:: 2.3 1264 This function now handles UNC paths correctly. 1265 1266 1267 .. function:: pathconf(path, name) 1268 1269 Return system configuration information relevant to a named file. *name* 1270 specifies the configuration value to retrieve; it may be a string which is the 1271 name of a defined system value; these names are specified in a number of 1272 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define 1273 additional names as well. The names known to the host operating system are 1274 given in the ``pathconf_names`` dictionary. For configuration variables not 1275 included in that mapping, passing an integer for *name* is also accepted. 1276 1277 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 1278 specific value for *name* is not supported by the host system, even if it is 1279 included in ``pathconf_names``, an :exc:`OSError` is raised with 1280 :const:`errno.EINVAL` for the error number. 1281 1282 Availability: Unix. 1283 1284 1285 .. data:: pathconf_names 1286 1287 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to 1288 the integer values defined for those names by the host operating system. This 1289 can be used to determine the set of names known to the system. Availability: 1290 Unix. 1291 1292 1293 .. function:: readlink(path) 1294 1295 Return a string representing the path to which the symbolic link points. The 1296 result may be either an absolute or relative pathname; if it is relative, it may 1297 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path), 1298 result)``. 1299 1300 .. versionchanged:: 2.6 1301 If the *path* is a Unicode object the result will also be a Unicode object. 1302 1303 Availability: Unix. 1304 1305 1306 .. function:: remove(path) 1307 1308 Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is 1309 raised; see :func:`rmdir` below to remove a directory. This is identical to 1310 the :func:`unlink` function documented below. On Windows, attempting to 1311 remove a file that is in use causes an exception to be raised; on Unix, the 1312 directory entry is removed but the storage allocated to the file is not made 1313 available until the original file is no longer in use. 1314 1315 Availability: Unix, Windows. 1316 1317 1318 .. function:: removedirs(path) 1319 1320 .. index:: single: directory; deleting 1321 1322 Remove directories recursively. Works like :func:`rmdir` except that, if the 1323 leaf directory is successfully removed, :func:`removedirs` tries to 1324 successively remove every parent directory mentioned in *path* until an error 1325 is raised (which is ignored, because it generally means that a parent directory 1326 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove 1327 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if 1328 they are empty. Raises :exc:`OSError` if the leaf directory could not be 1329 successfully removed. 1330 1331 .. versionadded:: 1.5.2 1332 1333 1334 .. function:: rename(src, dst) 1335 1336 Rename the file or directory *src* to *dst*. If *dst* is a directory, 1337 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will 1338 be replaced silently if the user has permission. The operation may fail on some 1339 Unix flavors if *src* and *dst* are on different filesystems. If successful, 1340 the renaming will be an atomic operation (this is a POSIX requirement). On 1341 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a 1342 file; there may be no way to implement an atomic rename when *dst* names an 1343 existing file. 1344 1345 Availability: Unix, Windows. 1346 1347 1348 .. function:: renames(old, new) 1349 1350 Recursive directory or file renaming function. Works like :func:`rename`, except 1351 creation of any intermediate directories needed to make the new pathname good is 1352 attempted first. After the rename, directories corresponding to rightmost path 1353 segments of the old name will be pruned away using :func:`removedirs`. 1354 1355 .. versionadded:: 1.5.2 1356 1357 .. note:: 1358 1359 This function can fail with the new directory structure made if you lack 1360 permissions needed to remove the leaf directory or file. 1361 1362 1363 .. function:: rmdir(path) 1364 1365 Remove (delete) the directory *path*. Only works when the directory is 1366 empty, otherwise, :exc:`OSError` is raised. In order to remove whole 1367 directory trees, :func:`shutil.rmtree` can be used. 1368 1369 Availability: Unix, Windows. 1370 1371 1372 .. function:: stat(path) 1373 1374 Perform the equivalent of a :c:func:`stat` system call on the given path. 1375 (This function follows symlinks; to stat a symlink use :func:`lstat`.) 1376 1377 The return value is an object whose attributes correspond to the members 1378 of the :c:type:`stat` structure, namely: 1379 1380 * :attr:`st_mode` - protection bits, 1381 * :attr:`st_ino` - inode number, 1382 * :attr:`st_dev` - device, 1383 * :attr:`st_nlink` - number of hard links, 1384 * :attr:`st_uid` - user id of owner, 1385 * :attr:`st_gid` - group id of owner, 1386 * :attr:`st_size` - size of file, in bytes, 1387 * :attr:`st_atime` - time of most recent access, 1388 * :attr:`st_mtime` - time of most recent content modification, 1389 * :attr:`st_ctime` - platform dependent; time of most recent metadata change on 1390 Unix, or the time of creation on Windows) 1391 1392 .. versionchanged:: 2.3 1393 If :func:`stat_float_times` returns ``True``, the time values are floats, measuring 1394 seconds. Fractions of a second may be reported if the system supports that. 1395 See :func:`stat_float_times` for further discussion. 1396 1397 On some Unix systems (such as Linux), the following attributes may also be 1398 available: 1399 1400 * :attr:`st_blocks` - number of 512-byte blocks allocated for file 1401 * :attr:`st_blksize` - filesystem blocksize for efficient file system I/O 1402 * :attr:`st_rdev` - type of device if an inode device 1403 * :attr:`st_flags` - user defined flags for file 1404 1405 On other Unix systems (such as FreeBSD), the following attributes may be 1406 available (but may be only filled out if root tries to use them): 1407 1408 * :attr:`st_gen` - file generation number 1409 * :attr:`st_birthtime` - time of file creation 1410 1411 On RISCOS systems, the following attributes are also available: 1412 1413 * :attr:`st_ftype` (file type) 1414 * :attr:`st_attrs` (attributes) 1415 * :attr:`st_obtype` (object type). 1416 1417 .. note:: 1418 1419 The exact meaning and resolution of the :attr:`st_atime`, 1420 :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating 1421 system and the file system. For example, on Windows systems using the FAT 1422 or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and 1423 :attr:`st_atime` has only 1-day resolution. See your operating system 1424 documentation for details. 1425 1426 For backward compatibility, the return value of :func:`~os.stat` is also accessible 1427 as a tuple of at least 10 integers giving the most important (and portable) 1428 members of the :c:type:`stat` structure, in the order :attr:`st_mode`, 1429 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`, 1430 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`, 1431 :attr:`st_ctime`. More items may be added at the end by some implementations. 1432 1433 .. index:: module: stat 1434 1435 The standard module :mod:`stat` defines functions and constants that are useful 1436 for extracting information from a :c:type:`stat` structure. (On Windows, some 1437 items are filled with dummy values.) 1438 1439 Example:: 1440 1441 >>> import os 1442 >>> statinfo = os.stat('somefile.txt') 1443 >>> statinfo 1444 (33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732) 1445 >>> statinfo.st_size 1446 926 1447 1448 Availability: Unix, Windows. 1449 1450 .. versionchanged:: 2.2 1451 Added access to values as attributes of the returned object. 1452 1453 .. versionchanged:: 2.5 1454 Added :attr:`st_gen` and :attr:`st_birthtime`. 1455 1456 1457 .. function:: stat_float_times([newvalue]) 1458 1459 Determine whether :class:`stat_result` represents time stamps as float objects. 1460 If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is 1461 ``False``, future calls return ints. If *newvalue* is omitted, return the 1462 current setting. 1463 1464 For compatibility with older Python versions, accessing :class:`stat_result` as 1465 a tuple always returns integers. 1466 1467 .. versionchanged:: 2.5 1468 Python now returns float values by default. Applications which do not work 1469 correctly with floating point time stamps can use this function to restore the 1470 old behaviour. 1471 1472 The resolution of the timestamps (that is the smallest possible fraction) 1473 depends on the system. Some systems only support second resolution; on these 1474 systems, the fraction will always be zero. 1475 1476 It is recommended that this setting is only changed at program startup time in 1477 the *__main__* module; libraries should never change this setting. If an 1478 application uses a library that works incorrectly if floating point time stamps 1479 are processed, this application should turn the feature off until the library 1480 has been corrected. 1481 1482 1483 .. function:: statvfs(path) 1484 1485 Perform a :c:func:`statvfs` system call on the given path. The return value is 1486 an object whose attributes describe the filesystem on the given path, and 1487 correspond to the members of the :c:type:`statvfs` structure, namely: 1488 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, 1489 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`, 1490 :attr:`f_flag`, :attr:`f_namemax`. 1491 1492 .. index:: module: statvfs 1493 1494 For backward compatibility, the return value is also accessible as a tuple whose 1495 values correspond to the attributes, in the order given above. The standard 1496 module :mod:`statvfs` defines constants that are useful for extracting 1497 information from a :c:type:`statvfs` structure when accessing it as a sequence; 1498 this remains useful when writing code that needs to work with versions of Python 1499 that don't support accessing the fields as attributes. 1500 1501 Availability: Unix. 1502 1503 .. versionchanged:: 2.2 1504 Added access to values as attributes of the returned object. 1505 1506 1507 .. function:: symlink(source, link_name) 1508 1509 Create a symbolic link pointing to *source* named *link_name*. 1510 1511 Availability: Unix. 1512 1513 1514 .. function:: tempnam([dir[, prefix]]) 1515 1516 Return a unique path name that is reasonable for creating a temporary file. 1517 This will be an absolute path that names a potential directory entry in the 1518 directory *dir* or a common location for temporary files if *dir* is omitted or 1519 ``None``. If given and not ``None``, *prefix* is used to provide a short prefix 1520 to the filename. Applications are responsible for properly creating and 1521 managing files created using paths returned by :func:`tempnam`; no automatic 1522 cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR` 1523 overrides *dir*, while on Windows :envvar:`TMP` is used. The specific 1524 behavior of this function depends on the C library implementation; some aspects 1525 are underspecified in system documentation. 1526 1527 .. warning:: 1528 1529 Use of :func:`tempnam` is vulnerable to symlink attacks; consider using 1530 :func:`tmpfile` (section :ref:`os-newstreams`) instead. 1531 1532 Availability: Unix, Windows. 1533 1534 1535 .. function:: tmpnam() 1536 1537 Return a unique path name that is reasonable for creating a temporary file. 1538 This will be an absolute path that names a potential directory entry in a common 1539 location for temporary files. Applications are responsible for properly 1540 creating and managing files created using paths returned by :func:`tmpnam`; no 1541 automatic cleanup is provided. 1542 1543 .. warning:: 1544 1545 Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using 1546 :func:`tmpfile` (section :ref:`os-newstreams`) instead. 1547 1548 Availability: Unix, Windows. This function probably shouldn't be used on 1549 Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a 1550 name in the root directory of the current drive, and that's generally a poor 1551 location for a temp file (depending on privileges, you may not even be able to 1552 open a file using this name). 1553 1554 1555 .. data:: TMP_MAX 1556 1557 The maximum number of unique names that :func:`tmpnam` will generate before 1558 reusing names. 1559 1560 1561 .. function:: unlink(path) 1562 1563 Remove (delete) the file *path*. This is the same function as 1564 :func:`remove`; the :func:`unlink` name is its traditional Unix 1565 name. 1566 1567 Availability: Unix, Windows. 1568 1569 1570 .. function:: utime(path, times) 1571 1572 Set the access and modified times of the file specified by *path*. If *times* 1573 is ``None``, then the file's access and modified times are set to the current 1574 time. (The effect is similar to running the Unix program :program:`touch` on 1575 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form 1576 ``(atime, mtime)`` which is used to set the access and modified times, 1577 respectively. Whether a directory can be given for *path* depends on whether 1578 the operating system implements directories as files (for example, Windows 1579 does not). Note that the exact times you set here may not be returned by a 1580 subsequent :func:`~os.stat` call, depending on the resolution with which your 1581 operating system records access and modification times; see :func:`~os.stat`. 1582 1583 .. versionchanged:: 2.0 1584 Added support for ``None`` for *times*. 1585 1586 Availability: Unix, Windows. 1587 1588 1589 .. function:: walk(top, topdown=True, onerror=None, followlinks=False) 1590 1591 .. index:: 1592 single: directory; walking 1593 single: directory; traversal 1594 1595 Generate the file names in a directory tree by walking the tree 1596 either top-down or bottom-up. For each directory in the tree rooted at directory 1597 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, 1598 filenames)``. 1599 1600 *dirpath* is a string, the path to the directory. *dirnames* is a list of the 1601 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``). 1602 *filenames* is a list of the names of the non-directory files in *dirpath*. 1603 Note that the names in the lists contain no path components. To get a full path 1604 (which begins with *top*) to a file or directory in *dirpath*, do 1605 ``os.path.join(dirpath, name)``. 1606 1607 If optional argument *topdown* is ``True`` or not specified, the triple for a 1608 directory is generated before the triples for any of its subdirectories 1609 (directories are generated top-down). If *topdown* is ``False``, the triple 1610 for a directory is generated after the triples for all of its subdirectories 1611 (directories are generated bottom-up). No matter the value of *topdown*, the 1612 list of subdirectories is retrieved before the tuples for the directory and 1613 its subdirectories are generated. 1614 1615 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place 1616 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only 1617 recurse into the subdirectories whose names remain in *dirnames*; this can be 1618 used to prune the search, impose a specific order of visiting, or even to inform 1619 :func:`walk` about directories the caller creates or renames before it resumes 1620 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has 1621 no effect on the behavior of the walk, because in bottom-up mode the directories 1622 in *dirnames* are generated before *dirpath* itself is generated. 1623 1624 By default, errors from the :func:`listdir` call are ignored. If optional 1625 argument *onerror* is specified, it should be a function; it will be called with 1626 one argument, an :exc:`OSError` instance. It can report the error to continue 1627 with the walk, or raise the exception to abort the walk. Note that the filename 1628 is available as the ``filename`` attribute of the exception object. 1629 1630 By default, :func:`walk` will not walk down into symbolic links that resolve to 1631 directories. Set *followlinks* to ``True`` to visit directories pointed to by 1632 symlinks, on systems that support them. 1633 1634 .. versionadded:: 2.6 1635 The *followlinks* parameter. 1636 1637 .. note:: 1638 1639 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a 1640 link points to a parent directory of itself. :func:`walk` does not keep track of 1641 the directories it visited already. 1642 1643 .. note:: 1644 1645 If you pass a relative pathname, don't change the current working directory 1646 between resumptions of :func:`walk`. :func:`walk` never changes the current 1647 directory, and assumes that its caller doesn't either. 1648 1649 This example displays the number of bytes taken by non-directory files in each 1650 directory under the starting directory, except that it doesn't look under any 1651 CVS subdirectory:: 1652 1653 import os 1654 from os.path import join, getsize 1655 for root, dirs, files in os.walk('python/Lib/email'): 1656 print root, "consumes", 1657 print sum(getsize(join(root, name)) for name in files), 1658 print "bytes in", len(files), "non-directory files" 1659 if 'CVS' in dirs: 1660 dirs.remove('CVS') # don't visit CVS directories 1661 1662 In the next example, walking the tree bottom-up is essential: :func:`rmdir` 1663 doesn't allow deleting a directory before the directory is empty:: 1664 1665 # Delete everything reachable from the directory named in "top", 1666 # assuming there are no symbolic links. 1667 # CAUTION: This is dangerous! For example, if top == '/', it 1668 # could delete all your disk files. 1669 import os 1670 for root, dirs, files in os.walk(top, topdown=False): 1671 for name in files: 1672 os.remove(os.path.join(root, name)) 1673 for name in dirs: 1674 os.rmdir(os.path.join(root, name)) 1675 1676 .. versionadded:: 2.3 1677 1678 1679 .. _os-process: 1680 1681 Process Management 1682 ------------------ 1683 1684 These functions may be used to create and manage processes. 1685 1686 The various :func:`exec\* <execl>` functions take a list of arguments for the new 1687 program loaded into the process. In each case, the first of these arguments is 1688 passed to the new program as its own name rather than as an argument a user may 1689 have typed on a command line. For the C programmer, this is the ``argv[0]`` 1690 passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', 1691 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem 1692 to be ignored. 1693 1694 1695 .. function:: abort() 1696 1697 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default 1698 behavior is to produce a core dump; on Windows, the process immediately returns 1699 an exit code of ``3``. Be aware that calling this function will not call the 1700 Python signal handler registered for :const:`SIGABRT` with 1701 :func:`signal.signal`. 1702 1703 Availability: Unix, Windows. 1704 1705 1706 .. function:: execl(path, arg0, arg1, ...) 1707 execle(path, arg0, arg1, ..., env) 1708 execlp(file, arg0, arg1, ...) 1709 execlpe(file, arg0, arg1, ..., env) 1710 execv(path, args) 1711 execve(path, args, env) 1712 execvp(file, args) 1713 execvpe(file, args, env) 1714 1715 These functions all execute a new program, replacing the current process; they 1716 do not return. On Unix, the new executable is loaded into the current process, 1717 and will have the same process id as the caller. Errors will be reported as 1718 :exc:`OSError` exceptions. 1719 1720 The current process is replaced immediately. Open file objects and 1721 descriptors are not flushed, so if there may be data buffered 1722 on these open files, you should flush them using 1723 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an 1724 :func:`exec\* <execl>` function. 1725 1726 The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how 1727 command-line arguments are passed. The "l" variants are perhaps the easiest 1728 to work with if the number of parameters is fixed when the code is written; the 1729 individual parameters simply become additional parameters to the :func:`execl\*` 1730 functions. The "v" variants are good when the number of parameters is 1731 variable, with the arguments being passed in a list or tuple as the *args* 1732 parameter. In either case, the arguments to the child process should start with 1733 the name of the command being run, but this is not enforced. 1734 1735 The variants which include a "p" near the end (:func:`execlp`, 1736 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the 1737 :envvar:`PATH` environment variable to locate the program *file*. When the 1738 environment is being replaced (using one of the :func:`exec\*e <execl>` variants, 1739 discussed in the next paragraph), the new environment is used as the source of 1740 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`, 1741 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to 1742 locate the executable; *path* must contain an appropriate absolute or relative 1743 path. 1744 1745 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note 1746 that these all end in "e"), the *env* parameter must be a mapping which is 1747 used to define the environment variables for the new process (these are used 1748 instead of the current process' environment); the functions :func:`execl`, 1749 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to 1750 inherit the environment of the current process. 1751 1752 Availability: Unix, Windows. 1753 1754 1755 .. function:: _exit(n) 1756 1757 Exit the process with status *n*, without calling cleanup handlers, flushing 1758 stdio buffers, etc. 1759 1760 Availability: Unix, Windows. 1761 1762 .. note:: 1763 1764 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should 1765 normally only be used in the child process after a :func:`fork`. 1766 1767 The following exit codes are defined and can be used with :func:`_exit`, 1768 although they are not required. These are typically used for system programs 1769 written in Python, such as a mail server's external command delivery program. 1770 1771 .. note:: 1772 1773 Some of these may not be available on all Unix platforms, since there is some 1774 variation. These constants are defined where they are defined by the underlying 1775 platform. 1776 1777 1778 .. data:: EX_OK 1779 1780 Exit code that means no error occurred. 1781 1782 Availability: Unix. 1783 1784 .. versionadded:: 2.3 1785 1786 1787 .. data:: EX_USAGE 1788 1789 Exit code that means the command was used incorrectly, such as when the wrong 1790 number of arguments are given. 1791 1792 Availability: Unix. 1793 1794 .. versionadded:: 2.3 1795 1796 1797 .. data:: EX_DATAERR 1798 1799 Exit code that means the input data was incorrect. 1800 1801 Availability: Unix. 1802 1803 .. versionadded:: 2.3 1804 1805 1806 .. data:: EX_NOINPUT 1807 1808 Exit code that means an input file did not exist or was not readable. 1809 1810 Availability: Unix. 1811 1812 .. versionadded:: 2.3 1813 1814 1815 .. data:: EX_NOUSER 1816 1817 Exit code that means a specified user did not exist. 1818 1819 Availability: Unix. 1820 1821 .. versionadded:: 2.3 1822 1823 1824 .. data:: EX_NOHOST 1825 1826 Exit code that means a specified host did not exist. 1827 1828 Availability: Unix. 1829 1830 .. versionadded:: 2.3 1831 1832 1833 .. data:: EX_UNAVAILABLE 1834 1835 Exit code that means that a required service is unavailable. 1836 1837 Availability: Unix. 1838 1839 .. versionadded:: 2.3 1840 1841 1842 .. data:: EX_SOFTWARE 1843 1844 Exit code that means an internal software error was detected. 1845 1846 Availability: Unix. 1847 1848 .. versionadded:: 2.3 1849 1850 1851 .. data:: EX_OSERR 1852 1853 Exit code that means an operating system error was detected, such as the 1854 inability to fork or create a pipe. 1855 1856 Availability: Unix. 1857 1858 .. versionadded:: 2.3 1859 1860 1861 .. data:: EX_OSFILE 1862 1863 Exit code that means some system file did not exist, could not be opened, or had 1864 some other kind of error. 1865 1866 Availability: Unix. 1867 1868 .. versionadded:: 2.3 1869 1870 1871 .. data:: EX_CANTCREAT 1872 1873 Exit code that means a user specified output file could not be created. 1874 1875 Availability: Unix. 1876 1877 .. versionadded:: 2.3 1878 1879 1880 .. data:: EX_IOERR 1881 1882 Exit code that means that an error occurred while doing I/O on some file. 1883 1884 Availability: Unix. 1885 1886 .. versionadded:: 2.3 1887 1888 1889 .. data:: EX_TEMPFAIL 1890 1891 Exit code that means a temporary failure occurred. This indicates something 1892 that may not really be an error, such as a network connection that couldn't be 1893 made during a retryable operation. 1894 1895 Availability: Unix. 1896 1897 .. versionadded:: 2.3 1898 1899 1900 .. data:: EX_PROTOCOL 1901 1902 Exit code that means that a protocol exchange was illegal, invalid, or not 1903 understood. 1904 1905 Availability: Unix. 1906 1907 .. versionadded:: 2.3 1908 1909 1910 .. data:: EX_NOPERM 1911 1912 Exit code that means that there were insufficient permissions to perform the 1913 operation (but not intended for file system problems). 1914 1915 Availability: Unix. 1916 1917 .. versionadded:: 2.3 1918 1919 1920 .. data:: EX_CONFIG 1921 1922 Exit code that means that some kind of configuration error occurred. 1923 1924 Availability: Unix. 1925 1926 .. versionadded:: 2.3 1927 1928 1929 .. data:: EX_NOTFOUND 1930 1931 Exit code that means something like "an entry was not found". 1932 1933 Availability: Unix. 1934 1935 .. versionadded:: 2.3 1936 1937 1938 .. function:: fork() 1939 1940 Fork a child process. Return ``0`` in the child and the child's process id in the 1941 parent. If an error occurs :exc:`OSError` is raised. 1942 1943 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have 1944 known issues when using fork() from a thread. 1945 1946 .. warning:: 1947 1948 See :mod:`ssl` for applications that use the SSL module with fork(). 1949 1950 Availability: Unix. 1951 1952 1953 .. function:: forkpty() 1954 1955 Fork a child process, using a new pseudo-terminal as the child's controlling 1956 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the 1957 new child's process id in the parent, and *fd* is the file descriptor of the 1958 master end of the pseudo-terminal. For a more portable approach, use the 1959 :mod:`pty` module. If an error occurs :exc:`OSError` is raised. 1960 1961 Availability: some flavors of Unix. 1962 1963 1964 .. function:: kill(pid, sig) 1965 1966 .. index:: 1967 single: process; killing 1968 single: process; signalling 1969 1970 Send signal *sig* to the process *pid*. Constants for the specific signals 1971 available on the host platform are defined in the :mod:`signal` module. 1972 1973 Windows: The :data:`signal.CTRL_C_EVENT` and 1974 :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can 1975 only be sent to console processes which share a common console window, 1976 e.g., some subprocesses. Any other value for *sig* will cause the process 1977 to be unconditionally killed by the TerminateProcess API, and the exit code 1978 will be set to *sig*. The Windows version of :func:`kill` additionally takes 1979 process handles to be killed. 1980 1981 .. versionadded:: 2.7 Windows support 1982 1983 1984 .. function:: killpg(pgid, sig) 1985 1986 .. index:: 1987 single: process; killing 1988 single: process; signalling 1989 1990 Send the signal *sig* to the process group *pgid*. 1991 1992 Availability: Unix. 1993 1994 .. versionadded:: 2.3 1995 1996 1997 .. function:: nice(increment) 1998 1999 Add *increment* to the process's "niceness". Return the new niceness. 2000 2001 Availability: Unix. 2002 2003 2004 .. function:: plock(op) 2005 2006 Lock program segments into memory. The value of *op* (defined in 2007 ``<sys/lock.h>``) determines which segments are locked. 2008 2009 Availability: Unix. 2010 2011 2012 .. function:: popen(...) 2013 popen2(...) 2014 popen3(...) 2015 popen4(...) 2016 :noindex: 2017 2018 Run child processes, returning opened pipes for communications. These functions 2019 are described in section :ref:`os-newstreams`. 2020 2021 2022 .. function:: spawnl(mode, path, ...) 2023 spawnle(mode, path, ..., env) 2024 spawnlp(mode, file, ...) 2025 spawnlpe(mode, file, ..., env) 2026 spawnv(mode, path, args) 2027 spawnve(mode, path, args, env) 2028 spawnvp(mode, file, args) 2029 spawnvpe(mode, file, args, env) 2030 2031 Execute the program *path* in a new process. 2032 2033 (Note that the :mod:`subprocess` module provides more powerful facilities for 2034 spawning new processes and retrieving their results; using that module is 2035 preferable to using these functions. Check especially the 2036 :ref:`subprocess-replacements` section.) 2037 2038 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new 2039 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it 2040 exits normally, or ``-signal``, where *signal* is the signal that killed the 2041 process. On Windows, the process id will actually be the process handle, so can 2042 be used with the :func:`waitpid` function. 2043 2044 The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how 2045 command-line arguments are passed. The "l" variants are perhaps the easiest 2046 to work with if the number of parameters is fixed when the code is written; the 2047 individual parameters simply become additional parameters to the 2048 :func:`spawnl\*` functions. The "v" variants are good when the number of 2049 parameters is variable, with the arguments being passed in a list or tuple as 2050 the *args* parameter. In either case, the arguments to the child process must 2051 start with the name of the command being run. 2052 2053 The variants which include a second "p" near the end (:func:`spawnlp`, 2054 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the 2055 :envvar:`PATH` environment variable to locate the program *file*. When the 2056 environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants, 2057 discussed in the next paragraph), the new environment is used as the source of 2058 the :envvar:`PATH` variable. The other variants, :func:`spawnl`, 2059 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the 2060 :envvar:`PATH` variable to locate the executable; *path* must contain an 2061 appropriate absolute or relative path. 2062 2063 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` 2064 (note that these all end in "e"), the *env* parameter must be a mapping 2065 which is used to define the environment variables for the new process (they are 2066 used instead of the current process' environment); the functions 2067 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause 2068 the new process to inherit the environment of the current process. Note that 2069 keys and values in the *env* dictionary must be strings; invalid keys or 2070 values will cause the function to fail, with a return value of ``127``. 2071 2072 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are 2073 equivalent:: 2074 2075 import os 2076 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') 2077 2078 L = ['cp', 'index.html', '/dev/null'] 2079 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) 2080 2081 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp` 2082 and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and 2083 :func:`spawnve` are not thread-safe on Windows; we advise you to use the 2084 :mod:`subprocess` module instead. 2085 2086 .. versionadded:: 1.6 2087 2088 2089 .. data:: P_NOWAIT 2090 P_NOWAITO 2091 2092 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 2093 functions. If either of these values is given, the :func:`spawn\*` functions 2094 will return as soon as the new process has been created, with the process id as 2095 the return value. 2096 2097 Availability: Unix, Windows. 2098 2099 .. versionadded:: 1.6 2100 2101 2102 .. data:: P_WAIT 2103 2104 Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 2105 functions. If this is given as *mode*, the :func:`spawn\*` functions will not 2106 return until the new process has run to completion and will return the exit code 2107 of the process the run is successful, or ``-signal`` if a signal kills the 2108 process. 2109 2110 Availability: Unix, Windows. 2111 2112 .. versionadded:: 1.6 2113 2114 2115 .. data:: P_DETACH 2116 P_OVERLAY 2117 2118 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 2119 functions. These are less portable than those listed above. :const:`P_DETACH` 2120 is similar to :const:`P_NOWAIT`, but the new process is detached from the 2121 console of the calling process. If :const:`P_OVERLAY` is used, the current 2122 process will be replaced; the :func:`spawn\*` function will not return. 2123 2124 Availability: Windows. 2125 2126 .. versionadded:: 1.6 2127 2128 2129 .. function:: startfile(path[, operation]) 2130 2131 Start a file with its associated application. 2132 2133 When *operation* is not specified or ``'open'``, this acts like double-clicking 2134 the file in Windows Explorer, or giving the file name as an argument to the 2135 :program:`start` command from the interactive command shell: the file is opened 2136 with whatever application (if any) its extension is associated. 2137 2138 When another *operation* is given, it must be a "command verb" that specifies 2139 what should be done with the file. Common verbs documented by Microsoft are 2140 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and 2141 ``'find'`` (to be used on directories). 2142 2143 :func:`startfile` returns as soon as the associated application is launched. 2144 There is no option to wait for the application to close, and no way to retrieve 2145 the application's exit status. The *path* parameter is relative to the current 2146 directory. If you want to use an absolute path, make sure the first character 2147 is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function 2148 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that 2149 the path is properly encoded for Win32. 2150 2151 Availability: Windows. 2152 2153 .. versionadded:: 2.0 2154 2155 .. versionadded:: 2.5 2156 The *operation* parameter. 2157 2158 2159 .. function:: system(command) 2160 2161 Execute the command (a string) in a subshell. This is implemented by calling 2162 the Standard C function :c:func:`system`, and has the same limitations. 2163 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the 2164 executed command. 2165 2166 On Unix, the return value is the exit status of the process encoded in the 2167 format specified for :func:`wait`. Note that POSIX does not specify the meaning 2168 of the return value of the C :c:func:`system` function, so the return value of 2169 the Python function is system-dependent. 2170 2171 On Windows, the return value is that returned by the system shell after running 2172 *command*, given by the Windows environment variable :envvar:`COMSPEC`: on 2173 :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on 2174 :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of 2175 the command run; on systems using a non-native shell, consult your shell 2176 documentation. 2177 2178 The :mod:`subprocess` module provides more powerful facilities for spawning new 2179 processes and retrieving their results; using that module is preferable to using 2180 this function. See the 2181 :ref:`subprocess-replacements` section in the :mod:`subprocess` documentation 2182 for some helpful recipes. 2183 2184 Availability: Unix, Windows. 2185 2186 2187 .. function:: times() 2188 2189 Return a 5-tuple of floating point numbers indicating accumulated (processor 2190 or other) times, in seconds. The items are: user time, system time, 2191 children's user time, children's system time, and elapsed real time since a 2192 fixed point in the past, in that order. See the Unix manual page 2193 :manpage:`times(2)` or the corresponding Windows Platform API documentation. 2194 On Windows, only the first two items are filled, the others are zero. 2195 2196 Availability: Unix, Windows 2197 2198 2199 .. function:: wait() 2200 2201 Wait for completion of a child process, and return a tuple containing its pid 2202 and exit status indication: a 16-bit number, whose low byte is the signal number 2203 that killed the process, and whose high byte is the exit status (if the signal 2204 number is zero); the high bit of the low byte is set if a core file was 2205 produced. 2206 2207 Availability: Unix. 2208 2209 2210 .. function:: waitpid(pid, options) 2211 2212 The details of this function differ on Unix and Windows. 2213 2214 On Unix: Wait for completion of a child process given by process id *pid*, and 2215 return a tuple containing its process id and exit status indication (encoded as 2216 for :func:`wait`). The semantics of the call are affected by the value of the 2217 integer *options*, which should be ``0`` for normal operation. 2218 2219 If *pid* is greater than ``0``, :func:`waitpid` requests status information for 2220 that specific process. If *pid* is ``0``, the request is for the status of any 2221 child in the process group of the current process. If *pid* is ``-1``, the 2222 request pertains to any child of the current process. If *pid* is less than 2223 ``-1``, status is requested for any process in the process group ``-pid`` (the 2224 absolute value of *pid*). 2225 2226 An :exc:`OSError` is raised with the value of errno when the syscall 2227 returns -1. 2228 2229 On Windows: Wait for completion of a process given by process handle *pid*, and 2230 return a tuple containing *pid*, and its exit status shifted left by 8 bits 2231 (shifting makes cross-platform use of the function easier). A *pid* less than or 2232 equal to ``0`` has no special meaning on Windows, and raises an exception. The 2233 value of integer *options* has no effect. *pid* can refer to any process whose 2234 id is known, not necessarily a child process. The :func:`spawn\* <spawnl>` 2235 functions called with :const:`P_NOWAIT` return suitable process handles. 2236 2237 2238 .. function:: wait3(options) 2239 2240 Similar to :func:`waitpid`, except no process id argument is given and a 2241 3-element tuple containing the child's process id, exit status indication, and 2242 resource usage information is returned. Refer to :mod:`resource`.\ 2243 :func:`~resource.getrusage` for details on resource usage information. The 2244 option argument is the same as that provided to :func:`waitpid` and 2245 :func:`wait4`. 2246 2247 Availability: Unix. 2248 2249 .. versionadded:: 2.5 2250 2251 2252 .. function:: wait4(pid, options) 2253 2254 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's 2255 process id, exit status indication, and resource usage information is returned. 2256 Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on 2257 resource usage information. The arguments to :func:`wait4` are the same as 2258 those provided to :func:`waitpid`. 2259 2260 Availability: Unix. 2261 2262 .. versionadded:: 2.5 2263 2264 2265 .. data:: WNOHANG 2266 2267 The option for :func:`waitpid` to return immediately if no child process status 2268 is available immediately. The function returns ``(0, 0)`` in this case. 2269 2270 Availability: Unix. 2271 2272 2273 .. data:: WCONTINUED 2274 2275 This option causes child processes to be reported if they have been continued 2276 from a job control stop since their status was last reported. 2277 2278 Availability: Some Unix systems. 2279 2280 .. versionadded:: 2.3 2281 2282 2283 .. data:: WUNTRACED 2284 2285 This option causes child processes to be reported if they have been stopped but 2286 their current state has not been reported since they were stopped. 2287 2288 Availability: Unix. 2289 2290 .. versionadded:: 2.3 2291 2292 The following functions take a process status code as returned by 2293 :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be 2294 used to determine the disposition of a process. 2295 2296 2297 .. function:: WCOREDUMP(status) 2298 2299 Return ``True`` if a core dump was generated for the process, otherwise 2300 return ``False``. 2301 2302 Availability: Unix. 2303 2304 .. versionadded:: 2.3 2305 2306 2307 .. function:: WIFCONTINUED(status) 2308 2309 Return ``True`` if the process has been continued from a job control stop, 2310 otherwise return ``False``. 2311 2312 Availability: Unix. 2313 2314 .. versionadded:: 2.3 2315 2316 2317 .. function:: WIFSTOPPED(status) 2318 2319 Return ``True`` if the process has been stopped, otherwise return 2320 ``False``. 2321 2322 Availability: Unix. 2323 2324 2325 .. function:: WIFSIGNALED(status) 2326 2327 Return ``True`` if the process exited due to a signal, otherwise return 2328 ``False``. 2329 2330 Availability: Unix. 2331 2332 2333 .. function:: WIFEXITED(status) 2334 2335 Return ``True`` if the process exited using the :manpage:`exit(2)` system call, 2336 otherwise return ``False``. 2337 2338 Availability: Unix. 2339 2340 2341 .. function:: WEXITSTATUS(status) 2342 2343 If ``WIFEXITED(status)`` is true, return the integer parameter to the 2344 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless. 2345 2346 Availability: Unix. 2347 2348 2349 .. function:: WSTOPSIG(status) 2350 2351 Return the signal which caused the process to stop. 2352 2353 Availability: Unix. 2354 2355 2356 .. function:: WTERMSIG(status) 2357 2358 Return the signal which caused the process to exit. 2359 2360 Availability: Unix. 2361 2362 2363 .. _os-path: 2364 2365 Miscellaneous System Information 2366 -------------------------------- 2367 2368 2369 .. function:: confstr(name) 2370 2371 Return string-valued system configuration values. *name* specifies the 2372 configuration value to retrieve; it may be a string which is the name of a 2373 defined system value; these names are specified in a number of standards (POSIX, 2374 Unix 95, Unix 98, and others). Some platforms define additional names as well. 2375 The names known to the host operating system are given as the keys of the 2376 ``confstr_names`` dictionary. For configuration variables not included in that 2377 mapping, passing an integer for *name* is also accepted. 2378 2379 If the configuration value specified by *name* isn't defined, ``None`` is 2380 returned. 2381 2382 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 2383 specific value for *name* is not supported by the host system, even if it is 2384 included in ``confstr_names``, an :exc:`OSError` is raised with 2385 :const:`errno.EINVAL` for the error number. 2386 2387 Availability: Unix 2388 2389 2390 .. data:: confstr_names 2391 2392 Dictionary mapping names accepted by :func:`confstr` to the integer values 2393 defined for those names by the host operating system. This can be used to 2394 determine the set of names known to the system. 2395 2396 Availability: Unix. 2397 2398 2399 .. function:: getloadavg() 2400 2401 Return the number of processes in the system run queue averaged over the last 2402 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was 2403 unobtainable. 2404 2405 Availability: Unix. 2406 2407 .. versionadded:: 2.3 2408 2409 2410 .. function:: sysconf(name) 2411 2412 Return integer-valued system configuration values. If the configuration value 2413 specified by *name* isn't defined, ``-1`` is returned. The comments regarding 2414 the *name* parameter for :func:`confstr` apply here as well; the dictionary that 2415 provides information on the known names is given by ``sysconf_names``. 2416 2417 Availability: Unix. 2418 2419 2420 .. data:: sysconf_names 2421 2422 Dictionary mapping names accepted by :func:`sysconf` to the integer values 2423 defined for those names by the host operating system. This can be used to 2424 determine the set of names known to the system. 2425 2426 Availability: Unix. 2427 2428 The following data values are used to support path manipulation operations. These 2429 are defined for all platforms. 2430 2431 Higher-level operations on pathnames are defined in the :mod:`os.path` module. 2432 2433 2434 .. data:: curdir 2435 2436 The constant string used by the operating system to refer to the current 2437 directory. This is ``'.'`` for Windows and POSIX. Also available via 2438 :mod:`os.path`. 2439 2440 2441 .. data:: pardir 2442 2443 The constant string used by the operating system to refer to the parent 2444 directory. This is ``'..'`` for Windows and POSIX. Also available via 2445 :mod:`os.path`. 2446 2447 2448 .. data:: sep 2449 2450 The character used by the operating system to separate pathname components. 2451 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this 2452 is not sufficient to be able to parse or concatenate pathnames --- use 2453 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally 2454 useful. Also available via :mod:`os.path`. 2455 2456 2457 .. data:: altsep 2458 2459 An alternative character used by the operating system to separate pathname 2460 components, or ``None`` if only one separator character exists. This is set to 2461 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via 2462 :mod:`os.path`. 2463 2464 2465 .. data:: extsep 2466 2467 The character which separates the base filename from the extension; for example, 2468 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`. 2469 2470 .. versionadded:: 2.2 2471 2472 2473 .. data:: pathsep 2474 2475 The character conventionally used by the operating system to separate search 2476 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for 2477 Windows. Also available via :mod:`os.path`. 2478 2479 2480 .. data:: defpath 2481 2482 The default search path used by :func:`exec\*p\* <execl>` and 2483 :func:`spawn\*p\* <spawnl>` if the environment doesn't have a ``'PATH'`` 2484 key. Also available via :mod:`os.path`. 2485 2486 2487 .. data:: linesep 2488 2489 The string used to separate (or, rather, terminate) lines on the current 2490 platform. This may be a single character, such as ``'\n'`` for POSIX, or 2491 multiple characters, for example, ``'\r\n'`` for Windows. Do not use 2492 *os.linesep* as a line terminator when writing files opened in text mode (the 2493 default); use a single ``'\n'`` instead, on all platforms. 2494 2495 2496 .. data:: devnull 2497 2498 The file path of the null device. For example: ``'/dev/null'`` for 2499 POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. 2500 2501 .. versionadded:: 2.4 2502 2503 2504 .. _os-miscfunc: 2505 2506 Miscellaneous Functions 2507 ----------------------- 2508 2509 2510 .. function:: urandom(n) 2511 2512 Return a string of *n* random bytes suitable for cryptographic use. 2513 2514 This function returns random bytes from an OS-specific randomness source. The 2515 returned data should be unpredictable enough for cryptographic applications, 2516 though its exact quality depends on the OS implementation. On a UNIX-like 2517 system this will query ``/dev/urandom``, and on Windows it will use 2518 ``CryptGenRandom()``. If a randomness source is not found, 2519 :exc:`NotImplementedError` will be raised. 2520 2521 For an easy-to-use interface to the random number generator 2522 provided by your platform, please see :class:`random.SystemRandom`. 2523 2524 .. versionadded:: 2.4 2525
