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

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 3 years, 9 months ago
Right Patch Set: Created 3 years, 7 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(src, dst, count, offset_src=None, offset_dst=None, 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 *src*, starting from offset 685 Copy *count* bytes from file descriptor *src*, starting from offset
677 *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*. 686 *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
678 If *offset_src* is None, then *src* is read from the current position; 687 If *offset_src* is None, then *src* is read from the current position;
679 respectively for *offset_dst*. The files pointed by *src* and *dst* 688 respectively for *offset_dst*. The files pointed by *src* and *dst*
680 must reside in the same filesystem, otherwise a :exc:`OSError` is 689 must reside in the same filesystem, otherwise a :exc:`OSError` is
681 raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`. 690 raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`.
682 691
683 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
684 filesystems could implement optimizations. The copy is done as if 693 filesystems could implement optimizations. The copy is done as if
685 both files are opened as binary, so no transcoding is possible. 694 both files are opened as binary.
686 695
687 The *flags* argument is provided for compatibility with the only currently 696 The return value is the amount of bytes copied. This could be less than the
688 supported implementation (Linux >=4.5) to allow for future extensions, and 697 amount requested.
689 currently can only be 0. 698
690 699 Availability: Linux 4.5, released May 2016 (see the man page
691 Availability: some recent flavors of Unix (see the man page
692 :manpage:`copy_file_range(2)` for further information). 700 :manpage:`copy_file_range(2)` for further information).
693 701
694 .. versionadded:: 3.6 702 .. versionadded:: 3.6
695 703
696 .. function:: device_encoding(fd) 704 .. function:: device_encoding(fd)
697 705
698 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*
699 if it is connected to a terminal; else return :const:`None`. 707 if it is connected to a terminal; else return :const:`None`.
700 708
701 709
(...skipping 2820 matching lines...) Expand 10 before | Expand all | Expand 10 after
3522 .. data:: SCHED_FIFO 3530 .. data:: SCHED_FIFO
3523 3531
3524 A First In First Out scheduling policy. 3532 A First In First Out scheduling policy.
3525 3533
3526 .. data:: SCHED_RR 3534 .. data:: SCHED_RR
3527 3535
3528 A round-robin scheduling policy. 3536 A round-robin scheduling policy.
3529 3537
3530 .. data:: SCHED_RESET_ON_FORK 3538 .. data:: SCHED_RESET_ON_FORK
3531 3539
3532 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
3533 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
3534 the default. 3542 the default.
3535 3543
3536 3544
3537 .. class:: sched_param(sched_priority) 3545 .. class:: sched_param(sched_priority)
3538 3546
3539 This class represents tunable scheduling parameters used in 3547 This class represents tunable scheduling parameters used in
3540 :func:`sched_setparam`, :func:`sched_setscheduler`, and 3548 :func:`sched_setparam`, :func:`sched_setscheduler`, and
3541 :func:`sched_getparam`. It is immutable. 3549 :func:`sched_getparam`. It is immutable.
3542 3550
(...skipping 231 matching lines...) Expand 10 before | Expand all | Expand 10 after
3774 Miscellaneous Functions 3782 Miscellaneous Functions
3775 ----------------------- 3783 -----------------------
3776 3784
3777 3785
3778 .. function:: urandom(n) 3786 .. function:: urandom(n)
3779 3787
3780 Return a string of *n* random bytes suitable for cryptographic use. 3788 Return a string of *n* random bytes suitable for cryptographic use.
3781 3789
3782 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
3783 returned data should be unpredictable enough for cryptographic applications, 3791 returned data should be unpredictable enough for cryptographic applications,
3784 though its exact quality depends on the OS implementation. On a Unix-like 3792 though its exact quality depends on the OS implementation.
3785 system this will query ``/dev/urandom``, and on Windows it will use 3793
3786 ``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,
3787 :exc:`NotImplementedError` will be raised. 3798 :exc:`NotImplementedError` will be raised.
3788 3799
3789 For an easy-to-use interface to the random number generator 3800 For an easy-to-use interface to the random number generator
3790 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``.
3791 3806
3792 .. versionchanged:: 3.5 3807 .. versionchanged:: 3.5
3793 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
3794 when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` 3809 when available. On OpenBSD 5.6 and newer, the C ``getentropy()``
3795 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
3796 descriptor. 3811 descriptor.
LEFTRIGHT

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