Unix/Linux Go Back    


Linux 2.6 - man page for pwrite (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


WRITE(P)			    POSIX Programmer's Manual				 WRITE(P)

NAME
       pwrite, write - write on a file

SYNOPSIS
       #include <unistd.h>

       ssize_t pwrite(int fildes, const void *buf, size_t nbyte,
	      off_t offset);
       ssize_t write(int fildes, const void *buf, size_t nbyte);

DESCRIPTION
       The  write() function shall attempt to write nbyte bytes from the buffer pointed to by buf
       to the file associated with the open file descriptor, fildes.

       Before any action described below is taken, and if nbyte is zero and the file is a regular
       file, the write() function may detect and return errors as described below. In the absence
       of errors, or if error detection is not performed, the write() function shall return  zero
       and  have  no  other  results.	If  nbyte is zero and the file is not a regular file, the
       results are unspecified.

       On a regular file or other file capable of seeking, the actual writing of data shall  pro-
       ceed  from  the	position in the file indicated by the file offset associated with fildes.
       Before successful return from write(), the file offset shall be incremented by the  number
       of  bytes  actually written. On a regular file, if this incremented file offset is greater
       than the length of the file, the length of the file shall be set to this file offset.

       On a file not capable of seeking, writing shall always take place starting at the  current
       position. The value of a file offset associated with such a device is undefined.

       If  the O_APPEND flag of the file status flags is set, the file offset shall be set to the
       end of the file prior to each write and no intervening file modification  operation  shall
       occur between changing the file offset and the write operation.

       If  a  write()  requests  that  more bytes be written than there is room for (for example,
	the process' file size limit or  the physical end of a medium), only  as  many	bytes  as
       there  is room for shall be written. For example, suppose there is space for 20 bytes more
       in a file before reaching a limit. A write of 512 bytes will return 20. The next write  of
       a non-zero number of bytes would give a failure return (except as noted below).

       If  the	request  would	cause  the  file  size to exceed the soft file size limit for the
       process and there is no room for any bytes to be written, the request shall fail  and  the
       implementation shall generate the SIGXFSZ signal for the thread.

       If  write()  is interrupted by a signal before it writes any data, it shall return -1 with
       errno set to [EINTR].

       If write() is interrupted by a signal after it successfully writes  some  data,	it  shall
       return the number of bytes written.

       If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-defined.

       After a write() to a regular file has successfully returned:

	* Any  successful  read()  from  each byte position in the file that was modified by that
	  write shall return the data specified by the write() for that position until such  byte
	  positions are again modified.

	* Any subsequent successful write() to the same byte position in the file shall overwrite
	  that file data.

       Write requests to a pipe or FIFO shall be handled in the same way as a regular  file  with
       the following exceptions:

	* There  is  no file offset associated with a pipe, hence each write request shall append
	  to the end of the pipe.

	* Write requests of {PIPE_BUF} bytes or less shall not	be  interleaved  with  data  from
	  other  processes doing writes on the same pipe. Writes of greater than {PIPE_BUF} bytes
	  may have data interleaved, on arbitrary boundaries, with  writes  by	other  processes,
	  whether or not the O_NONBLOCK flag of the file status flags is set.

	* If  the O_NONBLOCK flag is clear, a write request may cause the thread to block, but on
	  normal completion it shall return nbyte.

	* If the O_NONBLOCK flag is set, write() requests shall be handled  differently,  in  the
	  following ways:

	   * The write() function shall not block the thread.

	   * A	write  request	for {PIPE_BUF} or fewer bytes shall have the following effect: if
	     there is sufficient space available in the pipe, write() shall transfer all the data
	     and  return the number of bytes requested. Otherwise, write() shall transfer no data
	     and return -1 with errno set to [EAGAIN].

	   * A write request for more than {PIPE_BUF} bytes shall cause one of the following:

	      * When at least one byte can be written, transfer what it can and return the number
		of  bytes written. When all data previously written to the pipe is read, it shall
		transfer at least {PIPE_BUF} bytes.

	      * When no data can be written, transfer no data, and return -1 with  errno  set  to
		[EAGAIN].

       When  attempting  to  write to a file descriptor (other than a pipe or FIFO) that supports
       non-blocking writes and cannot accept the data immediately:

	* If the O_NONBLOCK flag is clear, write() shall block the calling thread until the  data
	  can be accepted.

	* If the O_NONBLOCK flag is set, write() shall not block the thread.  If some data can be
	  written without blocking the thread, write() shall write what it  can  and  return  the
	  number of bytes written. Otherwise, it shall return -1 and set errno to [EAGAIN].

       Upon  successful  completion, where nbyte is greater than 0, write() shall mark for update
       the st_ctime and st_mtime fields of the file, and if the  file  is  a  regular  file,  the
       S_ISUID and S_ISGID bits of the file mode may be cleared.

       For regular files, no data transfer shall occur past the offset maximum established in the
       open file description associated with fildes.

       If fildes refers to a socket, write() shall be equivalent to send() with no flags set.

       If the O_DSYNC bit has been set, write I/O operations on the file  descriptor  shall  com-
       plete as defined by synchronized I/O data integrity completion.

       If the O_SYNC bit has been set, write I/O operations on the file descriptor shall complete
       as defined by synchronized I/O file integrity completion.

       If fildes refers to a shared memory object, the result of the write() function is unspeci-
       fied.

       If  fildes refers to a typed memory object, the result of the write() function is unspeci-
       fied.

       If fildes refers to a STREAM, the operation of write() shall be determined by  the  values
       of  the minimum and maximum nbyte range (packet size) accepted by the STREAM. These values
       are determined by the topmost STREAM module. If nbyte falls within the packet size  range,
       nbyte  bytes  shall  be	written.  If nbyte does not fall within the range and the minimum
       packet size value is 0, write() shall break the buffer into maximum packet  size  segments
       prior  to  sending the data downstream (the last segment may contain less than the maximum
       packet size). If nbyte does not fall within the range and the minimum value  is	non-zero,
       write()	shall fail with errno set to [ERANGE]. Writing a zero-length buffer ( nbyte is 0)
       to a STREAMS device sends 0 bytes with 0 returned. However, writing a  zero-length  buffer
       to  a STREAMS-based pipe or FIFO sends no message and 0 is returned. The process may issue
       I_SWROPT ioctl() to enable zero-length messages to be sent across the pipe or FIFO.

       When writing to a STREAM, data messages are created with a priority band of 0. When  writ-
       ing to a STREAM that is not a pipe or FIFO:

	* If  O_NONBLOCK  is  clear, and the STREAM cannot accept data (the STREAM write queue is
	  full due to internal flow control conditions), write() shall block until  data  can  be
	  accepted.

	* If O_NONBLOCK is set and the STREAM cannot accept data, write() shall return -1 and set
	  errno to [EAGAIN].

	* If O_NONBLOCK is set and part of the buffer has been written while a condition in which
	  the STREAM cannot accept additional data occurs, write() shall terminate and return the
	  number of bytes written.

       In addition, write() shall fail if the STREAM head has  processed  an  asynchronous  error
       before  the call. In this case, the value of errno does not reflect the result of write(),
       but reflects the prior error.

       The pwrite() function shall be equivalent to write(), except that it writes into  a  given
       position  without changing the file pointer. The first three arguments to pwrite() are the
       same as write() with the addition of a fourth argument offset  for  the	desired  position
       inside the file.

RETURN VALUE
       Upon successful completion, write()    and pwrite() shall return the number of bytes actu-
       ally written to the file associated with fildes. This number shall never be  greater  than
       nbyte. Otherwise, -1 shall be returned and errno set to indicate the error.

ERRORS
       The write() and	 pwrite()  functions shall fail if:

       EAGAIN The  O_NONBLOCK flag is set for the file descriptor and the thread would be delayed
	      in the write() operation.

       EBADF  The fildes argument is not a valid file descriptor open for writing.

       EFBIG  An attempt was made to write a file that exceeds the implementation-defined maximum
	      file size    or the process' file size limit,   and there was no room for any bytes
	      to be written.

       EFBIG  The file is a regular file, nbyte is greater than 0, and the starting  position  is
	      greater  than  or equal to the offset maximum established in the open file descrip-
	      tion associated with fildes.

       EINTR  The write operation was terminated due to the receipt of a signal, and no data  was
	      transferred.

       EIO    The  process  is	a member of a background process group attempting to write to its
	      controlling terminal, TOSTOP is set, the process is neither ignoring  nor  blocking
	      SIGTTOU,	and  the process group of the process is orphaned. This error may also be
	      returned under implementation-defined conditions.

       ENOSPC There was no free space remaining on the device containing the file.

       EPIPE  An attempt is made to write to a pipe or FIFO that is not open for reading  by  any
	      process,	or that only has one end open. A SIGPIPE signal shall also be sent to the
	      thread.

       ERANGE The transfer request size was outside the range supported by the STREAMS file asso-
	      ciated with fildes.

       The write() function shall fail if:

       EAGAIN or EWOULDBLOCK

	      The file descriptor is for a socket, is marked O_NONBLOCK, and write would block.

       ECONNRESET
	      A write was attempted on a socket that is not connected.

       EPIPE  A  write	was  attempted on a socket that is shut down for writing, or is no longer
	      connected. In the latter case, if the socket is of type  SOCK_STREAM,  the  SIGPIPE
	      signal is generated to the calling process.

       The write() and	 pwrite()  functions may fail if:

       EINVAL The  STREAM  or multiplexer referenced by fildes is linked (directly or indirectly)
	      downstream from a multiplexer.

       EIO    A physical I/O error has occurred.

       ENOBUFS
	      Insufficient resources were available in the system to perform the operation.

       ENXIO  A request was made of a nonexistent device, or the request was outside the capabil-
	      ities of the device.

       ENXIO  A hangup occurred on the STREAM being written to.

       A  write  to  a	STREAMS file may fail if an error message has been received at the STREAM
       head. In this case, errno is set to the value included in the error message.

       The write() function may fail if:

       EACCES A write was attempted on a socket and the calling process does not have appropriate
	      privileges.

       ENETDOWN
	      A write was attempted on a socket and the local network interface used to reach the
	      destination is down.

       ENETUNREACH

	      A write was attempted on a socket and no route to the network is present.

       The pwrite() function shall fail and the file pointer remain unchanged if:

       EINVAL The offset argument is invalid. The value is negative.

       ESPIPE fildes is associated with a pipe or FIFO.

       The following sections are informative.

EXAMPLES
   Writing from a Buffer
       The following example writes data from the buffer pointed to by buf to the file associated
       with the file descriptor fd.

	      #include <sys/types.h>
	      #include <string.h>
	      ...
	      char buf[20];
	      size_t nbytes;
	      ssize_t bytes_written;
	      int fd;
	      ...
	      strcpy(buf, "This is a test\n");
	      nbytes = strlen(buf);

	      bytes_written = write(fd, buf, nbytes);
	      ...

APPLICATION USAGE
       None.

RATIONALE
       See also the RATIONALE section in read() .

       An attempt to write to a pipe or FIFO has several major characteristics:

	* Atomic/non-atomic:  A  write	is atomic if the whole amount written in one operation is
	  not interleaved with data from any other process. This is useful when there are  multi-
	  ple  writers	sending  data  to  a single reader. Applications need to know how large a
	  write request can be expected to  be	performed  atomically.	This  maximum  is  called
	  {PIPE_BUF}. This volume of IEEE Std 1003.1-2001 does not say whether write requests for
	  more than {PIPE_BUF} bytes are atomic, but requires that writes of {PIPE_BUF} or  fewer
	  bytes shall be atomic.

	* Blocking/immediate: Blocking is only possible with O_NONBLOCK clear. If there is enough
	  space for all the data requested to be written immediately, the  implementation  should
	  do so. Otherwise, the process may block; that is, pause until enough space is available
	  for writing. The effective size of a pipe or FIFO (the maximum amount that can be writ-
	  ten in one operation without blocking) may vary dynamically, depending on the implemen-
	  tation, so it is not possible to specify a fixed value for it.

	* Complete/partial/deferred: A write request:

	  int fildes;
	  size_t nbyte;
	  ssize_t ret;
	  char *buf;

	  ret = write(fildes, buf, nbyte);

       may return:

       Complete
	      ret=nbyte

       Partial
	      ret<nbyte

	      This shall never happen if nbyte<= {PIPE_BUF}.  If  it  does  happen  (with  nbyte>
	      {PIPE_BUF}), this volume of IEEE Std 1003.1-2001 does not guarantee atomicity, even
	      if ret<= {PIPE_BUF}, because  atomicity  is  guaranteed  according  to  the  amount
	      requested, not the amount written.

       Deferred:
	      ret=-1, errno=[EAGAIN]

	      This error indicates that a later request may succeed. It does not indicate that it
	      shall succeed, even if nbyte<= {PIPE_BUF}, because if no	process  reads	from  the
	      pipe  or	FIFO,  the  write never succeeds. An application could usefully count the
	      number of times [EAGAIN] is caused by a particular value of nbyte>  {PIPE_BUF}  and
	      perhaps  do later writes with a smaller value, on the assumption that the effective
	      size of the pipe may have decreased.

       Partial and deferred writes are only possible with O_NONBLOCK set.

       The relations of these properties are shown in the following tables:

			     Write to a Pipe or FIFO with O_NONBLOCK clear
	       Immediately Writable:  None	       Some		nbyte
	       nbyte<={PIPE_BUF}      Atomic blocking  Atomic blocking	Atomic immediate
				      nbyte	       nbyte		nbyte
	       nbyte>{PIPE_BUF}       Blocking nbyte   Blocking nbyte	Blocking nbyte

       If the O_NONBLOCK flag is clear, a write request shall block if the amount writable  imme-
       diately	is  less  than	that  requested. If the flag is set (by fcntl()), a write request
       shall never block.

			      Write to a Pipe or FIFO with O_NONBLOCK set
		   Immediately Writable:  None		Some	       nbyte
		   nbyte<={PIPE_BUF}	  -1, [EAGAIN]	-1, [EAGAIN]   Atomic nbyte
		   nbyte>{PIPE_BUF}	  -1, [EAGAIN]	<nbyte or -1,  <=nbyte or -1,
							[EAGAIN]       [EAGAIN]

       There is no exception regarding partial writes when O_NONBLOCK is set. With the	exception
       of  writing to an empty pipe, this volume of IEEE Std 1003.1-2001 does not specify exactly
       when a partial write is performed since that would require specifying internal details  of
       the  implementation.  Every  application  should be prepared to handle partial writes when
       O_NONBLOCK is set and the requested amount is  greater  than  {PIPE_BUF},  just	as  every
       application  should  be	prepared to handle partial writes on other kinds of file descrip-
       tors.

       The intent of forcing writing at least one byte if any can be written is  to  assure  that
       each  write  makes  progress  if  there	is  any  room  in the pipe. If the pipe is empty,
       {PIPE_BUF} bytes must be written; if not, at least some progress must have been made.

       Where this volume of IEEE Std 1003.1-2001 requires -1 to be  returned  and  errno  set  to
       [EAGAIN],  most	historical implementations return zero (with the O_NDELAY flag set, which
       is the historical predecessor  of  O_NONBLOCK,  but  is	not  itself  in  this  volume  of
       IEEE Std 1003.1-2001).  The  error indications in this volume of IEEE Std 1003.1-2001 were
       chosen so that an application can distinguish these cases from end-of-file.  While write()
       cannot  receive an indication of end-of-file, read() can, and the two functions have simi-
       lar return values. Also, some existing systems (for  example,  Eighth  Edition)	permit	a
       write  of  zero	bytes  to  mean that the reader should get an end-of-file indication; for
       those systems, a return value of zero from write() indicates a successful write of an end-
       of-file indication.

       Implementations	are  allowed,  but  not  required,  to perform error checking for write()
       requests of zero bytes.

       The concept of a {PIPE_MAX} limit (indicating the maximum number  of  bytes  that  can  be
       written	to  a pipe in a single operation) was considered, but rejected, because this con-
       cept would unnecessarily limit application writing.

       See also the discussion of O_NONBLOCK in read() .

       Writes can be serialized with respect to other reads and writes. If a read() of file  data
       can  be	proven	(by any means) to occur after a write() of the data, it must reflect that
       write(), even if the calls are made by different processes. A similar requirement  applies
       to  multiple  write  operations to the same file position. This is needed to guarantee the
       propagation of data from write() calls to subsequent read()  calls.  This  requirement  is
       particularly  significant  for  networked file systems, where some caching schemes violate
       these semantics.

       Note that this is specified in terms of read() and write().  The  XSI  extensions  readv()
       and writev() also obey these semantics. A new "high-performance" write analog that did not
       follow these serialization requirements would also be permitted by this wording. This vol-
       ume  of IEEE Std 1003.1-2001 is also silent about any effects of application-level caching
       (such as that done by stdio).

       This volume of IEEE Std 1003.1-2001 does not specify the value of the file offset after an
       error  is returned; there are too many cases. For programming errors, such as [EBADF], the
       concept is meaningless since no file is involved. For errors  that  are	detected  immedi-
       ately,  such  as  [EAGAIN],  clearly  the pointer should not change. After an interrupt or
       hardware error, however, an updated value would be very useful and is the behavior of many
       implementations.

       This  volume  of  IEEE Std 1003.1-2001 does not specify behavior of concurrent writes to a
       file from multiple processes.  Applications should use some form of concurrency control.

FUTURE DIRECTIONS
       None.

SEE ALSO
       chmod() , creat() , dup() , fcntl() , getrlimit() , lseek() , open() , pipe() , ulimit() ,
       writev()  ,  the Base Definitions volume of IEEE Std 1003.1-2001, <limits.h>, <stropts.h>,
       <sys/uio.h>, <unistd.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					 WRITE(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:44 PM.