1: @node Low-Level I/O, File System Interface, I/O on Streams, Top
    2: @c %MENU% Low-level, less portable I/O
    3: @chapter Low-Level Input/Output
    4: 
    5: This chapter describes functions for performing low-level input/output
    6: operations on file descriptors.  These functions include the primitives
    7: for the higher-level I/O functions described in @ref{I/O on Streams}, as
    8: well as functions for performing low-level control operations for which
    9: there are no equivalents on streams.
   10: 
   11: Stream-level I/O is more flexible and usually more convenient;
   12: therefore, programmers generally use the descriptor-level functions only
   13: when necessary.  These are some of the usual reasons:
   14: 
   15: @itemize @bullet
   16: @item
   17: For reading binary files in large chunks.
   18: 
   19: @item
   20: For reading an entire file into core before parsing it.
   21: 
   22: @item
   23: To perform operations other than data transfer, which can only be done
   24: with a descriptor.  (You can use @code{fileno} to get the descriptor
   25: corresponding to a stream.)
   26: 
   27: @item
   28: To pass descriptors to a child process.  (The child can create its own
   29: stream to use a descriptor that it inherits, but cannot inherit a stream
   30: directly.)
   31: @end itemize
   32: 
   33: @menu
   34: * Opening and Closing Files::           How to open and close file
   35:                                          descriptors.
   36: * I/O Primitives::                      Reading and writing data.
   37: * File Position Primitive::             Setting a descriptor's file
   38:                                          position.
   39: * Descriptors and Streams::             Converting descriptor to stream
   40:                                          or vice-versa.
   41: * Stream/Descriptor Precautions::       Precautions needed if you use both
   42:                                          descriptors and streams.
   43: * Scatter-Gather::                      Fast I/O to discontinuous buffers.
   44: * Memory-mapped I/O::                   Using files like memory.
   45: * Waiting for I/O::                     How to check for input or output
   46:                                          on multiple file descriptors.
   47: * Synchronizing I/O::                   Making sure all I/O actions completed.
   48: * Asynchronous I/O::                    Perform I/O in parallel.
   49: * Control Operations::                  Various other operations on file
   50:                                          descriptors.
   51: * Duplicating Descriptors::             Fcntl commands for duplicating
   52:                                          file descriptors.
   53: * Descriptor Flags::                    Fcntl commands for manipulating
   54:                                          flags associated with file
   55:                                          descriptors.
   56: * File Status Flags::                   Fcntl commands for manipulating
   57:                                          flags associated with open files.
   58: * File Locks::                          Fcntl commands for implementing
   59:                                          file locking.
   60: * Interrupt Input::                     Getting an asynchronous signal when
   61:                                          input arrives.
   62: * IOCTLs::                              Generic I/O Control operations.
   63: @end menu
   64: 
   65: 
   66: @node Opening and Closing Files
   67: @section Opening and Closing Files
   68: 
   69: @cindex opening a file descriptor
   70: @cindex closing a file descriptor
   71: This section describes the primitives for opening and closing files
   72: using file descriptors.  The @code{open} and @code{creat} functions are
   73: declared in the header file @file{fcntl.h}, while @code{close} is
   74: declared in @file{unistd.h}.
   75: @pindex unistd.h
   76: @pindex fcntl.h
   77: 
   78: @comment fcntl.h
   79: @comment POSIX.1
   80: @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
   81: The @code{open} function creates and returns a new file descriptor
   82: for the file named by @var{filename}.  Initially, the file position
   83: indicator for the file is at the beginning of the file.  The argument
   84: @var{mode} is used only when a file is created, but it doesn't hurt
   85: to supply the argument in any case.
   86: 
   87: The @var{flags} argument controls how the file is to be opened.  This is
   88: a bit mask; you create the value by the bitwise OR of the appropriate
   89: parameters (using the @samp{|} operator in C).
   90: @xref{File Status Flags}, for the parameters available.
   91: 
   92: The normal return value from @code{open} is a non-negative integer file
   93: descriptor.  In the case of an error, a value of @math{-1} is returned
   94: instead.  In addition to the usual file name errors (@pxref{File
   95: Name Errors}), the following @code{errno} error conditions are defined
   96: for this function:
   97: 
   98: @table @code
   99: @item EACCES
  100: The file exists but is not readable/writable as requested by the @var{flags}
  101: argument, the file does not exist and the directory is unwritable so
  102: it cannot be created.
  103: 
  104: @item EEXIST
  105: Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
  106: exists.
  107: 
  108: @item EINTR
  109: The @code{open} operation was interrupted by a signal.
  110: @xref{Interrupted Primitives}.
  111: 
  112: @item EISDIR
  113: The @var{flags} argument specified write access, and the file is a directory.
  114: 
  115: @item EMFILE
  116: The process has too many files open.
  117: The maximum number of file descriptors is controlled by the
  118: @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
  119: 
  120: @item ENFILE
  121: The entire system, or perhaps the file system which contains the
  122: directory, cannot support any additional open files at the moment.
  123: (This problem cannot happen on the GNU system.)
  124: 
  125: @item ENOENT
  126: The named file does not exist, and @code{O_CREAT} is not specified.
  127: 
  128: @item ENOSPC
  129: The directory or file system that would contain the new file cannot be
  130: extended, because there is no disk space left.
  131: 
  132: @item ENXIO
  133: @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
  134: argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
  135: FIFOs}), and no process has the file open for reading.
  136: 
  137: @item EROFS
  138: The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
  139: @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
  140: or @code{O_CREAT} is set and the file does not already exist.
  141: @end table
  142: 
  143: @c !!! umask
  144: 
  145: If on a 32 bit machine the sources are translated with
  146: @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
  147: descriptor opened in the large file mode which enables the file handling
  148: functions to use files up to @math{2^63} bytes in size and offset from
  149: @math{-2^63} to @math{2^63}.  This happens transparently for the user
  150: since all of the lowlevel file handling functions are equally replaced.
  151: 
  152: This function is a cancellation point in multi-threaded programs.  This
  153: is a problem if the thread allocates some resources (like memory, file
  154: descriptors, semaphores or whatever) at the time @code{open} is
  155: called.  If the thread gets canceled these resources stay allocated
  156: until the program ends.  To avoid this calls to @code{open} should be
  157: protected using cancellation handlers.
  158: @c ref pthread_cleanup_push / pthread_cleanup_pop
  159: 
  160: The @code{open} function is the underlying primitive for the @code{fopen}
  161: and @code{freopen} functions, that create streams.
  162: @end deftypefun
  163: 
  164: @comment fcntl.h
  165: @comment Unix98
  166: @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
  167: This function is similar to @code{open}.  It returns a file descriptor
  168: which can be used to access the file named by @var{filename}.  The only
  169: difference is that on 32 bit systems the file is opened in the
  170: large file mode.  I.e., file length and file offsets can exceed 31 bits.
  171: 
  172: When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
  173: function is actually available under the name @code{open}.  I.e., the
  174: new, extended API using 64 bit file sizes and offsets transparently
  175: replaces the old API.
  176: @end deftypefun
  177: 
  178: @comment fcntl.h
  179: @comment POSIX.1
  180: @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
  181: This function is obsolete.  The call:
  182: 
  183: @smallexample
  184: creat (@var{filename}, @var{mode})
  185: @end smallexample
  186: 
  187: @noindent
  188: is equivalent to:
  189: 
  190: @smallexample
  191: open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
  192: @end smallexample
  193: 
  194: If on a 32 bit machine the sources are translated with
  195: @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
  196: descriptor opened in the large file mode which enables the file handling
  197: functions to use files up to @math{2^63} in size and offset from
  198: @math{-2^63} to @math{2^63}.  This happens transparently for the user
  199: since all of the lowlevel file handling functions are equally replaced.
  200: @end deftypefn
  201: 
  202: @comment fcntl.h
  203: @comment Unix98
  204: @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
  205: This function is similar to @code{creat}.  It returns a file descriptor
  206: which can be used to access the file named by @var{filename}.  The only
  207: the difference is that on 32 bit systems the file is opened in the
  208: large file mode.  I.e., file length and file offsets can exceed 31 bits.
  209: 
  210: To use this file descriptor one must not use the normal operations but
  211: instead the counterparts named @code{*64}, e.g., @code{read64}.
  212: 
  213: When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
  214: function is actually available under the name @code{open}.  I.e., the
  215: new, extended API using 64 bit file sizes and offsets transparently
  216: replaces the old API.
  217: @end deftypefn
  218: 
  219: @comment unistd.h
  220: @comment POSIX.1
  221: @deftypefun int close (int @var{filedes})
  222: The function @code{close} closes the file descriptor @var{filedes}.
  223: Closing a file has the following consequences:
  224: 
  225: @itemize @bullet
  226: @item
  227: The file descriptor is deallocated.
  228: 
  229: @item
  230: Any record locks owned by the process on the file are unlocked.
  231: 
  232: @item
  233: When all file descriptors associated with a pipe or FIFO have been closed,
  234: any unread data is discarded.
  235: @end itemize
  236: 
  237: This function is a cancellation point in multi-threaded programs.  This
  238: is a problem if the thread allocates some resources (like memory, file
  239: descriptors, semaphores or whatever) at the time @code{close} is
  240: called.  If the thread gets canceled these resources stay allocated
  241: until the program ends.  To avoid this, calls to @code{close} should be
  242: protected using cancellation handlers.
  243: @c ref pthread_cleanup_push / pthread_cleanup_pop
  244: 
  245: The normal return value from @code{close} is @math{0}; a value of @math{-1}
  246: is returned in case of failure.  The following @code{errno} error
  247: conditions are defined for this function:
  248: 
  249: @table @code
  250: @item EBADF
  251: The @var{filedes} argument is not a valid file descriptor.
  252: 
  253: @item EINTR
  254: The @code{close} call was interrupted by a signal.
  255: @xref{Interrupted Primitives}.
  256: Here is an example of how to handle @code{EINTR} properly:
  257: 
  258: @smallexample
  259: TEMP_FAILURE_RETRY (close (desc));
  260: @end smallexample
  261: 
  262: @item ENOSPC
  263: @itemx EIO
  264: @itemx EDQUOT
  265: When the file is accessed by NFS, these errors from @code{write} can sometimes
  266: not be detected until @code{close}.  @xref{I/O Primitives}, for details
  267: on their meaning.
  268: @end table
  269: 
  270: Please note that there is @emph{no} separate @code{close64} function.
  271: This is not necessary since this function does not determine nor depend
  272: on the mode of the file.  The kernel which performs the @code{close}
  273: operation knows which mode the descriptor is used for and can handle
  274: this situation.
  275: @end deftypefun
  276: 
  277: To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
  278: of trying to close its underlying file descriptor with @code{close}.
  279: This flushes any buffered output and updates the stream object to
  280: indicate that it is closed.
  281: 
  282: @node I/O Primitives
  283: @section Input and Output Primitives
  284: 
  285: This section describes the functions for performing primitive input and
  286: output operations on file descriptors: @code{read}, @code{write}, and
  287: @code{lseek}.  These functions are declared in the header file
  288: @file{unistd.h}.
  289: @pindex unistd.h
  290: 
  291: @comment unistd.h
  292: @comment POSIX.1
  293: @deftp {Data Type} ssize_t
  294: This data type is used to represent the sizes of blocks that can be
  295: read or written in a single operation.  It is similar to @code{size_t},
  296: but must be a signed type.
  297: @end deftp
  298: 
  299: @cindex reading from a file descriptor
  300: @comment unistd.h
  301: @comment POSIX.1
  302: @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
  303: The @code{read} function reads up to @var{size} bytes from the file
  304: with descriptor @var{filedes}, storing the results in the @var{buffer}.
  305: (This is not necessarily a character string, and no terminating null
  306: character is added.)
  307: 
  308: @cindex end-of-file, on a file descriptor
  309: The return value is the number of bytes actually read.  This might be
  310: less than @var{size}; for example, if there aren't that many bytes left
  311: in the file or if there aren't that many bytes immediately available.
  312: The exact behavior depends on what kind of file it is.  Note that
  313: reading less than @var{size} bytes is not an error.
  314: 
  315: A value of zero indicates end-of-file (except if the value of the
  316: @var{size} argument is also zero).  This is not considered an error.
  317: If you keep calling @code{read} while at end-of-file, it will keep
  318: returning zero and doing nothing else.
  319: 
  320: If @code{read} returns at least one character, there is no way you can
  321: tell whether end-of-file was reached.  But if you did reach the end, the
  322: next read will return zero.
  323: 
  324: In case of an error, @code{read} returns @math{-1}.  The following
  325: @code{errno} error conditions are defined for this function:
  326: 
  327: @table @code
  328: @item EAGAIN
  329: Normally, when no input is immediately available, @code{read} waits for
  330: some input.  But if the @code{O_NONBLOCK} flag is set for the file
  331: (@pxref{File Status Flags}), @code{read} returns immediately without
  332: reading any data, and reports this error.
  333: 
  334: @strong{Compatibility Note:} Most versions of BSD Unix use a different
  335: error code for this: @code{EWOULDBLOCK}.  In the GNU library,
  336: @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
  337: which name you use.
  338: 
  339: On some systems, reading a large amount of data from a character special
  340: file can also fail with @code{EAGAIN} if the kernel cannot find enough
  341: physical memory to lock down the user's pages.  This is limited to
  342: devices that transfer with direct memory access into the user's memory,
  343: which means it does not include terminals, since they always use
  344: separate buffers inside the kernel.  This problem never happens in the
  345: GNU system.
  346: 
  347: Any condition that could result in @code{EAGAIN} can instead result in a
  348: successful @code{read} which returns fewer bytes than requested.
  349: Calling @code{read} again immediately would result in @code{EAGAIN}.
  350: 
  351: @item EBADF
  352: The @var{filedes} argument is not a valid file descriptor,
  353: or is not open for reading.
  354: 
  355: @item EINTR
  356: @code{read} was interrupted by a signal while it was waiting for input.
  357: @xref{Interrupted Primitives}.  A signal will not necessary cause
  358: @code{read} to return @code{EINTR}; it may instead result in a
  359: successful @code{read} which returns fewer bytes than requested.
  360: 
  361: @item EIO
  362: For many devices, and for disk files, this error code indicates
  363: a hardware error.
  364: 
  365: @code{EIO} also occurs when a background process tries to read from the
  366: controlling terminal, and the normal action of stopping the process by
  367: sending it a @code{SIGTTIN} signal isn't working.  This might happen if
  368: the signal is being blocked or ignored, or because the process group is
  369: orphaned.  @xref{Job Control}, for more information about job control,
  370: and @ref{Signal Handling}, for information about signals.
  371: 
  372: @item EINVAL
  373: In some systems, when reading from a character or block device, position
  374: and size offsets must be aligned to a particular block size.  This error
  375: indicates that the offsets were not properly aligned.
  376: @end table
  377: 
  378: Please note that there is no function named @code{read64}.  This is not
  379: necessary since this function does not directly modify or handle the
  380: possibly wide file offset.  Since the kernel handles this state
  381: internally, the @code{read} function can be used for all cases.
  382: 
  383: This function is a cancellation point in multi-threaded programs.  This
  384: is a problem if the thread allocates some resources (like memory, file
  385: descriptors, semaphores or whatever) at the time @code{read} is
  386: called.  If the thread gets canceled these resources stay allocated
  387: until the program ends.  To avoid this, calls to @code{read} should be
  388: protected using cancellation handlers.
  389: @c ref pthread_cleanup_push / pthread_cleanup_pop
  390: 
  391: The @code{read} function is the underlying primitive for all of the
  392: functions that read from streams, such as @code{fgetc}.
  393: @end deftypefun
  394: 
  395: @comment unistd.h
  396: @comment Unix98
  397: @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
  398: The @code{pread} function is similar to the @code{read} function.  The
  399: first three arguments are identical, and the return values and error
  400: codes also correspond.
  401: 
  402: The difference is the fourth argument and its handling.  The data block
  403: is not read from the current position of the file descriptor
  404: @code{filedes}.  Instead the data is read from the file starting at
  405: position @var{offset}.  The position of the file descriptor itself is
  406: not affected by the operation.  The value is the same as before the call.
  407: 
  408: When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
  409: @code{pread} function is in fact @code{pread64} and the type
  410: @code{off_t} has 64 bits, which makes it possible to handle files up to
  411: @math{2^63} bytes in length.
  412: 
  413: The return value of @code{pread} describes the number of bytes read.
  414: In the error case it returns @math{-1} like @code{read} does and the
  415: error codes are also the same, with these additions:
  416: 
  417: @table @code
  418: @item EINVAL
  419: The value given for @var{offset} is negative and therefore illegal.
  420: 
  421: @item ESPIPE
  422: The file descriptor @var{filedes} is associate with a pipe or a FIFO and
  423: this device does not allow positioning of the file pointer.
  424: @end table
  425: 
  426: The function is an extension defined in the Unix Single Specification
  427: version 2.
  428: @end deftypefun
  429: 
  430: @comment unistd.h
  431: @comment Unix98
  432: @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
  433: This function is similar to the @code{pread} function.  The difference
  434: is that the @var{offset} parameter is of type @code{off64_t} instead of
  435: @code{off_t} which makes it possible on 32 bit machines to address
  436: files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
  437: file descriptor @code{filedes} must be opened using @code{open64} since
  438: otherwise the large offsets possible with @code{off64_t} will lead to
  439: errors with a descriptor in small file mode.
  440: 
  441: When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
  442: 32 bit machine this function is actually available under the name
  443: @code{pread} and so transparently replaces the 32 bit interface.
  444: @end deftypefun
  445: 
  446: @cindex writing to a file descriptor
  447: @comment unistd.h
  448: @comment POSIX.1
  449: @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
  450: The @code{write} function writes up to @var{size} bytes from
  451: @var{buffer} to the file with descriptor @var{filedes}.  The data in
  452: @var{buffer} is not necessarily a character string and a null character is
  453: output like any other character.
  454: 
  455: The return value is the number of bytes actually written.  This may be
  456: @var{size}, but can always be smaller.  Your program should always call
  457: @code{write} in a loop, iterating until all the data is written.
  458: 
  459: Once @code{write} returns, the data is enqueued to be written and can be
  460: read back right away, but it is not necessarily written out to permanent
  461: storage immediately.  You can use @code{fsync} when you need to be sure
  462: your data has been permanently stored before continuing.  (It is more
  463: efficient for the system to batch up consecutive writes and do them all
  464: at once when convenient.  Normally they will always be written to disk
  465: within a minute or less.)  Modern systems provide another function
  466: @code{fdatasync} which guarantees integrity only for the file data and
  467: is therefore faster.
  468: @c !!! xref fsync, fdatasync
  469: You can use the @code{O_FSYNC} open mode to make @code{write} always
  470: store the data to disk before returning; @pxref{Operating Modes}.
  471: 
  472: In the case of an error, @code{write} returns @math{-1}.  The following
  473: @code{errno} error conditions are defined for this function:
  474: 
  475: @table @code
  476: @item EAGAIN
  477: Normally, @code{write} blocks until the write operation is complete.
  478: But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
  479: Operations}), it returns immediately without writing any data and
  480: reports this error.  An example of a situation that might cause the
  481: process to block on output is writing to a terminal device that supports
  482: flow control, where output has been suspended by receipt of a STOP
  483: character.
  484: 
  485: @strong{Compatibility Note:} Most versions of BSD Unix use a different
  486: error code for this: @code{EWOULDBLOCK}.  In the GNU library,
  487: @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
  488: which name you use.
  489: 
  490: On some systems, writing a large amount of data from a character special
  491: file can also fail with @code{EAGAIN} if the kernel cannot find enough
  492: physical memory to lock down the user's pages.  This is limited to
  493: devices that transfer with direct memory access into the user's memory,
  494: which means it does not include terminals, since they always use
  495: separate buffers inside the kernel.  This problem does not arise in the
  496: GNU system.
  497: 
  498: @item EBADF
  499: The @var{filedes} argument is not a valid file descriptor,
  500: or is not open for writing.
  501: 
  502: @item EFBIG
  503: The size of the file would become larger than the implementation can support.
  504: 
  505: @item EINTR
  506: The @code{write} operation was interrupted by a signal while it was
  507: blocked waiting for completion.  A signal will not necessarily cause
  508: @code{write} to return @code{EINTR}; it may instead result in a
  509: successful @code{write} which writes fewer bytes than requested.
  510: @xref{Interrupted Primitives}.
  511: 
  512: @item EIO
  513: For many devices, and for disk files, this error code indicates
  514: a hardware error.
  515: 
  516: @item ENOSPC
  517: The device containing the file is full.
  518: 
  519: @item EPIPE
  520: This error is returned when you try to write to a pipe or FIFO that
  521: isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
  522: signal is also sent to the process; see @ref{Signal Handling}.
  523: 
  524: @item EINVAL
  525: In some systems, when writing to a character or block device, position
  526: and size offsets must be aligned to a particular block size.  This error
  527: indicates that the offsets were not properly aligned.
  528: @end table
  529: 
  530: Unless you have arranged to prevent @code{EINTR} failures, you should
  531: check @code{errno} after each failing call to @code{write}, and if the
  532: error was @code{EINTR}, you should simply repeat the call.
  533: @xref{Interrupted Primitives}.  The easy way to do this is with the
  534: macro @code{TEMP_FAILURE_RETRY}, as follows:
  535: 
  536: @smallexample
  537: nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
  538: @end smallexample
  539: 
  540: Please note that there is no function named @code{write64}.  This is not
  541: necessary since this function does not directly modify or handle the
  542: possibly wide file offset.  Since the kernel handles this state
  543: internally the @code{write} function can be used for all cases.
  544: 
  545: This function is a cancellation point in multi-threaded programs.  This
  546: is a problem if the thread allocates some resources (like memory, file
  547: descriptors, semaphores or whatever) at the time @code{write} is
  548: called.  If the thread gets canceled these resources stay allocated
  549: until the program ends.  To avoid this, calls to @code{write} should be
  550: protected using cancellation handlers.
  551: @c ref pthread_cleanup_push / pthread_cleanup_pop
  552: 
  553: The @code{write} function is the underlying primitive for all of the
  554: functions that write to streams, such as @code{fputc}.
  555: @end deftypefun
  556: 
  557: @comment unistd.h
  558: @comment Unix98
  559: @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
  560: The @code{pwrite} function is similar to the @code{write} function.  The
  561: first three arguments are identical, and the return values and error codes
  562: also correspond.
  563: 
  564: The difference is the fourth argument and its handling.  The data block
  565: is not written to the current position of the file descriptor
  566: @code{filedes}.  Instead the data is written to the file starting at
  567: position @var{offset}.  The position of the file descriptor itself is
  568: not affected by the operation.  The value is the same as before the call.
  569: 
  570: When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
  571: @code{pwrite} function is in fact @code{pwrite64} and the type
  572: @code{off_t} has 64 bits, which makes it possible to handle files up to
  573: @math{2^63} bytes in length.
  574: 
  575: The return value of @code{pwrite} describes the number of written bytes.
  576: In the error case it returns @math{-1} like @code{write} does and the
  577: error codes are also the same, with these additions:
  578: 
  579: @table @code
  580: @item EINVAL
  581: The value given for @var{offset} is negative and therefore illegal.
  582: 
  583: @item ESPIPE
  584: The file descriptor @var{filedes} is associated with a pipe or a FIFO and
  585: this device does not allow positioning of the file pointer.
  586: @end table
  587: 
  588: The function is an extension defined in the Unix Single Specification
  589: version 2.
  590: @end deftypefun
  591: 
  592: @comment unistd.h
  593: @comment Unix98
  594: @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
  595: This function is similar to the @code{pwrite} function.  The difference
  596: is that the @var{offset} parameter is of type @code{off64_t} instead of
  597: @code{off_t} which makes it possible on 32 bit machines to address
  598: files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
  599: file descriptor @code{filedes} must be opened using @code{open64} since
  600: otherwise the large offsets possible with @code{off64_t} will lead to
  601: errors with a descriptor in small file mode.
  602: 
  603: When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
  604: 32 bit machine this function is actually available under the name
  605: @code{pwrite} and so transparently replaces the 32 bit interface.
  606: @end deftypefun
  607: 
  608: 
  609: @node File Position Primitive
  610: @section Setting the File Position of a Descriptor
  611: 
  612: Just as you can set the file position of a stream with @code{fseek}, you
  613: can set the file position of a descriptor with @code{lseek}.  This
  614: specifies the position in the file for the next @code{read} or
  615: @code{write} operation.  @xref{File Positioning}, for more information
  616: on the file position and what it means.
  617: 
  618: To read the current file position value from a descriptor, use
  619: @code{lseek (@var{desc}, 0, SEEK_CUR)}.
  620: 
  621: @cindex file positioning on a file descriptor
  622: @cindex positioning a file descriptor
  623: @cindex seeking on a file descriptor
  624: @comment unistd.h
  625: @comment POSIX.1
  626: @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
  627: The @code{lseek} function is used to change the file position of the
  628: file with descriptor @var{filedes}.
  629: 
  630: The @var{whence} argument specifies how the @var{offset} should be
  631: interpreted, in the same way as for the @code{fseek} function, and it must
  632: be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
  633: @code{SEEK_END}.
  634: 
  635: @table @code
  636: @item SEEK_SET
  637: Specifies that @var{whence} is a count of characters from the beginning
  638: of the file.
  639: 
  640: @item SEEK_CUR
  641: Specifies that @var{whence} is a count of characters from the current
  642: file position.  This count may be positive or negative.
  643: 
  644: @item SEEK_END
  645: Specifies that @var{whence} is a count of characters from the end of
  646: the file.  A negative count specifies a position within the current
  647: extent of the file; a positive count specifies a position past the
  648: current end.  If you set the position past the current end, and
  649: actually write data, you will extend the file with zeros up to that
  650: position.
  651: @end table
  652: 
  653: The return value from @code{lseek} is normally the resulting file
  654: position, measured in bytes from the beginning of the file.
  655: You can use this feature together with @code{SEEK_CUR} to read the
  656: current file position.
  657: 
  658: If you want to append to the file, setting the file position to the
  659: current end of file with @code{SEEK_END} is not sufficient.  Another
  660: process may write more data after you seek but before you write,
  661: extending the file so the position you write onto clobbers their data.
  662: Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
  663: 
  664: You can set the file position past the current end of the file.  This
  665: does not by itself make the file longer; @code{lseek} never changes the
  666: file.  But subsequent output at that position will extend the file.
  667: Characters between the previous end of file and the new position are
  668: filled with zeros.  Extending the file in this way can create a
  669: ``hole'': the blocks of zeros are not actually allocated on disk, so the
  670: file takes up less space than it appears to; it is then called a
  671: ``sparse file''.
  672: @cindex sparse files
  673: @cindex holes in files
  674: 
  675: If the file position cannot be changed, or the operation is in some way
  676: invalid, @code{lseek} returns a value of @math{-1}.  The following
  677: @code{errno} error conditions are defined for this function:
  678: 
  679: @table @code
  680: @item EBADF
  681: The @var{filedes} is not a valid file descriptor.
  682: 
  683: @item EINVAL
  684: The @var{whence} argument value is not valid, or the resulting
  685: file offset is not valid.  A file offset is invalid.
  686: 
  687: @item ESPIPE
  688: The @var{filedes} corresponds to an object that cannot be positioned,
  689: such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
  690: only for pipes and FIFOs, but in the GNU system, you always get
  691: @code{ESPIPE} if the object is not seekable.)
  692: @end table
  693: 
  694: When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
  695: @code{lseek} function is in fact @code{lseek64} and the type
  696: @code{off_t} has 64 bits which makes it possible to handle files up to
  697: @math{2^63} bytes in length.
  698: 
  699: This function is a cancellation point in multi-threaded programs.  This
  700: is a problem if the thread allocates some resources (like memory, file
  701: descriptors, semaphores or whatever) at the time @code{lseek} is
  702: called.  If the thread gets canceled these resources stay allocated
  703: until the program ends.  To avoid this calls to @code{lseek} should be
  704: protected using cancellation handlers.
  705: @c ref pthread_cleanup_push / pthread_cleanup_pop
  706: 
  707: The @code{lseek} function is the underlying primitive for the
  708: @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
  709: @code{rewind} functions, which operate on streams instead of file
  710: descriptors.
  711: @end deftypefun
  712: 
  713: @comment unistd.h
  714: @comment Unix98
  715: @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
  716: This function is similar to the @code{lseek} function.  The difference
  717: is that the @var{offset} parameter is of type @code{off64_t} instead of
  718: @code{off_t} which makes it possible on 32 bit machines to address
  719: files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
  720: file descriptor @code{filedes} must be opened using @code{open64} since
  721: otherwise the large offsets possible with @code{off64_t} will lead to
  722: errors with a descriptor in small file mode.
  723: 
  724: When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
  725: 32 bits machine this function is actually available under the name
  726: @code{lseek} and so transparently replaces the 32 bit interface.
  727: @end deftypefun
  728: 
  729: You can have multiple descriptors for the same file if you open the file
  730: more than once, or if you duplicate a descriptor with @code{dup}.
  731: Descriptors that come from separate calls to @code{open} have independent
  732: file positions; using @code{lseek} on one descriptor has no effect on the
  733: other.  For example,
  734: 
  735: @smallexample
  736: @group
  737: @{
  738:   int d1, d2;
  739:   char buf[4];
  740:   d1 = open ("foo", O_RDONLY);
  741:   d2 = open ("foo", O_RDONLY);
  742:   lseek (d1, 1024, SEEK_SET);
  743:   read (d2, buf, 4);
  744: @}
  745: @end group
  746: @end smallexample
  747: 
  748: @noindent
  749: will read the first four characters of the file @file{foo}.  (The
  750: error-checking code necessary for a real p