WRITE(2) — HP-UX

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;

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_t	iov_base;
	int	iov_len;

};

Each iovec entry specifies the base address and length of an area in memory where data should be copied from. The iovec array may be 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).

A write to an ordinary file will be blocked if enforcement-mode file and record locking is set, and there is a lock owned by another process on the segment of the file to be written:

If O_NDELAY is set, the write will return −1 and set errno to EAGAIN.

If O_NDELAY is clear, the write will sleep until the blocking record lock is removed.

If the file being written is a pipe (or FIFO), the system-dependent maximum number of bytes which it can store is given by PIPSIZ (defined in <sys/inode.h>). The minimum value of PIPSIZ on any HP-UX system is 8192. 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 PIPSIZ 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 PIPSIZ 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 PIPSIZ, 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.

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.

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.

[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) and fcntl(2)).

[EAGAIN] Enforcement-mode file and record locking was set, O_NDELAY was set, and there was a blocking record lock.

[ENOLCK] The system record lock table was full, so the write could not go to sleep until the blocking record lock was removed.

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

[EFAULT] Iov_base or iov points outside of the allocated address space. The reliable detection of this error will be implementation dependent.

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

[ENOSPC] Not enough space on the file system.

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. The reliable detection of this error will be implementation dependent.

EXAMPLES

Assuming a process opened a file for writing, the following call to write(2) attempts to write mybufsize bytes to the file from the buffer to which mybuf points.

#include <string.h>
int mybufsize;
char *mybuf = "aeiou and sometimes y";
int nbytes;

mybufsize = strlen (mybuf);
nbytes = write (outfd, mybuf, mybufsize);

WARNINGS

Check all references to signal(2) for appropriateness on systems that support sigvector(2). Sigvector(2) can affect the behavior described on this page.

The character special devices, and raw disks in particular, apply constraints on how write can be used. See the specific section (7) entries for details on particular devices.

AUTHOR

Write was developed by HP, AT&T, and the University of California, Berkeley.

Museum

Related Articles