Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

write(2) [ultrix man page]

write(2)							System Calls Manual							  write(2)

Name
       write, writev - write on a file

Syntax
       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;

Arguments
       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 starting location of the set of vectors forming the array and the length
		   of each individual vector in the array to be written.

		   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 character 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.

Description
       The system call attempts to write a buffer of data to a file.  The system 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
       associated  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 undefined.

       By default, does asynchronous writes.  That is, after the data is written 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
	    nbytes.

       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].

Environment
   SYSTEM V
       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.

Diagnostics
       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 writing.

       [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  (approxi-
		      mately 2 Gigabytes).

       [EFAULT]       Part of the array pointed to by iov or data to be written 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 operation.

       [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.

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

       [EINTR]	      The write operation was interrupted, no data was transferred.

       [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 dependent 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)

																	  write(2)
Man Page