io_trywrite(3)

1io_trywrite(3)             Library Functions Manual             io_trywrite(3)
2
3
4

NAME

6       io_trywrite - write to a descriptor without blocking
7

SYNTAX

9       #include <io.h>
10
11       int io_trywrite(int64 fd,const char* buf,int64 len);
12

DESCRIPTION

14       io_trywrite  tries to write len bytes of data from buf[0], buf[1], ...,
15       buf[len-1] to descriptor fd. (The effects are undefined if len is 0  or
16       smaller.) There are several possible results:
17
18
19       ·  o_trywrite  returns  an  integer  between  1 and len: This number of
20          bytes was immediately written from the beginning of buf.  Note  that
21          this  number  can  be,  and often is, smaller than len; you must not
22          assume that io_trywrite  always  succeeds  in  writing  exactly  len
23          bytes.
24
25       ·  io_trywrite returns -1, setting errno to EAGAIN: No bytes were writ‐
26          ten, because the descriptor is not ready. For example, the  descrip‐
27          tor is writing to a full pipe that could still be read.
28
29       ·  io_trywrite  returns  -3,  setting  errno  to  something  other than
30          EAGAIN: No bytes were written, because the write attempt encountered
31          a  persistent  error,  such  as  a  serious  disk  failure (EIO), an
32          unreachable network (ENETUNREACH), or an invalid  descriptor  number
33          (EBADF).
34
35       io_trywrite  does not pause waiting for a descriptor that is not ready.
36       If you want to pause, use io_waitread or io_wait.
37
38       You can make io_trywrite faster and more efficient by making the socket
39       non-blocking with io_nonblock().
40
41       Once  upon a time, many UNIX programs neglected to check the success of
42       their writes. They would often encounter EPIPE, and would blithely con‐
43       tinue  writing,  rather than exiting with an appropriate exit code. The
44       UNIX kernel developers decided to send a SIGPIPE signal,  which  termi‐
45       nates  the  process by default, along with returning EPIPE. This papers
46       over the problem without fixing it:  the  same  programs  ignore  other
47       errors such as EIO. One hopes that the programs have been fixed by now;
48       kernels nevertheless continue to generate the SIGPIPE signal. The first
49       time  io_trywrite or io_waitwrite is called, it arranges for SIGPIPE to
50       be ignored.  (Technically, for SIGPIPE to be caught by an empty  signal
51       handler,  so  this  doesn't affect child processes.) Do not use SIGPIPE
52       elsewhere in the program.
53

NAME

SYNTAX

DESCRIPTION

SEE ALSO