WRITE(2)

NAME

write, writev − write on a file

SYNOPSIS

int write (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte; #include <sys/types.h>
#include <sys/uio.h>
int writev (fildes, iov, iovcnt)
int fildes;
struct iovec *iov;
int iovcnt;

HP-UX COMPATIBILITY

Level: write: HP-UX/RUN ONLY

writev: HP-UX/STANDARD

Origin: System V

DESCRIPTION

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call.

Write attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the fildes. Writev performs the same action, but gathers the output data from the iovlen buffers specified by the elements of the iovec array: iov[0], iov[1], ..., iov[ iovcnt - 1].

For writev the iovec structure is defined as

struct iovec {
caddr_tiov_base;
intiov_len;
};

Each iovec entry specifies the base address and length of an area in memory where data should be copied from. The iovec array maybe at most MAXIOV long.

On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. Upon return from write, the file pointer is incremented by the number of bytes actually written.

On devices incapable of seeking, writing always takes place starting at the device’s current position. The value of a file pointer associated with such a device is undefined.

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

If a write requests that more bytes be written than there is room for (e.g., the ulimit (see ulimit(2)) or the physical end of a medium), only as many bytes as there is room for will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20. The next write of a non-zero number of bytes will give a failure return (except as noted below).

If the file being written is a pipe (or FIFO), there is a system dependent maximum number of bytes which it can store (NPIPE). The minimum value of NPIPE on any HP-UX system is 4096. In writing a pipe, the following conditions apply:

If the O_NDELAY flag of the file flag word is set:

If nbyte is less than or equal to NPIPE and there is sufficient room in the pipe or FIFO, then the write is successful and returns the number of bytes written;

If nbyte is less than or equal to NPIPE but there is not enough room in the pipe or FIFO, the write returns without error, having written nothing, and with a return value of 0.

If nbyte is greater than NPIPE the write fails and returns −1. [EINVAL]

If the O_NDELAY flag of the file flag word is clear:

the write always executes correctly (blocking as necessary) and returns the number of bytes written.

ERRORS

Write will fail and the file pointer will remain unchanged if one of the following conditions is true and errno will be set accordingly:

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

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

[EFBIG] The current file position (as set by lseek) is less than zero.

[EINTR] A signal was caught during the write system call.

[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2)).

In addition, writev may return one of the following errors:

[EINVAL] Iovcnt was less than or equal to 0, or greater then MAXIOV.

[EINVAL] One of the iov len values in the iov array was negative.

[EINVAL] The sum of iov len values in the iov array overflowed a 32-bit integer.

Write or writev will fail and the file pointer will be updated to reflect the amount of data transferred if one of the following conditions is true and errno will be set accordingly:

[EFBIG] An attempt was made to write a file that exceeds the process’s file size limit or the maximum file size. See ulimit(2).

[EFAULT] Buf points outside the process’s allocated address space.

RETURN VALUE

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

HARDWARE DEPENDENCIES

Series 500:
If you perform a write operation following an lseek past the previous end-of-file, all "unused" bytes from the previous end-of-file up to your new position are zeroed-out before writing your data.

Writev is not implemented on this release.

The size of a pipe (NPIPE) is currently 5120 bytes.

Series 200:
The size of a pipe (NPIPE) is currently 8192 bytes.

Integral PC:
Under the conditions for which O_NDELAY is set, nbyte can be less than or equal to 10240 bytes.

BUGS

The character special devices, and raw discs in particular, apply constraints on how write can be used. See the specific Section 4 entry for details on particular devices.

Museum

Related Articles