|
|
|
|
.TH io_trywrite 3
|
|
|
|
|
.SH NAME
|
|
|
|
|
io_trywrite \- write to a descriptor without blocking
|
|
|
|
|
.SH SYNTAX
|
|
|
|
|
.B #include <libowfat/io.h>
|
|
|
|
|
|
|
|
|
|
int \fBio_trywrite\fP(int64 fd,const char* buf,int64 len);
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
io_trywrite tries to write \fIlen\fR bytes of data from
|
|
|
|
|
buf[0], buf[1], ..., buf[len-1] to descriptor \fIfd\fR. (The effects are
|
|
|
|
|
undefined if \fIlen\fR is 0 or smaller.) There are several possible
|
|
|
|
|
results:
|
|
|
|
|
|
|
|
|
|
.RS 0
|
|
|
|
|
.IP \[bu] 3
|
|
|
|
|
o_trywrite returns an integer between 1 and \fIlen\fR: This number of bytes was
|
|
|
|
|
immediately written from the beginning of \fIbuf\fR.
|
|
|
|
|
Note that this number can be, and often is, smaller than \fIlen\fR;
|
|
|
|
|
you must not assume that io_trywrite always succeeds in writing exactly
|
|
|
|
|
\fIlen\fR bytes.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
io_trywrite returns -1, setting \fIerrno\fR to EAGAIN: No bytes were
|
|
|
|
|
written, because the descriptor is not ready. For example, the
|
|
|
|
|
descriptor is writing to a full pipe that could still be read.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
io_trywrite returns -3, setting \fIerrno\fR to something other than
|
|
|
|
|
EAGAIN: No bytes were written, because the write attempt encountered a
|
|
|
|
|
persistent error, such as a serious disk failure (EIO), an unreachable
|
|
|
|
|
network (ENETUNREACH), or an invalid descriptor number (EBADF).
|
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
io_trywrite does not pause waiting for a descriptor that is not ready.
|
|
|
|
|
If you want to pause, use io_waitread or io_wait.
|
|
|
|
|
|
|
|
|
|
You can make io_trywrite faster and more efficient by making
|
|
|
|
|
the socket non-blocking with io_nonblock().
|
|
|
|
|
|
|
|
|
|
Once upon a time, many UNIX programs neglected to check the success of
|
|
|
|
|
their writes. They would often encounter EPIPE, and would blithely
|
|
|
|
|
continue writing, rather than exiting with an appropriate exit code. The
|
|
|
|
|
UNIX kernel developers decided to send a SIGPIPE signal, which
|
|
|
|
|
terminates the process by default, along with returning EPIPE. This
|
|
|
|
|
papers over the problem without fixing it: the same programs ignore
|
|
|
|
|
other errors such as EIO. One hopes that the programs have been fixed by
|
|
|
|
|
now; kernels nevertheless continue to generate the SIGPIPE signal. The
|
|
|
|
|
first time io_trywrite or io_waitwrite is called, it arranges for
|
|
|
|
|
SIGPIPE to be ignored. (Technically, for SIGPIPE to be caught by an
|
|
|
|
|
empty signal handler, so this doesn't affect child processes.) Do not
|
|
|
|
|
use SIGPIPE elsewhere in the program.
|
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
io_nonblock(3), io_waitread(3), io_trywritetimeout(3)
|
