Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WRITE(2V)							     WRITE(2V)

NAME
       write, writev - write output

SYNOPSIS
       int write(fd, buf, nbyte)
       int fd;
       char *buf;
       int nbyte;

       #include	<sys/types.h>
       #include	<sys/uio.h>

       int writev(fd, iov, iovcnt)
       int fd;
       struct iovec *iov;
       int iovcnt;

SYSTEM V SYNOPSIS
       int write(fd, buf, nbyte)
       int fd;
       char *buf;
       unsigned	nbyte;

DESCRIPTION
       write()	attempts to write nbyte	bytes of data to the object referenced
       by the descriptor fd from the buffer pointed to by buf.	writev()  per-
       forms the same action, but gathers the output data from the iovcnt buf-
       fers specified by the members of	the  iov  array:  iov[0],iov[1],  ...,
       iov[iovcnt-1].	If  nbyte is zero, write() takes no action and returns
       0.  writev(), however, returns -1 and sets the  global  variable	 errno
       (see ERRORS below).

       For writev(), the iovec structure is defined as

	      struct iovec {
		   caddr_t   iov_base;
		   int	iov_len;
	      };

       Each  iovec  entry  specifies the base address and length of an area in
       memory from which data should be	written.   writev()  always  writes  a
       complete	area before proceeding to the next.

       On  objects  capable of seeking,	the write() starts at a	position given
       by the seek pointer associated with fd, (see lseek(2V)).	  Upon	return
       from  write(),  the  seek pointer is incremented	by the number of bytes
       actually	written.

       Objects that are	not capable of seeking always write from  the  current
       position.  The value of the seek	pointer	associated with	such an	object
       is undefined.

       If the O_APPEND flag of the file	status flags is	set, the seek  pointer
       is set to the end of the	file prior to each write.

       If the process calling write() or writev() receives a signal before any
       data are	written, the system call is restarted, unless the process  ex-
       plicitly	 set the signal	to interrupt the call using sigvec() or	sigac-
       tion() (see the discussions of SV_INTERRUPT on sigvec(2)	and  SA_INTER-
       RUPT  on	 sigaction(3V)).   If  write() or writev() is interrupted by a
       signal after successfully writing some data, it returns the  number  of
       bytes written.

       For  regular files, if the O_SYNC flag of the file status flags is set,
       write() does not	return until both the file data	and file  status  have
       been  physically	 updated.   This  function is for special applications
       that require extra reliability at the cost of performance.   For	 block
       special	files, if O_SYNC is set, the write() does not return until the
       data has	been physically	updated.

       If the real user	is not the super-user, then write()  clears  the  set-
       user-id bit on a	file.  This prevents penetration of system security by
       a user who "captures" a writable	set-user-id file owned by  the	super-
       user.

       For STREAMS (see	intro(2)) files, the operation of write() and writev()
       are determined by the values of the minimum and	maximum	 packet	 sizes
       accepted	 by  the  stream.   These  values are contained	in the topmost
       stream module.  Unless the user pushes (see I_PUSH in streamio(4))  the
       topmost	module,	these values can not be	set or tested from user	level.
       If the total number of bytes to be written falls	within the packet size
       range, that many	bytes are written.  If the total number	of bytes to be
       written does not	fall within the	range  and  the	 minimum  packet  size
       value  is  zero,	write()	and writev() break the data to be written into
       maximum packet size segments prior to sending the data downstream  (the
       last  segment  may  contain less	than the maximum packet	size).	If the
       total number of bytes to	be written does	not fall within	the range  and
       the  minimum value is non-zero, write() and writev() fail and set errno
       to ERANGE.  Writing a zero-length buffer	(the total number of bytes  to
       be written is zero) sends zero bytes with zero returned.

       When a descriptor or the	object it refers to is marked for non-blocking
       I/O, and	the descriptor refers to an object subject  to	flow  control,
       such  as	 a socket, a pipe (or FIFO), or	a stream, write() and writev()
       may write fewer bytes than requested; the return	value must  be	noted,
       and the remainder of the	operation should be retried when possible.  If
       such an object's	buffers	are full, so that it cannot accept  any	 data,
       then:

	      o	 If  the  object  to which the descriptor refers is marked for
		 non-blocking I/O using	the FIONBIO request to ioctl(2), or by
		 using	fcntl(2V) to set the FNDELAY or	O_NDELAY flag (defined
		 in <sys/fcntl.h>), write()  returns  -1  and  sets  errno  to
		 EWOULDBLOCK.

       Upon  successful	 completion, write() marks for update the st_ctime and
       st_mtime	fields of the file.

