2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
|
|
|
|
.\" 1993 Michael Haardt, Ian Jackson.
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith <faith@cs.unc.edu>
|
|
|
|
.\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith <faith@cs.unc.edu>
|
|
|
|
.\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt
|
|
|
|
.\" <michael@cantor.informatik.rwth-aachen.de>
|
|
|
|
.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
|
|
|
|
.\" 2001-12-13 added remark by Zack Weinberg
|
2007-06-11 19:51:09 +00:00
|
|
|
.\" 2007-06-18 mtk:
|
|
|
|
.\" Added details about seekable files and file offset.
|
|
|
|
.\" Noted that write() may write less than 'count' bytes, and
|
|
|
|
.\" gave some examples of why this might occur.
|
|
|
|
.\" Noted what happens if write() is interrupted by a signal.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2010-08-29 13:50:27 +00:00
|
|
|
.TH WRITE 2 2010-08-29 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
write \- write to a file descriptor
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.sp
|
|
|
|
.BI "ssize_t write(int " fd ", const void *" buf ", size_t " count );
|
|
|
|
.SH DESCRIPTION
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR write ()
|
2004-11-03 13:51:07 +00:00
|
|
|
writes up to
|
|
|
|
.I count
|
2007-06-21 22:55:04 +00:00
|
|
|
bytes from the buffer pointed
|
2007-09-20 16:26:31 +00:00
|
|
|
.I buf
|
2007-06-11 19:51:09 +00:00
|
|
|
to the file referred to by the file descriptor
|
2007-09-04 06:30:39 +00:00
|
|
|
.IR fd .
|
2007-06-11 19:51:09 +00:00
|
|
|
|
|
|
|
The number of bytes written may be less than
|
|
|
|
.I count
|
|
|
|
if, for example,
|
|
|
|
there is insufficient space on the underlying physical medium, or the
|
|
|
|
.B RLIMIT_FSIZE
|
|
|
|
resource limit is encountered (see
|
|
|
|
.BR setrlimit (2)),
|
|
|
|
or the call was interrupted by a signal
|
|
|
|
handler after having written less than
|
|
|
|
.I count
|
|
|
|
bytes.
|
|
|
|
(See also
|
|
|
|
.BR pipe (7).)
|
|
|
|
|
|
|
|
For a seekable file (i.e., one to which
|
|
|
|
.BR lseek (2)
|
|
|
|
may be applied, for example, a regular file)
|
|
|
|
writing takes place at the current file offset,
|
|
|
|
and the file offset is incremented by
|
|
|
|
the number of bytes actually written.
|
|
|
|
If the file was
|
|
|
|
.BR open (2)ed
|
|
|
|
with
|
|
|
|
.BR O_APPEND ,
|
|
|
|
the file offset is first set to the end of the file before writing.
|
|
|
|
The adjustment of the file offset and the write operation
|
|
|
|
are performed as an atomic step.
|
|
|
|
|
2007-05-12 09:06:04 +00:00
|
|
|
POSIX requires that a
|
|
|
|
.BR read (2)
|
|
|
|
which can be proved to occur after a
|
|
|
|
.BR write ()
|
|
|
|
has returned returns the new data.
|
2007-06-11 19:51:09 +00:00
|
|
|
Note that not all file systems are POSIX conforming.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2007-06-11 19:51:09 +00:00
|
|
|
On success, the number of bytes written is returned (zero indicates
|
2007-04-12 22:42:49 +00:00
|
|
|
nothing was written).
|
|
|
|
On error, \-1 is returned, and \fIerrno\fP is set
|
|
|
|
appropriately.
|
2006-12-04 05:36:13 +00:00
|
|
|
|
|
|
|
If \fIcount\fP is zero and
|
|
|
|
.I fd
|
|
|
|
refers to a regular file, then
|
2007-06-11 19:51:09 +00:00
|
|
|
.BR write ()
|
2006-12-04 05:36:13 +00:00
|
|
|
may return a failure status if one of the errors below is detected.
|
|
|
|
If no errors are detected,
|
|
|
|
0 will be returned without causing any other effect.
|
|
|
|
If
|
|
|
|
\fIcount\fP is zero and
|
|
|
|
.I fd
|
2007-04-12 22:42:49 +00:00
|
|
|
refers to a file other than a regular file,
|
2006-12-04 05:36:13 +00:00
|
|
|
the results are not specified.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EAGAIN
|
2007-06-11 19:51:09 +00:00
|
|
|
The file descriptor
|
|
|
|
.I fd
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
refers to a file other than a socket and has been marked nonblocking
|
2009-02-23 04:57:43 +00:00
|
|
|
.RB ( O_NONBLOCK ),
|
2004-11-03 13:51:07 +00:00
|
|
|
and the write would block.
|
|
|
|
.TP
|
2009-02-23 04:57:43 +00:00
|
|
|
.BR EAGAIN " or " EWOULDBLOCK
|
|
|
|
.\" Actually EAGAIN on Linux
|
|
|
|
The file descriptor
|
|
|
|
.I fd
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
refers to a socket and has been marked nonblocking
|
2009-02-23 04:57:43 +00:00
|
|
|
.RB ( O_NONBLOCK ),
|
|
|
|
and the write would block.
|
|
|
|
POSIX.1-2001 allows either error to be returned for this case,
|
|
|
|
and does not require these constants to have the same value,
|
|
|
|
so a portable application should check for both possibilities.
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EBADF
|
|
|
|
.I fd
|
|
|
|
is not a valid file descriptor or is not open for writing.
|
|
|
|
.TP
|
2010-08-29 13:50:27 +00:00
|
|
|
.B EDESTADDRREQ
|
|
|
|
.I fd
|
|
|
|
refers to a datagram socket for which a peer address has not been set using
|
|
|
|
.BR connect (2).
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EFAULT
|
|
|
|
.I buf
|
|
|
|
is outside your accessible address space.
|
|
|
|
.TP
|
|
|
|
.B EFBIG
|
|
|
|
An attempt was made to write a file that exceeds the implementation-defined
|
2007-06-11 19:51:09 +00:00
|
|
|
maximum file size or the process's file size limit,
|
|
|
|
or to write at a position past the maximum allowed offset.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINTR
|
2008-07-04 15:50:36 +00:00
|
|
|
The call was interrupted by a signal before any data was written; see
|
|
|
|
.BR signal (7).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I fd
|
2005-10-10 13:07:32 +00:00
|
|
|
is attached to an object which is unsuitable for writing;
|
2007-04-12 22:42:49 +00:00
|
|
|
or the file was opened with the
|
2005-10-10 13:07:32 +00:00
|
|
|
.B O_DIRECT
|
|
|
|
flag, and either the address specified in
|
|
|
|
.IR buf ,
|
|
|
|
the value specified in
|
|
|
|
.IR count ,
|
|
|
|
or the current file offset is not suitably aligned.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EIO
|
|
|
|
A low-level I/O error occurred while modifying the inode.
|
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
The device containing the file referred to by
|
|
|
|
.I fd
|
|
|
|
has no room for the data.
|
|
|
|
.TP
|
|
|
|
.B EPIPE
|
|
|
|
.I fd
|
2007-04-12 22:42:49 +00:00
|
|
|
is connected to a pipe or socket whose reading end is closed.
|
|
|
|
When this happens the writing process will also receive a
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SIGPIPE
|
|
|
|
signal.
|
|
|
|
(Thus, the write return value is seen only if the program
|
|
|
|
catches, blocks or ignores this signal.)
|
|
|
|
.PP
|
|
|
|
Other errors may occur, depending on the object connected to
|
|
|
|
.IR fd .
|
|
|
|
.SH "CONFORMING TO"
|
2007-04-12 22:42:49 +00:00
|
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
2006-08-03 13:57:17 +00:00
|
|
|
.\" SVr4 documents additional error
|
|
|
|
.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
|
|
|
|
|
2007-07-09 20:07:44 +00:00
|
|
|
Under SVr4 a write may be interrupted and return
|
|
|
|
.B EINTR
|
|
|
|
at any point,
|
2007-04-12 22:42:49 +00:00
|
|
|
not just before any data is written.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
A successful return from
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR write ()
|
2004-11-03 13:51:07 +00:00
|
|
|
does not make any guarantee that data has been committed to disk.
|
|
|
|
In fact, on some buggy implementations, it does not even guarantee
|
|
|
|
that space has successfully been reserved for the data.
|
|
|
|
The only way to be sure is to call
|
|
|
|
.BR fsync (2)
|
|
|
|
after you are done writing all your data.
|
2007-06-11 19:51:09 +00:00
|
|
|
|
|
|
|
If a
|
|
|
|
.BR write ()
|
|
|
|
is interrupted by a signal handler before any bytes are written,
|
|
|
|
then the call fails with the error
|
|
|
|
.BR EINTR ;
|
|
|
|
if it is interrupted after at least one byte has been written,
|
|
|
|
the call succeeds, and returns the number of bytes written.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR close (2),
|
|
|
|
.BR fcntl (2),
|
|
|
|
.BR fsync (2),
|
|
|
|
.BR ioctl (2),
|
|
|
|
.BR lseek (2),
|
|
|
|
.BR open (2),
|
2006-02-08 04:18:44 +00:00
|
|
|
.BR pwrite (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR read (2),
|
|
|
|
.BR select (2),
|
2006-08-10 05:15:07 +00:00
|
|
|
.BR writev (2),
|
2006-05-29 04:48:39 +00:00
|
|
|
.BR fwrite (3)
|