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

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

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