1:mod:`os` --- Miscellaneous operating system interfaces 2======================================================= 3 4.. module:: os 5 :synopsis: Miscellaneous operating system interfaces. 6 7**Source code:** :source:`Lib/os.py` 8 9-------------- 10 11This module provides a portable way of using operating system dependent 12functionality. If you just want to read or write a file see :func:`open`, if 13you want to manipulate paths, see the :mod:`os.path` module, and if you want to 14read all the lines in all the files on the command line see the :mod:`fileinput` 15module. For creating temporary files and directories see the :mod:`tempfile` 16module, and for high-level file and directory handling see the :mod:`shutil` 17module. 18 19Notes on the availability of these functions: 20 21* The design of all built-in operating system dependent modules of Python is 22 such that as long as the same functionality is available, it uses the same 23 interface; for example, the function ``os.stat(path)`` returns stat 24 information about *path* in the same format (which happens to have originated 25 with the POSIX interface). 26 27* Extensions peculiar to a particular operating system are also available 28 through the :mod:`os` module, but using them is of course a threat to 29 portability. 30 31* All functions accepting path or file names accept both bytes and string 32 objects, and result in an object of the same type, if a path or file name is 33 returned. 34 35* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported. 36 37.. note:: 38 39 All functions in this module raise :exc:`OSError` (or subclasses thereof) in 40 the case of invalid or inaccessible file names and paths, or other arguments 41 that have the correct type, but are not accepted by the operating system. 42 43.. exception:: error 44 45 An alias for the built-in :exc:`OSError` exception. 46 47 48.. data:: name 49 50 The name of the operating system dependent module imported. The following 51 names have currently been registered: ``'posix'``, ``'nt'``, 52 ``'java'``. 53 54 .. seealso:: 55 :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives 56 system-dependent version information. 57 58 The :mod:`platform` module provides detailed checks for the 59 system's identity. 60 61 62.. _os-filenames: 63.. _filesystem-encoding: 64 65File Names, Command Line Arguments, and Environment Variables 66------------------------------------------------------------- 67 68In Python, file names, command line arguments, and environment variables are 69represented using the string type. On some systems, decoding these strings to 70and from bytes is necessary before passing them to the operating system. Python 71uses the file system encoding to perform this conversion (see 72:func:`sys.getfilesystemencoding`). 73 74.. versionchanged:: 3.1 75 On some systems, conversion using the file system encoding may fail. In this 76 case, Python uses the :ref:`surrogateescape encoding error handler 77 <surrogateescape>`, which means that undecodable bytes are replaced by a 78 Unicode character U+DCxx on decoding, and these are again translated to the 79 original byte on encoding. 80 81 82The file system encoding must guarantee to successfully decode all bytes 83below 128. If the file system encoding fails to provide this guarantee, API 84functions may raise UnicodeErrors. 85 86 87.. _os-procinfo: 88 89Process Parameters 90------------------ 91 92These functions and data items provide information and operate on the current 93process and user. 94 95 96.. function:: ctermid() 97 98 Return the filename corresponding to the controlling terminal of the process. 99 100 .. availability:: Unix. 101 102 103.. data:: environ 104 105 A :term:`mapping` object representing the string environment. For example, 106 ``environ['HOME']`` is the pathname of your home directory (on some platforms), 107 and is equivalent to ``getenv("HOME")`` in C. 108 109 This mapping is captured the first time the :mod:`os` module is imported, 110 typically during Python startup as part of processing :file:`site.py`. Changes 111 to the environment made after this time are not reflected in ``os.environ``, 112 except for changes made by modifying ``os.environ`` directly. 113 114 If the platform supports the :func:`putenv` function, this mapping may be used 115 to modify the environment as well as query the environment. :func:`putenv` will 116 be called automatically when the mapping is modified. 117 118 On Unix, keys and values use :func:`sys.getfilesystemencoding` and 119 ``'surrogateescape'`` error handler. Use :data:`environb` if you would like 120 to use a different encoding. 121 122 .. note:: 123 124 Calling :func:`putenv` directly does not change ``os.environ``, so it's better 125 to modify ``os.environ``. 126 127 .. note:: 128 129 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may 130 cause memory leaks. Refer to the system documentation for 131 :c:func:`putenv`. 132 133 If :func:`putenv` is not provided, a modified copy of this mapping may be 134 passed to the appropriate process-creation functions to cause child processes 135 to use a modified environment. 136 137 If the platform supports the :func:`unsetenv` function, you can delete items in 138 this mapping to unset environment variables. :func:`unsetenv` will be called 139 automatically when an item is deleted from ``os.environ``, and when 140 one of the :meth:`pop` or :meth:`clear` methods is called. 141 142 143.. data:: environb 144 145 Bytes version of :data:`environ`: a :term:`mapping` object representing the 146 environment as byte strings. :data:`environ` and :data:`environb` are 147 synchronized (modify :data:`environb` updates :data:`environ`, and vice 148 versa). 149 150 :data:`environb` is only available if :data:`supports_bytes_environ` is 151 ``True``. 152 153 .. versionadded:: 3.2 154 155 156.. function:: chdir(path) 157 fchdir(fd) 158 getcwd() 159 :noindex: 160 161 These functions are described in :ref:`os-file-dir`. 162 163 164.. function:: fsencode(filename) 165 166 Encode :term:`path-like <path-like object>` *filename* to the filesystem 167 encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on 168 Windows; return :class:`bytes` unchanged. 169 170 :func:`fsdecode` is the reverse function. 171 172 .. versionadded:: 3.2 173 174 .. versionchanged:: 3.6 175 Support added to accept objects implementing the :class:`os.PathLike` 176 interface. 177 178 179.. function:: fsdecode(filename) 180 181 Decode the :term:`path-like <path-like object>` *filename* from the 182 filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'`` 183 on Windows; return :class:`str` unchanged. 184 185 :func:`fsencode` is the reverse function. 186 187 .. versionadded:: 3.2 188 189 .. versionchanged:: 3.6 190 Support added to accept objects implementing the :class:`os.PathLike` 191 interface. 192 193 194.. function:: fspath(path) 195 196 Return the file system representation of the path. 197 198 If :class:`str` or :class:`bytes` is passed in, it is returned unchanged. 199 Otherwise :meth:`~os.PathLike.__fspath__` is called and its value is 200 returned as long as it is a :class:`str` or :class:`bytes` object. 201 In all other cases, :exc:`TypeError` is raised. 202 203 .. versionadded:: 3.6 204 205 206.. class:: PathLike 207 208 An :term:`abstract base class` for objects representing a file system path, 209 e.g. :class:`pathlib.PurePath`. 210 211 .. versionadded:: 3.6 212 213 .. abstractmethod:: __fspath__() 214 215 Return the file system path representation of the object. 216 217 The method should only return a :class:`str` or :class:`bytes` object, 218 with the preference being for :class:`str`. 219 220 221.. function:: getenv(key, default=None) 222 223 Return the value of the environment variable *key* if it exists, or 224 *default* if it doesn't. *key*, *default* and the result are str. 225 226 On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding` 227 and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you 228 would like to use a different encoding. 229 230 .. availability:: most flavors of Unix, Windows. 231 232 233.. function:: getenvb(key, default=None) 234 235 Return the value of the environment variable *key* if it exists, or 236 *default* if it doesn't. *key*, *default* and the result are bytes. 237 238 :func:`getenvb` is only available if :data:`supports_bytes_environ` 239 is ``True``. 240 241 .. availability:: most flavors of Unix. 242 243 .. versionadded:: 3.2 244 245 246.. function:: get_exec_path(env=None) 247 248 Returns the list of directories that will be searched for a named 249 executable, similar to a shell, when launching a process. 250 *env*, when specified, should be an environment variable dictionary 251 to lookup the PATH in. 252 By default, when *env* is ``None``, :data:`environ` is used. 253 254 .. versionadded:: 3.2 255 256 257.. function:: getegid() 258 259 Return the effective group id of the current process. This corresponds to the 260 "set id" bit on the file being executed in the current process. 261 262 .. availability:: Unix. 263 264 265.. function:: geteuid() 266 267 .. index:: single: user; effective id 268 269 Return the current process's effective user id. 270 271 .. availability:: Unix. 272 273 274.. function:: getgid() 275 276 .. index:: single: process; group 277 278 Return the real group id of the current process. 279 280 .. availability:: Unix. 281 282 283.. function:: getgrouplist(user, group) 284 285 Return list of group ids that *user* belongs to. If *group* is not in the 286 list, it is included; typically, *group* is specified as the group ID 287 field from the password record for *user*. 288 289 .. availability:: Unix. 290 291 .. versionadded:: 3.3 292 293 294.. function:: getgroups() 295 296 Return list of supplemental group ids associated with the current process. 297 298 .. availability:: Unix. 299 300 .. note:: 301 302 On Mac OS X, :func:`getgroups` behavior differs somewhat from 303 other Unix platforms. If the Python interpreter was built with a 304 deployment target of :const:`10.5` or earlier, :func:`getgroups` returns 305 the list of effective group ids associated with the current user process; 306 this list is limited to a system-defined number of entries, typically 16, 307 and may be modified by calls to :func:`setgroups` if suitably privileged. 308 If built with a deployment target greater than :const:`10.5`, 309 :func:`getgroups` returns the current group access list for the user 310 associated with the effective user id of the process; the group access 311 list may change over the lifetime of the process, it is not affected by 312 calls to :func:`setgroups`, and its length is not limited to 16. The 313 deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be 314 obtained with :func:`sysconfig.get_config_var`. 315 316 317.. function:: getlogin() 318 319 Return the name of the user logged in on the controlling terminal of the 320 process. For most purposes, it is more useful to use 321 :func:`getpass.getuser` since the latter checks the environment variables 322 :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, and 323 falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the 324 current real user id. 325 326 .. availability:: Unix, Windows. 327 328 329.. function:: getpgid(pid) 330 331 Return the process group id of the process with process id *pid*. If *pid* is 0, 332 the process group id of the current process is returned. 333 334 .. availability:: Unix. 335 336.. function:: getpgrp() 337 338 .. index:: single: process; group 339 340 Return the id of the current process group. 341 342 .. availability:: Unix. 343 344 345.. function:: getpid() 346 347 .. index:: single: process; id 348 349 Return the current process id. 350 351 352.. function:: getppid() 353 354 .. index:: single: process; id of parent 355 356 Return the parent's process id. When the parent process has exited, on Unix 357 the id returned is the one of the init process (1), on Windows it is still 358 the same id, which may be already reused by another process. 359 360 .. availability:: Unix, Windows. 361 362 .. versionchanged:: 3.2 363 Added support for Windows. 364 365 366.. function:: getpriority(which, who) 367 368 .. index:: single: process; scheduling priority 369 370 Get program scheduling priority. The value *which* is one of 371 :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* 372 is interpreted relative to *which* (a process identifier for 373 :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a 374 user ID for :const:`PRIO_USER`). A zero value for *who* denotes 375 (respectively) the calling process, the process group of the calling process, 376 or the real user ID of the calling process. 377 378 .. availability:: Unix. 379 380 .. versionadded:: 3.3 381 382 383.. data:: PRIO_PROCESS 384 PRIO_PGRP 385 PRIO_USER 386 387 Parameters for the :func:`getpriority` and :func:`setpriority` functions. 388 389 .. availability:: Unix. 390 391 .. versionadded:: 3.3 392 393 394.. function:: getresuid() 395 396 Return a tuple (ruid, euid, suid) denoting the current process's 397 real, effective, and saved user ids. 398 399 .. availability:: Unix. 400 401 .. versionadded:: 3.2 402 403 404.. function:: getresgid() 405 406 Return a tuple (rgid, egid, sgid) denoting the current process's 407 real, effective, and saved group ids. 408 409 .. availability:: Unix. 410 411 .. versionadded:: 3.2 412 413 414.. function:: getuid() 415 416 .. index:: single: user; id 417 418 Return the current process's real user id. 419 420 .. availability:: Unix. 421 422 423.. function:: initgroups(username, gid) 424 425 Call the system initgroups() to initialize the group access list with all of 426 the groups of which the specified username is a member, plus the specified 427 group id. 428 429 .. availability:: Unix. 430 431 .. versionadded:: 3.2 432 433 434.. function:: putenv(key, value) 435 436 .. index:: single: environment variables; setting 437 438 Set the environment variable named *key* to the string *value*. Such 439 changes to the environment affect subprocesses started with :func:`os.system`, 440 :func:`popen` or :func:`fork` and :func:`execv`. 441 442 .. availability:: most flavors of Unix, Windows. 443 444 .. note:: 445 446 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may 447 cause memory leaks. Refer to the system documentation for putenv. 448 449 When :func:`putenv` is supported, assignments to items in ``os.environ`` are 450 automatically translated into corresponding calls to :func:`putenv`; however, 451 calls to :func:`putenv` don't update ``os.environ``, so it is actually 452 preferable to assign to items of ``os.environ``. 453 454 .. audit-event:: os.putenv key,value os.putenv 455 456 457.. function:: setegid(egid) 458 459 Set the current process's effective group id. 460 461 .. availability:: Unix. 462 463 464.. function:: seteuid(euid) 465 466 Set the current process's effective user id. 467 468 .. availability:: Unix. 469 470 471.. function:: setgid(gid) 472 473 Set the current process' group id. 474 475 .. availability:: Unix. 476 477 478.. function:: setgroups(groups) 479 480 Set the list of supplemental group ids associated with the current process to 481 *groups*. *groups* must be a sequence, and each element must be an integer 482 identifying a group. This operation is typically available only to the superuser. 483 484 .. availability:: Unix. 485 486 .. note:: On Mac OS X, the length of *groups* may not exceed the 487 system-defined maximum number of effective group ids, typically 16. 488 See the documentation for :func:`getgroups` for cases where it may not 489 return the same group list set by calling setgroups(). 490 491.. function:: setpgrp() 492 493 Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on 494 which version is implemented (if any). See the Unix manual for the semantics. 495 496 .. availability:: Unix. 497 498 499.. function:: setpgid(pid, pgrp) 500 501 Call the system call :c:func:`setpgid` to set the process group id of the 502 process with id *pid* to the process group with id *pgrp*. See the Unix manual 503 for the semantics. 504 505 .. availability:: Unix. 506 507 508.. function:: setpriority(which, who, priority) 509 510 .. index:: single: process; scheduling priority 511 512 Set program scheduling priority. The value *which* is one of 513 :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* 514 is interpreted relative to *which* (a process identifier for 515 :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a 516 user ID for :const:`PRIO_USER`). A zero value for *who* denotes 517 (respectively) the calling process, the process group of the calling process, 518 or the real user ID of the calling process. 519 *priority* is a value in the range -20 to 19. The default priority is 0; 520 lower priorities cause more favorable scheduling. 521 522 .. availability:: Unix. 523 524 .. versionadded:: 3.3 525 526 527.. function:: setregid(rgid, egid) 528 529 Set the current process's real and effective group ids. 530 531 .. availability:: Unix. 532 533 534.. function:: setresgid(rgid, egid, sgid) 535 536 Set the current process's real, effective, and saved group ids. 537 538 .. availability:: Unix. 539 540 .. versionadded:: 3.2 541 542 543.. function:: setresuid(ruid, euid, suid) 544 545 Set the current process's real, effective, and saved user ids. 546 547 .. availability:: Unix. 548 549 .. versionadded:: 3.2 550 551 552.. function:: setreuid(ruid, euid) 553 554 Set the current process's real and effective user ids. 555 556 .. availability:: Unix. 557 558 559.. function:: getsid(pid) 560 561 Call the system call :c:func:`getsid`. See the Unix manual for the semantics. 562 563 .. availability:: Unix. 564 565 566.. function:: setsid() 567 568 Call the system call :c:func:`setsid`. See the Unix manual for the semantics. 569 570 .. availability:: Unix. 571 572 573.. function:: setuid(uid) 574 575 .. index:: single: user; id, setting 576 577 Set the current process's user id. 578 579 .. availability:: Unix. 580 581 582.. placed in this section since it relates to errno.... a little weak 583.. function:: strerror(code) 584 585 Return the error message corresponding to the error code in *code*. 586 On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown 587 error number, :exc:`ValueError` is raised. 588 589 590.. data:: supports_bytes_environ 591 592 ``True`` if the native OS type of the environment is bytes (eg. ``False`` on 593 Windows). 594 595 .. versionadded:: 3.2 596 597 598.. function:: umask(mask) 599 600 Set the current numeric umask and return the previous umask. 601 602 603.. function:: uname() 604 605 .. index:: 606 single: gethostname() (in module socket) 607 single: gethostbyaddr() (in module socket) 608 609 Returns information identifying the current operating system. 610 The return value is an object with five attributes: 611 612 * :attr:`sysname` - operating system name 613 * :attr:`nodename` - name of machine on network (implementation-defined) 614 * :attr:`release` - operating system release 615 * :attr:`version` - operating system version 616 * :attr:`machine` - hardware identifier 617 618 For backwards compatibility, this object is also iterable, behaving 619 like a five-tuple containing :attr:`sysname`, :attr:`nodename`, 620 :attr:`release`, :attr:`version`, and :attr:`machine` 621 in that order. 622 623 Some systems truncate :attr:`nodename` to 8 characters or to the 624 leading component; a better way to get the hostname is 625 :func:`socket.gethostname` or even 626 ``socket.gethostbyaddr(socket.gethostname())``. 627 628 .. availability:: recent flavors of Unix. 629 630 .. versionchanged:: 3.3 631 Return type changed from a tuple to a tuple-like object 632 with named attributes. 633 634 635.. function:: unsetenv(key) 636 637 .. index:: single: environment variables; deleting 638 639 Unset (delete) the environment variable named *key*. Such changes to the 640 environment affect subprocesses started with :func:`os.system`, :func:`popen` or 641 :func:`fork` and :func:`execv`. 642 643 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is 644 automatically translated into a corresponding call to :func:`unsetenv`; however, 645 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually 646 preferable to delete items of ``os.environ``. 647 648 .. audit-event:: os.unsetenv key os.unsetenv 649 650 .. availability:: most flavors of Unix. 651 652 653.. _os-newstreams: 654 655File Object Creation 656-------------------- 657 658These functions create new :term:`file objects <file object>`. (See also 659:func:`~os.open` for opening file descriptors.) 660 661 662.. function:: fdopen(fd, *args, **kwargs) 663 664 Return an open file object connected to the file descriptor *fd*. This is an 665 alias of the :func:`open` built-in function and accepts the same arguments. 666 The only difference is that the first argument of :func:`fdopen` must always 667 be an integer. 668 669 670.. _os-fd-ops: 671 672File Descriptor Operations 673-------------------------- 674 675These functions operate on I/O streams referenced using file descriptors. 676 677File descriptors are small integers corresponding to a file that has been opened 678by the current process. For example, standard input is usually file descriptor 6790, standard output is 1, and standard error is 2. Further files opened by a 680process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" 681is slightly deceptive; on Unix platforms, sockets and pipes are also referenced 682by file descriptors. 683 684The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor 685associated with a :term:`file object` when required. Note that using the file 686descriptor directly will bypass the file object methods, ignoring aspects such 687as internal buffering of data. 688 689 690.. function:: close(fd) 691 692 Close file descriptor *fd*. 693 694 .. note:: 695 696 This function is intended for low-level I/O and must be applied to a file 697 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file 698 object" returned by the built-in function :func:`open` or by :func:`popen` or 699 :func:`fdopen`, use its :meth:`~io.IOBase.close` method. 700 701 702.. function:: closerange(fd_low, fd_high) 703 704 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), 705 ignoring errors. Equivalent to (but much faster than):: 706 707 for fd in range(fd_low, fd_high): 708 try: 709 os.close(fd) 710 except OSError: 711 pass 712 713 714.. function:: copy_file_range(src, dst, count, offset_src=None, offset_dst=None) 715 716 Copy *count* bytes from file descriptor *src*, starting from offset 717 *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*. 718 If *offset_src* is None, then *src* is read from the current position; 719 respectively for *offset_dst*. The files pointed by *src* and *dst* 720 must reside in the same filesystem, otherwise an :exc:`OSError` is 721 raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`. 722 723 This copy is done without the additional cost of transferring data 724 from the kernel to user space and then back into the kernel. Additionally, 725 some filesystems could implement extra optimizations. The copy is done as if 726 both files are opened as binary. 727 728 The return value is the amount of bytes copied. This could be less than the 729 amount requested. 730 731 .. availability:: Linux kernel >= 4.5 or glibc >= 2.27. 732 733 .. versionadded:: 3.8 734 735 736.. function:: device_encoding(fd) 737 738 Return a string describing the encoding of the device associated with *fd* 739 if it is connected to a terminal; else return :const:`None`. 740 741 742.. function:: dup(fd) 743 744 Return a duplicate of file descriptor *fd*. The new file descriptor is 745 :ref:`non-inheritable <fd_inheritance>`. 746 747 On Windows, when duplicating a standard stream (0: stdin, 1: stdout, 748 2: stderr), the new file descriptor is :ref:`inheritable 749 <fd_inheritance>`. 750 751 .. versionchanged:: 3.4 752 The new file descriptor is now non-inheritable. 753 754 755.. function:: dup2(fd, fd2, inheritable=True) 756 757 Duplicate file descriptor *fd* to *fd2*, closing the latter first if 758 necessary. Return *fd2*. The new file descriptor is :ref:`inheritable 759 <fd_inheritance>` by default or non-inheritable if *inheritable* 760 is ``False``. 761 762 .. versionchanged:: 3.4 763 Add the optional *inheritable* parameter. 764 765 .. versionchanged:: 3.7 766 Return *fd2* on success. Previously, ``None`` was always returned. 767 768 769.. function:: fchmod(fd, mode) 770 771 Change the mode of the file given by *fd* to the numeric *mode*. See the 772 docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this 773 is equivalent to ``os.chmod(fd, mode)``. 774 775 .. audit-event:: os.chmod path,mode,dir_fd os.fchmod 776 777 .. availability:: Unix. 778 779 780.. function:: fchown(fd, uid, gid) 781 782 Change the owner and group id of the file given by *fd* to the numeric *uid* 783 and *gid*. To leave one of the ids unchanged, set it to -1. See 784 :func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid, 785 gid)``. 786 787 .. audit-event:: os.chown path,uid,gid,dir_fd os.fchown 788 789 .. availability:: Unix. 790 791 792.. function:: fdatasync(fd) 793 794 Force write of file with filedescriptor *fd* to disk. Does not force update of 795 metadata. 796 797 .. availability:: Unix. 798 799 .. note:: 800 This function is not available on MacOS. 801 802 803.. function:: fpathconf(fd, name) 804 805 Return system configuration information relevant to an open file. *name* 806 specifies the configuration value to retrieve; it may be a string which is the 807 name of a defined system value; these names are specified in a number of 808 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define 809 additional names as well. The names known to the host operating system are 810 given in the ``pathconf_names`` dictionary. For configuration variables not 811 included in that mapping, passing an integer for *name* is also accepted. 812 813 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 814 specific value for *name* is not supported by the host system, even if it is 815 included in ``pathconf_names``, an :exc:`OSError` is raised with 816 :const:`errno.EINVAL` for the error number. 817 818 As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``. 819 820 .. availability:: Unix. 821 822 823.. function:: fstat(fd) 824 825 Get the status of the file descriptor *fd*. Return a :class:`stat_result` 826 object. 827 828 As of Python 3.3, this is equivalent to ``os.stat(fd)``. 829 830 .. seealso:: 831 832 The :func:`.stat` function. 833 834 835.. function:: fstatvfs(fd) 836 837 Return information about the filesystem containing the file associated with 838 file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is 839 equivalent to ``os.statvfs(fd)``. 840 841 .. availability:: Unix. 842 843 844.. function:: fsync(fd) 845 846 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the 847 native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function. 848 849 If you're starting with a buffered Python :term:`file object` *f*, first do 850 ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal 851 buffers associated with *f* are written to disk. 852 853 .. availability:: Unix, Windows. 854 855 856.. function:: ftruncate(fd, length) 857 858 Truncate the file corresponding to file descriptor *fd*, so that it is at 859 most *length* bytes in size. As of Python 3.3, this is equivalent to 860 ``os.truncate(fd, length)``. 861 862 .. audit-event:: os.truncate fd,length os.ftruncate 863 864 .. availability:: Unix, Windows. 865 866 .. versionchanged:: 3.5 867 Added support for Windows 868 869 870.. function:: get_blocking(fd) 871 872 Get the blocking mode of the file descriptor: ``False`` if the 873 :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared. 874 875 See also :func:`set_blocking` and :meth:`socket.socket.setblocking`. 876 877 .. availability:: Unix. 878 879 .. versionadded:: 3.5 880 881 882.. function:: isatty(fd) 883 884 Return ``True`` if the file descriptor *fd* is open and connected to a 885 tty(-like) device, else ``False``. 886 887 888.. function:: lockf(fd, cmd, len) 889 890 Apply, test or remove a POSIX lock on an open file descriptor. 891 *fd* is an open file descriptor. 892 *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`, 893 :data:`F_ULOCK` or :data:`F_TEST`. 894 *len* specifies the section of the file to lock. 895 896 .. audit-event:: os.lockf fd,cmd,len os.lockf 897 898 .. availability:: Unix. 899 900 .. versionadded:: 3.3 901 902 903.. data:: F_LOCK 904 F_TLOCK 905 F_ULOCK 906 F_TEST 907 908 Flags that specify what action :func:`lockf` will take. 909 910 .. availability:: Unix. 911 912 .. versionadded:: 3.3 913 914 915.. function:: lseek(fd, pos, how) 916 917 Set the current position of file descriptor *fd* to position *pos*, modified 918 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the 919 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the 920 current position; :const:`SEEK_END` or ``2`` to set it relative to the end of 921 the file. Return the new cursor position in bytes, starting from the beginning. 922 923 924.. data:: SEEK_SET 925 SEEK_CUR 926 SEEK_END 927 928 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, 929 respectively. 930 931 .. versionadded:: 3.3 932 Some operating systems could support additional values, like 933 :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`. 934 935 936.. function:: open(path, flags, mode=0o777, *, dir_fd=None) 937 938 Open the file *path* and set various flags according to *flags* and possibly 939 its mode according to *mode*. When computing *mode*, the current umask value 940 is first masked out. Return the file descriptor for the newly opened file. 941 The new file descriptor is :ref:`non-inheritable <fd_inheritance>`. 942 943 For a description of the flag and mode values, see the C run-time documentation; 944 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in 945 the :mod:`os` module. In particular, on Windows adding 946 :const:`O_BINARY` is needed to open files in binary mode. 947 948 This function can support :ref:`paths relative to directory descriptors 949 <dir_fd>` with the *dir_fd* parameter. 950 951 .. audit-event:: open path,mode,flags os.open 952 953 .. versionchanged:: 3.4 954 The new file descriptor is now non-inheritable. 955 956 .. note:: 957 958 This function is intended for low-level I/O. For normal usage, use the 959 built-in function :func:`open`, which returns a :term:`file object` with 960 :meth:`~file.read` and :meth:`~file.write` methods (and many more). To 961 wrap a file descriptor in a file object, use :func:`fdopen`. 962 963 .. versionadded:: 3.3 964 The *dir_fd* argument. 965 966 .. versionchanged:: 3.5 967 If the system call is interrupted and the signal handler does not raise an 968 exception, the function now retries the system call instead of raising an 969 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 970 971 .. versionchanged:: 3.6 972 Accepts a :term:`path-like object`. 973 974The following constants are options for the *flags* parameter to the 975:func:`~os.open` function. They can be combined using the bitwise OR operator 976``|``. Some of them are not available on all platforms. For descriptions of 977their availability and use, consult the :manpage:`open(2)` manual page on Unix 978or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. 979 980 981.. data:: O_RDONLY 982 O_WRONLY 983 O_RDWR 984 O_APPEND 985 O_CREAT 986 O_EXCL 987 O_TRUNC 988 989 The above constants are available on Unix and Windows. 990 991 992.. data:: O_DSYNC 993 O_RSYNC 994 O_SYNC 995 O_NDELAY 996 O_NONBLOCK 997 O_NOCTTY 998 O_CLOEXEC 999 1000 The above constants are only available on Unix. 1001 1002 .. versionchanged:: 3.3 1003 Add :data:`O_CLOEXEC` constant. 1004 1005.. data:: O_BINARY 1006 O_NOINHERIT 1007 O_SHORT_LIVED 1008 O_TEMPORARY 1009 O_RANDOM 1010 O_SEQUENTIAL 1011 O_TEXT 1012 1013 The above constants are only available on Windows. 1014 1015 1016.. data:: O_ASYNC 1017 O_DIRECT 1018 O_DIRECTORY 1019 O_NOFOLLOW 1020 O_NOATIME 1021 O_PATH 1022 O_TMPFILE 1023 O_SHLOCK 1024 O_EXLOCK 1025 1026 The above constants are extensions and not present if they are not defined by 1027 the C library. 1028 1029 .. versionchanged:: 3.4 1030 Add :data:`O_PATH` on systems that support it. 1031 Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11 1032 or newer. 1033 1034 1035.. function:: openpty() 1036 1037 .. index:: module: pty 1038 1039 Open a new pseudo-terminal pair. Return a pair of file descriptors 1040 ``(master, slave)`` for the pty and the tty, respectively. The new file 1041 descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more 1042 portable approach, use the :mod:`pty` module. 1043 1044 .. availability:: some flavors of Unix. 1045 1046 .. versionchanged:: 3.4 1047 The new file descriptors are now non-inheritable. 1048 1049 1050.. function:: pipe() 1051 1052 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for 1053 reading and writing, respectively. The new file descriptor is 1054 :ref:`non-inheritable <fd_inheritance>`. 1055 1056 .. availability:: Unix, Windows. 1057 1058 .. versionchanged:: 3.4 1059 The new file descriptors are now non-inheritable. 1060 1061 1062.. function:: pipe2(flags) 1063 1064 Create a pipe with *flags* set atomically. 1065 *flags* can be constructed by ORing together one or more of these values: 1066 :data:`O_NONBLOCK`, :data:`O_CLOEXEC`. 1067 Return a pair of file descriptors ``(r, w)`` usable for reading and writing, 1068 respectively. 1069 1070 .. availability:: some flavors of Unix. 1071 1072 .. versionadded:: 3.3 1073 1074 1075.. function:: posix_fallocate(fd, offset, len) 1076 1077 Ensures that enough disk space is allocated for the file specified by *fd* 1078 starting from *offset* and continuing for *len* bytes. 1079 1080 .. availability:: Unix. 1081 1082 .. versionadded:: 3.3 1083 1084 1085.. function:: posix_fadvise(fd, offset, len, advice) 1086 1087 Announces an intention to access data in a specific pattern thus allowing 1088 the kernel to make optimizations. 1089 The advice applies to the region of the file specified by *fd* starting at 1090 *offset* and continuing for *len* bytes. 1091 *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`, 1092 :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`, 1093 :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`. 1094 1095 .. availability:: Unix. 1096 1097 .. versionadded:: 3.3 1098 1099 1100.. data:: POSIX_FADV_NORMAL 1101 POSIX_FADV_SEQUENTIAL 1102 POSIX_FADV_RANDOM 1103 POSIX_FADV_NOREUSE 1104 POSIX_FADV_WILLNEED 1105 POSIX_FADV_DONTNEED 1106 1107 Flags that can be used in *advice* in :func:`posix_fadvise` that specify 1108 the access pattern that is likely to be used. 1109 1110 .. availability:: Unix. 1111 1112 .. versionadded:: 3.3 1113 1114 1115.. function:: pread(fd, n, offset) 1116 1117 Read at most *n* bytes from file descriptor *fd* at a position of *offset*, 1118 leaving the file offset unchanged. 1119 1120 Return a bytestring containing the bytes read. If the end of the file 1121 referred to by *fd* has been reached, an empty bytes object is returned. 1122 1123 .. availability:: Unix. 1124 1125 .. versionadded:: 3.3 1126 1127 1128.. function:: preadv(fd, buffers, offset, flags=0) 1129 1130 Read from a file descriptor *fd* at a position of *offset* into mutable 1131 :term:`bytes-like objects <bytes-like object>` *buffers*, leaving the file 1132 offset unchanged. Transfer data into each buffer until it is full and then 1133 move on to the next buffer in the sequence to hold the rest of the data. 1134 1135 The flags argument contains a bitwise OR of zero or more of the following 1136 flags: 1137 1138 - :data:`RWF_HIPRI` 1139 - :data:`RWF_NOWAIT` 1140 1141 Return the total number of bytes actually read which can be less than the 1142 total capacity of all the objects. 1143 1144 The operating system may set a limit (:func:`sysconf` value 1145 ``'SC_IOV_MAX'``) on the number of buffers that can be used. 1146 1147 Combine the functionality of :func:`os.readv` and :func:`os.pread`. 1148 1149 .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, 1150 OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer. 1151 1152 .. versionadded:: 3.7 1153 1154 1155.. data:: RWF_NOWAIT 1156 1157 Do not wait for data which is not immediately available. If this flag is 1158 specified, the system call will return instantly if it would have to read 1159 data from the backing storage or wait for a lock. 1160 1161 If some data was successfully read, it will return the number of bytes read. 1162 If no bytes were read, it will return ``-1`` and set errno to 1163 :data:`errno.EAGAIN`. 1164 1165 .. availability:: Linux 4.14 and newer. 1166 1167 .. versionadded:: 3.7 1168 1169 1170.. data:: RWF_HIPRI 1171 1172 High priority read/write. Allows block-based filesystems to use polling 1173 of the device, which provides lower latency, but may use additional 1174 resources. 1175 1176 Currently, on Linux, this feature is usable only on a file descriptor opened 1177 using the :data:`O_DIRECT` flag. 1178 1179 .. availability:: Linux 4.6 and newer. 1180 1181 .. versionadded:: 3.7 1182 1183 1184.. function:: pwrite(fd, str, offset) 1185 1186 Write the bytestring in *str* to file descriptor *fd* at position of 1187 *offset*, leaving the file offset unchanged. 1188 1189 Return the number of bytes actually written. 1190 1191 .. availability:: Unix. 1192 1193 .. versionadded:: 3.3 1194 1195 1196.. function:: pwritev(fd, buffers, offset, flags=0) 1197 1198 Write the *buffers* contents to file descriptor *fd* at a offset *offset*, 1199 leaving the file offset unchanged. *buffers* must be a sequence of 1200 :term:`bytes-like objects <bytes-like object>`. Buffers are processed in 1201 array order. Entire contents of the first buffer is written before 1202 proceeding to the second, and so on. 1203 1204 The flags argument contains a bitwise OR of zero or more of the following 1205 flags: 1206 1207 - :data:`RWF_DSYNC` 1208 - :data:`RWF_SYNC` 1209 1210 Return the total number of bytes actually written. 1211 1212 The operating system may set a limit (:func:`sysconf` value 1213 ``'SC_IOV_MAX'``) on the number of buffers that can be used. 1214 1215 Combine the functionality of :func:`os.writev` and :func:`os.pwrite`. 1216 1217 .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, 1218 OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer. 1219 1220 .. versionadded:: 3.7 1221 1222 1223.. data:: RWF_DSYNC 1224 1225 Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This 1226 flag effect applies only to the data range written by the system call. 1227 1228 .. availability:: Linux 4.7 and newer. 1229 1230 .. versionadded:: 3.7 1231 1232 1233.. data:: RWF_SYNC 1234 1235 Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This 1236 flag effect applies only to the data range written by the system call. 1237 1238 .. availability:: Linux 4.7 and newer. 1239 1240 .. versionadded:: 3.7 1241 1242 1243.. function:: read(fd, n) 1244 1245 Read at most *n* bytes from file descriptor *fd*. 1246 1247 Return a bytestring containing the bytes read. If the end of the file 1248 referred to by *fd* has been reached, an empty bytes object is returned. 1249 1250 .. note:: 1251 1252 This function is intended for low-level I/O and must be applied to a file 1253 descriptor as returned by :func:`os.open` or :func:`pipe`. To read a 1254 "file object" returned by the built-in function :func:`open` or by 1255 :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its 1256 :meth:`~file.read` or :meth:`~file.readline` methods. 1257 1258 .. versionchanged:: 3.5 1259 If the system call is interrupted and the signal handler does not raise an 1260 exception, the function now retries the system call instead of raising an 1261 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1262 1263 1264.. function:: sendfile(out, in, offset, count) 1265 sendfile(out, in, offset, count, [headers], [trailers], flags=0) 1266 1267 Copy *count* bytes from file descriptor *in* to file descriptor *out* 1268 starting at *offset*. 1269 Return the number of bytes sent. When EOF is reached return 0. 1270 1271 The first function notation is supported by all platforms that define 1272 :func:`sendfile`. 1273 1274 On Linux, if *offset* is given as ``None``, the bytes are read from the 1275 current position of *in* and the position of *in* is updated. 1276 1277 The second case may be used on Mac OS X and FreeBSD where *headers* and 1278 *trailers* are arbitrary sequences of buffers that are written before and 1279 after the data from *in* is written. It returns the same as the first case. 1280 1281 On Mac OS X and FreeBSD, a value of 0 for *count* specifies to send until 1282 the end of *in* is reached. 1283 1284 All platforms support sockets as *out* file descriptor, and some platforms 1285 allow other types (e.g. regular file, pipe) as well. 1286 1287 Cross-platform applications should not use *headers*, *trailers* and *flags* 1288 arguments. 1289 1290 .. availability:: Unix. 1291 1292 .. note:: 1293 1294 For a higher-level wrapper of :func:`sendfile`, see 1295 :meth:`socket.socket.sendfile`. 1296 1297 .. versionadded:: 3.3 1298 1299 1300.. function:: set_blocking(fd, blocking) 1301 1302 Set the blocking mode of the specified file descriptor. Set the 1303 :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise. 1304 1305 See also :func:`get_blocking` and :meth:`socket.socket.setblocking`. 1306 1307 .. availability:: Unix. 1308 1309 .. versionadded:: 3.5 1310 1311 1312.. data:: SF_NODISKIO 1313 SF_MNOWAIT 1314 SF_SYNC 1315 1316 Parameters to the :func:`sendfile` function, if the implementation supports 1317 them. 1318 1319 .. availability:: Unix. 1320 1321 .. versionadded:: 3.3 1322 1323 1324.. function:: readv(fd, buffers) 1325 1326 Read from a file descriptor *fd* into a number of mutable :term:`bytes-like 1327 objects <bytes-like object>` *buffers*. Transfer data into each buffer until 1328 it is full and then move on to the next buffer in the sequence to hold the 1329 rest of the data. 1330 1331 Return the total number of bytes actually read which can be less than the 1332 total capacity of all the objects. 1333 1334 The operating system may set a limit (:func:`sysconf` value 1335 ``'SC_IOV_MAX'``) on the number of buffers that can be used. 1336 1337 .. availability:: Unix. 1338 1339 .. versionadded:: 3.3 1340 1341 1342.. function:: tcgetpgrp(fd) 1343 1344 Return the process group associated with the terminal given by *fd* (an open 1345 file descriptor as returned by :func:`os.open`). 1346 1347 .. availability:: Unix. 1348 1349 1350.. function:: tcsetpgrp(fd, pg) 1351 1352 Set the process group associated with the terminal given by *fd* (an open file 1353 descriptor as returned by :func:`os.open`) to *pg*. 1354 1355 .. availability:: Unix. 1356 1357 1358.. function:: ttyname(fd) 1359 1360 Return a string which specifies the terminal device associated with 1361 file descriptor *fd*. If *fd* is not associated with a terminal device, an 1362 exception is raised. 1363 1364 .. availability:: Unix. 1365 1366 1367.. function:: write(fd, str) 1368 1369 Write the bytestring in *str* to file descriptor *fd*. 1370 1371 Return the number of bytes actually written. 1372 1373 .. note:: 1374 1375 This function is intended for low-level I/O and must be applied to a file 1376 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file 1377 object" returned by the built-in function :func:`open` or by :func:`popen` or 1378 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its 1379 :meth:`~file.write` method. 1380 1381 .. versionchanged:: 3.5 1382 If the system call is interrupted and the signal handler does not raise an 1383 exception, the function now retries the system call instead of raising an 1384 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1385 1386 1387.. function:: writev(fd, buffers) 1388 1389 Write the contents of *buffers* to file descriptor *fd*. *buffers* must be 1390 a sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are 1391 processed in array order. Entire contents of the first buffer is written 1392 before proceeding to the second, and so on. 1393 1394 Returns the total number of bytes actually written. 1395 1396 The operating system may set a limit (:func:`sysconf` value 1397 ``'SC_IOV_MAX'``) on the number of buffers that can be used. 1398 1399 .. availability:: Unix. 1400 1401 .. versionadded:: 3.3 1402 1403 1404.. _terminal-size: 1405 1406Querying the size of a terminal 1407~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1408 1409.. versionadded:: 3.3 1410 1411.. function:: get_terminal_size(fd=STDOUT_FILENO) 1412 1413 Return the size of the terminal window as ``(columns, lines)``, 1414 tuple of type :class:`terminal_size`. 1415 1416 The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard 1417 output) specifies which file descriptor should be queried. 1418 1419 If the file descriptor is not connected to a terminal, an :exc:`OSError` 1420 is raised. 1421 1422 :func:`shutil.get_terminal_size` is the high-level function which 1423 should normally be used, ``os.get_terminal_size`` is the low-level 1424 implementation. 1425 1426 .. availability:: Unix, Windows. 1427 1428.. class:: terminal_size 1429 1430 A subclass of tuple, holding ``(columns, lines)`` of the terminal window size. 1431 1432 .. attribute:: columns 1433 1434 Width of the terminal window in characters. 1435 1436 .. attribute:: lines 1437 1438 Height of the terminal window in characters. 1439 1440 1441.. _fd_inheritance: 1442 1443Inheritance of File Descriptors 1444~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1445 1446.. versionadded:: 3.4 1447 1448A file descriptor has an "inheritable" flag which indicates if the file descriptor 1449can be inherited by child processes. Since Python 3.4, file descriptors 1450created by Python are non-inheritable by default. 1451 1452On UNIX, non-inheritable file descriptors are closed in child processes at the 1453execution of a new program, other file descriptors are inherited. 1454 1455On Windows, non-inheritable handles and file descriptors are closed in child 1456processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout 1457and stderr), which are always inherited. Using :func:`spawn\* <spawnl>` functions, 1458all inheritable handles and all inheritable file descriptors are inherited. 1459Using the :mod:`subprocess` module, all file descriptors except standard 1460streams are closed, and inheritable handles are only inherited if the 1461*close_fds* parameter is ``False``. 1462 1463.. function:: get_inheritable(fd) 1464 1465 Get the "inheritable" flag of the specified file descriptor (a boolean). 1466 1467.. function:: set_inheritable(fd, inheritable) 1468 1469 Set the "inheritable" flag of the specified file descriptor. 1470 1471.. function:: get_handle_inheritable(handle) 1472 1473 Get the "inheritable" flag of the specified handle (a boolean). 1474 1475 .. availability:: Windows. 1476 1477.. function:: set_handle_inheritable(handle, inheritable) 1478 1479 Set the "inheritable" flag of the specified handle. 1480 1481 .. availability:: Windows. 1482 1483 1484.. _os-file-dir: 1485 1486Files and Directories 1487--------------------- 1488 1489On some Unix platforms, many of these functions support one or more of these 1490features: 1491 1492.. _path_fd: 1493 1494* **specifying a file descriptor:** 1495 Normally the *path* argument provided to functions in the :mod:`os` module 1496 must be a string specifying a file path. However, some functions now 1497 alternatively accept an open file descriptor for their *path* argument. 1498 The function will then operate on the file referred to by the descriptor. 1499 (For POSIX systems, Python will call the variant of the function prefixed 1500 with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).) 1501 1502 You can check whether or not *path* can be specified as a file descriptor 1503 for a particular function on your platform using :data:`os.supports_fd`. 1504 If this functionality is unavailable, using it will raise a 1505 :exc:`NotImplementedError`. 1506 1507 If the function also supports *dir_fd* or *follow_symlinks* arguments, it's 1508 an error to specify one of those when supplying *path* as a file descriptor. 1509 1510.. _dir_fd: 1511 1512* **paths relative to directory descriptors:** If *dir_fd* is not ``None``, it 1513 should be a file descriptor referring to a directory, and the path to operate 1514 on should be relative; path will then be relative to that directory. If the 1515 path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call 1516 the variant of the function with an ``at`` suffix and possibly prefixed with 1517 ``f`` (e.g. call ``faccessat`` instead of ``access``). 1518 1519 You can check whether or not *dir_fd* is supported for a particular function 1520 on your platform using :data:`os.supports_dir_fd`. If it's unavailable, 1521 using it will raise a :exc:`NotImplementedError`. 1522 1523.. _follow_symlinks: 1524 1525* **not following symlinks:** If *follow_symlinks* is 1526 ``False``, and the last element of the path to operate on is a symbolic link, 1527 the function will operate on the symbolic link itself rather than the file 1528 pointed to by the link. (For POSIX systems, Python will call the ``l...`` 1529 variant of the function.) 1530 1531 You can check whether or not *follow_symlinks* is supported for a particular 1532 function on your platform using :data:`os.supports_follow_symlinks`. 1533 If it's unavailable, using it will raise a :exc:`NotImplementedError`. 1534 1535 1536 1537.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True) 1538 1539 Use the real uid/gid to test for access to *path*. Note that most operations 1540 will use the effective uid/gid, therefore this routine can be used in a 1541 suid/sgid environment to test if the invoking user has the specified access to 1542 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it 1543 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and 1544 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed, 1545 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more 1546 information. 1547 1548 This function can support specifying :ref:`paths relative to directory 1549 descriptors <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`. 1550 1551 If *effective_ids* is ``True``, :func:`access` will perform its access 1552 checks using the effective uid/gid instead of the real uid/gid. 1553 *effective_ids* may not be supported on your platform; you can check whether 1554 or not it is available using :data:`os.supports_effective_ids`. If it is 1555 unavailable, using it will raise a :exc:`NotImplementedError`. 1556 1557 .. note:: 1558 1559 Using :func:`access` to check if a user is authorized to e.g. open a file 1560 before actually doing so using :func:`open` creates a security hole, 1561 because the user might exploit the short time interval between checking 1562 and opening the file to manipulate it. It's preferable to use :term:`EAFP` 1563 techniques. For example:: 1564 1565 if os.access("myfile", os.R_OK): 1566 with open("myfile") as fp: 1567 return fp.read() 1568 return "some default data" 1569 1570 is better written as:: 1571 1572 try: 1573 fp = open("myfile") 1574 except PermissionError: 1575 return "some default data" 1576 else: 1577 with fp: 1578 return fp.read() 1579 1580 .. note:: 1581 1582 I/O operations may fail even when :func:`access` indicates that they would 1583 succeed, particularly for operations on network filesystems which may have 1584 permissions semantics beyond the usual POSIX permission-bit model. 1585 1586 .. versionchanged:: 3.3 1587 Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters. 1588 1589 .. versionchanged:: 3.6 1590 Accepts a :term:`path-like object`. 1591 1592 1593.. data:: F_OK 1594 R_OK 1595 W_OK 1596 X_OK 1597 1598 Values to pass as the *mode* parameter of :func:`access` to test the 1599 existence, readability, writability and executability of *path*, 1600 respectively. 1601 1602 1603.. function:: chdir(path) 1604 1605 .. index:: single: directory; changing 1606 1607 Change the current working directory to *path*. 1608 1609 This function can support :ref:`specifying a file descriptor <path_fd>`. The 1610 descriptor must refer to an opened directory, not an open file. 1611 1612 This function can raise :exc:`OSError` and subclasses such as 1613 :exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`. 1614 1615 .. audit-event:: os.chdir path os.chdir 1616 1617 .. versionadded:: 3.3 1618 Added support for specifying *path* as a file descriptor 1619 on some platforms. 1620 1621 .. versionchanged:: 3.6 1622 Accepts a :term:`path-like object`. 1623 1624 1625.. function:: chflags(path, flags, *, follow_symlinks=True) 1626 1627 Set the flags of *path* to the numeric *flags*. *flags* may take a combination 1628 (bitwise OR) of the following values (as defined in the :mod:`stat` module): 1629 1630 * :data:`stat.UF_NODUMP` 1631 * :data:`stat.UF_IMMUTABLE` 1632 * :data:`stat.UF_APPEND` 1633 * :data:`stat.UF_OPAQUE` 1634 * :data:`stat.UF_NOUNLINK` 1635 * :data:`stat.UF_COMPRESSED` 1636 * :data:`stat.UF_HIDDEN` 1637 * :data:`stat.SF_ARCHIVED` 1638 * :data:`stat.SF_IMMUTABLE` 1639 * :data:`stat.SF_APPEND` 1640 * :data:`stat.SF_NOUNLINK` 1641 * :data:`stat.SF_SNAPSHOT` 1642 1643 This function can support :ref:`not following symlinks <follow_symlinks>`. 1644 1645 .. audit-event:: os.chflags path,flags os.chflags 1646 1647 .. availability:: Unix. 1648 1649 .. versionadded:: 3.3 1650 The *follow_symlinks* argument. 1651 1652 .. versionchanged:: 3.6 1653 Accepts a :term:`path-like object`. 1654 1655 1656.. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True) 1657 1658 Change the mode of *path* to the numeric *mode*. *mode* may take one of the 1659 following values (as defined in the :mod:`stat` module) or bitwise ORed 1660 combinations of them: 1661 1662 * :data:`stat.S_ISUID` 1663 * :data:`stat.S_ISGID` 1664 * :data:`stat.S_ENFMT` 1665 * :data:`stat.S_ISVTX` 1666 * :data:`stat.S_IREAD` 1667 * :data:`stat.S_IWRITE` 1668 * :data:`stat.S_IEXEC` 1669 * :data:`stat.S_IRWXU` 1670 * :data:`stat.S_IRUSR` 1671 * :data:`stat.S_IWUSR` 1672 * :data:`stat.S_IXUSR` 1673 * :data:`stat.S_IRWXG` 1674 * :data:`stat.S_IRGRP` 1675 * :data:`stat.S_IWGRP` 1676 * :data:`stat.S_IXGRP` 1677 * :data:`stat.S_IRWXO` 1678 * :data:`stat.S_IROTH` 1679 * :data:`stat.S_IWOTH` 1680 * :data:`stat.S_IXOTH` 1681 1682 This function can support :ref:`specifying a file descriptor <path_fd>`, 1683 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not 1684 following symlinks <follow_symlinks>`. 1685 1686 .. note:: 1687 1688 Although Windows supports :func:`chmod`, you can only set the file's 1689 read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` 1690 constants or a corresponding integer value). All other bits are ignored. 1691 1692 .. audit-event:: os.chmod path,mode,dir_fd os.chmod 1693 1694 .. versionadded:: 3.3 1695 Added support for specifying *path* as an open file descriptor, 1696 and the *dir_fd* and *follow_symlinks* arguments. 1697 1698 .. versionchanged:: 3.6 1699 Accepts a :term:`path-like object`. 1700 1701 1702.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) 1703 1704 Change the owner and group id of *path* to the numeric *uid* and *gid*. To 1705 leave one of the ids unchanged, set it to -1. 1706 1707 This function can support :ref:`specifying a file descriptor <path_fd>`, 1708 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not 1709 following symlinks <follow_symlinks>`. 1710 1711 See :func:`shutil.chown` for a higher-level function that accepts names in 1712 addition to numeric ids. 1713 1714 .. audit-event:: os.chown path,uid,gid,dir_fd os.chown 1715 1716 .. availability:: Unix. 1717 1718 .. versionadded:: 3.3 1719 Added support for specifying *path* as an open file descriptor, 1720 and the *dir_fd* and *follow_symlinks* arguments. 1721 1722 .. versionchanged:: 3.6 1723 Supports a :term:`path-like object`. 1724 1725 1726.. function:: chroot(path) 1727 1728 Change the root directory of the current process to *path*. 1729 1730 .. availability:: Unix. 1731 1732 .. versionchanged:: 3.6 1733 Accepts a :term:`path-like object`. 1734 1735 1736.. function:: fchdir(fd) 1737 1738 Change the current working directory to the directory represented by the file 1739 descriptor *fd*. The descriptor must refer to an opened directory, not an 1740 open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``. 1741 1742 .. audit-event:: os.chdir path os.fchdir 1743 1744 .. availability:: Unix. 1745 1746 1747.. function:: getcwd() 1748 1749 Return a string representing the current working directory. 1750 1751 1752.. function:: getcwdb() 1753 1754 Return a bytestring representing the current working directory. 1755 1756 .. versionchanged:: 3.8 1757 The function now uses the UTF-8 encoding on Windows, rather than the ANSI 1758 code page: see :pep:`529` for the rationale. The function is no longer 1759 deprecated on Windows. 1760 1761 1762.. function:: lchflags(path, flags) 1763 1764 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do 1765 not follow symbolic links. As of Python 3.3, this is equivalent to 1766 ``os.chflags(path, flags, follow_symlinks=False)``. 1767 1768 .. audit-event:: os.chflags path,flags os.lchflags 1769 1770 .. availability:: Unix. 1771 1772 .. versionchanged:: 3.6 1773 Accepts a :term:`path-like object`. 1774 1775 1776.. function:: lchmod(path, mode) 1777 1778 Change the mode of *path* to the numeric *mode*. If path is a symlink, this 1779 affects the symlink rather than the target. See the docs for :func:`chmod` 1780 for possible values of *mode*. As of Python 3.3, this is equivalent to 1781 ``os.chmod(path, mode, follow_symlinks=False)``. 1782 1783 .. audit-event:: os.chmod path,mode,dir_fd os.lchmod 1784 1785 .. availability:: Unix. 1786 1787 .. versionchanged:: 3.6 1788 Accepts a :term:`path-like object`. 1789 1790.. function:: lchown(path, uid, gid) 1791 1792 Change the owner and group id of *path* to the numeric *uid* and *gid*. This 1793 function will not follow symbolic links. As of Python 3.3, this is equivalent 1794 to ``os.chown(path, uid, gid, follow_symlinks=False)``. 1795 1796 .. audit-event:: os.chown path,uid,gid,dir_fd os.lchown 1797 1798 .. availability:: Unix. 1799 1800 .. versionchanged:: 3.6 1801 Accepts a :term:`path-like object`. 1802 1803 1804.. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True) 1805 1806 Create a hard link pointing to *src* named *dst*. 1807 1808 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to 1809 supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not 1810 following symlinks <follow_symlinks>`. 1811 1812 .. audit-event:: os.link src,dst,src_dir_fd,dst_dir_fd os.link 1813 1814 .. availability:: Unix, Windows. 1815 1816 .. versionchanged:: 3.2 1817 Added Windows support. 1818 1819 .. versionadded:: 3.3 1820 Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments. 1821 1822 .. versionchanged:: 3.6 1823 Accepts a :term:`path-like object` for *src* and *dst*. 1824 1825 1826.. function:: listdir(path='.') 1827 1828 Return a list containing the names of the entries in the directory given by 1829 *path*. The list is in arbitrary order, and does not include the special 1830 entries ``'.'`` and ``'..'`` even if they are present in the directory. 1831 If a file is removed from or added to the directory during the call of 1832 this function, whether a name for that file be included is unspecified. 1833 1834 *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` 1835 (directly or indirectly through the :class:`PathLike` interface), 1836 the filenames returned will also be of type ``bytes``; 1837 in all other circumstances, they will be of type ``str``. 1838 1839 This function can also support :ref:`specifying a file descriptor 1840 <path_fd>`; the file descriptor must refer to a directory. 1841 1842 .. audit-event:: os.listdir path os.listdir 1843 1844 .. note:: 1845 To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`. 1846 1847 .. seealso:: 1848 1849 The :func:`scandir` function returns directory entries along with 1850 file attribute information, giving better performance for many 1851 common use cases. 1852 1853 .. versionchanged:: 3.2 1854 The *path* parameter became optional. 1855 1856 .. versionadded:: 3.3 1857 Added support for specifying *path* as an open file descriptor. 1858 1859 .. versionchanged:: 3.6 1860 Accepts a :term:`path-like object`. 1861 1862 1863.. function:: lstat(path, *, dir_fd=None) 1864 1865 Perform the equivalent of an :c:func:`lstat` system call on the given path. 1866 Similar to :func:`~os.stat`, but does not follow symbolic links. Return a 1867 :class:`stat_result` object. 1868 1869 On platforms that do not support symbolic links, this is an alias for 1870 :func:`~os.stat`. 1871 1872 As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd, 1873 follow_symlinks=False)``. 1874 1875 This function can also support :ref:`paths relative to directory descriptors 1876 <dir_fd>`. 1877 1878 .. seealso:: 1879 1880 The :func:`.stat` function. 1881 1882 .. versionchanged:: 3.2 1883 Added support for Windows 6.0 (Vista) symbolic links. 1884 1885 .. versionchanged:: 3.3 1886 Added the *dir_fd* parameter. 1887 1888 .. versionchanged:: 3.6 1889 Accepts a :term:`path-like object`. 1890 1891 .. versionchanged:: 3.8 1892 On Windows, now opens reparse points that represent another path 1893 (name surrogates), including symbolic links and directory junctions. 1894 Other kinds of reparse points are resolved by the operating system as 1895 for :func:`~os.stat`. 1896 1897 1898.. function:: mkdir(path, mode=0o777, *, dir_fd=None) 1899 1900 Create a directory named *path* with numeric mode *mode*. 1901 1902 If the directory already exists, :exc:`FileExistsError` is raised. 1903 1904 .. _mkdir_modebits: 1905 1906 On some systems, *mode* is ignored. Where it is used, the current umask 1907 value is first masked out. If bits other than the last 9 (i.e. the last 3 1908 digits of the octal representation of the *mode*) are set, their meaning is 1909 platform-dependent. On some platforms, they are ignored and you should call 1910 :func:`chmod` explicitly to set them. 1911 1912 This function can also support :ref:`paths relative to directory descriptors 1913 <dir_fd>`. 1914 1915 It is also possible to create temporary directories; see the 1916 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function. 1917 1918 .. audit-event:: os.mkdir path,mode,dir_fd os.mkdir 1919 1920 .. versionadded:: 3.3 1921 The *dir_fd* argument. 1922 1923 .. versionchanged:: 3.6 1924 Accepts a :term:`path-like object`. 1925 1926 1927.. function:: makedirs(name, mode=0o777, exist_ok=False) 1928 1929 .. index:: 1930 single: directory; creating 1931 single: UNC paths; and os.makedirs() 1932 1933 Recursive directory creation function. Like :func:`mkdir`, but makes all 1934 intermediate-level directories needed to contain the leaf directory. 1935 1936 The *mode* parameter is passed to :func:`mkdir` for creating the leaf 1937 directory; see :ref:`the mkdir() description <mkdir_modebits>` for how it 1938 is interpreted. To set the file permission bits of any newly-created parent 1939 directories you can set the umask before invoking :func:`makedirs`. The 1940 file permission bits of existing parent directories are not changed. 1941 1942 If *exist_ok* is ``False`` (the default), an :exc:`FileExistsError` is 1943 raised if the target directory already exists. 1944 1945 .. note:: 1946 1947 :func:`makedirs` will become confused if the path elements to create 1948 include :data:`pardir` (eg. ".." on UNIX systems). 1949 1950 This function handles UNC paths correctly. 1951 1952 .. audit-event:: os.mkdir path,mode,dir_fd os.makedirs 1953 1954 .. versionadded:: 3.2 1955 The *exist_ok* parameter. 1956 1957 .. versionchanged:: 3.4.1 1958 1959 Before Python 3.4.1, if *exist_ok* was ``True`` and the directory existed, 1960 :func:`makedirs` would still raise an error if *mode* did not match the 1961 mode of the existing directory. Since this behavior was impossible to 1962 implement safely, it was removed in Python 3.4.1. See :issue:`21082`. 1963 1964 .. versionchanged:: 3.6 1965 Accepts a :term:`path-like object`. 1966 1967 .. versionchanged:: 3.7 1968 The *mode* argument no longer affects the file permission bits of 1969 newly-created intermediate-level directories. 1970 1971 1972.. function:: mkfifo(path, mode=0o666, *, dir_fd=None) 1973 1974 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. 1975 The current umask value is first masked out from the mode. 1976 1977 This function can also support :ref:`paths relative to directory descriptors 1978 <dir_fd>`. 1979 1980 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they 1981 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as 1982 rendezvous between "client" and "server" type processes: the server opens the 1983 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo` 1984 doesn't open the FIFO --- it just creates the rendezvous point. 1985 1986 .. availability:: Unix. 1987 1988 .. versionadded:: 3.3 1989 The *dir_fd* argument. 1990 1991 .. versionchanged:: 3.6 1992 Accepts a :term:`path-like object`. 1993 1994 1995.. function:: mknod(path, mode=0o600, device=0, *, dir_fd=None) 1996 1997 Create a filesystem node (file, device special file or named pipe) named 1998 *path*. *mode* specifies both the permissions to use and the type of node 1999 to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, 2000 ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are 2001 available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``, 2002 *device* defines the newly created device special file (probably using 2003 :func:`os.makedev`), otherwise it is ignored. 2004 2005 This function can also support :ref:`paths relative to directory descriptors 2006 <dir_fd>`. 2007 2008 .. availability:: Unix. 2009 2010 .. versionadded:: 3.3 2011 The *dir_fd* argument. 2012 2013 .. versionchanged:: 3.6 2014 Accepts a :term:`path-like object`. 2015 2016 2017.. function:: major(device) 2018 2019 Extract the device major number from a raw device number (usually the 2020 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). 2021 2022 2023.. function:: minor(device) 2024 2025 Extract the device minor number from a raw device number (usually the 2026 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). 2027 2028 2029.. function:: makedev(major, minor) 2030 2031 Compose a raw device number from the major and minor device numbers. 2032 2033 2034.. function:: pathconf(path, name) 2035 2036 Return system configuration information relevant to a named file. *name* 2037 specifies the configuration value to retrieve; it may be a string which is the 2038 name of a defined system value; these names are specified in a number of 2039 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define 2040 additional names as well. The names known to the host operating system are 2041 given in the ``pathconf_names`` dictionary. For configuration variables not 2042 included in that mapping, passing an integer for *name* is also accepted. 2043 2044 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 2045 specific value for *name* is not supported by the host system, even if it is 2046 included in ``pathconf_names``, an :exc:`OSError` is raised with 2047 :const:`errno.EINVAL` for the error number. 2048 2049 This function can support :ref:`specifying a file descriptor 2050 <path_fd>`. 2051 2052 .. availability:: Unix. 2053 2054 .. versionchanged:: 3.6 2055 Accepts a :term:`path-like object`. 2056 2057 2058.. data:: pathconf_names 2059 2060 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to 2061 the integer values defined for those names by the host operating system. This 2062 can be used to determine the set of names known to the system. 2063 2064 .. availability:: Unix. 2065 2066 2067.. function:: readlink(path, *, dir_fd=None) 2068 2069 Return a string representing the path to which the symbolic link points. The 2070 result may be either an absolute or relative pathname; if it is relative, it 2071 may be converted to an absolute pathname using 2072 ``os.path.join(os.path.dirname(path), result)``. 2073 2074 If the *path* is a string object (directly or indirectly through a 2075 :class:`PathLike` interface), the result will also be a string object, 2076 and the call may raise a UnicodeDecodeError. If the *path* is a bytes 2077 object (direct or indirectly), the result will be a bytes object. 2078 2079 This function can also support :ref:`paths relative to directory descriptors 2080 <dir_fd>`. 2081 2082 When trying to resolve a path that may contain links, use 2083 :func:`~os.path.realpath` to properly handle recursion and platform 2084 differences. 2085 2086 .. availability:: Unix, Windows. 2087 2088 .. versionchanged:: 3.2 2089 Added support for Windows 6.0 (Vista) symbolic links. 2090 2091 .. versionadded:: 3.3 2092 The *dir_fd* argument. 2093 2094 .. versionchanged:: 3.6 2095 Accepts a :term:`path-like object` on Unix. 2096 2097 .. versionchanged:: 3.8 2098 Accepts a :term:`path-like object` and a bytes object on Windows. 2099 2100 .. versionchanged:: 3.8 2101 Added support for directory junctions, and changed to return the 2102 substitution path (which typically includes ``\\?\`` prefix) rather 2103 than the optional "print name" field that was previously returned. 2104 2105.. function:: remove(path, *, dir_fd=None) 2106 2107 Remove (delete) the file *path*. If *path* is a directory, an 2108 :exc:`IsADirectoryError` is raised. Use :func:`rmdir` to remove directories. 2109 If the file does not exist, a :exc:`FileNotFoundError` is raised. 2110 2111 This function can support :ref:`paths relative to directory descriptors 2112 <dir_fd>`. 2113 2114 On Windows, attempting to remove a file that is in use causes an exception to 2115 be raised; on Unix, the directory entry is removed but the storage allocated 2116 to the file is not made available until the original file is no longer in use. 2117 2118 This function is semantically identical to :func:`unlink`. 2119 2120 .. audit-event:: os.remove path,dir_fd os.remove 2121 2122 .. versionadded:: 3.3 2123 The *dir_fd* argument. 2124 2125 .. versionchanged:: 3.6 2126 Accepts a :term:`path-like object`. 2127 2128 2129.. function:: removedirs(name) 2130 2131 .. index:: single: directory; deleting 2132 2133 Remove directories recursively. Works like :func:`rmdir` except that, if the 2134 leaf directory is successfully removed, :func:`removedirs` tries to 2135 successively remove every parent directory mentioned in *path* until an error 2136 is raised (which is ignored, because it generally means that a parent directory 2137 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove 2138 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if 2139 they are empty. Raises :exc:`OSError` if the leaf directory could not be 2140 successfully removed. 2141 2142 .. audit-event:: os.remove path,dir_fd os.removedirs 2143 2144 .. versionchanged:: 3.6 2145 Accepts a :term:`path-like object`. 2146 2147 2148.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) 2149 2150 Rename the file or directory *src* to *dst*. If *dst* exists, the operation 2151 will fail with an :exc:`OSError` subclass in a number of cases: 2152 2153 On Windows, if *dst* exists a :exc:`FileExistsError` is always raised. 2154 2155 On Unix, if *src* is a file and *dst* is a directory or vice-versa, an 2156 :exc:`IsADirectoryError` or a :exc:`NotADirectoryError` will be raised 2157 respectively. If both are directories and *dst* is empty, *dst* will be 2158 silently replaced. If *dst* is a non-empty directory, an :exc:`OSError` 2159 is raised. If both are files, *dst* it will be replaced silently if the user 2160 has permission. The operation may fail on some Unix flavors if *src* and 2161 *dst* are on different filesystems. If successful, the renaming will be an 2162 atomic operation (this is a POSIX requirement). 2163 2164 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to 2165 supply :ref:`paths relative to directory descriptors <dir_fd>`. 2166 2167 If you want cross-platform overwriting of the destination, use :func:`replace`. 2168 2169 .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.rename 2170 2171 .. versionadded:: 3.3 2172 The *src_dir_fd* and *dst_dir_fd* arguments. 2173 2174 .. versionchanged:: 3.6 2175 Accepts a :term:`path-like object` for *src* and *dst*. 2176 2177 2178.. function:: renames(old, new) 2179 2180 Recursive directory or file renaming function. Works like :func:`rename`, except 2181 creation of any intermediate directories needed to make the new pathname good is 2182 attempted first. After the rename, directories corresponding to rightmost path 2183 segments of the old name will be pruned away using :func:`removedirs`. 2184 2185 .. note:: 2186 2187 This function can fail with the new directory structure made if you lack 2188 permissions needed to remove the leaf directory or file. 2189 2190 .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.renames 2191 2192 .. versionchanged:: 3.6 2193 Accepts a :term:`path-like object` for *old* and *new*. 2194 2195 2196.. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None) 2197 2198 Rename the file or directory *src* to *dst*. If *dst* is a directory, 2199 :exc:`OSError` will be raised. If *dst* exists and is a file, it will 2200 be replaced silently if the user has permission. The operation may fail 2201 if *src* and *dst* are on different filesystems. If successful, 2202 the renaming will be an atomic operation (this is a POSIX requirement). 2203 2204 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to 2205 supply :ref:`paths relative to directory descriptors <dir_fd>`. 2206 2207 .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.replace 2208 2209 .. versionadded:: 3.3 2210 2211 .. versionchanged:: 3.6 2212 Accepts a :term:`path-like object` for *src* and *dst*. 2213 2214 2215.. function:: rmdir(path, *, dir_fd=None) 2216 2217 Remove (delete) the directory *path*. If the directory does not exist or is 2218 not empty, an :exc:`FileNotFoundError` or an :exc:`OSError` is raised 2219 respectively. In order to remove whole directory trees, 2220 :func:`shutil.rmtree` can be used. 2221 2222 This function can support :ref:`paths relative to directory descriptors 2223 <dir_fd>`. 2224 2225 .. audit-event:: os.rmdir path,dir_fd os.rmdir 2226 2227 .. versionadded:: 3.3 2228 The *dir_fd* parameter. 2229 2230 .. versionchanged:: 3.6 2231 Accepts a :term:`path-like object`. 2232 2233 2234.. function:: scandir(path='.') 2235 2236 Return an iterator of :class:`os.DirEntry` objects corresponding to the 2237 entries in the directory given by *path*. The entries are yielded in 2238 arbitrary order, and the special entries ``'.'`` and ``'..'`` are not 2239 included. If a file is removed from or added to the directory after 2240 creating the iterator, whether an entry for that file be included is 2241 unspecified. 2242 2243 Using :func:`scandir` instead of :func:`listdir` can significantly 2244 increase the performance of code that also needs file type or file 2245 attribute information, because :class:`os.DirEntry` objects expose this 2246 information if the operating system provides it when scanning a directory. 2247 All :class:`os.DirEntry` methods may perform a system call, but 2248 :func:`~os.DirEntry.is_dir` and :func:`~os.DirEntry.is_file` usually only 2249 require a system call for symbolic links; :func:`os.DirEntry.stat` 2250 always requires a system call on Unix but only requires one for 2251 symbolic links on Windows. 2252 2253 *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` 2254 (directly or indirectly through the :class:`PathLike` interface), 2255 the type of the :attr:`~os.DirEntry.name` and :attr:`~os.DirEntry.path` 2256 attributes of each :class:`os.DirEntry` will be ``bytes``; in all other 2257 circumstances, they will be of type ``str``. 2258 2259 This function can also support :ref:`specifying a file descriptor 2260 <path_fd>`; the file descriptor must refer to a directory. 2261 2262 .. audit-event:: os.scandir path os.scandir 2263 2264 The :func:`scandir` iterator supports the :term:`context manager` protocol 2265 and has the following method: 2266 2267 .. method:: scandir.close() 2268 2269 Close the iterator and free acquired resources. 2270 2271 This is called automatically when the iterator is exhausted or garbage 2272 collected, or when an error happens during iterating. However it 2273 is advisable to call it explicitly or use the :keyword:`with` 2274 statement. 2275 2276 .. versionadded:: 3.6 2277 2278 The following example shows a simple use of :func:`scandir` to display all 2279 the files (excluding directories) in the given *path* that don't start with 2280 ``'.'``. The ``entry.is_file()`` call will generally not make an additional 2281 system call:: 2282 2283 with os.scandir(path) as it: 2284 for entry in it: 2285 if not entry.name.startswith('.') and entry.is_file(): 2286 print(entry.name) 2287 2288 .. note:: 2289 2290 On Unix-based systems, :func:`scandir` uses the system's 2291 `opendir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html>`_ 2292 and 2293 `readdir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html>`_ 2294 functions. On Windows, it uses the Win32 2295 `FindFirstFileW <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx>`_ 2296 and 2297 `FindNextFileW <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx>`_ 2298 functions. 2299 2300 .. versionadded:: 3.5 2301 2302 .. versionadded:: 3.6 2303 Added support for the :term:`context manager` protocol and the 2304 :func:`~scandir.close()` method. If a :func:`scandir` iterator is neither 2305 exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted 2306 in its destructor. 2307 2308 The function accepts a :term:`path-like object`. 2309 2310 .. versionchanged:: 3.7 2311 Added support for :ref:`file descriptors <path_fd>` on Unix. 2312 2313 2314.. class:: DirEntry 2315 2316 Object yielded by :func:`scandir` to expose the file path and other file 2317 attributes of a directory entry. 2318 2319 :func:`scandir` will provide as much of this information as possible without 2320 making additional system calls. When a ``stat()`` or ``lstat()`` system call 2321 is made, the ``os.DirEntry`` object will cache the result. 2322 2323 ``os.DirEntry`` instances are not intended to be stored in long-lived data 2324 structures; if you know the file metadata has changed or if a long time has 2325 elapsed since calling :func:`scandir`, call ``os.stat(entry.path)`` to fetch 2326 up-to-date information. 2327 2328 Because the ``os.DirEntry`` methods can make operating system calls, they may 2329 also raise :exc:`OSError`. If you need very fine-grained 2330 control over errors, you can catch :exc:`OSError` when calling one of the 2331 ``os.DirEntry`` methods and handle as appropriate. 2332 2333 To be directly usable as a :term:`path-like object`, ``os.DirEntry`` 2334 implements the :class:`PathLike` interface. 2335 2336 Attributes and methods on a ``os.DirEntry`` instance are as follows: 2337 2338 .. attribute:: name 2339 2340 The entry's base filename, relative to the :func:`scandir` *path* 2341 argument. 2342 2343 The :attr:`name` attribute will be ``bytes`` if the :func:`scandir` 2344 *path* argument is of type ``bytes`` and ``str`` otherwise. Use 2345 :func:`~os.fsdecode` to decode byte filenames. 2346 2347 .. attribute:: path 2348 2349 The entry's full path name: equivalent to ``os.path.join(scandir_path, 2350 entry.name)`` where *scandir_path* is the :func:`scandir` *path* 2351 argument. The path is only absolute if the :func:`scandir` *path* 2352 argument was absolute. If the :func:`scandir` *path* 2353 argument was a :ref:`file descriptor <path_fd>`, the :attr:`path` 2354 attribute is the same as the :attr:`name` attribute. 2355 2356 The :attr:`path` attribute will be ``bytes`` if the :func:`scandir` 2357 *path* argument is of type ``bytes`` and ``str`` otherwise. Use 2358 :func:`~os.fsdecode` to decode byte filenames. 2359 2360 .. method:: inode() 2361 2362 Return the inode number of the entry. 2363 2364 The result is cached on the ``os.DirEntry`` object. Use 2365 ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date 2366 information. 2367 2368 On the first, uncached call, a system call is required on Windows but 2369 not on Unix. 2370 2371 .. method:: is_dir(*, follow_symlinks=True) 2372 2373 Return ``True`` if this entry is a directory or a symbolic link pointing 2374 to a directory; return ``False`` if the entry is or points to any other 2375 kind of file, or if it doesn't exist anymore. 2376 2377 If *follow_symlinks* is ``False``, return ``True`` only if this entry 2378 is a directory (without following symlinks); return ``False`` if the 2379 entry is any other kind of file or if it doesn't exist anymore. 2380 2381 The result is cached on the ``os.DirEntry`` object, with a separate cache 2382 for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` along 2383 with :func:`stat.S_ISDIR` to fetch up-to-date information. 2384 2385 On the first, uncached call, no system call is required in most cases. 2386 Specifically, for non-symlinks, neither Windows or Unix require a system 2387 call, except on certain Unix file systems, such as network file systems, 2388 that return ``dirent.d_type == DT_UNKNOWN``. If the entry is a symlink, 2389 a system call will be required to follow the symlink unless 2390 *follow_symlinks* is ``False``. 2391 2392 This method can raise :exc:`OSError`, such as :exc:`PermissionError`, 2393 but :exc:`FileNotFoundError` is caught and not raised. 2394 2395 .. method:: is_file(*, follow_symlinks=True) 2396 2397 Return ``True`` if this entry is a file or a symbolic link pointing to a 2398 file; return ``False`` if the entry is or points to a directory or other 2399 non-file entry, or if it doesn't exist anymore. 2400 2401 If *follow_symlinks* is ``False``, return ``True`` only if this entry 2402 is a file (without following symlinks); return ``False`` if the entry is 2403 a directory or other non-file entry, or if it doesn't exist anymore. 2404 2405 The result is cached on the ``os.DirEntry`` object. Caching, system calls 2406 made, and exceptions raised are as per :func:`~os.DirEntry.is_dir`. 2407 2408 .. method:: is_symlink() 2409 2410 Return ``True`` if this entry is a symbolic link (even if broken); 2411 return ``False`` if the entry points to a directory or any kind of file, 2412 or if it doesn't exist anymore. 2413 2414 The result is cached on the ``os.DirEntry`` object. Call 2415 :func:`os.path.islink` to fetch up-to-date information. 2416 2417 On the first, uncached call, no system call is required in most cases. 2418 Specifically, neither Windows or Unix require a system call, except on 2419 certain Unix file systems, such as network file systems, that return 2420 ``dirent.d_type == DT_UNKNOWN``. 2421 2422 This method can raise :exc:`OSError`, such as :exc:`PermissionError`, 2423 but :exc:`FileNotFoundError` is caught and not raised. 2424 2425 .. method:: stat(*, follow_symlinks=True) 2426 2427 Return a :class:`stat_result` object for this entry. This method 2428 follows symbolic links by default; to stat a symbolic link add the 2429 ``follow_symlinks=False`` argument. 2430 2431 On Unix, this method always requires a system call. On Windows, it 2432 only requires a system call if *follow_symlinks* is ``True`` and the 2433 entry is a reparse point (for example, a symbolic link or directory 2434 junction). 2435 2436 On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the 2437 :class:`stat_result` are always set to zero. Call :func:`os.stat` to 2438 get these attributes. 2439 2440 The result is cached on the ``os.DirEntry`` object, with a separate cache 2441 for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` to 2442 fetch up-to-date information. 2443 2444 Note that there is a nice correspondence between several attributes 2445 and methods of ``os.DirEntry`` and of :class:`pathlib.Path`. In 2446 particular, the ``name`` attribute has the same 2447 meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()`` 2448 and ``stat()`` methods. 2449 2450 .. versionadded:: 3.5 2451 2452 .. versionchanged:: 3.6 2453 Added support for the :class:`~os.PathLike` interface. Added support 2454 for :class:`bytes` paths on Windows. 2455 2456 2457.. function:: stat(path, *, dir_fd=None, follow_symlinks=True) 2458 2459 Get the status of a file or a file descriptor. Perform the equivalent of a 2460 :c:func:`stat` system call on the given path. *path* may be specified as 2461 either a string or bytes -- directly or indirectly through the :class:`PathLike` 2462 interface -- or as an open file descriptor. Return a :class:`stat_result` 2463 object. 2464 2465 This function normally follows symlinks; to stat a symlink add the argument 2466 ``follow_symlinks=False``, or use :func:`lstat`. 2467 2468 This function can support :ref:`specifying a file descriptor <path_fd>` and 2469 :ref:`not following symlinks <follow_symlinks>`. 2470 2471 On Windows, passing ``follow_symlinks=False`` will disable following all 2472 name-surrogate reparse points, which includes symlinks and directory 2473 junctions. Other types of reparse points that do not resemble links or that 2474 the operating system is unable to follow will be opened directly. When 2475 following a chain of multiple links, this may result in the original link 2476 being returned instead of the non-link that prevented full traversal. To 2477 obtain stat results for the final path in this case, use the 2478 :func:`os.path.realpath` function to resolve the path name as far as 2479 possible and call :func:`lstat` on the result. This does not apply to 2480 dangling symlinks or junction points, which will raise the usual exceptions. 2481 2482 .. index:: module: stat 2483 2484 Example:: 2485 2486 >>> import os 2487 >>> statinfo = os.stat('somefile.txt') 2488 >>> statinfo 2489 os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026, 2490 st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295, 2491 st_mtime=1297230027, st_ctime=1297230027) 2492 >>> statinfo.st_size 2493 264 2494 2495 .. seealso:: 2496 2497 :func:`fstat` and :func:`lstat` functions. 2498 2499 .. versionadded:: 3.3 2500 Added the *dir_fd* and *follow_symlinks* arguments, specifying a file 2501 descriptor instead of a path. 2502 2503 .. versionchanged:: 3.6 2504 Accepts a :term:`path-like object`. 2505 2506 .. versionchanged:: 3.8 2507 On Windows, all reparse points that can be resolved by the operating 2508 system are now followed, and passing ``follow_symlinks=False`` 2509 disables following all name surrogate reparse points. If the operating 2510 system reaches a reparse point that it is not able to follow, *stat* now 2511 returns the information for the original path as if 2512 ``follow_symlinks=False`` had been specified instead of raising an error. 2513 2514 2515.. class:: stat_result 2516 2517 Object whose attributes correspond roughly to the members of the 2518 :c:type:`stat` structure. It is used for the result of :func:`os.stat`, 2519 :func:`os.fstat` and :func:`os.lstat`. 2520 2521 Attributes: 2522 2523 .. attribute:: st_mode 2524 2525 File mode: file type and file mode bits (permissions). 2526 2527 .. attribute:: st_ino 2528 2529 Platform dependent, but if non-zero, uniquely identifies the 2530 file for a given value of ``st_dev``. Typically: 2531 2532 * the inode number on Unix, 2533 * the `file index 2534 <https://msdn.microsoft.com/en-us/library/aa363788>`_ on 2535 Windows 2536 2537 .. attribute:: st_dev 2538 2539 Identifier of the device on which this file resides. 2540 2541 .. attribute:: st_nlink 2542 2543 Number of hard links. 2544 2545 .. attribute:: st_uid 2546 2547 User identifier of the file owner. 2548 2549 .. attribute:: st_gid 2550 2551 Group identifier of the file owner. 2552 2553 .. attribute:: st_size 2554 2555 Size of the file in bytes, if it is a regular file or a symbolic link. 2556 The size of a symbolic link is the length of the pathname it contains, 2557 without a terminating null byte. 2558 2559 Timestamps: 2560 2561 .. attribute:: st_atime 2562 2563 Time of most recent access expressed in seconds. 2564 2565 .. attribute:: st_mtime 2566 2567 Time of most recent content modification expressed in seconds. 2568 2569 .. attribute:: st_ctime 2570 2571 Platform dependent: 2572 2573 * the time of most recent metadata change on Unix, 2574 * the time of creation on Windows, expressed in seconds. 2575 2576 .. attribute:: st_atime_ns 2577 2578 Time of most recent access expressed in nanoseconds as an integer. 2579 2580 .. attribute:: st_mtime_ns 2581 2582 Time of most recent content modification expressed in nanoseconds as an 2583 integer. 2584 2585 .. attribute:: st_ctime_ns 2586 2587 Platform dependent: 2588 2589 * the time of most recent metadata change on Unix, 2590 * the time of creation on Windows, expressed in nanoseconds as an 2591 integer. 2592 2593 .. note:: 2594 2595 The exact meaning and resolution of the :attr:`st_atime`, 2596 :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating 2597 system and the file system. For example, on Windows systems using the FAT 2598 or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and 2599 :attr:`st_atime` has only 1-day resolution. See your operating system 2600 documentation for details. 2601 2602 Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`, 2603 and :attr:`st_ctime_ns` are always expressed in nanoseconds, many 2604 systems do not provide nanosecond precision. On systems that do 2605 provide nanosecond precision, the floating-point object used to 2606 store :attr:`st_atime`, :attr:`st_mtime`, and :attr:`st_ctime` 2607 cannot preserve all of it, and as such will be slightly inexact. 2608 If you need the exact timestamps you should always use 2609 :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`. 2610 2611 On some Unix systems (such as Linux), the following attributes may also be 2612 available: 2613 2614 .. attribute:: st_blocks 2615 2616 Number of 512-byte blocks allocated for file. 2617 This may be smaller than :attr:`st_size`/512 when the file has holes. 2618 2619 .. attribute:: st_blksize 2620 2621 "Preferred" blocksize for efficient file system I/O. Writing to a file in 2622 smaller chunks may cause an inefficient read-modify-rewrite. 2623 2624 .. attribute:: st_rdev 2625 2626 Type of device if an inode device. 2627 2628 .. attribute:: st_flags 2629 2630 User defined flags for file. 2631 2632 On other Unix systems (such as FreeBSD), the following attributes may be 2633 available (but may be only filled out if root tries to use them): 2634 2635 .. attribute:: st_gen 2636 2637 File generation number. 2638 2639 .. attribute:: st_birthtime 2640 2641 Time of file creation. 2642 2643 On Solaris and derivatives, the following attributes may also be 2644 available: 2645 2646 .. attribute:: st_fstype 2647 2648 String that uniquely identifies the type of the filesystem that 2649 contains the file. 2650 2651 On Mac OS systems, the following attributes may also be available: 2652 2653 .. attribute:: st_rsize 2654 2655 Real size of the file. 2656 2657 .. attribute:: st_creator 2658 2659 Creator of the file. 2660 2661 .. attribute:: st_type 2662 2663 File type. 2664 2665 On Windows systems, the following attributes are also available: 2666 2667 .. attribute:: st_file_attributes 2668 2669 Windows file attributes: ``dwFileAttributes`` member of the 2670 ``BY_HANDLE_FILE_INFORMATION`` structure returned by 2671 :c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*`` 2672 constants in the :mod:`stat` module. 2673 2674 .. attribute:: st_reparse_tag 2675 2676 When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT`` 2677 set, this field contains the tag identifying the type of reparse point. 2678 See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module. 2679 2680 The standard module :mod:`stat` defines functions and constants that are 2681 useful for extracting information from a :c:type:`stat` structure. (On 2682 Windows, some items are filled with dummy values.) 2683 2684 For backward compatibility, a :class:`stat_result` instance is also 2685 accessible as a tuple of at least 10 integers giving the most important (and 2686 portable) members of the :c:type:`stat` structure, in the order 2687 :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, 2688 :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, 2689 :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by 2690 some implementations. For compatibility with older Python versions, 2691 accessing :class:`stat_result` as a tuple always returns integers. 2692 2693 .. versionadded:: 3.3 2694 Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and 2695 :attr:`st_ctime_ns` members. 2696 2697 .. versionadded:: 3.5 2698 Added the :attr:`st_file_attributes` member on Windows. 2699 2700 .. versionchanged:: 3.5 2701 Windows now returns the file index as :attr:`st_ino` when 2702 available. 2703 2704 .. versionadded:: 3.7 2705 Added the :attr:`st_fstype` member to Solaris/derivatives. 2706 2707 .. versionadded:: 3.8 2708 Added the :attr:`st_reparse_tag` member on Windows. 2709 2710 .. versionchanged:: 3.8 2711 On Windows, the :attr:`st_mode` member now identifies special 2712 files as :const:`S_IFCHR`, :const:`S_IFIFO` or :const:`S_IFBLK` 2713 as appropriate. 2714 2715.. function:: statvfs(path) 2716 2717 Perform a :c:func:`statvfs` system call on the given path. The return value is 2718 an object whose attributes describe the filesystem on the given path, and 2719 correspond to the members of the :c:type:`statvfs` structure, namely: 2720 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, 2721 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`, 2722 :attr:`f_flag`, :attr:`f_namemax`, :attr:`f_fsid`. 2723 2724 Two module-level constants are defined for the :attr:`f_flag` attribute's 2725 bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted 2726 read-only, and if :const:`ST_NOSUID` is set, the semantics of 2727 setuid/setgid bits are disabled or not supported. 2728 2729 Additional module-level constants are defined for GNU/glibc based systems. 2730 These are :const:`ST_NODEV` (disallow access to device special files), 2731 :const:`ST_NOEXEC` (disallow program execution), :const:`ST_SYNCHRONOUS` 2732 (writes are synced at once), :const:`ST_MANDLOCK` (allow mandatory locks on an FS), 2733 :const:`ST_WRITE` (write on file/directory/symlink), :const:`ST_APPEND` 2734 (append-only file), :const:`ST_IMMUTABLE` (immutable file), :const:`ST_NOATIME` 2735 (do not update access times), :const:`ST_NODIRATIME` (do not update directory access 2736 times), :const:`ST_RELATIME` (update atime relative to mtime/ctime). 2737 2738 This function can support :ref:`specifying a file descriptor <path_fd>`. 2739 2740 .. availability:: Unix. 2741 2742 .. versionchanged:: 3.2 2743 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. 2744 2745 .. versionadded:: 3.3 2746 Added support for specifying *path* as an open file descriptor. 2747 2748 .. versionchanged:: 3.4 2749 The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`, 2750 :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`, 2751 :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`, 2752 and :const:`ST_RELATIME` constants were added. 2753 2754 .. versionchanged:: 3.6 2755 Accepts a :term:`path-like object`. 2756 2757 .. versionadded:: 3.7 2758 Added :attr:`f_fsid`. 2759 2760 2761.. data:: supports_dir_fd 2762 2763 A :class:`set` object indicating which functions in the :mod:`os` 2764 module accept an open file descriptor for their *dir_fd* parameter. 2765 Different platforms provide different features, and the underlying 2766 functionality Python uses to implement the *dir_fd* parameter is not 2767 available on all platforms Python supports. For consistency's sake, 2768 functions that may support *dir_fd* always allow specifying the 2769 parameter, but will throw an exception if the functionality is used 2770 when it's not locally available. (Specifying ``None`` for *dir_fd* 2771 is always supported on all platforms.) 2772 2773 To check whether a particular function accepts an open file descriptor 2774 for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``. 2775 As an example, this expression evaluates to ``True`` if :func:`os.stat` 2776 accepts open file descriptors for *dir_fd* on the local platform:: 2777 2778 os.stat in os.supports_dir_fd 2779 2780 Currently *dir_fd* parameters only work on Unix platforms; 2781 none of them work on Windows. 2782 2783 .. versionadded:: 3.3 2784 2785 2786.. data:: supports_effective_ids 2787 2788 A :class:`set` object indicating whether :func:`os.access` permits 2789 specifying ``True`` for its *effective_ids* parameter on the local platform. 2790 (Specifying ``False`` for *effective_ids* is always supported on all 2791 platforms.) If the local platform supports it, the collection will contain 2792 :func:`os.access`; otherwise it will be empty. 2793 2794 This expression evaluates to ``True`` if :func:`os.access` supports 2795 ``effective_ids=True`` on the local platform:: 2796 2797 os.access in os.supports_effective_ids 2798 2799 Currently *effective_ids* is only supported on Unix platforms; 2800 it does not work on Windows. 2801 2802 .. versionadded:: 3.3 2803 2804 2805.. data:: supports_fd 2806 2807 A :class:`set` object indicating which functions in the 2808 :mod:`os` module permit specifying their *path* parameter as an open file 2809 descriptor on the local platform. Different platforms provide different 2810 features, and the underlying functionality Python uses to accept open file 2811 descriptors as *path* arguments is not available on all platforms Python 2812 supports. 2813 2814 To determine whether a particular function permits specifying an open file 2815 descriptor for its *path* parameter, use the ``in`` operator on 2816 ``supports_fd``. As an example, this expression evaluates to ``True`` if 2817 :func:`os.chdir` accepts open file descriptors for *path* on your local 2818 platform:: 2819 2820 os.chdir in os.supports_fd 2821 2822 .. versionadded:: 3.3 2823 2824 2825.. data:: supports_follow_symlinks 2826 2827 A :class:`set` object indicating which functions in the :mod:`os` module 2828 accept ``False`` for their *follow_symlinks* parameter on the local platform. 2829 Different platforms provide different features, and the underlying 2830 functionality Python uses to implement *follow_symlinks* is not available 2831 on all platforms Python supports. For consistency's sake, functions that 2832 may support *follow_symlinks* always allow specifying the parameter, but 2833 will throw an exception if the functionality is used when it's not locally 2834 available. (Specifying ``True`` for *follow_symlinks* is always supported 2835 on all platforms.) 2836 2837 To check whether a particular function accepts ``False`` for its 2838 *follow_symlinks* parameter, use the ``in`` operator on 2839 ``supports_follow_symlinks``. As an example, this expression evaluates 2840 to ``True`` if you may specify ``follow_symlinks=False`` when calling 2841 :func:`os.stat` on the local platform:: 2842 2843 os.stat in os.supports_follow_symlinks 2844 2845 .. versionadded:: 3.3 2846 2847 2848.. function:: symlink(src, dst, target_is_directory=False, *, dir_fd=None) 2849 2850 Create a symbolic link pointing to *src* named *dst*. 2851 2852 On Windows, a symlink represents either a file or a directory, and does not 2853 morph to the target dynamically. If the target is present, the type of the 2854 symlink will be created to match. Otherwise, the symlink will be created 2855 as a directory if *target_is_directory* is ``True`` or a file symlink (the 2856 default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. 2857 2858 This function can support :ref:`paths relative to directory descriptors 2859 <dir_fd>`. 2860 2861 .. note:: 2862 2863 On newer versions of Windows 10, unprivileged accounts can create symlinks 2864 if Developer Mode is enabled. When Developer Mode is not available/enabled, 2865 the *SeCreateSymbolicLinkPrivilege* privilege is required, or the process 2866 must be run as an administrator. 2867 2868 2869 :exc:`OSError` is raised when the function is called by an unprivileged 2870 user. 2871 2872 .. audit-event:: os.symlink src,dst,dir_fd os.symlink 2873 2874 .. availability:: Unix, Windows. 2875 2876 .. versionchanged:: 3.2 2877 Added support for Windows 6.0 (Vista) symbolic links. 2878 2879 .. versionadded:: 3.3 2880 Added the *dir_fd* argument, and now allow *target_is_directory* 2881 on non-Windows platforms. 2882 2883 .. versionchanged:: 3.6 2884 Accepts a :term:`path-like object` for *src* and *dst*. 2885 2886 .. versionchanged:: 3.8 2887 Added support for unelevated symlinks on Windows with Developer Mode. 2888 2889 2890.. function:: sync() 2891 2892 Force write of everything to disk. 2893 2894 .. availability:: Unix. 2895 2896 .. versionadded:: 3.3 2897 2898 2899.. function:: truncate(path, length) 2900 2901 Truncate the file corresponding to *path*, so that it is at most 2902 *length* bytes in size. 2903 2904 This function can support :ref:`specifying a file descriptor <path_fd>`. 2905 2906 .. audit-event:: os.truncate path,length os.truncate 2907 2908 .. availability:: Unix, Windows. 2909 2910 .. versionadded:: 3.3 2911 2912 .. versionchanged:: 3.5 2913 Added support for Windows 2914 2915 .. versionchanged:: 3.6 2916 Accepts a :term:`path-like object`. 2917 2918 2919.. function:: unlink(path, *, dir_fd=None) 2920 2921 Remove (delete) the file *path*. This function is semantically 2922 identical to :func:`remove`; the ``unlink`` name is its 2923 traditional Unix name. Please see the documentation for 2924 :func:`remove` for further information. 2925 2926 .. audit-event:: os.remove path,dir_fd os.unlink 2927 2928 .. versionadded:: 3.3 2929 The *dir_fd* parameter. 2930 2931 .. versionchanged:: 3.6 2932 Accepts a :term:`path-like object`. 2933 2934 2935.. function:: utime(path, times=None, *[, ns], dir_fd=None, follow_symlinks=True) 2936 2937 Set the access and modified times of the file specified by *path*. 2938 2939 :func:`utime` takes two optional parameters, *times* and *ns*. 2940 These specify the times set on *path* and are used as follows: 2941 2942 - If *ns* is specified, 2943 it must be a 2-tuple of the form ``(atime_ns, mtime_ns)`` 2944 where each member is an int expressing nanoseconds. 2945 - If *times* is not ``None``, 2946 it must be a 2-tuple of the form ``(atime, mtime)`` 2947 where each member is an int or float expressing seconds. 2948 - If *times* is ``None`` and *ns* is unspecified, 2949 this is equivalent to specifying ``ns=(atime_ns, mtime_ns)`` 2950 where both times are the current time. 2951 2952 It is an error to specify tuples for both *times* and *ns*. 2953 2954 Note that the exact times you set here may not be returned by a subsequent 2955 :func:`~os.stat` call, depending on the resolution with which your operating 2956 system records access and modification times; see :func:`~os.stat`. The best 2957 way to preserve exact times is to use the *st_atime_ns* and *st_mtime_ns* 2958 fields from the :func:`os.stat` result object with the *ns* parameter to 2959 `utime`. 2960 2961 This function can support :ref:`specifying a file descriptor <path_fd>`, 2962 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not 2963 following symlinks <follow_symlinks>`. 2964 2965 .. audit-event:: os.utime path,times,ns,dir_fd os.utime 2966 2967 .. versionadded:: 3.3 2968 Added support for specifying *path* as an open file descriptor, 2969 and the *dir_fd*, *follow_symlinks*, and *ns* parameters. 2970 2971 .. versionchanged:: 3.6 2972 Accepts a :term:`path-like object`. 2973 2974 2975.. function:: walk(top, topdown=True, onerror=None, followlinks=False) 2976 2977 .. index:: 2978 single: directory; walking 2979 single: directory; traversal 2980 2981 Generate the file names in a directory tree by walking the tree 2982 either top-down or bottom-up. For each directory in the tree rooted at directory 2983 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, 2984 filenames)``. 2985 2986 *dirpath* is a string, the path to the directory. *dirnames* is a list of the 2987 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``). 2988 *filenames* is a list of the names of the non-directory files in *dirpath*. 2989 Note that the names in the lists contain no path components. To get a full path 2990 (which begins with *top*) to a file or directory in *dirpath*, do 2991 ``os.path.join(dirpath, name)``. Whether or not the lists are sorted 2992 depends on the file system. If a file is removed from or added to the 2993 *dirpath* directory during generating the lists, whether a name for that 2994 file be included is unspecified. 2995 2996 If optional argument *topdown* is ``True`` or not specified, the triple for a 2997 directory is generated before the triples for any of its subdirectories 2998 (directories are generated top-down). If *topdown* is ``False``, the triple 2999 for a directory is generated after the triples for all of its subdirectories 3000 (directories are generated bottom-up). No matter the value of *topdown*, the 3001 list of subdirectories is retrieved before the tuples for the directory and 3002 its subdirectories are generated. 3003 3004 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place 3005 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only 3006 recurse into the subdirectories whose names remain in *dirnames*; this can be 3007 used to prune the search, impose a specific order of visiting, or even to inform 3008 :func:`walk` about directories the caller creates or renames before it resumes 3009 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has 3010 no effect on the behavior of the walk, because in bottom-up mode the directories 3011 in *dirnames* are generated before *dirpath* itself is generated. 3012 3013 By default, errors from the :func:`scandir` call are ignored. If optional 3014 argument *onerror* is specified, it should be a function; it will be called with 3015 one argument, an :exc:`OSError` instance. It can report the error to continue 3016 with the walk, or raise the exception to abort the walk. Note that the filename 3017 is available as the ``filename`` attribute of the exception object. 3018 3019 By default, :func:`walk` will not walk down into symbolic links that resolve to 3020 directories. Set *followlinks* to ``True`` to visit directories pointed to by 3021 symlinks, on systems that support them. 3022 3023 .. note:: 3024 3025 Be aware that setting *followlinks* to ``True`` can lead to infinite 3026 recursion if a link points to a parent directory of itself. :func:`walk` 3027 does not keep track of the directories it visited already. 3028 3029 .. note:: 3030 3031 If you pass a relative pathname, don't change the current working directory 3032 between resumptions of :func:`walk`. :func:`walk` never changes the current 3033 directory, and assumes that its caller doesn't either. 3034 3035 This example displays the number of bytes taken by non-directory files in each 3036 directory under the starting directory, except that it doesn't look under any 3037 CVS subdirectory:: 3038 3039 import os 3040 from os.path import join, getsize 3041 for root, dirs, files in os.walk('python/Lib/email'): 3042 print(root, "consumes", end=" ") 3043 print(sum(getsize(join(root, name)) for name in files), end=" ") 3044 print("bytes in", len(files), "non-directory files") 3045 if 'CVS' in dirs: 3046 dirs.remove('CVS') # don't visit CVS directories 3047 3048 In the next example (simple implementation of :func:`shutil.rmtree`), 3049 walking the tree bottom-up is essential, :func:`rmdir` doesn't allow 3050 deleting a directory before the directory is empty:: 3051 3052 # Delete everything reachable from the directory named in "top", 3053 # assuming there are no symbolic links. 3054 # CAUTION: This is dangerous! For example, if top == '/', it 3055 # could delete all your disk files. 3056 import os 3057 for root, dirs, files in os.walk(top, topdown=False): 3058 for name in files: 3059 os.remove(os.path.join(root, name)) 3060 for name in dirs: 3061 os.rmdir(os.path.join(root, name)) 3062 3063 .. versionchanged:: 3.5 3064 This function now calls :func:`os.scandir` instead of :func:`os.listdir`, 3065 making it faster by reducing the number of calls to :func:`os.stat`. 3066 3067 .. versionchanged:: 3.6 3068 Accepts a :term:`path-like object`. 3069 3070 3071.. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None) 3072 3073 .. index:: 3074 single: directory; walking 3075 single: directory; traversal 3076 3077 This behaves exactly like :func:`walk`, except that it yields a 4-tuple 3078 ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``. 3079 3080 *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output, 3081 and *dirfd* is a file descriptor referring to the directory *dirpath*. 3082 3083 This function always supports :ref:`paths relative to directory descriptors 3084 <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`. Note however 3085 that, unlike other functions, the :func:`fwalk` default value for 3086 *follow_symlinks* is ``False``. 3087 3088 .. note:: 3089 3090 Since :func:`fwalk` yields file descriptors, those are only valid until 3091 the next iteration step, so you should duplicate them (e.g. with 3092 :func:`dup`) if you want to keep them longer. 3093 3094 This example displays the number of bytes taken by non-directory files in each 3095 directory under the starting directory, except that it doesn't look under any 3096 CVS subdirectory:: 3097 3098 import os 3099 for root, dirs, files, rootfd in os.fwalk('python/Lib/email'): 3100 print(root, "consumes", end="") 3101 print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]), 3102 end="") 3103 print("bytes in", len(files), "non-directory files") 3104 if 'CVS' in dirs: 3105 dirs.remove('CVS') # don't visit CVS directories 3106 3107 In the next example, walking the tree bottom-up is essential: 3108 :func:`rmdir` doesn't allow deleting a directory before the directory is 3109 empty:: 3110 3111 # Delete everything reachable from the directory named in "top", 3112 # assuming there are no symbolic links. 3113 # CAUTION: This is dangerous! For example, if top == '/', it 3114 # could delete all your disk files. 3115 import os 3116 for root, dirs, files, rootfd in os.fwalk(top, topdown=False): 3117 for name in files: 3118 os.unlink(name, dir_fd=rootfd) 3119 for name in dirs: 3120 os.rmdir(name, dir_fd=rootfd) 3121 3122 .. availability:: Unix. 3123 3124 .. versionadded:: 3.3 3125 3126 .. versionchanged:: 3.6 3127 Accepts a :term:`path-like object`. 3128 3129 .. versionchanged:: 3.7 3130 Added support for :class:`bytes` paths. 3131 3132 3133.. function:: memfd_create(name[, flags=os.MFD_CLOEXEC]) 3134 3135 Create an anonymous file and return a file descriptor that refers to it. 3136 *flags* must be one of the ``os.MFD_*`` constants available on the system 3137 (or a bitwise ORed combination of them). By default, the new file 3138 descriptor is :ref:`non-inheritable <fd_inheritance>`. 3139 3140 The name supplied in *name* is used as a filename and will be displayed as 3141 the target of the corresponding symbolic link in the directory 3142 ``/proc/self/fd/``. The displayed name is always prefixed with ``memfd:`` 3143 and serves only for debugging purposes. Names do not affect the behavior of 3144 the file descriptor, and as such multiple files can have the same name 3145 without any side effects. 3146 3147 .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. 3148 3149 .. versionadded:: 3.8 3150 3151 3152.. data:: MFD_CLOEXEC 3153 MFD_ALLOW_SEALING 3154 MFD_HUGETLB 3155 MFD_HUGE_SHIFT 3156 MFD_HUGE_MASK 3157 MFD_HUGE_64KB 3158 MFD_HUGE_512KB 3159 MFD_HUGE_1MB 3160 MFD_HUGE_2MB 3161 MFD_HUGE_8MB 3162 MFD_HUGE_16MB 3163 MFD_HUGE_32MB 3164 MFD_HUGE_256MB 3165 MFD_HUGE_512MB 3166 MFD_HUGE_1GB 3167 MFD_HUGE_2GB 3168 MFD_HUGE_16GB 3169 3170 These flags can be passed to :func:`memfd_create`. 3171 3172 .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. The 3173 ``MFD_HUGE*`` flags are only available since Linux 4.14. 3174 3175 .. versionadded:: 3.8 3176 3177 3178Linux extended attributes 3179~~~~~~~~~~~~~~~~~~~~~~~~~ 3180 3181.. versionadded:: 3.3 3182 3183These functions are all available on Linux only. 3184 3185.. function:: getxattr(path, attribute, *, follow_symlinks=True) 3186 3187 Return the value of the extended filesystem attribute *attribute* for 3188 *path*. *attribute* can be bytes or str (directly or indirectly through the 3189 :class:`PathLike` interface). If it is str, it is encoded with the filesystem 3190 encoding. 3191 3192 This function can support :ref:`specifying a file descriptor <path_fd>` and 3193 :ref:`not following symlinks <follow_symlinks>`. 3194 3195 .. audit-event:: os.getxattr path,attribute os.getxattr 3196 3197 .. versionchanged:: 3.6 3198 Accepts a :term:`path-like object` for *path* and *attribute*. 3199 3200 3201.. function:: listxattr(path=None, *, follow_symlinks=True) 3202 3203 Return a list of the extended filesystem attributes on *path*. The 3204 attributes in the list are represented as strings decoded with the filesystem 3205 encoding. If *path* is ``None``, :func:`listxattr` will examine the current 3206 directory. 3207 3208 This function can support :ref:`specifying a file descriptor <path_fd>` and 3209 :ref:`not following symlinks <follow_symlinks>`. 3210 3211 .. audit-event:: os.listxattr path os.listxattr 3212 3213 .. versionchanged:: 3.6 3214 Accepts a :term:`path-like object`. 3215 3216 3217.. function:: removexattr(path, attribute, *, follow_symlinks=True) 3218 3219 Removes the extended filesystem attribute *attribute* from *path*. 3220 *attribute* should be bytes or str (directly or indirectly through the 3221 :class:`PathLike` interface). If it is a string, it is encoded 3222 with the filesystem encoding. 3223 3224 This function can support :ref:`specifying a file descriptor <path_fd>` and 3225 :ref:`not following symlinks <follow_symlinks>`. 3226 3227 .. audit-event:: os.removexattr path,attribute os.removexattr 3228 3229 .. versionchanged:: 3.6 3230 Accepts a :term:`path-like object` for *path* and *attribute*. 3231 3232 3233.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True) 3234 3235 Set the extended filesystem attribute *attribute* on *path* to *value*. 3236 *attribute* must be a bytes or str with no embedded NULs (directly or 3237 indirectly through the :class:`PathLike` interface). If it is a str, 3238 it is encoded with the filesystem encoding. *flags* may be 3239 :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is 3240 given and the attribute does not exist, ``ENODATA`` will be raised. 3241 If :data:`XATTR_CREATE` is given and the attribute already exists, the 3242 attribute will not be created and ``EEXISTS`` will be raised. 3243 3244 This function can support :ref:`specifying a file descriptor <path_fd>` and 3245 :ref:`not following symlinks <follow_symlinks>`. 3246 3247 .. note:: 3248 3249 A bug in Linux kernel versions less than 2.6.39 caused the flags argument 3250 to be ignored on some filesystems. 3251 3252 .. audit-event:: os.setxattr path,attribute,value,flags os.setxattr 3253 3254 .. versionchanged:: 3.6 3255 Accepts a :term:`path-like object` for *path* and *attribute*. 3256 3257 3258.. data:: XATTR_SIZE_MAX 3259 3260 The maximum size the value of an extended attribute can be. Currently, this 3261 is 64 KiB on Linux. 3262 3263 3264.. data:: XATTR_CREATE 3265 3266 This is a possible value for the flags argument in :func:`setxattr`. It 3267 indicates the operation must create an attribute. 3268 3269 3270.. data:: XATTR_REPLACE 3271 3272 This is a possible value for the flags argument in :func:`setxattr`. It 3273 indicates the operation must replace an existing attribute. 3274 3275 3276.. _os-process: 3277 3278Process Management 3279------------------ 3280 3281These functions may be used to create and manage processes. 3282 3283The various :func:`exec\* <execl>` functions take a list of arguments for the new 3284program loaded into the process. In each case, the first of these arguments is 3285passed to the new program as its own name rather than as an argument a user may 3286have typed on a command line. For the C programmer, this is the ``argv[0]`` 3287passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', 3288['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem 3289to be ignored. 3290 3291 3292.. function:: abort() 3293 3294 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default 3295 behavior is to produce a core dump; on Windows, the process immediately returns 3296 an exit code of ``3``. Be aware that calling this function will not call the 3297 Python signal handler registered for :const:`SIGABRT` with 3298 :func:`signal.signal`. 3299 3300 3301.. function:: add_dll_directory(path) 3302 3303 Add a path to the DLL search path. 3304 3305 This search path is used when resolving dependencies for imported 3306 extension modules (the module itself is resolved through sys.path), 3307 and also by :mod:`ctypes`. 3308 3309 Remove the directory by calling **close()** on the returned object 3310 or using it in a :keyword:`with` statement. 3311 3312 See the `Microsoft documentation 3313 <https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5>`_ 3314 for more information about how DLLs are loaded. 3315 3316 .. audit-event:: os.add_dll_directory path os.add_dll_directory 3317 3318 .. availability:: Windows. 3319 3320 .. versionadded:: 3.8 3321 Previous versions of CPython would resolve DLLs using the default 3322 behavior for the current process. This led to inconsistencies, 3323 such as only sometimes searching :envvar:`PATH` or the current 3324 working directory, and OS functions such as ``AddDllDirectory`` 3325 having no effect. 3326 3327 In 3.8, the two primary ways DLLs are loaded now explicitly 3328 override the process-wide behavior to ensure consistency. See the 3329 :ref:`porting notes <bpo-36085-whatsnew>` for information on 3330 updating libraries. 3331 3332 3333.. function:: execl(path, arg0, arg1, ...) 3334 execle(path, arg0, arg1, ..., env) 3335 execlp(file, arg0, arg1, ...) 3336 execlpe(file, arg0, arg1, ..., env) 3337 execv(path, args) 3338 execve(path, args, env) 3339 execvp(file, args) 3340 execvpe(file, args, env) 3341 3342 These functions all execute a new program, replacing the current process; they 3343 do not return. On Unix, the new executable is loaded into the current process, 3344 and will have the same process id as the caller. Errors will be reported as 3345 :exc:`OSError` exceptions. 3346 3347 The current process is replaced immediately. Open file objects and 3348 descriptors are not flushed, so if there may be data buffered 3349 on these open files, you should flush them using 3350 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an 3351 :func:`exec\* <execl>` function. 3352 3353 The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how 3354 command-line arguments are passed. The "l" variants are perhaps the easiest 3355 to work with if the number of parameters is fixed when the code is written; the 3356 individual parameters simply become additional parameters to the :func:`execl\*` 3357 functions. The "v" variants are good when the number of parameters is 3358 variable, with the arguments being passed in a list or tuple as the *args* 3359 parameter. In either case, the arguments to the child process should start with 3360 the name of the command being run, but this is not enforced. 3361 3362 The variants which include a "p" near the end (:func:`execlp`, 3363 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the 3364 :envvar:`PATH` environment variable to locate the program *file*. When the 3365 environment is being replaced (using one of the :func:`exec\*e <execl>` variants, 3366 discussed in the next paragraph), the new environment is used as the source of 3367 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`, 3368 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to 3369 locate the executable; *path* must contain an appropriate absolute or relative 3370 path. 3371 3372 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note 3373 that these all end in "e"), the *env* parameter must be a mapping which is 3374 used to define the environment variables for the new process (these are used 3375 instead of the current process' environment); the functions :func:`execl`, 3376 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to 3377 inherit the environment of the current process. 3378 3379 For :func:`execve` on some platforms, *path* may also be specified as an open 3380 file descriptor. This functionality may not be supported on your platform; 3381 you can check whether or not it is available using :data:`os.supports_fd`. 3382 If it is unavailable, using it will raise a :exc:`NotImplementedError`. 3383 3384 .. audit-event:: os.exec path,args,env os.execl 3385 3386 .. availability:: Unix, Windows. 3387 3388 .. versionadded:: 3.3 3389 Added support for specifying *path* as an open file descriptor 3390 for :func:`execve`. 3391 3392 .. versionchanged:: 3.6 3393 Accepts a :term:`path-like object`. 3394 3395.. function:: _exit(n) 3396 3397 Exit the process with status *n*, without calling cleanup handlers, flushing 3398 stdio buffers, etc. 3399 3400 .. note:: 3401 3402 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should 3403 normally only be used in the child process after a :func:`fork`. 3404 3405The following exit codes are defined and can be used with :func:`_exit`, 3406although they are not required. These are typically used for system programs 3407written in Python, such as a mail server's external command delivery program. 3408 3409.. note:: 3410 3411 Some of these may not be available on all Unix platforms, since there is some 3412 variation. These constants are defined where they are defined by the underlying 3413 platform. 3414 3415 3416.. data:: EX_OK 3417 3418 Exit code that means no error occurred. 3419 3420 .. availability:: Unix. 3421 3422 3423.. data:: EX_USAGE 3424 3425 Exit code that means the command was used incorrectly, such as when the wrong 3426 number of arguments are given. 3427 3428 .. availability:: Unix. 3429 3430 3431.. data:: EX_DATAERR 3432 3433 Exit code that means the input data was incorrect. 3434 3435 .. availability:: Unix. 3436 3437 3438.. data:: EX_NOINPUT 3439 3440 Exit code that means an input file did not exist or was not readable. 3441 3442 .. availability:: Unix. 3443 3444 3445.. data:: EX_NOUSER 3446 3447 Exit code that means a specified user did not exist. 3448 3449 .. availability:: Unix. 3450 3451 3452.. data:: EX_NOHOST 3453 3454 Exit code that means a specified host did not exist. 3455 3456 .. availability:: Unix. 3457 3458 3459.. data:: EX_UNAVAILABLE 3460 3461 Exit code that means that a required service is unavailable. 3462 3463 .. availability:: Unix. 3464 3465 3466.. data:: EX_SOFTWARE 3467 3468 Exit code that means an internal software error was detected. 3469 3470 .. availability:: Unix. 3471 3472 3473.. data:: EX_OSERR 3474 3475 Exit code that means an operating system error was detected, such as the 3476 inability to fork or create a pipe. 3477 3478 .. availability:: Unix. 3479 3480 3481.. data:: EX_OSFILE 3482 3483 Exit code that means some system file did not exist, could not be opened, or had 3484 some other kind of error. 3485 3486 .. availability:: Unix. 3487 3488 3489.. data:: EX_CANTCREAT 3490 3491 Exit code that means a user specified output file could not be created. 3492 3493 .. availability:: Unix. 3494 3495 3496.. data:: EX_IOERR 3497 3498 Exit code that means that an error occurred while doing I/O on some file. 3499 3500 .. availability:: Unix. 3501 3502 3503.. data:: EX_TEMPFAIL 3504 3505 Exit code that means a temporary failure occurred. This indicates something 3506 that may not really be an error, such as a network connection that couldn't be 3507 made during a retryable operation. 3508 3509 .. availability:: Unix. 3510 3511 3512.. data:: EX_PROTOCOL 3513 3514 Exit code that means that a protocol exchange was illegal, invalid, or not 3515 understood. 3516 3517 .. availability:: Unix. 3518 3519 3520.. data:: EX_NOPERM 3521 3522 Exit code that means that there were insufficient permissions to perform the 3523 operation (but not intended for file system problems). 3524 3525 .. availability:: Unix. 3526 3527 3528.. data:: EX_CONFIG 3529 3530 Exit code that means that some kind of configuration error occurred. 3531 3532 .. availability:: Unix. 3533 3534 3535.. data:: EX_NOTFOUND 3536 3537 Exit code that means something like "an entry was not found". 3538 3539 .. availability:: Unix. 3540 3541 3542.. function:: fork() 3543 3544 Fork a child process. Return ``0`` in the child and the child's process id in the 3545 parent. If an error occurs :exc:`OSError` is raised. 3546 3547 Note that some platforms including FreeBSD <= 6.3 and Cygwin have 3548 known issues when using ``fork()`` from a thread. 3549 3550 .. audit-event:: os.fork "" os.fork 3551 3552 .. versionchanged:: 3.8 3553 Calling ``fork()`` in a subinterpreter is no longer supported 3554 (:exc:`RuntimeError` is raised). 3555 3556 .. warning:: 3557 3558 See :mod:`ssl` for applications that use the SSL module with fork(). 3559 3560 .. availability:: Unix. 3561 3562 3563.. function:: forkpty() 3564 3565 Fork a child process, using a new pseudo-terminal as the child's controlling 3566 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the 3567 new child's process id in the parent, and *fd* is the file descriptor of the 3568 master end of the pseudo-terminal. For a more portable approach, use the 3569 :mod:`pty` module. If an error occurs :exc:`OSError` is raised. 3570 3571 .. audit-event:: os.forkpty "" os.forkpty 3572 3573 .. versionchanged:: 3.8 3574 Calling ``forkpty()`` in a subinterpreter is no longer supported 3575 (:exc:`RuntimeError` is raised). 3576 3577 .. availability:: some flavors of Unix. 3578 3579 3580.. function:: kill(pid, sig) 3581 3582 .. index:: 3583 single: process; killing 3584 single: process; signalling 3585 3586 Send signal *sig* to the process *pid*. Constants for the specific signals 3587 available on the host platform are defined in the :mod:`signal` module. 3588 3589 Windows: The :data:`signal.CTRL_C_EVENT` and 3590 :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can 3591 only be sent to console processes which share a common console window, 3592 e.g., some subprocesses. Any other value for *sig* will cause the process 3593 to be unconditionally killed by the TerminateProcess API, and the exit code 3594 will be set to *sig*. The Windows version of :func:`kill` additionally takes 3595 process handles to be killed. 3596 3597 See also :func:`signal.pthread_kill`. 3598 3599 .. audit-event:: os.kill pid,sig os.kill 3600 3601 .. versionadded:: 3.2 3602 Windows support. 3603 3604 3605.. function:: killpg(pgid, sig) 3606 3607 .. index:: 3608 single: process; killing 3609 single: process; signalling 3610 3611 Send the signal *sig* to the process group *pgid*. 3612 3613 .. audit-event:: os.killpg pgid,sig os.killpg 3614 3615 .. availability:: Unix. 3616 3617 3618.. function:: nice(increment) 3619 3620 Add *increment* to the process's "niceness". Return the new niceness. 3621 3622 .. availability:: Unix. 3623 3624 3625.. function:: plock(op) 3626 3627 Lock program segments into memory. The value of *op* (defined in 3628 ``<sys/lock.h>``) determines which segments are locked. 3629 3630 .. availability:: Unix. 3631 3632 3633.. function:: popen(cmd, mode='r', buffering=-1) 3634 3635 Open a pipe to or from command *cmd*. 3636 The return value is an open file object 3637 connected to the pipe, which can be read or written depending on whether *mode* 3638 is ``'r'`` (default) or ``'w'``. The *buffering* argument has the same meaning as 3639 the corresponding argument to the built-in :func:`open` function. The 3640 returned file object reads or writes text strings rather than bytes. 3641 3642 The ``close`` method returns :const:`None` if the subprocess exited 3643 successfully, or the subprocess's return code if there was an 3644 error. On POSIX systems, if the return code is positive it 3645 represents the return value of the process left-shifted by one 3646 byte. If the return code is negative, the process was terminated 3647 by the signal given by the negated value of the return code. (For 3648 example, the return value might be ``- signal.SIGKILL`` if the 3649 subprocess was killed.) On Windows systems, the return value 3650 contains the signed integer return code from the child process. 3651 3652 This is implemented using :class:`subprocess.Popen`; see that class's 3653 documentation for more powerful ways to manage and communicate with 3654 subprocesses. 3655 3656 3657.. function:: posix_spawn(path, argv, env, *, file_actions=None, \ 3658 setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ 3659 setsigdef=(), scheduler=None) 3660 3661 Wraps the :c:func:`posix_spawn` C library API for use from Python. 3662 3663 Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`. 3664 3665 The positional-only arguments *path*, *args*, and *env* are similar to 3666 :func:`execve`. 3667 3668 The *path* parameter is the path to the executable file. The *path* should 3669 contain a directory. Use :func:`posix_spawnp` to pass an executable file 3670 without directory. 3671 3672 The *file_actions* argument may be a sequence of tuples describing actions 3673 to take on specific file descriptors in the child process between the C 3674 library implementation's :c:func:`fork` and :c:func:`exec` steps. 3675 The first item in each tuple must be one of the three type indicator 3676 listed below describing the remaining tuple elements: 3677 3678 .. data:: POSIX_SPAWN_OPEN 3679 3680 (``os.POSIX_SPAWN_OPEN``, *fd*, *path*, *flags*, *mode*) 3681 3682 Performs ``os.dup2(os.open(path, flags, mode), fd)``. 3683 3684 .. data:: POSIX_SPAWN_CLOSE 3685 3686 (``os.POSIX_SPAWN_CLOSE``, *fd*) 3687 3688 Performs ``os.close(fd)``. 3689 3690 .. data:: POSIX_SPAWN_DUP2 3691 3692 (``os.POSIX_SPAWN_DUP2``, *fd*, *new_fd*) 3693 3694 Performs ``os.dup2(fd, new_fd)``. 3695 3696 These tuples correspond to the C library 3697 :c:func:`posix_spawn_file_actions_addopen`, 3698 :c:func:`posix_spawn_file_actions_addclose`, and 3699 :c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare 3700 for the :c:func:`posix_spawn` call itself. 3701 3702 The *setpgroup* argument will set the process group of the child to the value 3703 specified. If the value specified is 0, the child's process group ID will be 3704 made the same as its process ID. If the value of *setpgroup* is not set, the 3705 child will inherit the parent's process group ID. This argument corresponds 3706 to the C library :c:data:`POSIX_SPAWN_SETPGROUP` flag. 3707 3708 If the *resetids* argument is ``True`` it will reset the effective UID and 3709 GID of the child to the real UID and GID of the parent process. If the 3710 argument is ``False``, then the child retains the effective UID and GID of 3711 the parent. In either case, if the set-user-ID and set-group-ID permission 3712 bits are enabled on the executable file, their effect will override the 3713 setting of the effective UID and GID. This argument corresponds to the C 3714 library :c:data:`POSIX_SPAWN_RESETIDS` flag. 3715 3716 If the *setsid* argument is ``True``, it will create a new session ID 3717 for `posix_spawn`. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` 3718 or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` 3719 is raised. 3720 3721 The *setsigmask* argument will set the signal mask to the signal set 3722 specified. If the parameter is not used, then the child inherits the 3723 parent's signal mask. This argument corresponds to the C library 3724 :c:data:`POSIX_SPAWN_SETSIGMASK` flag. 3725 3726 The *sigdef* argument will reset the disposition of all signals in the set 3727 specified. This argument corresponds to the C library 3728 :c:data:`POSIX_SPAWN_SETSIGDEF` flag. 3729 3730 The *scheduler* argument must be a tuple containing the (optional) scheduler 3731 policy and an instance of :class:`sched_param` with the scheduler parameters. 3732 A value of ``None`` in the place of the scheduler policy indicates that is 3733 not being provided. This argument is a combination of the C library 3734 :c:data:`POSIX_SPAWN_SETSCHEDPARAM` and :c:data:`POSIX_SPAWN_SETSCHEDULER` 3735 flags. 3736 3737 .. audit-event:: os.posix_spawn path,argv,env os.posix_spawn 3738 3739 .. versionadded:: 3.8 3740 3741 .. availability:: Unix. 3742 3743.. function:: posix_spawnp(path, argv, env, *, file_actions=None, \ 3744 setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ 3745 setsigdef=(), scheduler=None) 3746 3747 Wraps the :c:func:`posix_spawnp` C library API for use from Python. 3748 3749 Similar to :func:`posix_spawn` except that the system searches 3750 for the *executable* file in the list of directories specified by the 3751 :envvar:`PATH` environment variable (in the same way as for ``execvp(3)``). 3752 3753 .. audit-event:: os.posix_spawn path,argv,env os.posix_spawnp 3754 3755 .. versionadded:: 3.8 3756 3757 .. availability:: See :func:`posix_spawn` documentation. 3758 3759 3760.. function:: register_at_fork(*, before=None, after_in_parent=None, \ 3761 after_in_child=None) 3762 3763 Register callables to be executed when a new child process is forked 3764 using :func:`os.fork` or similar process cloning APIs. 3765 The parameters are optional and keyword-only. 3766 Each specifies a different call point. 3767 3768 * *before* is a function called before forking a child process. 3769 * *after_in_parent* is a function called from the parent process 3770 after forking a child process. 3771 * *after_in_child* is a function called from the child process. 3772 3773 These calls are only made if control is expected to return to the 3774 Python interpreter. A typical :mod:`subprocess` launch will not 3775 trigger them as the child is not going to re-enter the interpreter. 3776 3777 Functions registered for execution before forking are called in 3778 reverse registration order. Functions registered for execution 3779 after forking (either in the parent or in the child) are called 3780 in registration order. 3781 3782 Note that :c:func:`fork` calls made by third-party C code may not 3783 call those functions, unless it explicitly calls :c:func:`PyOS_BeforeFork`, 3784 :c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`. 3785 3786 There is no way to unregister a function. 3787 3788 .. availability:: Unix. 3789 3790 .. versionadded:: 3.7 3791 3792 3793.. function:: spawnl(mode, path, ...) 3794 spawnle(mode, path, ..., env) 3795 spawnlp(mode, file, ...) 3796 spawnlpe(mode, file, ..., env) 3797 spawnv(mode, path, args) 3798 spawnve(mode, path, args, env) 3799 spawnvp(mode, file, args) 3800 spawnvpe(mode, file, args, env) 3801 3802 Execute the program *path* in a new process. 3803 3804 (Note that the :mod:`subprocess` module provides more powerful facilities for 3805 spawning new processes and retrieving their results; using that module is 3806 preferable to using these functions. Check especially the 3807 :ref:`subprocess-replacements` section.) 3808 3809 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new 3810 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it 3811 exits normally, or ``-signal``, where *signal* is the signal that killed the 3812 process. On Windows, the process id will actually be the process handle, so can 3813 be used with the :func:`waitpid` function. 3814 3815 Note on VxWorks, this function doesn't return ``-signal`` when the new process is 3816 killed. Instead it raises OSError exception. 3817 3818 The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how 3819 command-line arguments are passed. The "l" variants are perhaps the easiest 3820 to work with if the number of parameters is fixed when the code is written; the 3821 individual parameters simply become additional parameters to the 3822 :func:`spawnl\*` functions. The "v" variants are good when the number of 3823 parameters is variable, with the arguments being passed in a list or tuple as 3824 the *args* parameter. In either case, the arguments to the child process must 3825 start with the name of the command being run. 3826 3827 The variants which include a second "p" near the end (:func:`spawnlp`, 3828 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the 3829 :envvar:`PATH` environment variable to locate the program *file*. When the 3830 environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants, 3831 discussed in the next paragraph), the new environment is used as the source of 3832 the :envvar:`PATH` variable. The other variants, :func:`spawnl`, 3833 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the 3834 :envvar:`PATH` variable to locate the executable; *path* must contain an 3835 appropriate absolute or relative path. 3836 3837 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` 3838 (note that these all end in "e"), the *env* parameter must be a mapping 3839 which is used to define the environment variables for the new process (they are 3840 used instead of the current process' environment); the functions 3841 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause 3842 the new process to inherit the environment of the current process. Note that 3843 keys and values in the *env* dictionary must be strings; invalid keys or 3844 values will cause the function to fail, with a return value of ``127``. 3845 3846 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are 3847 equivalent:: 3848 3849 import os 3850 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') 3851 3852 L = ['cp', 'index.html', '/dev/null'] 3853 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) 3854 3855 .. audit-event:: os.spawn mode,path,args,env os.spawnl 3856 3857 .. availability:: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp` 3858 and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and 3859 :func:`spawnve` are not thread-safe on Windows; we advise you to use the 3860 :mod:`subprocess` module instead. 3861 3862 .. versionchanged:: 3.6 3863 Accepts a :term:`path-like object`. 3864 3865 3866.. data:: P_NOWAIT 3867 P_NOWAITO 3868 3869 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 3870 functions. If either of these values is given, the :func:`spawn\*` functions 3871 will return as soon as the new process has been created, with the process id as 3872 the return value. 3873 3874 .. availability:: Unix, Windows. 3875 3876 3877.. data:: P_WAIT 3878 3879 Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 3880 functions. If this is given as *mode*, the :func:`spawn\*` functions will not 3881 return until the new process has run to completion and will return the exit code 3882 of the process the run is successful, or ``-signal`` if a signal kills the 3883 process. 3884 3885 .. availability:: Unix, Windows. 3886 3887 3888.. data:: P_DETACH 3889 P_OVERLAY 3890 3891 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of 3892 functions. These are less portable than those listed above. :const:`P_DETACH` 3893 is similar to :const:`P_NOWAIT`, but the new process is detached from the 3894 console of the calling process. If :const:`P_OVERLAY` is used, the current 3895 process will be replaced; the :func:`spawn\* <spawnl>` function will not return. 3896 3897 .. availability:: Windows. 3898 3899 3900.. function:: startfile(path[, operation]) 3901 3902 Start a file with its associated application. 3903 3904 When *operation* is not specified or ``'open'``, this acts like double-clicking 3905 the file in Windows Explorer, or giving the file name as an argument to the 3906 :program:`start` command from the interactive command shell: the file is opened 3907 with whatever application (if any) its extension is associated. 3908 3909 When another *operation* is given, it must be a "command verb" that specifies 3910 what should be done with the file. Common verbs documented by Microsoft are 3911 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and 3912 ``'find'`` (to be used on directories). 3913 3914 :func:`startfile` returns as soon as the associated application is launched. 3915 There is no option to wait for the application to close, and no way to retrieve 3916 the application's exit status. The *path* parameter is relative to the current 3917 directory. If you want to use an absolute path, make sure the first character 3918 is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function 3919 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that 3920 the path is properly encoded for Win32. 3921 3922 To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute` 3923 function is not resolved until this function is first called. If the function 3924 cannot be resolved, :exc:`NotImplementedError` will be raised. 3925 3926 .. audit-event:: os.startfile path,operation os.startfile 3927 3928 .. availability:: Windows. 3929 3930 3931.. function:: system(command) 3932 3933 Execute the command (a string) in a subshell. This is implemented by calling 3934 the Standard C function :c:func:`system`, and has the same limitations. 3935 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of 3936 the executed command. If *command* generates any output, it will be sent to 3937 the interpreter standard output stream. 3938 3939 On Unix, the return value is the exit status of the process encoded in the 3940 format specified for :func:`wait`. Note that POSIX does not specify the 3941 meaning of the return value of the C :c:func:`system` function, so the return 3942 value of the Python function is system-dependent. 3943 3944 On Windows, the return value is that returned by the system shell after 3945 running *command*. The shell is given by the Windows environment variable 3946 :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit 3947 status of the command run; on systems using a non-native shell, consult your 3948 shell documentation. 3949 3950 The :mod:`subprocess` module provides more powerful facilities for spawning 3951 new processes and retrieving their results; using that module is preferable 3952 to using this function. See the :ref:`subprocess-replacements` section in 3953 the :mod:`subprocess` documentation for some helpful recipes. 3954 3955 .. audit-event:: os.system command os.system 3956 3957 .. availability:: Unix, Windows. 3958 3959 3960.. function:: times() 3961 3962 Returns the current global process times. 3963 The return value is an object with five attributes: 3964 3965 * :attr:`user` - user time 3966 * :attr:`system` - system time 3967 * :attr:`children_user` - user time of all child processes 3968 * :attr:`children_system` - system time of all child processes 3969 * :attr:`elapsed` - elapsed real time since a fixed point in the past 3970 3971 For backwards compatibility, this object also behaves like a five-tuple 3972 containing :attr:`user`, :attr:`system`, :attr:`children_user`, 3973 :attr:`children_system`, and :attr:`elapsed` in that order. 3974 3975 See the Unix manual page 3976 :manpage:`times(2)` and :manpage:`times(3)` manual page on Unix or `the GetProcessTimes MSDN 3977 <https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes>`_ 3978 on Windows. On Windows, only :attr:`user` and :attr:`system` are known; the other attributes are zero. 3979 3980 .. availability:: Unix, Windows. 3981 3982 .. versionchanged:: 3.3 3983 Return type changed from a tuple to a tuple-like object 3984 with named attributes. 3985 3986 3987.. function:: wait() 3988 3989 Wait for completion of a child process, and return a tuple containing its pid 3990 and exit status indication: a 16-bit number, whose low byte is the signal number 3991 that killed the process, and whose high byte is the exit status (if the signal 3992 number is zero); the high bit of the low byte is set if a core file was 3993 produced. 3994 3995 .. availability:: Unix. 3996 3997.. function:: waitid(idtype, id, options) 3998 3999 Wait for the completion of one or more child processes. 4000 *idtype* can be :data:`P_PID`, :data:`P_PGID` or :data:`P_ALL`. 4001 *id* specifies the pid to wait on. 4002 *options* is constructed from the ORing of one or more of :data:`WEXITED`, 4003 :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with 4004 :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object 4005 representing the data contained in the :c:type:`siginfo_t` structure, namely: 4006 :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`, 4007 :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no 4008 children in a waitable state. 4009 4010 .. availability:: Unix. 4011 4012 .. versionadded:: 3.3 4013 4014.. data:: P_PID 4015 P_PGID 4016 P_ALL 4017 4018 These are the possible values for *idtype* in :func:`waitid`. They affect 4019 how *id* is interpreted. 4020 4021 .. availability:: Unix. 4022 4023 .. versionadded:: 3.3 4024 4025.. data:: WEXITED 4026 WSTOPPED 4027 WNOWAIT 4028 4029 Flags that can be used in *options* in :func:`waitid` that specify what 4030 child signal to wait for. 4031 4032 .. availability:: Unix. 4033 4034 .. versionadded:: 3.3 4035 4036 4037.. data:: CLD_EXITED 4038 CLD_DUMPED 4039 CLD_TRAPPED 4040 CLD_CONTINUED 4041 4042 These are the possible values for :attr:`si_code` in the result returned by 4043 :func:`waitid`. 4044 4045 .. availability:: Unix. 4046 4047 .. versionadded:: 3.3 4048 4049 4050.. function:: waitpid(pid, options) 4051 4052 The details of this function differ on Unix and Windows. 4053 4054 On Unix: Wait for completion of a child process given by process id *pid*, and 4055 return a tuple containing its process id and exit status indication (encoded as 4056 for :func:`wait`). The semantics of the call are affected by the value of the 4057 integer *options*, which should be ``0`` for normal operation. 4058 4059 If *pid* is greater than ``0``, :func:`waitpid` requests status information for 4060 that specific process. If *pid* is ``0``, the request is for the status of any 4061 child in the process group of the current process. If *pid* is ``-1``, the 4062 request pertains to any child of the current process. If *pid* is less than 4063 ``-1``, status is requested for any process in the process group ``-pid`` (the 4064 absolute value of *pid*). 4065 4066 An :exc:`OSError` is raised with the value of errno when the syscall 4067 returns -1. 4068 4069 On Windows: Wait for completion of a process given by process handle *pid*, and 4070 return a tuple containing *pid*, and its exit status shifted left by 8 bits 4071 (shifting makes cross-platform use of the function easier). A *pid* less than or 4072 equal to ``0`` has no special meaning on Windows, and raises an exception. The 4073 value of integer *options* has no effect. *pid* can refer to any process whose 4074 id is known, not necessarily a child process. The :func:`spawn\* <spawnl>` 4075 functions called with :const:`P_NOWAIT` return suitable process handles. 4076 4077 .. versionchanged:: 3.5 4078 If the system call is interrupted and the signal handler does not raise an 4079 exception, the function now retries the system call instead of raising an 4080 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 4081 4082 4083.. function:: wait3(options) 4084 4085 Similar to :func:`waitpid`, except no process id argument is given and a 4086 3-element tuple containing the child's process id, exit status indication, 4087 and resource usage information is returned. Refer to 4088 :mod:`resource`.\ :func:`~resource.getrusage` for details on resource usage 4089 information. The option argument is the same as that provided to 4090 :func:`waitpid` and :func:`wait4`. 4091 4092 .. availability:: Unix. 4093 4094 4095.. function:: wait4(pid, options) 4096 4097 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's 4098 process id, exit status indication, and resource usage information is returned. 4099 Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on 4100 resource usage information. The arguments to :func:`wait4` are the same 4101 as those provided to :func:`waitpid`. 4102 4103 .. availability:: Unix. 4104 4105 4106.. data:: WNOHANG 4107 4108 The option for :func:`waitpid` to return immediately if no child process status 4109 is available immediately. The function returns ``(0, 0)`` in this case. 4110 4111 .. availability:: Unix. 4112 4113 4114.. data:: WCONTINUED 4115 4116 This option causes child processes to be reported if they have been continued 4117 from a job control stop since their status was last reported. 4118 4119 .. availability:: some Unix systems. 4120 4121 4122.. data:: WUNTRACED 4123 4124 This option causes child processes to be reported if they have been stopped but 4125 their current state has not been reported since they were stopped. 4126 4127 .. availability:: Unix. 4128 4129 4130The following functions take a process status code as returned by 4131:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be 4132used to determine the disposition of a process. 4133 4134.. function:: WCOREDUMP(status) 4135 4136 Return ``True`` if a core dump was generated for the process, otherwise 4137 return ``False``. 4138 4139 This function should be employed only if :func:`WIFSIGNALED` is true. 4140 4141 .. availability:: Unix. 4142 4143 4144.. function:: WIFCONTINUED(status) 4145 4146 Return ``True`` if a stopped child has been resumed by delivery of 4147 :data:`~signal.SIGCONT` (if the process has been continued from a job 4148 control stop), otherwise return ``False``. 4149 4150 See :data:`WCONTINUED` option. 4151 4152 .. availability:: Unix. 4153 4154 4155.. function:: WIFSTOPPED(status) 4156 4157 Return ``True`` if the process was stopped by delivery of a signal, 4158 otherwise return ``False``. 4159 4160 :func:`WIFSTOPPED` only returns ``True`` if the :func:`waitpid` call was 4161 done using :data:`WUNTRACED` option or when the process is being traced (see 4162 :manpage:`ptrace(2)`). 4163 4164 .. availability:: Unix. 4165 4166.. function:: WIFSIGNALED(status) 4167 4168 Return ``True`` if the process was terminated by a signal, otherwise return 4169 ``False``. 4170 4171 .. availability:: Unix. 4172 4173 4174.. function:: WIFEXITED(status) 4175 4176 Return ``True`` if the process exited terminated normally, that is, 4177 by calling ``exit()`` or ``_exit()``, or by returning from ``main()``; 4178 otherwise return ``False``. 4179 4180 .. availability:: Unix. 4181 4182 4183.. function:: WEXITSTATUS(status) 4184 4185 Return the process exit status. 4186 4187 This function should be employed only if :func:`WIFEXITED` is true. 4188 4189 .. availability:: Unix. 4190 4191 4192.. function:: WSTOPSIG(status) 4193 4194 Return the signal which caused the process to stop. 4195 4196 This function should be employed only if :func:`WIFSTOPPED` is true. 4197 4198 .. availability:: Unix. 4199 4200 4201.. function:: WTERMSIG(status) 4202 4203 Return the number of the signal that caused the process to terminate. 4204 4205 This function should be employed only if :func:`WIFSIGNALED` is true. 4206 4207 .. availability:: Unix. 4208 4209 4210Interface to the scheduler 4211-------------------------- 4212 4213These functions control how a process is allocated CPU time by the operating 4214system. They are only available on some Unix platforms. For more detailed 4215information, consult your Unix manpages. 4216 4217.. versionadded:: 3.3 4218 4219The following scheduling policies are exposed if they are supported by the 4220operating system. 4221 4222.. data:: SCHED_OTHER 4223 4224 The default scheduling policy. 4225 4226.. data:: SCHED_BATCH 4227 4228 Scheduling policy for CPU-intensive processes that tries to preserve 4229 interactivity on the rest of the computer. 4230 4231.. data:: SCHED_IDLE 4232 4233 Scheduling policy for extremely low priority background tasks. 4234 4235.. data:: SCHED_SPORADIC 4236 4237 Scheduling policy for sporadic server programs. 4238 4239.. data:: SCHED_FIFO 4240 4241 A First In First Out scheduling policy. 4242 4243.. data:: SCHED_RR 4244 4245 A round-robin scheduling policy. 4246 4247.. data:: SCHED_RESET_ON_FORK 4248 4249 This flag can be OR'ed with any other scheduling policy. When a process with 4250 this flag set forks, its child's scheduling policy and priority are reset to 4251 the default. 4252 4253 4254.. class:: sched_param(sched_priority) 4255 4256 This class represents tunable scheduling parameters used in 4257 :func:`sched_setparam`, :func:`sched_setscheduler`, and 4258 :func:`sched_getparam`. It is immutable. 4259 4260 At the moment, there is only one possible parameter: 4261 4262 .. attribute:: sched_priority 4263 4264 The scheduling priority for a scheduling policy. 4265 4266 4267.. function:: sched_get_priority_min(policy) 4268 4269 Get the minimum priority value for *policy*. *policy* is one of the 4270 scheduling policy constants above. 4271 4272 4273.. function:: sched_get_priority_max(policy) 4274 4275 Get the maximum priority value for *policy*. *policy* is one of the 4276 scheduling policy constants above. 4277 4278 4279.. function:: sched_setscheduler(pid, policy, param) 4280 4281 Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means 4282 the calling process. *policy* is one of the scheduling policy constants 4283 above. *param* is a :class:`sched_param` instance. 4284 4285 4286.. function:: sched_getscheduler(pid) 4287 4288 Return the scheduling policy for the process with PID *pid*. A *pid* of 0 4289 means the calling process. The result is one of the scheduling policy 4290 constants above. 4291 4292 4293.. function:: sched_setparam(pid, param) 4294 4295 Set a scheduling parameters for the process with PID *pid*. A *pid* of 0 means 4296 the calling process. *param* is a :class:`sched_param` instance. 4297 4298 4299.. function:: sched_getparam(pid) 4300 4301 Return the scheduling parameters as a :class:`sched_param` instance for the 4302 process with PID *pid*. A *pid* of 0 means the calling process. 4303 4304 4305.. function:: sched_rr_get_interval(pid) 4306 4307 Return the round-robin quantum in seconds for the process with PID *pid*. A 4308 *pid* of 0 means the calling process. 4309 4310 4311.. function:: sched_yield() 4312 4313 Voluntarily relinquish the CPU. 4314 4315 4316.. function:: sched_setaffinity(pid, mask) 4317 4318 Restrict the process with PID *pid* (or the current process if zero) to a 4319 set of CPUs. *mask* is an iterable of integers representing the set of 4320 CPUs to which the process should be restricted. 4321 4322 4323.. function:: sched_getaffinity(pid) 4324 4325 Return the set of CPUs the process with PID *pid* (or the current process 4326 if zero) is restricted to. 4327 4328 4329.. _os-path: 4330 4331Miscellaneous System Information 4332-------------------------------- 4333 4334 4335.. function:: confstr(name) 4336 4337 Return string-valued system configuration values. *name* specifies the 4338 configuration value to retrieve; it may be a string which is the name of a 4339 defined system value; these names are specified in a number of standards (POSIX, 4340 Unix 95, Unix 98, and others). Some platforms define additional names as well. 4341 The names known to the host operating system are given as the keys of the 4342 ``confstr_names`` dictionary. For configuration variables not included in that 4343 mapping, passing an integer for *name* is also accepted. 4344 4345 If the configuration value specified by *name* isn't defined, ``None`` is 4346 returned. 4347 4348 If *name* is a string and is not known, :exc:`ValueError` is raised. If a 4349 specific value for *name* is not supported by the host system, even if it is 4350 included in ``confstr_names``, an :exc:`OSError` is raised with 4351 :const:`errno.EINVAL` for the error number. 4352 4353 .. availability:: Unix. 4354 4355 4356.. data:: confstr_names 4357 4358 Dictionary mapping names accepted by :func:`confstr` to the integer values 4359 defined for those names by the host operating system. This can be used to 4360 determine the set of names known to the system. 4361 4362 .. availability:: Unix. 4363 4364 4365.. function:: cpu_count() 4366 4367 Return the number of CPUs in the system. Returns ``None`` if undetermined. 4368 4369 This number is not equivalent to the number of CPUs the current process can 4370 use. The number of usable CPUs can be obtained with 4371 ``len(os.sched_getaffinity(0))`` 4372 4373 4374 .. versionadded:: 3.4 4375 4376 4377.. function:: getloadavg() 4378 4379 Return the number of processes in the system run queue averaged over the last 4380 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was 4381 unobtainable. 4382 4383 .. availability:: Unix. 4384 4385 4386.. function:: sysconf(name) 4387 4388 Return integer-valued system configuration values. If the configuration value 4389 specified by *name* isn't defined, ``-1`` is returned. The comments regarding 4390 the *name* parameter for :func:`confstr` apply here as well; the dictionary that 4391 provides information on the known names is given by ``sysconf_names``. 4392 4393 .. availability:: Unix. 4394 4395 4396.. data:: sysconf_names 4397 4398 Dictionary mapping names accepted by :func:`sysconf` to the integer values 4399 defined for those names by the host operating system. This can be used to 4400 determine the set of names known to the system. 4401 4402 .. availability:: Unix. 4403 4404The following data values are used to support path manipulation operations. These 4405are defined for all platforms. 4406 4407Higher-level operations on pathnames are defined in the :mod:`os.path` module. 4408 4409 4410.. index:: single: . (dot); in pathnames 4411.. data:: curdir 4412 4413 The constant string used by the operating system to refer to the current 4414 directory. This is ``'.'`` for Windows and POSIX. Also available via 4415 :mod:`os.path`. 4416 4417 4418.. index:: single: ..; in pathnames 4419.. data:: pardir 4420 4421 The constant string used by the operating system to refer to the parent 4422 directory. This is ``'..'`` for Windows and POSIX. Also available via 4423 :mod:`os.path`. 4424 4425 4426.. index:: single: / (slash); in pathnames 4427.. index:: single: \ (backslash); in pathnames (Windows) 4428.. data:: sep 4429 4430 The character used by the operating system to separate pathname components. 4431 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this 4432 is not sufficient to be able to parse or concatenate pathnames --- use 4433 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally 4434 useful. Also available via :mod:`os.path`. 4435 4436 4437.. index:: single: / (slash); in pathnames 4438.. data:: altsep 4439 4440 An alternative character used by the operating system to separate pathname 4441 components, or ``None`` if only one separator character exists. This is set to 4442 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via 4443 :mod:`os.path`. 4444 4445 4446.. index:: single: . (dot); in pathnames 4447.. data:: extsep 4448 4449 The character which separates the base filename from the extension; for example, 4450 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`. 4451 4452 4453.. index:: single: : (colon); path separator (POSIX) 4454 single: ; (semicolon) 4455.. data:: pathsep 4456 4457 The character conventionally used by the operating system to separate search 4458 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for 4459 Windows. Also available via :mod:`os.path`. 4460 4461 4462.. data:: defpath 4463 4464 The default search path used by :func:`exec\*p\* <execl>` and 4465 :func:`spawn\*p\* <spawnl>` if the environment doesn't have a ``'PATH'`` 4466 key. Also available via :mod:`os.path`. 4467 4468 4469.. data:: linesep 4470 4471 The string used to separate (or, rather, terminate) lines on the current 4472 platform. This may be a single character, such as ``'\n'`` for POSIX, or 4473 multiple characters, for example, ``'\r\n'`` for Windows. Do not use 4474 *os.linesep* as a line terminator when writing files opened in text mode (the 4475 default); use a single ``'\n'`` instead, on all platforms. 4476 4477 4478.. data:: devnull 4479 4480 The file path of the null device. For example: ``'/dev/null'`` for 4481 POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. 4482 4483.. data:: RTLD_LAZY 4484 RTLD_NOW 4485 RTLD_GLOBAL 4486 RTLD_LOCAL 4487 RTLD_NODELETE 4488 RTLD_NOLOAD 4489 RTLD_DEEPBIND 4490 4491 Flags for use with the :func:`~sys.setdlopenflags` and 4492 :func:`~sys.getdlopenflags` functions. See the Unix manual page 4493 :manpage:`dlopen(3)` for what the different flags mean. 4494 4495 .. versionadded:: 3.3 4496 4497 4498Random numbers 4499-------------- 4500 4501 4502.. function:: getrandom(size, flags=0) 4503 4504 Get up to *size* random bytes. The function can return less bytes than 4505 requested. 4506 4507 These bytes can be used to seed user-space random number generators or for 4508 cryptographic purposes. 4509 4510 ``getrandom()`` relies on entropy gathered from device drivers and other 4511 sources of environmental noise. Unnecessarily reading large quantities of 4512 data will have a negative impact on other users of the ``/dev/random`` and 4513 ``/dev/urandom`` devices. 4514 4515 The flags argument is a bit mask that can contain zero or more of the 4516 following values ORed together: :py:data:`os.GRND_RANDOM` and 4517 :py:data:`GRND_NONBLOCK`. 4518 4519 See also the `Linux getrandom() manual page 4520 <http://man7.org/linux/man-pages/man2/getrandom.2.html>`_. 4521 4522 .. availability:: Linux 3.17 and newer. 4523 4524 .. versionadded:: 3.6 4525 4526.. function:: urandom(size) 4527 4528 Return a string of *size* random bytes suitable for cryptographic use. 4529 4530 This function returns random bytes from an OS-specific randomness source. The 4531 returned data should be unpredictable enough for cryptographic applications, 4532 though its exact quality depends on the OS implementation. 4533 4534 On Linux, if the ``getrandom()`` syscall is available, it is used in 4535 blocking mode: block until the system urandom entropy pool is initialized 4536 (128 bits of entropy are collected by the kernel). See the :pep:`524` for 4537 the rationale. On Linux, the :func:`getrandom` function can be used to get 4538 random bytes in non-blocking mode (using the :data:`GRND_NONBLOCK` flag) or 4539 to poll until the system urandom entropy pool is initialized. 4540 4541 On a Unix-like system, random bytes are read from the ``/dev/urandom`` 4542 device. If the ``/dev/urandom`` device is not available or not readable, the 4543 :exc:`NotImplementedError` exception is raised. 4544 4545 On Windows, it will use ``CryptGenRandom()``. 4546 4547 .. seealso:: 4548 The :mod:`secrets` module provides higher level functions. For an 4549 easy-to-use interface to the random number generator provided by your 4550 platform, please see :class:`random.SystemRandom`. 4551 4552 .. versionchanged:: 3.6.0 4553 On Linux, ``getrandom()`` is now used in blocking mode to increase the 4554 security. 4555 4556 .. versionchanged:: 3.5.2 4557 On Linux, if the ``getrandom()`` syscall blocks (the urandom entropy pool 4558 is not initialized yet), fall back on reading ``/dev/urandom``. 4559 4560 .. versionchanged:: 3.5 4561 On Linux 3.17 and newer, the ``getrandom()`` syscall is now used 4562 when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` 4563 function is now used. These functions avoid the usage of an internal file 4564 descriptor. 4565 4566.. data:: GRND_NONBLOCK 4567 4568 By default, when reading from ``/dev/random``, :func:`getrandom` blocks if 4569 no random bytes are available, and when reading from ``/dev/urandom``, it blocks 4570 if the entropy pool has not yet been initialized. 4571 4572 If the :py:data:`GRND_NONBLOCK` flag is set, then :func:`getrandom` does not 4573 block in these cases, but instead immediately raises :exc:`BlockingIOError`. 4574 4575 .. versionadded:: 3.6 4576 4577.. data:: GRND_RANDOM 4578 4579 If this bit is set, then random bytes are drawn from the 4580 ``/dev/random`` pool instead of the ``/dev/urandom`` pool. 4581 4582 .. versionadded:: 3.6 4583