##
14.1.3 File Descriptor Operations

These functions operate on I/O streams referenced using file descriptors.

File descriptors are small integers corresponding to a file that has been opened by the current process. For example, standard input is usually file descriptor 0, standard output is 1, and standard error is 2. Further files opened by a process will then be assigned 3, 4, 5, and so forth. The name ``file descriptor'' is slightly deceptive; on Unix platforms, sockets and pipes are also referenced by file descriptors.

`close`( | fd)

  Close file descriptor fd. Availability: Macintosh, Unix, Windows.

  Note: This function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()` or `pipe()`. To close a ``file object'' returned by the built-in function `open()` or by `popen()` or `fdopen()`, use its `close()` method.

`dup`( | fd)

  Return a duplicate of file descriptor fd. Availability: Macintosh, Unix, Windows.

`dup2`( | fd, fd2)

  Duplicate file descriptor fd to fd2, closing the latter first if necessary. Availability: Macintosh, Unix, Windows.

`fdatasync`( | fd)

  Force write of file with filedescriptor fd to disk. Does not force update of metadata. Availability: Unix.

`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 included in that mapping, passing an integer for name is also accepted. Availability: Macintosh, Unix.

  If name is a string and is not known, `ValueError` is raised. If a specific value for name is not supported by the host system, even if it is included in `pathconf_names`, an `OSError` is raised with `errno.EINVAL` for the error number.

`fstat`( | fd)

  Return status for file descriptor fd, like `stat()`. Availability: Macintosh, Unix, Windows.

`fstatvfs`( | fd)

  Return information about the filesystem containing the file associated with file descriptor fd, like `statvfs()`. Availability: Unix.

`fsync`( | fd)

  Force write of file with filedescriptor fd to disk. On Unix, this calls the native `fsync()` function; on Windows, the MS `_commit()` function.

  If you're starting with a Python file object f, first do `f.flush()`, and then do `os.fsync(f.fileno())`, to ensure that all internal buffers associated with f are written to disk. Availability: Macintosh, Unix, and Windows starting in 2.2.3.

`ftruncate`( | fd, length)

  Truncate the file corresponding to file descriptor fd, so that it is at most length bytes in size. Availability: Macintosh, Unix.

`isatty`( | fd)

  Return `True` if the file descriptor fd is open and connected to a tty(-like) device, else `False`. Availability: Macintosh, Unix.

`lseek`( | fd, pos, how)

  Set the current position of file descriptor fd to position pos, modified by how: `0` to set the position relative to the beginning of the file; `1` to set it relative to the current position; `2` to set it relative to the end of the file. Availability: Macintosh, Unix, Windows.

`open`( | file, flags[, mode])

  Open the file file and set various flags according to flags and possibly its mode according to mode. The default mode is `0777` (octal), and the current umask value is first masked out. Return the file descriptor for the newly opened file. Availability: Macintosh, Unix, Windows.

  For a description of the flag and mode values, see the C run-time documentation; flag constants (like `O_RDONLY` and `O_WRONLY`) are defined in this module too (see below).

  Note: This function is intended for low-level I/O. For normal usage, use the built-in function `open()`, which returns a ``file object'' with `read()` and `write()` methods (and many more). To wrap a file descriptor in a ``file object'', use `fdopen()`.

`openpty`( | )

  Open a new pseudo-terminal pair. Return a pair of file descriptors `(master, slave)` for the pty and the tty, respectively. For a (slightly) more portable approach, use the `pty` module. Availability: Macintosh, Some flavors of Unix.

`pipe`( | )

  Create a pipe. Return a pair of file descriptors `(r, w)` usable for reading and writing, respectively. Availability: Macintosh, Unix, Windows.

`read`( | fd, n)

  Read at most n bytes from file descriptor fd. Return a string containing the bytes read. If the end of the file referred to by fd has been reached, an empty string is returned. Availability: Macintosh, Unix, Windows.

  Note: This function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()` or `pipe()`. To read a ``file object'' returned by the built-in function `open()` or by `popen()` or `fdopen()`, or `sys.stdin`, use its `read()` or `readline()` methods.

`tcgetpgrp`( | fd)

  Return the process group associated with the terminal given by fd (an open file descriptor as returned by `open()`). Availability: Macintosh, Unix.

`tcsetpgrp`( | fd, pg)

  Set the process group associated with the terminal given by fd (an open file descriptor as returned by `open()`) to pg. Availability: Macintosh, Unix.

`ttyname`( | fd)

  Return a string which specifies the terminal device associated with file-descriptor fd. If fd is not associated with a terminal device, an exception is raised. Availability:Macintosh, Unix.

`write`( | fd, str)

  Write the string str to file descriptor fd. Return the number of bytes actually written. Availability: Macintosh, Unix, Windows.

  Note: This function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()` or `pipe()`. To write a ``file object'' returned by the built-in function `open()` or by `popen()` or `fdopen()`, or `sys.stdout` or `sys.stderr`, use its `write()` method.

The following data items are available for use in constructing the flags parameter to the `open()` function. Some items will not be available on all platforms. For descriptions of their availability and use, consult open(2).

`O_RDONLY`
`O_WRONLY`
`O_RDWR`
`O_APPEND`
`O_CREAT`
`O_EXCL`
`O_TRUNC`
  Options for the flag argument to the `open()` function. These can be bit-wise OR'd together. Availability: Macintosh, Unix, Windows.

`O_DSYNC`
`O_RSYNC`
`O_SYNC`
`O_NDELAY`
`O_NONBLOCK`
`O_NOCTTY`
`O_SHLOCK`
`O_EXLOCK`
  More options for the flag argument to the `open()` function. Availability: Macintosh, Unix.

`O_BINARY`
  Option for the flag argument to the `open()` function. This can be bit-wise OR'd together with those listed above. Availability: Windows.

`O_NOINHERIT`
`O_SHORT_LIVED`
`O_TEMPORARY`
`O_RANDOM`
`O_SEQUENTIAL`
`O_TEXT`
  Options for the flag argument to the `open()` function. These can be bit-wise OR'd together. Availability: Windows.

`SEEK_SET`
`SEEK_CUR`
`SEEK_END`
  Parameters to the `lseek()` function. Their values are 0, 1, and 2, respectively. Availability: Windows, Macintosh, Unix. New in version 2.5.