Add some posix functions

Doc/library/os.rst

 :mod:`os` --- Miscellaneous operating system interfaces
 =======================================================
 
 .. module:: os
    :synopsis: Miscellaneous operating system interfaces.
 
 
 This module provides a portable way of using operating system dependent
 functionality.  If you just want to read or write a file see :func:`open`, if
 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
@@ skipping 617 matching lines @@
 
 .. function:: fdatasync(fd)
 
    Force write of file with filedescriptor *fd* to disk. Does not force update of
    metadata.
 
    Availability: Unix.
 
    .. note::
       This function is not available on MacOS.
+
+
+.. function:: fexecve(fd, args, env)
+
+   Execute the program specified by a file descriptor *fd* with arguments given
+   by *args* and environment given by *env*, replacing the current process.
+   *args* and *env* are given as in :func:`execve`.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: fpathconf(fd, name)
 
    Return system configuration information relevant to an open file. *name*
    specifies the configuration value to retrieve; it may be a string which is the
    name of a defined system value; these names are specified in a number of
    standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
    additional names as well.  The names known to the host operating system are
    given in the ``pathconf_names`` dictionary.  For configuration variables not
@@ skipping 33 matching lines @@
 
    Availability: Unix, and Windows.
 
 
 .. function:: ftruncate(fd, length)
 
    Truncate the file corresponding to file descriptor *fd*, so that it is at most
    *length* bytes in size.
 
    Availability: Unix.
+
+
+.. function:: futimens(fd, (atime_sec, atime_nsec), (mtime_sec, mtime_nsec))
+              futimens(fd, None, None)
+
+   Updates the timestamps of a file specified by the file descriptor *fd*, with
+   nanosecond precision.
+   The second form sets *atime* and *mtime* to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_NOW`, the corresponding
+   timestamp is updated to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_OMIT`, the corresponding
+   timestamp is not updated.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: UTIME_NOW
+          UTIME_OMIT
+
+   Flags used with :func:`futimens` to specify that the timestamp must be
+   updated either to the current time or not updated at all.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: futimes(fd, (atime, mtime))
+              futimes(fd, None)
+
+   Set the access and modified time of the file specified by the file
+   descriptor *fd* to the given values. If the second form is used, set the
+   access and modified times to the current time.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: isatty(fd)
 
    Return ``True`` if the file descriptor *fd* is open and connected to a
    tty(-like) device, else ``False``.
 
    Availability: Unix.
 
