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)