Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(18)

Delta Between Two Patch Sets: Doc/library/os.rst

Issue 26826: Expose new copy_file_range() syscal in os module and use it to improve shutils.copy()
Left Patch Set: Created 4 years, 1 month ago
Right Patch Set: Created 3 years, 11 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « configure.ac ('k') | Lib/test/test_os.py » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`os` --- Miscellaneous operating system interfaces 1 :mod:`os` --- Miscellaneous operating system interfaces
2 ======================================================= 2 =======================================================
3 3
4 .. module:: os 4 .. module:: os
5 :synopsis: Miscellaneous operating system interfaces. 5 :synopsis: Miscellaneous operating system interfaces.
6 6
7 7
8 This module provides a portable way of using operating system dependent 8 This module provides a portable way of using operating system dependent
9 functionality. If you just want to read or write a file see :func:`open`, if 9 functionality. If you just want to read or write a file see :func:`open`, if
10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to 10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
(...skipping 166 matching lines...) Expand 10 before | Expand all | Expand 10 after
177 177
178 178
179 .. function:: fsdecode(filename) 179 .. function:: fsdecode(filename)
180 180
181 Decode *filename* from the filesystem encoding with ``'surrogateescape'`` 181 Decode *filename* from the filesystem encoding with ``'surrogateescape'``
182 error handler, or ``'strict'`` on Windows; return :class:`str` unchanged. 182 error handler, or ``'strict'`` on Windows; return :class:`str` unchanged.
183 183
184 :func:`fsencode` is the reverse function. 184 :func:`fsencode` is the reverse function.
185 185
186 .. versionadded:: 3.2 186 .. versionadded:: 3.2
187
188
189 .. function:: fspath(path)
190
191 Return the string representation of the path.
192
193 If :class:`str` or :class:`bytes` is passed in, it is returned unchanged;
194 otherwise, the result of calling ``type(path).__fspath__`` is returned, or an
195 exception is raised.
187 196
188 197
189 .. function:: getenv(key, default=None) 198 .. function:: getenv(key, default=None)
190 199
191 Return the value of the environment variable *key* if it exists, or 200 Return the value of the environment variable *key* if it exists, or
192 *default* if it doesn't. *key*, *default* and the result are str. 201 *default* if it doesn't. *key*, *default* and the result are str.
193 202
194 On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding` 203 On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
195 and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you 204 and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
196 would like to use a different encoding. 205 would like to use a different encoding.
(...skipping 467 matching lines...) Expand 10 before | Expand all | Expand 10 after
664 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive) , 673 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive) ,
665 ignoring errors. Equivalent to (but much faster than):: 674 ignoring errors. Equivalent to (but much faster than)::
666 675
667 for fd in range(fd_low, fd_high): 676 for fd in range(fd_low, fd_high):
668 try: 677 try:
669 os.close(fd) 678 os.close(fd)
670 except OSError: 679 except OSError:
671 pass 680 pass
672 681
673 682
674 .. function:: copy_file_range(in, offset_in, out, offset_out, count, flags=0) 683 .. function:: copy_file_range(src, dst, count, offset_src=None, offset_dst=None)
675 684
676 Copy *count* bytes from file descriptor *in*, starting from offset 685 Copy *count* bytes from file descriptor *src*, starting from offset
677 *offset_in*, to file descriptor *out*, starting from offset *offset_out*. 686 *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
678 If *offset_in* is None, then *in* is read from the current position; 687 If *offset_src* is None, then *src* is read from the current position;
679 respectively for *offset_out*. *in* and *out* must reside in the same 688 respectively for *offset_dst*. The files pointed by *src* and *dst*
680 filesystem, otherwise a *OSError* is raised with *errno* set to *errno.EXDEV* . 689 must reside in the same filesystem, otherwise a :exc:`OSError` is
690 raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`.
681 691
682 This copy is done without using any user space buffers, and some 692 This copy is done without using any user space buffers, and some
683 filesystems could implement optimizations. Because of this, errors 693 filesystems could implement optimizations. The copy is done as if
684 like UnicodeDecodingError will not arise on files opened in text mode 694 both files are opened as binary.
685 with the wrong encoding. 695
686 696 The return value is the amount of bytes copied. This could be less than the
687 The flags argument is provided to allow for future extensions and 697 amount requested.
688 currently must be set to 0. 698
689 699 Availability: Linux 4.5, released May 2016 (see the man page
690 Availability: some recent flavors of Unix (see the man page
691 :manpage:`copy_file_range(2)` for further information). 700 :manpage:`copy_file_range(2)` for further information).
692 701
693 .. versionadded:: 3.6 702 .. versionadded:: 3.6
694 703
695 .. function:: device_encoding(fd) 704 .. function:: device_encoding(fd)
696 705
697 Return a string describing the encoding of the device associated with *fd* 706 Return a string describing the encoding of the device associated with *fd*
698 if it is connected to a terminal; else return :const:`None`. 707 if it is connected to a terminal; else return :const:`None`.
699 708
700 709
(...skipping 2820 matching lines...) Expand 10 before | Expand all | Expand 10 after
3521 .. data:: SCHED_FIFO 3530 .. data:: SCHED_FIFO
3522 3531
3523 A First In First Out scheduling policy. 3532 A First In First Out scheduling policy.
3524 3533
3525 .. data:: SCHED_RR 3534 .. data:: SCHED_RR
3526 3535
3527 A round-robin scheduling policy. 3536 A round-robin scheduling policy.
3528 3537
3529 .. data:: SCHED_RESET_ON_FORK 3538 .. data:: SCHED_RESET_ON_FORK
3530 3539
3531 This flag can OR'ed with any other scheduling policy. When a process with 3540 This flag can be OR'ed with any other scheduling policy. When a process with
3532 this flag set forks, its child's scheduling policy and priority are reset to 3541 this flag set forks, its child's scheduling policy and priority are reset to
3533 the default. 3542 the default.
3534 3543
3535 3544
3536 .. class:: sched_param(sched_priority) 3545 .. class:: sched_param(sched_priority)
3537 3546
3538 This class represents tunable scheduling parameters used in 3547 This class represents tunable scheduling parameters used in
3539 :func:`sched_setparam`, :func:`sched_setscheduler`, and 3548 :func:`sched_setparam`, :func:`sched_setscheduler`, and
3540 :func:`sched_getparam`. It is immutable. 3549 :func:`sched_getparam`. It is immutable.
3541 3550
(...skipping 231 matching lines...) Expand 10 before | Expand all | Expand 10 after
3773 Miscellaneous Functions 3782 Miscellaneous Functions
3774 ----------------------- 3783 -----------------------
3775 3784
3776 3785
3777 .. function:: urandom(n) 3786 .. function:: urandom(n)
3778 3787
3779 Return a string of *n* random bytes suitable for cryptographic use. 3788 Return a string of *n* random bytes suitable for cryptographic use.
3780 3789
3781 This function returns random bytes from an OS-specific randomness source. Th e 3790 This function returns random bytes from an OS-specific randomness source. Th e
3782 returned data should be unpredictable enough for cryptographic applications, 3791 returned data should be unpredictable enough for cryptographic applications,
3783 though its exact quality depends on the OS implementation. On a Unix-like 3792 though its exact quality depends on the OS implementation.
3784 system this will query ``/dev/urandom``, and on Windows it will use 3793
3785 ``CryptGenRandom()``. If a randomness source is not found, 3794 On Linux, ``getrandom()`` syscall is used if available and the urandom
3795 entropy pool is initialized (``getrandom()`` does not block).
3796 On a Unix-like system this will query ``/dev/urandom``. On Windows, it
3797 will use ``CryptGenRandom()``. If a randomness source is not found,
3786 :exc:`NotImplementedError` will be raised. 3798 :exc:`NotImplementedError` will be raised.
3787 3799
3788 For an easy-to-use interface to the random number generator 3800 For an easy-to-use interface to the random number generator
3789 provided by your platform, please see :class:`random.SystemRandom`. 3801 provided by your platform, please see :class:`random.SystemRandom`.
3802
3803 .. versionchanged:: 3.5.2
3804 On Linux, if ``getrandom()`` blocks (the urandom entropy pool is not
3805 initialized yet), fall back on reading ``/dev/urandom``.
3790 3806
3791 .. versionchanged:: 3.5 3807 .. versionchanged:: 3.5
3792 On Linux 3.17 and newer, the ``getrandom()`` syscall is now used 3808 On Linux 3.17 and newer, the ``getrandom()`` syscall is now used
3793 when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` 3809 when available. On OpenBSD 5.6 and newer, the C ``getentropy()``
3794 function is now used. These functions avoid the usage of an internal file 3810 function is now used. These functions avoid the usage of an internal file
3795 descriptor. 3811 descriptor.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+