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

FreeBSD Manual Pages

  
 
  

home | help
WRITE(2)		  FreeBSD System Calls Manual		      WRITE(2)

NAME
     write, writev, pwrite, pwritev -- write output

SYNOPSIS
     #include <unistd.h>

     ssize_t
     write(int d, const	void *buf, size_t nbytes);

     ssize_t
     pwrite(int	d, const void *buf, size_t nbytes, off_t offset);

     #include <sys/uio.h>

     ssize_t
     writev(int	d, const struct	iovec *iov, int	iovcnt);

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

     ssize_t
     pwritev(int d, const struct iovec *iov, int iovcnt, off_t offset);

DESCRIPTION
     write() attempts to write nbytes of data to the object referenced by the
     descriptor	d from the buffer pointed to by	buf.  writev() performs	the
     same action, but gathers the output data from the iovcnt buffers speci-
     fied by the members of the	iov array: iov[0], iov[1], ...,	iov[iovcnt-1].
     pwrite() and pwritev() perform the	same functions,	but write to the spec-
     ified position offset in the file without modifying the file pointer.

     For writev() and pwritev(), the iovec structure is	defined	as:

	   struct iovec	{
		   void	*iov_base;
		   size_t iov_len;
	   };

     Each iovec	entry specifies	the base address and length of an area in mem-
     ory from which data should	be written.  writev() and pwritev() will al-
     ways write	a complete area	before proceeding to the next.

     On	objects	capable	of seeking, the	write()	starts at a position given by
     the pointer associated with d (see	lseek(2)).  Upon return	from write(),
     the pointer is incremented	by the number of bytes which were written.  If
     a file was	opened with the	O_APPEND flag (see open(2)), calls to write()
     or	writev() will automatically set	the pointer to the end of the file be-
     fore writing.

     Objects that are not capable of seeking always write from the current po-
     sition.  The value	of the pointer associated with such an object is unde-
     fined.

     If	the real user is not the superuser, 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 superuser.

     If	write()	succeeds it will update	the st_ctime and st_mtime fields of
     the file's	meta-data (see stat(2)).

     When using	non-blocking I/O on objects such as sockets that are subject
     to	flow control, write() and writev() may write fewer bytes than re-
     quested; the return value must be noted, and the remainder	of the opera-
     tion should be retried when possible.

     Note that writev()	and pwritev() will fail	if the value of	iovcnt exceeds
     the constant IOV_MAX.

RETURN VALUES
     Upon successful completion	the number of bytes which were written is re-
     turned.  Otherwise, a -1 is returned and the global variable errno	is set
     to	indicate the error.

EXAMPLES
     A typical loop allowing partial writes looks like this:

     const char	*buf;
     size_t bsz, off;
     ssize_t nw;
     int d;

     for (off =	0; off < bsz; off += nw)
	     if	((nw = write(d,	buf + off, bsz - off)) == 0 || nw == -1)
		     err(1, "write");

ERRORS
     write(), pwrite(),	writev(), and pwritev()	will fail and the file pointer
     will remain unchanged if:

     [EBADF]		d is not a valid descriptor open for writing.

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

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

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

     [EINTR]		A write	to a slow device (i.e. one that	might block
			for an arbitrary amount	of time) was interrupted by
			the delivery of	a signal before	any data could be
			written.

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

     [EFAULT]		Part of	buf points outside the process's allocated ad-
			dress space.

     In	addition, write() and writev() may return the following	errors:

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

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

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

     [ENETDOWN]		The destination	address	specified a network that is
			down.

     [EDESTADDRREQ]	The destination	is no longer available when writing to
			a UNIX-domain datagram socket on which connect(2) had
			been used to set a destination address.

     [EIO]		The process is a member	of a background	process	at-
			tempting to write to its controlling terminal, TOSTOP
			is set on the terminal,	the process isn't ignoring the
			SIGTTOUT signal	and the	thread isn't blocking the
			SIGTTOUT signal, and either the	process	was created
			with vfork(2) and hasn't successfully executed one of
			the exec functions or the process group	is orphaned.

     write() and pwrite() may return the following error:

     [EINVAL]		nbytes was larger than SSIZE_MAX.

     pwrite() and pwritev() may	return the following error:

     [EINVAL]		offset was negative.

     [ESPIPE]		d is associated	with a pipe, socket, FIFO, or tty.

     writev() and pwritev() may	return one of the following errors:

     [EINVAL]		iovcnt was less	than or	equal to 0, or greater than
			IOV_MAX.

     [EINVAL]		The sum	of the iov_len values in the iov array over-
			flowed an ssize_t.

     [EFAULT]		Part of	iov points outside the process's allocated ad-
			dress space.

     [ENOBUFS]		The system lacked sufficient buffer space or a queue
			was full.

SEE ALSO
     fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4)

STANDARDS
     The write(), writev(), and	pwrite() functions conform to IEEE Std
     1003.1-2008 ("POSIX.1").

HISTORY
     The write() function call appeared	in Version 1 AT&T UNIX,	pwrite() in
     AT&T System V Release 4 UNIX, writev() in 4.2BSD, and pwritev() in
     OpenBSD 2.7.

CAVEATS
     Error checks should explicitly test for -1.  On some platforms, if	nbytes
     is	larger than SSIZE_MAX but smaller than SIZE_MAX	- 2, the return	value
     of	an error-free call may appear as a negative number distinct from -1.

FreeBSD	13.0		       September 6, 2019		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

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

home | help