WRITE(2-POSIX) RISC/os Reference Manual WRITE(2-POSIX)
NAME
write - write output
SYNOPSIS
ssizet write(fildes, buf, nbyte)
int fildes;
char *buf;
sizet nbyte;
DESCRIPTION
write attempts to write nbyte of data to the object refer-
enced by the descriptor fildes from the buffer pointed to by
buf.
On objects capable of seeking, the write starts at a posi-
tion given by the pointer associated with fildes, see
lseek(2). Upon return from write, the pointer is incre-
mented by the number of bytes actually written.
Objects that are not capable of seeking always write from
the current position. The value of the pointer associated
with such an object is undefined.
If the O_APPEND flag of the file status flags is set, the
file offset is set to the end of the file prior to each
write.
If the real user is not the super-user, then write clears
the set-user-id bit on a file. This prevents penetration of
system security by a user who "captures" a writable set-
user-id file owned by the super-user.
If write requests that more bytes be written than there is
room for, only as many bytes as there is room for are writ-
ten. For example, suppose there is space for 20 bytes more
in a file before reaching a limit. A write of 512 bytes
would return 20. The next write of a non-zero number of
bytes would give a failure return (except as noted below).
Upon successful completion, write returns the number of
bytes actually written to the file associated with fildes.
This number is never greater than nbyte.
If a write is interrupted by a signal before it writes any
data, it returns -1 and errno is set to EINTR.
If a write is interrupted by a signal after it successfully
writes some data, it returns the number of bytes written.
Write requests to a pipe or FIFO are handled the same as a
regular file with the following exceptions:
Printed 1/15/91 Page 1
WRITE(2-POSIX) RISC/os Reference Manual WRITE(2-POSIX)
1. There is no file offset associated with a pipe; hence
each write request appends to the end of the pipe.
2. Write requests of {PIPE_BUF} bytes or less will not be
interleaved with data from other processes doing writes
on the same pipe. Writes of greater than {PIPE_BUF}
bytes may have data interleaved, on arbitrary boundaries,
with writes by other processes, whether or not the
O_NONBLOCK flag of the files status flags is set.
3. If the O_NONBLOCK flag is clear, a write request may
cause the process to block, but on normal completion it
returns nbyte.
4. If the O_NONBLOCK flag is set, write requests are handled
in the following ways:
(a) the write function does not block the process;
(b) write requests for {PIPE_BUF} or fewer bytes will
either:
[1] succeed completely and return nbyte, if there is
sufficient space available in the pipe, or
[2] transfer no data and return -1 with errno set to
EAGAIN if there is not suffictient space avail-
able in the pipe.
(c) a write request for greater than {PIPE_BUF} bytes
will:
[1] transfer what it can when at least one byte can
be written and return the number of bytes writ-
ten. If all data previous written to the pipe
has been read, write will transfer at least
{PIPE_BUF} bytes.
[2] transfer no data when no data can be written and
return -1 with errno set to EAGAIN.
When attempting to write to a file descriptor other than a
pipe or FIFO that supports nonblocking writes and cannot
accept the data immediately:
1. If the O_NONBLOCK flag is clear, write blocks until the
data can be accepted.
2. If the O_NONBLOCK flag is set, write does not block the
process. If some data can be written without blocking
the process, write writes what it can and returns the
number of bytes written. Otherwise, it returns -1 and
Page 2 Printed 1/15/91
WRITE(2-POSIX) RISC/os Reference Manual WRITE(2-POSIX)
errno is set to EAGAIN.
Upon successful completion, write marks the st_ctime and
st_mtime fields of the file for update.
If nbyte is zero, and the file is a regular file, write
returns zero immediately. If nbyte is greater than
{SSIZE_MAX}, write will attempt to write the specified
number of bytes, as though nbyte were an unsigned number.
RETURN VALUE
Upon successful completion the number of bytes actually
written is returned. Otherwise a -1 is returned and the
global variable errno is set to indicate the error.
ERRORS
write fails and the file pointer is unchanged if one or more
of the following are true:
[EBADF] fildes is not a valid descriptor open
for writing.
[EPIPE] An attempt was made to write to a pipe
or FIFO that is not open for reading by
any process. A SIGPIPE signal will also
be sent to the process.
[EFBIG] An attempt was made to write a file that
exceeds the process's file size limit or
the maximum file size.
[EFAULT] Part of buf points outside the process's
allocated address space.
[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.
[EAGAIN] The file was marked for non-blocking
I/O, and no data could be written
immediately.
[EIO] An I/O error occurred while reading from
or writing to the file system, or the
process is in a background process group
and is attempting to write to its con-
trolling terminal, TOSTOP is set, the
process is neither ignoring nor blocking
SIGTTOU signals, and the process group
Printed 1/15/91 Page 3
WRITE(2-POSIX) RISC/os Reference Manual WRITE(2-POSIX)
of the process is orphaned.
[EINTR] The write operation was interrupted by a
signal.
SEE ALSO
creat(2), dup(2), fcntl(2), open(2), pipe(2).
Page 4 Printed 1/15/91