SYSTEM V DESCRIPTION
       write() and writev() behave as described	above, except:

       When a descriptor or the	object it refers to is marked for non-blocking
       I/O,  and  the  descriptor refers to an object subject to flow control,
       such as a socket, a pipe	(or FIFO), or a	stream,	write()	 and  writev()
       may  write  fewer bytes than requested; the return value	must be	noted,
       and the remainder of the	operation should be retried when possible.  If
       such  an	 object's buffers are full, so that it cannot accept any data,
       then:

	      o	 If the	descriptor is marked for non-blocking I/O by using fc-
		 ntl()	to set the FNBIO or O_NDELAY flag (defined in <sys/fc-
		 ntl.h>), and does not refer to	a stream, the write()  returns
		 0.   If  the  descriptor  is marked for non-blocking I/O, and
		 refers	to a stream, write() returns -1	and sets errno to  EA-
		 GAIN.

	      o	 If  the  descriptor  is marked	for non-blocking I/O using fc-
		 ntl() to set the FNONBLOCK or	O_NONBLOCK  flag  (defined  in
		 <sys/fcntl.h>),  write()  requests  for {PIPE_BUF} (see path-
		 conf(2V)) or fewer bytes either succeed completely and	return
		 nbyte,	 or  return -1 and set errno to	EAGAIN.	 A write() re-
		 quest for greater than	{PIPE_BUF} bytes either	transfers what
		 it  can and returns the number	of bytes written, or transfers
		 no data and returns -1	 and  sets  errno  to  EAGAIN.	 If  a
		 write() request is greater than {PIPE_BUF} bytes and all data
		 previously written to the pipe	has been read, write()	trans-
		 fers at least {PIPE_BUF} bytes.

RETURN VALUES
       write()	and  writev()  return  the number of bytes actually written on
       success.	 On failure, they return -1 and	set errno to indicate the  er-
       ror.

ERRORS
       write() and writev() fail and the seek pointer remains unchanged	if one
       or more of the following	are true:

       EBADF		   fd is not a valid descriptor	open for writing.

       EDQUOT		   The user's quota of disk blocks on the file	system
			   containing the file has been	exhausted.

       EFAULT		   Part	 of  iov  or  data  to	be written to the file
			   points  outside  the	 process's  allocated  address
			   space.

       EFBIG		   An  attempt	was  made to write a file that exceeds
			   the process's file size limit or the	 maximum  file
			   size.

       EINTR		   The	process	 performing  a write received a	signal
			   before any data were	written, and  the  signal  was
			   set to interrupt the	system call.

       EINVAL		   The stream is linked	below a	multiplexor.

			   The seek pointer associated with fd was negative.

       EIO		   An I/O error	occurred while reading from or writing
			   to the file system.

			   The process is in a background process group	and is
			   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.

       ENOSPC		   There is no free space remaining on the file	system
			   containing the file.

       ENXIO		   A hangup occurred on	the stream being written to.

       EPIPE		   An  attempt	is made	to write to a pipe that	is not
			   open	for reading by any process (or to a socket  of
			   type	 SOCK_STREAM  that  is	connected  to  a  peer
			   socket.)  Note: an attempted	 write	of  this  kind
			   also	 causes	 you  to receive a SIGPIPE signal from
			   the kernel.	If you've not made a special provision
			   to  catch  or ignore	this signal, then your process
			   dies.

       ERANGE		   fd refers to	a stream, the total number of bytes to
			   be written is outside the minimum and maximum write
			   range, and the minimum value	is non-zero.

       EWOULDBLOCK	   The file was	marked for non-blocking	 I/O,  and  no
			   data	could be written immediately.

       In addition to the above, writev() may set errno	to:

       EINVAL		   iovcnt was less than	or equal to 0, or greater than
			   16.

			   One of the iov_len values in	the iov	array was neg-
			   ative.

			   The	sum  of	 the  iov_len  values in the iov array
			   overflowed a	32-bit integer.

       A write to a STREAMS file can fail if an	error  message	has  been  re-
       ceived at the stream head.  In this case, errno is set to the value in-
       cluded in the error message.

SYSTEM V ERRORS
       write() fails and sets errno as described above,	except:

       EAGAIN		   The descriptor referred to a	stream,	was marked for
			   non-blocking	 I/O, and no data could	be written im-
			   mediately.

			   The O_NONBLOCK flag is set for the file  descriptor
			   and write() would block.

SEE ALSO
       dup(2V),	 fcntl(2V), intro(2), ioctl(2),	lseek(2V), open(2V), pipe(2V),
       select(2), sigvec(2), signal(3V)

				21 January 1990			     WRITE(2V)

NAME | SYNOPSIS | SYSTEM V SYNOPSIS | DESCRIPTION | SYSTEM V DESCRIPTION | RETURN VALUES | ERRORS | SYSTEM V ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=write&sektion=2v&manpath=SunOS+4.1.3>

home | help