+
+.. function:: lockf(fd, cmd, len)
+
+   Apply, test or remove a POSIX lock on an open file descriptor.
+   *fd* is an open file descriptor.
+   *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`,
+   :data:`F_ULOCK` or :data:`F_TEST`.
+   *len* specifies the section of the file to lock.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: F_LOCK
+          F_TLOCK
+          F_ULOCK
+          F_TEST
+
+   Flags that specify what action :func:`lockf` will take.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 .. function:: lseek(fd, pos, how)
 
    Set the current position of file descriptor *fd* to position *pos*, modified
    by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
    beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
    current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
    the file.
 
    Availability: Unix, Windows.
@@ skipping 39 matching lines @@
 
    Availability: some flavors of Unix.
 
 
 .. function:: pipe()
 
    Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for reading
    and writing, respectively.
 
    Availability: Unix, Windows.
+
+
+.. function:: posix_fallocate(fd, offset, len)
+
+   Ensures that enough disk space is allocated for the file specified by *fd*
+   starting from *offset* and continuing for *len* bytes.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: posix_fadvise(fd, offset, len, advice)
+
+   Announces an intention to access data in a specific pattern thus allowing
+   the kernel to make optimizations.
+   The advice applies to the region of the file specified by *fd* starting at
+   *offset* and continuing for *len* bytes.
+   *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
+   :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
+   :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: POSIX_FADV_NORMAL
+          POSIX_FADV_SEQUENTIAL
+          POSIX_FADV_RANDOM
+          POSIX_FADV_NOREUSE
+          POSIX_FADV_WILLNEED
+          POSIX_FADV_DONTNEED
+
+   Flags that can be used in *advice* in :func:`posix_fadvise` that specify
+   the access pattern that is likely to be used.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: pread(fd, buffersize, offset)
+
+   Read from a file descriptor, *fd*, at a position of *offset*. It will read up
+   to *buffersize* number of bytes. The file offset remains unchanged.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: pwrite(fd, string, offset)
+
+   Write *string* to a file descriptor, *fd*, from *offset*, leaving the file
+   offset unchanged.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: read(fd, n)
 
    Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
    bytes read.  If the end of the file referred to by *fd* has been reached, an
    empty bytes object is returned.
 
    Availability: Unix, Windows.
 
    .. note::
 
       This function is intended for low-level I/O and must be applied to a file
       descriptor as returned by :func:`os.open` or :func:`pipe`.  To read a "file object"
       returned by the built-in function :func:`open` or by :func:`popen` or
       :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
       :meth:`~file.readline` methods.
+
+
+.. function:: readv(fd, buffers)
+
+   Read from a file descriptor into a number of writable buffers. *buffers* is
+   an arbitrary sequence of writable buffers. Returns the total number of bytes
+   read.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: tcgetpgrp(fd)
 
    Return the process group associated with the terminal given by *fd* (an open
    file descriptor as returned by :func:`os.open`).
 
    Availability: Unix.
 
 
@@ skipping 21 matching lines @@
 
    Availability: Unix, Windows.
 
    .. note::
 
       This function is intended for low-level I/O and must be applied to a file
       descriptor as returned by :func:`os.open` or :func:`pipe`.  To write a "file
       object" returned by the built-in function :func:`open` or by :func:`popen` or
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
       :meth:`~file.write` method.
+
+
+.. function:: writev(fd, buffers)
+
+   Write the the contents of *buffers* to file descriptor *fd*, where *buffers*
+   is an arbitrary sequence of buffers.
+   Returns the total number of bytes written.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. _open-constants:
 
 ``open()`` flag constants
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following constants are options for the *flags* parameter to the
 :func:`~os.open` function.  They can be combined using the bitwise OR operator
 ``|``.  Some of them are not available on all platforms.  For descriptions of
@@ skipping 251 matching lines @@
    .. versionchanged:: 3.2
       The *path* parameter became optional.
 
 .. function:: lstat(path)
 
    Like :func:`stat`, but do not follow symbolic links.  This is an alias for
    :func:`stat` on platforms that do not support symbolic links.
 
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
+
+
+.. function:: lutimes(path, (atime, mtime))
+              lutimes(path, None)
+
+   Like :func:`utime`, but if *path* is a symbolic link, it is not
+   dereferenced.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: mkfifo(path[, mode])
 
    Create a FIFO (a named pipe) named *path* with numeric mode *mode*.  The
    default *mode* is ``0o666`` (octal).  The current umask value is first masked
    out from the mode.
 
    FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
    are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
@@ skipping 304 matching lines @@
       application as an administrator are ways to successfully create symlinks.
 
 
       :exc:`OSError` is raised when the function is called by an unprivileged
       user.
 
    Availability: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
+
+
+.. function:: sync()
+
+   Force write of everything to disk.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: truncate(path, length)
+
+   Truncate the file corresponding to *path*, so that it is at most
+   *length* bytes in size.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: unlink(path)
 
    Remove (delete) the file *path*.  This is the same function as
    :func:`remove`; the :func:`unlink` name is its traditional Unix
    name.
 
    Availability: Unix, Windows.
 
@@ skipping 560 matching lines @@
 
 .. function:: wait()
 
    Wait for completion of a child process, and return a tuple containing its pid
    and exit status indication: a 16-bit number, whose low byte is the signal number
    that killed the process, and whose high byte is the exit status (if the signal
    number is zero); the high bit of the low byte is set if a core file was
    produced.
 
    Availability: Unix.
+
+.. function:: waitid(idtype, id, options)
+
+   Wait for the completion of one or more child processes.
+   *idtype* can be :data:`P_PID`, :data:`P_PGID` or :data:`P_ALL`.
+   *id* specifies the pid to wait on.
+   *options* is constructed from the ORing of one or more of :data:`WEXITED`,
+   :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
+   :data:`WNOHANG` or :data:`WNOWAIT`. The result is a tuple containing the
+   same data as *siginfo_t* in the POSIX specification.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+.. data:: P_PID
+          P_PGID
+          P_ALL
+
+   These are the possible values for *idtype* in :func:`waitid`. They affect
+   how *id* is interpreted.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+.. data:: WEXITED
+          WSTOPPED
+          WNOWAIT
+
+   Flags that can be used in *options* in :func:`waitid` that specify what
+   child signal to wait for.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: waitpid(pid, options)
 
    The details of this function differ on Unix and Windows.
 
    On Unix: Wait for completion of a child process given by process id *pid*, and
    return a tuple containing its process id and exit status indication (encoded as
    for :func:`wait`).  The semantics of the call are affected by the value of the
    integer *options*, which should be ``0`` for normal operation.
@@ skipping 156 matching lines @@
    Availability: Unix
 
 
 .. data:: confstr_names
 
    Dictionary mapping names accepted by :func:`confstr` to the integer values
    defined for those names by the host operating system. This can be used to
    determine the set of names known to the system.
 
    Availability: Unix.
+
+
+.. function:: gethostid()
+
+   Returns the host id, a unique 32-bit identifier for the current machine.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: getloadavg()
 
    Return the number of processes in the system run queue averaged over the last
    1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
    unobtainable.
 
    Availability: Unix.
+
+
+.. function:: sethostname(name)
+
+   Sets the machine's hostname to *name*.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 
 .. function:: sysconf(name)
 
    Return integer-valued system configuration values. If the configuration value
    specified by *name* isn't defined, ``-1`` is returned.  The comments regarding
    the *name* parameter for :func:`confstr` apply here as well; the dictionary that
    provides information on the known names is given by ``sysconf_names``.
 
    Availability: Unix.
@@ skipping 86 matching lines @@
 
 .. function:: urandom(n)
 
    Return a string of *n* random bytes suitable for cryptographic use.
 
    This function returns random bytes from an OS-specific randomness source.  The
    returned data should be unpredictable enough for cryptographic applications,
    though its exact quality depends on the OS implementation.  On a UNIX-like
    system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
    If a randomness source is not found, :exc:`NotImplementedError` will be raised.