unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



write(2)							     write(2)



NAME

  write, pwrite, writev	- Write	to a file

SYNOPSIS

  #include <&lt;unistd.h>&gt;

  ssize_t write(
	  int filedes,
	  const	void *buffer,
	  size_t nbytes);

  ssize_t pwrite(
	  int filedes,
	  const	void *buffer,
	  size_t nbytes);
	  off_t	offset);

  #include <&lt;sys/uio.h>&gt;

  ssize_t writev(
	  int filedes,
	  const	struct iovec *iov,
	  int iov_count);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  write():  XSH4.2, XNS5.0

  pwrite():  POSIX.1c

  writev():  XSH4.2, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  filedes   Identifies the file	to which the data is to	be written.

  buffer    Points to the buffer containing the	data to	be written.

  nbytes    Specifies the number of bytes to write to the file associated
	    with the filedes parameter.

  offset    Specifies the desired start	position inside	the file associated
	    with the filedes parameter.

  iov	    Points to an array of iovec	structures, which identifies the
	    buffers containing the data	to be written. The iovec structure is
	    defined in the sys/uio.h header file and contains the following
	    members:
		    void  *iov_base;
		    size_t iov_len;



  iov_count Specifies the number of iovec structures pointed to	by the iov
	    parameter.

DESCRIPTION

  The write() function attempts	to write nbytes	of data	to the file associ-
  ated with the	filedes	parameter from the buffer pointed to by	the buffer
  parameter.

  If the nbytes	parameter is 0 (zero), the write() function returns 0 (zero)
  and has no other results if the file is a regular file.

  [XNS5.0]  If filedes refers to a socket, a write() request is	equivalent to
  a send() request with	no flags set.

  The pwrite() function	performs the same action as write(), except that it
  writes into a	given position in the file (specified by the offset parame-
  ter) without changing	the file pointer.

  The writev() function	performs the same action as the	write()	function, but
  gathers the output data from the iov_count buffers specified by the array
  of iovec structures pointed to by the	iov parameter. Each iovec entry
  specifies the	base address and length	of an area in memory from which	data
  should be written.  The iov_count parameter is valid if greater than 0
  (zero) and less than or equal	to IOV_MAX, which is defined in	the limits.h
  header file.	The writev() function always writes a complete area before
  proceeding to	the next.

  If filedes refers to a regular file and all of the iov_len members in	the
  array	pointed	to by iov are 0	(zero),	writev() returns 0 and has no other
  effect.

  With regular files and devices capable of seeking, the actual	writing	of
  data proceeds	from the position in the file indicated	by the file pointer.
  If this incremented file pointer is greater than the length of the file,
  the length of	the file is set	to this	file offset.  Upon return from the
  write() or pwrite() function,	the file pointer increments by the number of
  bytes	actually written.

  If the O_SYNC	flag of	the file status	flags is set and the filedes parame-
  ter refers to	a regular file,	a successful write() or	pwrite() function
  does not return until	the data is delivered to the underlying	hardware (as
  described in the open() function).

  With devices incapable of seeking, writing always takes place	starting at
  the current position.	The value of a file pointer associated with such a
  device is undefined.

  If the O_APPEND flag of the file status is set, the file offset is set to
  the end of the file prior to each write, and no intervening file modifica-
  tion operation occurs	between	changing the file offset and the write opera-
  tion.

  If a write() or pwrite() requests that more bytes be written than there is
  space	for (for example, the ulimit() or the physical end of a	medium), only
  as many bytes	as there is space for are written. For example,	suppose	there
  is space for 20 bytes	more in	a file before reaching a limit.	A write	of
  512 bytes returns 20.	 The next write	of a nonzero number of bytes will
  give a failure return	(except	as noted below)	and [XSH4.2]   a SIGXFSZ sig-
  nal is generated for the process.

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

  If a write() or pwrite() function is interrupted by a	signal after it	suc-
  cessfully writes some	data, it returns the number of bytes written.

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

    +  Any successful read() from each byte position in	the file that was
       modified	by that	write returns the data specified by the	write()	or
       pwrite()	for that position until	such byte positions are	again modi-
       fied.

    +  Any subsequent successful write() or pwrite() to	the same byte posi-
       tion in the file	overwrites that	file data.

  Write	requests to a pipe (or FIFO) are handled the same as a regular file
  with the following exceptions:

    +  There is	no file	offset associated with a pipe; hence each write() or
       pwrite()	request	appends	to the end of the pipe.

    +  If the size of the write() or pwrite() request is less than or equal
       to the value of the PIPE_BUF system variable, the write() or pwrite()
       function	is guaranteed to be atomic. The	data is	not interleaved	with
       data from other processes doing writes on the same pipe.	Writes of
       greater than PIPE_BUF bytes can have data interleaved, on arbitrary
       boundaries, with	writes by other	processes, whether or not O_NONBLOCK
       is set.

       [Tru64 UNIX]  This also applies whether or not O_NDELAY is set.

    +  If O_NONBLOCK is	clear, a write() or pwrite() request to	a full pipe
       causes the process to block until enough	space becomes available	to
       handle the entire request.

       [Tru64 UNIX]  This also applies if O_NDELAY is clear.

    +  If the O_NONBLOCK flag is set, write() or pwrite() requests are han-
       dled differently	in the following ways: the function does block the
       process;	requests for PIPE_BUF or fewer bytes either succeed com-
       pletely and return nbytes, or return -1 and set errno to	[EAGAIN]. A
       request for greater than	PIPE_BUF bytes either transfers	as much	as it
       can and returns the number of bytes written, or transfers no data and
       returns -1 with errno set to [EAGAIN]. Also, if a request is greater
       than PIPE_BUF bytes and all data	previously written to the pipe has
       been read, write() or pwrite() transfers	at least PIPE_BUF bytes.

       [Tru64 UNIX]  This also applies if O_NDELAY is set.

  When attempting to write to a	file descriptor	(other than a pipe or a	FIFO)
  that supports	nonblocking writes and cannot accept data immediately, the
  write() and pwrite() functions behave	as follows:

    +  If O_NONBLOCK is	clear, the function blocks until the data can be
       accepted.

       [Tru64 UNIX]  This also applies if O_NDELAY is clear.

    +  If O_NONBLOCK is	set, the function does not block the process.
       Instead,	if some	data can be written without blocking the process, it
       writes as much as it can	and returns the	number of bytes	written.
       Otherwise, it returns -1	and errno is set to [EAGAIN].

       [Tru64 UNIX]  This also applies if O_NDELAY is set, except 0 (zero) is
       returned.

  [Tru64 UNIX]	When attempting	to write to a regular file with	enforcement
  mode record locking enabled and all or part of the region to be written is
  currently locked by another process, the write() and pwrite()	functions
  behave as follows:

    +  If O_NDELAY and O_NONBLOCK are clear (the default), the calling pro-
       cess blocks until all of	the blocking locks are removed or until	the
       function	is terminated by a signal.

    +  If O_NDELAY or O_NONBLOCK is set, the function returns -1 and sets
       errno to	[EAGAIN].

  Upon successful completion, the write() or pwrite() function marks the
  st_ctime and st_mtime	fields of the file for update and, if the file is a
  regular file,	clears its set-user ID and set-group ID	attributes.

  The fcntl() function provides	more information about record locks.

  Writing Data to STREAMS Files

  [XSH4.2]  For	STREAMS	files, the operation of	write()	and pwrite() is
  determined by	the values of the minimum and maximum nbytes range ("packet
  size"	accepted by the	STREAM.	These values are contained in the topmost
  STREAM module.  Unless the user pushes the topmost module, these values
  cannot be set	or tested from user level (see I_PUSH on the streamio(7))
  reference page).  If nbytes falls within the packet size range, nbytes
  bytes	are written. If	nbytes does not	fall within the	range and the minimum
  packet size value is 0 (zero), write() or pwrite() breaks 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 nbytes does not
  fall within the range	and the	minimum	value is nonzero, write() or pwrite()
  fails	with errno set to [ERANGE].  Writing a zero-length buffer (nbytes is
  0) 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 pro-
  cess may issue I_SWROPT ioctl() to enable zero-length	messages to be sent
  across the pipe or FIFO.

  [XSH4.2]   When writing to a STREAM, data messages are created with a
  priority band	of 0 (zero). When writing to a STREAM that is not a pipe or
  FIFO,	the write() and	pwrite() functions behave as follows:

    +  If O_NONBLOCK is	clear and the STREAM cannot accept data	(that is, the
       STREAM write queue is full due to internal flow control conditions),
       the function blocks until data can be accepted.

       [Tru64 UNIX]  This also applies if O_NDELAY is clear.

    +  If O_NONBLOCK is	set and	the STREAM cannot accept data, the function
       returns -1 and sets errno to [EAGAIN].

       [Tru64 UNIX]  This also applies if O_NDELAY is set.

    +  If O_NONBLOCK is	set and	part of	the buffer has been written when a
       condition occurs	in which the STREAM cannot accept additional data,
       the function terminates and returns the number of bytes written.

       [Tru64 UNIX]  This also applies if O_NDELAY is set.

  [XSH4.2]  In addition, write(), pwrite() and writev()	will fail if the
  STREAM head had processed an asynchronous error before the call. In this
  case,	the value of errno does	not reflect the	result of write(), pwrite(),
  or writev(), but reflects the	prior error.

