bionic (3) io_trywrite.3.gz

NAME

       io_trywrite - write to a descriptor without blocking

SYNTAX

       #include <io.h>

       int io_trywrite(int64 fd,const char* buf,int64 len);

DESCRIPTION

       io_trywrite  tries to write len bytes of data from buf[0], buf[1], ..., buf[len-1] to descriptor fd. (The
       effects are undefined if len is 0 or smaller.) There are several possible results:

       •  o_trywrite returns an integer between 1 and len: This number of bytes was immediately written from the
          beginning  of  buf.  Note that this number can be, and often is, smaller than len; you must not assume
          that io_trywrite always succeeds in writing exactly len bytes.

       •  io_trywrite returns -1, setting errno 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.

       •  io_trywrite  returns  -3, setting errno 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).

       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.

SEE ALSO

       io_nonblock(3), io_waitread(3), io_trywritetimeout(3)

                                                                                                  io_trywrite(3)