DragonFly On-Line Manual Pages

io_trywrite(3)        DragonFly Library Functions Manual        io_trywrite(3)

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  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.

       o  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.

       o  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)