NOTES

  [Tru64 UNIX]	For compatibility with earlier releases, values	for iov_len
  that are greater than	or equal to 2^63 will be treated as zero.

  [Tru64 UNIX]	The write(), pwrite(), and writev() functions, which suspend
  the calling process until the	request	is completed, are redefined so that
  only the calling thread is suspended.

  [Tru64 UNIX]	When debugging a module	that includes the writev() function,
  use _Ewritev to refer	to the writev()	call.

  When a read(), pread(), write(), or pwrite() system call on a	pipe is
  interrupted by a signal and no bytes have been transferred through the
  pipe,	a value	of -1 is returned and errno is set to [EINTR]. This behavior
  is different from previous releases in which both read() and write() either
  restarted the	transfer or set	errno to [EINTR], depending on the setting of
  the SA_RESTART flag for the interrupting signal.

  As a result of this change, applications must	now either handle the [EINTR]
  return or block any expected signals for the duration	of the read(),
  pread(), write(), or pwrite()	operation.

RETURN VALUES

  Upon successful completion, the write() or pwrite() function returns the
  number of bytes actually written to the file associated with the filedes
  parameter.  This number is never greater than	nbytes.	 Otherwise, a value
  of -1	is returned and	errno is set to	indicate the error.

  Upon successful completion, the writev() function returns the	number of
  bytes	that were actually written.  Otherwise,	a value	of -1 is returned,
  the file-pointer remains unchanged, and errno	is set to indicate the error.

  End-of-Media Handling	for Tapes

  If writing goes beyond the "early warning" EOT indicator while this indica-
  tor is disabled, the write(),	pwrite(), and writev() functions will return
  the number of	bytes actually written.	The write(), pwrite(), and writev()
  functions return a value of -1, if:

    +  Attempting to write past	the "real" EOT.

    +  Attempting to write past	"early warning"	EOT indicator while this
       indicator is enabled.

  Refer	to mtio(7) for information on enabling and disabling "early warning"
  EOT.

  End-of-Media Handling	for Disks

  Disk end-of-media handling is	POSIX-compliant. Attempting to write at	or
  beyond the end of a partition	returns	a value	of -1.	A partial write
  returns the number of	bytes actually written.

  Note:	A partial write	is a request that spans	the end	of a partition.

