Write bytes to a file
Synopsis:
#include <unistd.h>
ssize_t write( int fildes,
const void* buf,
size_t nbytes );
Arguments:
- fildes
- The file descriptor for the file you want to write in.
- buf
- A pointer to a buffer that contains the data you want to write.
- nbytes
- The number of bytes to write. If nbytes is zero, write()
returns zero, and has no other effect. If nbytes is greater than
SSIZE_MAX - sizeof(io_write_t) (see <limits.h>),
write() returns -1 and sets errno to EOVERFLOW.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The write() function attempts to write nbytes bytes to
the file associated with the open file descriptor, fildes,
from the buffer pointed to by buf.
On a regular file or other file capable of seeking, and if
O_APPEND isn't set, write() starts at a position in
the file given by the file offset associated with fildes. If
O_APPEND is set, the file offset is set to the end of file
before each write operation. Before successfully returning from
write(), the file offset is incremented by the number of bytes
actually written. On a regular file, if this incremented file offset
is greater than the length of the file, the length of the file is set
to this file offset.
Note:
Note that the
write() call ignores advisory locks that may
have been set by the
fcntl()
function.
On a file not capable of seeking, write() starts at the current
position.
If write() requests that more bytes be written than there's
room for (for example, all blocks on a disk are already allocated),
only as many bytes as there's room for are written. For example,
if there's only room for 80 more bytes in a file, a write of 512
bytes would return 80. The next write of a nonzero number of bytes
would give a failure return (except as noted below).
When write() returns successfully, its return value is the
number of bytes actually written to the file. This number is never
greater then nbytes, although it may be less than
nbytes under certain circumstances detailed below.
If write() is interrupted by a signal before it has written any
data, it returns -1 and sets errno
to EINTR. However, if write() is interrupted by a signal
after it has successfully written 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:
- There's no file offset associated with a pipe, therefore each write
request appends to the end of the pipe.
- Write requests of PIPE_BUF bytes or less aren't
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 is set.
- If the O_NONBLOCK flag is clear, a write request may block,
but on normal completion it returns right away with a value of nbytes.
- If the O_NONBLOCK flag is set, write requests are
handled differently, in the following ways:
- The write() function doesn't block.
- Write requests for PIPE_BUF bytes or
less either succeed completely and return nbytes, or
return -1 and errno is set to EAGAIN.
If you call write() with nbytes greater than
PIPE_BUF bytes, it either transfers what it can and returns
the number of bytes
written, or transfers no data, returning -1 and setting
errno to EAGAIN. Also, if nbytes is
greater than PIPE_BUF bytes and all data previously
written to the pipe has been read (that is, the pipe is empty),
write() transfers at least PIPE_BUF bytes.
When attempting to write to a file (other than a pipe or FIFO) that
supports nonblocking writes and can't accept the data immediately:
- If the O_NONBLOCK flag is clear, write() blocks
until the data can be accepted.
- If the O_NONBLOCK flag is set, write()
doesn't block. If some data can be written without blocking,
write() transfers what it can and returns the number
of bytes written. Otherwise, it returns -1 and sets errno
to EAGAIN.
If write() is called with the file offset beyond the
end-of-file, the file is extended to the current file offset with the
intervening bytes filled with zeroes. This is a useful technique for
pregrowing a file.
If write() succeeds, the st_ctime and
st_mtime fields of the file are marked for update.
Returns:
The number of bytes written, or -1 if an error occurred
(errno is set).
Errors:
- EAGAIN
- The O_NONBLOCK flag is set for the file descriptor and the write operation would block.
- EBADF
- The file descriptor, fildes, isn't a valid file descriptor
open for writing.
- ECONNRESET
- A write was attempted on a socket that isn't connected.
- EFBIG
- One of the following occurred:
- An attempt was made to write a file that exceeds the maximum file size
and there was no room for any bytes to be written.
- The file is a regular file, nbytes is greater than 0,
and the starting position is greater than or equal to the offset
maximum established in the open file description associated with
fildes.
- EINTR
- The write operation was interrupted by a signal, and either no data
was transferred, or the resource manager responsible for that file
doesn't report partial transfers.
- EIO
- One of the following:
- The process is a member of a background process group attempting to
write to its controlling terminal, TOSTOP is set,
the process is neither ignoring nor blocking SIGTTOU,
and the process group of the process is orphaned.
- A physical I/O error occurred (for example, a bad block on a disk). The
precise meaning is device-dependent.
- The filesystem resides on a removable media device, and the media
has been forcibly removed.
- ENETDOWN
- A write was attempted on a socket and the local network interface used to reach the destination is down.
- ENETUNREACH
- A write was attempted on a socket and no route to the network is present.
- ENOSPC
- There's no free space remaining on the device containing the file.
- ENOSYS
- The write() function isn't implemented for the filesystem specified
by filedes.
- ENXIO
- One of the following occurred:
- A request was made of a nonexistent device, or the request was outside
the capabilities of the device.
- A hangup occurred on the STREAM being written to.
- EOVERFLOW
- An attempt was made to write a number of bytes that when added to the size of the
write message structure exceeds the allowable limit.
- EPIPE
- One of the following occurred:
- An attempt was made to write to a pipe (or FIFO) that isn't open for
reading by any process, or that has only one end open.
A SIGPIPE signal is also sent to
the process.
- A write was attempted on a socket that is shut down for writing, or
is no longer connected.
In the latter case, if the socket is of type SOCK_STREAM,
a SIGPIPE signal is delivered to the calling process.
- ERANGE
- The transfer request size was outside the range supported by the
STREAMS file associated with fildes.
Examples:
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdlib.h>
char buffer[] = { "A text record to be written" };
int main( void )
{
int fd;
int size_written;
/* open a file for output */
/* replace existing file if it exists */
fd = creat( "myfile.dat", S_IRUSR | S_IWUSR );
/* write the text */
size_written = write( fd, buffer,
sizeof( buffer ) );
/* test for error */
if( size_written != sizeof( buffer ) ) {
perror( "Error writing myfile.dat" );
return EXIT_FAILURE;
}
/* close the file */
close( fd );
return EXIT_SUCCESS;
}
Classification:
POSIX 1003.1 XSI
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |