write(2) CLIX write(2)
NAME
write - Writes to a file
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
int write(
int file_des ,
char *buffer ,
unsigned int nbytes );
PARAMETERS
file_des Identifies a file descriptor obtained from a creat(), open(),
dup(), fcntl(), pipe(), accept(), socket(), or socketpair()
function.
buffer Identifies the buffer containing the data to be written.
nbytes Specifies the number of bytes to write.
DESCRIPTION
The write() function attempts to write nbytes bytes of data from the
buffer pointed to by the buffer parameter to the file associated with the
file_des parameter.
With regular files and devices capable of seeking, the actual writing of
data proceeds from the position in the file indicated by the file pointer.
With devices incapable of seeking, writing always takes place starting at
the current position. The value of a file pointer associated with such a
device is undefined.
If the O_APPEND flag of the file status is set, the file offset is set to
the end of the file prior to each write.
When attempting to write to a regular file and mandatory file/record
locking is set (see the chmod() function), and all or part of the region
to be written is currently locked by another process, if O_NDELAY and
O_NONBLOCK are clear (the default), the calling process blocks until the
lock is released.
Fewer bytes can be written than requested if there is not enough room to
satisfy the request. In this case the number of bytes written is
returned. The next attempt to write a nonzero number of bytes fails
(except as noted in the following text). The limit reached can be either
2/94 - Intergraph Corporation 1
write(2) CLIX write(2)
the ulimit or the end of the physical medium. 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 nonzero number of bytes
will give a failure return (except as noted below).
For STREAMS (see intro(2)) files, the operation of write() is determined
by the values of the minimum and maximum nbyte range (``packet size'')
accepted by the stream. These values are contained in the topmost stream
module. Unless the user pushes (see I_PUSH in the streamio file) the
topmost module, these values cannot be set or tested from user level. If
nbyte falls within the packet size range, nbyte bytes will be written. If
nbyte does not fall within the range and the minimum packet size value is
0, write() breaks the buffer into maximum packet size setments before
sending the data downstream. (The last segment may contain less than the
maximum packet size.) If nbyte does not fall within the range and the
minimum value is nonzero, write() fails with errno set to ERANGE. Writing
a 0-length buffer (nbyte is 0) sends 0 bytes with 0 returned.
For STREAMS files, if the nonblocking flag is not set and the stream
cannot accept data because the stream write queue is full due to internal
flow control conditions, write() will block until data can be accepted. A
nonblocking flag will prevent a process from blocking due to flow control
conditions. If a nonblocking flag is set and the stream cannot accept
data, write() fails. If a nonblocking flag is set and part of the buffer
has been written when a condition in which the stream cannot accept
additional data occurs, write() terminates and returns the number of bytes
written.
Upon successful completion, the write() function will return the number of
bytes actually written to the file associated with fildes.
Write requests to a pipe (or FIFO) are handled the same as a regular file
with the following exceptions:
⊕ If O_NDELAY (see open(2)) and O_NONBLOCK are clear (the default), a
write() request to a full pipe causes the process to block until enough
space becomes available to handle the entire request.
⊕ If O_NDELAY is set, a write to a full pipe returns 0.
⊕ If the O_NONBLOCK flag is set, write() requests will be handled
differently in the following ways: the write() function will not block
the process; write requests for PIPE_BUF or fewer bytes will either
succeed completely and return nbyte, or return -1 and set errno to
EAGAIN. A write() request for greater than PIPE_BUF bytes will either
transfer what it can and return the number of bytes written, or
transfer no data and return -1 with errno set to EAGAIN. Also, if a
request is greater than PIPE_BUF bytes and all data previously written
to the pipe has been read, write() will transfer at least PIPE_BUF
bytes.
2 Intergraph Corporation - 2/94
write(2) CLIX write(2)
EXAMPLES
To write a NULL-terminated string to file descriptor 1, the conventional
stdout file descriptor:
length = strlen(string);
return_value = write(1, string, length);
if (return_value == -1) {
perror("write failed");
return(-1);
} else if (return_value != length) {
fprintf(stderr, "Could not write full string\n");
return(-1);
} else {
/* Write successfully completed */
...
}
RETURN VALUES
Upon successful completion, write() returns the number of bytes that were
actually written. Otherwise, the value -1 is returned and the global
variable errno is set to indicate the error.
ERRORS
The write() function fails when one or more of the following is true:
[EBADF]
The file_des parameter does not specify a valid file descriptor
open for writing.
[EFAULT]
The buffer parameter points to a location outside of the allocated
address space of the process.
[EPIPE]
[SIGPIPE]
An attempt was made to write to a pipe that is not opened for
reading by any process.
[EAGAIN]
Mandatory file/record locking was set, a nonblocking flag was set,
and there was a blocking record lock. This error also occurs if
the total amount of system memory available when reading through
raw I/O is temporarily insufficient; or if an attempt was made to
write to a stream that cannot accept data with a nonblocking flag
set.
[EFBIG]
2/94 - Intergraph Corporation 3
write(2) CLIX write(2)
An attempt was made to write a file that exceeds the process's file
size limit or the maximum file size. (See the ulimit() function.)
[EINTR]
A signal was caught during the write() operation.
[ENXIO]
A hangup occurred on the stream being written to.
[EDEADLK]
The write() operation was going to go to sleep and cause a deadlock
situation to occur.
[EINVAL]
Attempt to write to a stream linked below a multiplexor.
[ENOLCK]
The system record lock table was full, so the write() function
could not go to sleep until the blocking record lock was removed.
[ENOLINK]
The fildes parameter is on a remote machine and the link to that
machine is no longer active.
[ENOSPC]
During a write() attempt to an ordinary file, no free space remains
on the device.
[ENXIO]
A hangup occurred on the stream being written to.
[ERANGE]
An attempt is made to write to a stream with nbyte outside the
specified minimum and maximum write range, and the minimum value is
nonzero.
[EWOULDBLOCK]
The descriptor references a socket marked nonblocking and the
requested operation would block.
[ENOTCONN]
The descriptor references a socket attempting to send data on a
stream that is not connected.
[EDESTADDRREQ]
The descriptor references a socket attempting to send data on a
datagram without a destination address.
[EPIPE]
The descriptor references a socket that was disconnected or
shutdown for writing.
4 Intergraph Corporation - 2/94
write(2) CLIX write(2)
A write to a STREAMS file can fail if an error message is received at the
stream head. In this case, errno is set to the value included in the
error message.
RELATED INFORMATION
Functions: accept(2), creat(2), dup(2), fcntl(2), intro(2), lseek(2),
open(2), pipe(2), select(2), socket(2), socketpair(2), ulimit(2)
2/94 - Intergraph Corporation 5