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

FreeBSD Manual Pages


home | help
write(2)							      write(2)

       write, writev - write on	a file

       write (fd, buf, nbytes)
       int fd;
       char *buf;
       int nbytes;

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

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

       fd	   Descriptor returned by a or system call.

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

       nbytes	   Positive integer defining the number	of bytes to be written
		   from	the buffer.

       iov	   Points to a data structure of type which defines the	start-
		   ing	location  of  the set of vectors forming the array and
		   the length of each individual vector	in  the	 array	to  be

		   This	structure is defined in	as follows: struct iovec {

			  caddr_t   iov_base ;
			  int	     iov_len ; } ; The data type is defined in
		   and is the recommended way to define	an address for a char-
		   acter  value.   In  any  case,  the address is the starting
		   address of the set of vectors.  The integer	value  is  the
		   length of each individual vector, in	bytes.

       ioveclen	   Defines  the	 number	 of vectors in the array of data to be
		   written.  Note that the numbering  of  the  vectors	begins
		   with	0 and proceeds through ioveclen	-1.

       The system call attempts	to write a buffer of data to a file.  The sys-
       tem call	attempts to write an array of buffers of data to a file.

       When a file is opened to	a device capable of seeking (such as a disk or
       tape), the write	starts at the position given by	the file pointer asso-
       ciated with the file descriptor,	fd.  This file pointer is the  offset,
       in  bytes,  from	the beginning of the file where	the write is to	begin.
       When the	file is	first opened, the file pointer is set at 0.  It	can be
       modified	 by  the  and  system  calls.  When the	call returns, the file
       pointer is incremented by the number of bytes actually written.

       When the	file is	opened to a device not capable	of  seeking  (such  as
       sockets,	 pipes,	 or  terminals), the write starts at the current posi-
       tion.  The value	of the pointer associated with such an object is unde-

       By default, does	asynchronous writes.  That is, after the data is writ-
       ten to a	buffer cache, control returns  to  the	program.   The	actual
       write  to  a device takes place after control returns.  However,	if you
       use an or call to open a	file for synchronous writes, control does  not
       return  to the program until after the buffer cache has been written to
       the device.

       If a program is using to	a remote file over NFS,	 and  an  asynchronous
       write  error  occurs,  then  all	subsequent requests will return	-1 and
       errno will be set to the	asynchronous error code. Also, a subsequent or
       will  likewise  fail.  The  return code from should be inspected	by any
       program that can	over NFS.

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

       o    A  file  offset  is	 not  associated  with a pipe. Therefore, each
	    request appends to the end of the pipe.

       o    Write requests less	than or	equivalent to {PIPE_BUF} bytes are not
	    interleaved	 with  data  from  other processes doing writes	on the
	    same pipe.	Write  requests	 greater  than	{PIPE_BUF}  bytes  can
	    interleave on arbitrary boundaries with writes by other processes.

       o    If the O_NDELAY and	O_NONBLOCK flags are clear, a write can	 cause
	    the	 process  to  block,  but, under normal	completion, it returns

       o    If the O_NDELAY or O_NONBLOCK flag is set, the function  does  not
	    block   the	 process.   Write  requests  less  than	 or  equal  to
	    {PIPE_BUF} bytes either succeed and	return nbytes or -1, and errno
	    is	set  to	 [EWOULDBLOCK].	 Write requests	that exceed {PIPE_BUF}
	    bytes can return complete success, partial write, or  no  success,
	    and	errno is to [EWOULDBLOCK].

       When  your  program is compiled using the System	V environment, and the
       file was	opened with the	O_NDELAY flag set, a to	a full pipe (or	 FIFO)
       returns	a zero (0), rather than	an error, as for the ULTRIX non-System
       V environment.

       Differs from the	System V definition in that the	value nbytes  is  int,
       rather than unsigned.

   When	your program is	compiled using POSIX environment, EAGAIN is returned
       in errno, in place of EWOULDBLOCK.

Return Values
       Upon  successful	 completion,  the  number of bytes actually written is
       returned.  Otherwise, a -1 is returned, and errno is  set  to  indicate
       the error.

       The  system  call  fails	and the	file pointer will remain unchanged, if
       any of the following is true:

       [EACCESS]      The file does not	permit writing.	NFS only.

       [EBADF]	      The fd argument is not a valid descriptor	open for writ-

       [EPIPE]	      An  attempt was made to write to a pipe that is not open
		      for reading by any process.

       [EPIPE]	      An attempt was  made  to	write  to  a  socket  of  type
		      SOCK_STREAM that is not connected	to a peer socket.

       [EFBIG]	      An  attempt  was	made  to write a file that exceeds the
		      process's	file size limit, set by	or  the	 maximum  file
		      size (approximately 2 Gigabytes).

       [EFAULT]	      Part  of the array pointed to by iov or data to be writ-
		      ten to the file points outside the  process's  allocated
		      address space.

       [EWOULDBLOCK]  The  O_NDELAY  or	 O_NONBLOCK  flag  is set for the file
		      descriptor and the process would be delayed in the write

       [ENOSPC]	      There is no free space remaining on the file system con-
		      taining the file.

       [EDQUOT]	      The user's quota of disk blocks on the file system  con-
		      taining the file has been	exhausted.

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

       [EINTR]	      The write	operation was interrupted, no data was	trans-

       [EINVAL]	      The nbytes argument is negative.

       [EROFS]	      The file is on a read-only file system. NFS only.

       [ESTALE]	      The  fd argument is invalid because the file referred to
		      by that  file  handle  no	 longer	 exists	 or  has  been
		      revoked. NFS only.

       [ETIMEDOUT]    A	 write	operation  failed  because  the	server did not
		      properly respond after a period of time that  is	depen-
		      dent on the options. NFS only.

See Also
       close(2),  creat(2),  dup(2),  fcntl(2),	 fsync(2),  lseek(2), open(2),
       pipe(2),	socket(2)


Name | Syntax | Arguments | Description | Environment | Return Values | Diagnostics | See Also

Want to link to this manual page? Use this URL:

home | help