.\" SCCSID: @(#)write.2	2.1	3/10/87.TH write 2.SH Namewrite, writev \- write on a file.SH Syntax.nf.B write (\fIfd, buf, nbytes\fP).B int \fIfd\fP;.B char *\fIbuf\fP;.B int \fInbytes\fP;.PP.B #include <sys/types.h>.B #include <sys/uio.h>.PP.B writev (\fIfd, iov, ioveclen\fP).B int \fIfd\fP;.B struct \fIiovec *iov\fP;.B int \fIioveclen\fP;.fi.SH Arguments.TP 12.I fdDescriptor returned by a.PN creat ,.PN open ,.PN dup ,.PN fcntl ,.PN pipe , or.PN socketsystem call..TP.I bufPoints to the buffer containing the data to bewritten..TP.I nbytesPositive integer defining the number of bytes tobe written from the buffer..TP.I iovPoints to a data structure of type.PN iovec ,which defines the starting location of the set of vectorsforming the array and the length of each individualvector in the array to be written..spThis structure is defined in .PN <sys/uio.h>as follows:.EXstruct iovec {       caddr_t   iov_base ;       int       iov_len ;} ;.EEThe.PN caddr_tdata type is defined in .PN <sys/types.h> and is the recommended way to define an addressfor a character value.  In any case, theaddress.PN iov_baseis the starting address of the set of vectors.The integer value.PN iov_lenis the length of each individual vector, in bytes..TP 12.I ioveclenDefines the number of vectorsin the array of data to be written.  Note that the numberingof the vectors begins with 0 and proceeds through \fIioveclen\fR \-1..SH Description.NXR "write system call".NXR "socket" "writing".NXR "writev system call".NXA "write system call" "read system call".NXA "write system call" "send system call"The.PN writesystem call attempts to write a buffer ofdata to a file.  The.PN writevsystem call attempts to write an array of buffers of data to a file..PPWhen 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,.IR fd .This file pointer is the offset, in bytes, from the beginningof 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 .PN read (2) ,.PN lseek (2) ,and.PN writesystem calls.When the .PN writecall returns, the file pointer is incremented by the number ofbytes actually written..PPWhen the file is opened to a devicenot capable of seeking (such as sockets, pipes, or terminals), the write starts at the current position. The value of the pointer associated with such an object isundefined..PPBy default,.PN writedoes asynchronous writes.  That is, after the data is written to abuffer cache, control returns to the program.  The actual write toa device takes place after control returns.However, if you use an .PN open or.PN fcntlcall to open a file for synchronous writes, control does notreturn to the program until after the buffer cache has been writtento the device..PPIf a program is using .PN writeto a remote file over NFS, andan asynchronous write error occurs, then all subsequent .PN writerequests will return \-1 and errno will be set to the asynchronouserror code. Also, a subsequent .MS fsync 2 or .MS close 2 willlikewise fail. The return code from .MS close 2 should be inspectedby any program that can .PN writeover NFS..PPWrite requests to a pipe (or FIFO) are handled the same as a regular file,with the following exceptions:.IP \(bu 5A file offset is not associated with a pipe. Therefore, each .PN writerequest appends to the end of the pipe..IP \(bu 5Write requests less than or equivalent to {PIPE_BUF} bytes are notinterleaved with data from other processes doing writes on the same pipe.  Write requests greater than {PIPE_BUF} bytes can interleaveon arbitrary boundaries with writes by other processes..IP \(bu 5If the O_NDELAY and O_NONBLOCK flags are clear, a writecan cause the process to block, but, under normal completion, it returnsnbytes..IP \(bu 5If the O_NDELAY or O_NONBLOCK flag is set, the.PN writefunction does not block the process.  Write requests less than orequal 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]..SH Environment.NXR "write system call" "System V and".SS SYSTEM VWhen your program is compiled using the System V environment,and the file was opened with the O_NDELAY flag set, a.PN writeto a full pipe (or FIFO) returns a zero (0), rather than anerror, as for the ULTRIX non-System V environment..PPDiffers from the System V definition in that the value.I nbytesis .IR int ,rather than .IR unsigned ..SSWhen your program is compiled using POSIX environment, EAGAIN is returned in errno, in place of EWOULDBLOCK..SH Return ValuesUpon successful completion, the number of bytes actuallywritten is returned.  Otherwise, a \-1 is returned, and.I errnois set to indicate the error..SH Diagnostics.NXR "write system call" "diagnostics"The.PN writesystem callfails and the file pointer will remain unchanged, if anyof the following is true:.TP 15[EACCESS]The file does not permit writing. NFS only..TP 15[EBADF]The \fIfd\fR argument is not a valid descriptor open for writing..TP 15[EPIPE]An attempt was made to write to a pipe that is not openfor reading by any process..TP 15[EPIPE]An attempt was made to write to a socket of type SOCK_STREAMthat is not connected to a peer socket..TP 15[EFBIG]An attempt was made to write a file that exceeds the process'sfile size limit, set by.PN ulimit (2) ,or the maximum file size (approximately 2 Gigabytes)..TP 15[EFAULT]Part of the array pointed to by \fIiov\fP or data to be written to the filepoints outside the process's allocated address space..TP 15[EWOULDBLOCK]The O_NDELAY or O_NONBLOCK flag is set for the file descriptor and the processwould be delayed in the write operation..TP 15[ENOSPC]There is no free space remaining on the file system containingthe file..TP 15[EDQUOT]The user's quota of disk blocks on the file system containingthe file has been exhausted..TP 15[EIO]An I/O error occurred while reading from or writing to the filesystem..TP[EINTR]The write operation was interrupted, no data was transferred..TP 15[EINVAL]The.I nbytes argument is negative..TP 15[EROFS]The file is on a read-only file system. NFS only..TP 15[ESTALE]The.I fdargument is invalid because the file referredto by that file handle no longer exists or has been revoked. NFS only..TP[ETIMEDOUT]A write operation failedbecause the serverdid not properly respond after a periodof time that is dependent on the .MS mount 8nfsoptions. NFS only..SH See Alsoclose(2), creat(2), dup(2), fcntl(2), fsync(2), lseek(2), open(2), pipe(2), socket(2)