ERRORS

  The write(), pwrite(), and writev() functions	set errno to the specified
  values for the following conditions:

  [EAGAIN]  The	O_NONBLOCK flag	is set on this file and	the process would be
	    delayed in the write operation.

	    [Tru64 UNIX]  An attempt was made to write to a STREAM that	can-
	    not	accept data with either	the O_NDELAY or	O_NONBLOCK flag	set.

	    [Tru64 UNIX]  An enforcement mode record lock is outstanding in
	    the	portion	of the file that is to be written.

  [EBADF]   The	filedes	parameter does not specify a valid file	descriptor
	    that is open for writing.

  [EDEADLK] [Tru64 UNIX]  Enforced record locking is enabled, O_NDELAY is
	    clear, and a deadlock condition is detected.

  [EDQUOT]  [Tru64 UNIX]  The write failed because the user's disk block
	    quota is exhausted.

  [EFAULT]  [Tru64 UNIX]  The buffer parameter or part of the iov parameter
	    points to a	location outside the allocated address space of	the
	    process.

  [EFBIG]   An attempt was made	to write a file	that exceeds the maximum file
	    size.

  [EINTR]   A write() or pwrite() on a pipe is interrupted by a	signal and no
	    bytes have been transferred	through	the pipe.

  [EINVAL]  [XSH4.2]  The STREAM or multiplexer	referenced by filedes is
	    linked (directly or	indirectly) downstream from a multiplexer.

	    [XSH4.2]  The iov_count parameter value was	less than or equal to
	    0 or greater than IOV_MAX.

	    [XSH4.2]  The sum of the iov_len values in the iov array would
	    overflow an	ssize_t.

	    [Tru64 UNIX]  The file position pointer associated with the
	    filedes parameter was negative.

	    [Tru64 UNIX]  One of the iov_len values in the iov array was
	    negative or	the sum	overflowed a 32-bit integer.

  [EIO]	    [XSH4.2]  A	physical I/O error occurred. These errors do not
	    always occur with the associated function, but can occur with the
	    subsequent function.

  [ENOLCK]  [Tru64 UNIX]  The file has enforcement mode	file locking set, and
	    allocating another locked region would exceed the configurable
	    system limit of NLOCK_RECORD.

  [ENOSPC]  [XSH4.2]  No free space is left on the file	system containing the
	    file.

	    [Tru64 UNIX]  An attempt was made to write past the	"early warn-
	    ing" EOT while this	indicator was enabled.

	    [Tru64 UNIX]  An attempt was made to write at or beyond the	end
	    of a partition.

  [ENXIO]   [XSH4.2]  A	hangup occurred	on the STREAM being written to.

	    The	device associated with file descriptor (the filedes parame-
	    ter) is a block special device or character	special	file, and the
	    file pointer is out	of range.

  [EPERM]   [Tru64 UNIX]  An attempt was made to write to a socket or type
	    SOCK_STREAM	that is	not connected to a peer	socket.

  [EPIPE]   [XSH4.2]  An attempt was made to write to a	pipe that has only
	    one	end open.

	    An attempt was made	to write to a pipe or FIFO that	is not opened
	    for	reading	by any process.	 A SIGPIPE signal is sent to the pro-
	    cess.

  [ERANGE]  [XSH4.2]  The transfer request size	was outside the	range sup-
	    ported by the STREAMS file associated with filedes.

  In addition, the pwrite() function fails and the file	pointer	remains
  unchanged if the following is	true:

  [ESPIPE]  The	file specified by fildes is associated with a pipe or FIFO.

  [XSH4.2]  A write to a STREAMS file can 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.

  For NFS file access, if the write(), pwrite(), or writev() function fails,
  errno	may also be set	to one of the following	values:

  [EFBIG]   [Tru64 UNIX]   For filesystems mounted with	the nfsv2 option, the
	    process attempted to write beyond the 2 gigabyte boundary.

  [EISDIR]  [Tru64 UNIX]   The named file is a directory and write access is
	    requested.

  [ENOBUFS] [Tru64 UNIX]   Insufficient	resources, such	as buffers, are
	    available to complete the call. Typically, a call used with	sock-
	    ets	has failed due to a shortage of	message	or send/receive
	    buffer space.

  [EROFS]   [Tru64 UNIX]   The named file resides on a read-only file system
	    and	write access is	required.

  [ESTALE]  [Tru64 UNIX]   The NFS file	handle is stale. An opened file	was
	    deleted by the server or another client, a client cannot open a
	    file because the server has	unmounted or unexported	the remote
	    directory, or the directory	that contains an opened	file was
	    either unmounted or	unexported by the server.

  If the write(), pwrite(), or writev()	function fails while in	the System V
  habitat, errno may also be set to one	of the following errors:

  [EAGAIN]  [Tru64 UNIX]   A write to a	pipe (FIFO) of PIPE_BUF	bytes or less
	    is requested, O_NONBLOCK is	set, and less than nbytes bytes	of
	    free space is available.

	    [Tru64 UNIX]  Enforced record locking was enabled, O_NDELAY	or
	    O_NONBLOCK was set and there were record-locks on the file,	or
	    O_NONBLOCK was set,	and data cannot	be accepted immediately.

  [EINVAL]  [Tru64 UNIX]   The sum of the iov_len values in the	iov array
	    overflowed an integer.

  [ERANGE]  [Tru64 UNIX]   Attempts to write to	a STREAM with nbytes are out-
	    side the specified minimum and maximum range, and the minimum
	    value is non-zero.

RELATED	INFORMATION

  Functions: open(2), fcntl(2),	lseek(2), mtio(7), open(2), getmsg(2),
  lockf(3), pipe(2), poll(2), select(2)	ulimit(3)


  Standards: standards(5)