allreadwrite.html (7545B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the allreadwrite library interface</title> 7 <meta name="Description" content="skalibs: the allreadwrite library interface" /> 8 <meta name="Keywords" content="skalibs c unix allreadwrite library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>allreadwrite</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/allreadwrite.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>allreadwrite</tt> is a set of IO function helpers. It's the 32 basis for safe reading and writing, either in blocking or in 33 non-blocking mode. The <a href="buffer.html">buffer</a> interface 34 relies heavily on <tt>allreadwrite</tt>. 35 </p> 36 37 <p> 38 Unless the IO you need is very simple, you generally should not 39 be using the <tt>allreadwrite</tt> functions directly; you should 40 use higher-level APIs such as <a href="buffer.html">buffer</a> and 41 <a href="bufalloc.html">bufalloc</a>. 42 </p> 43 44 <h2> Function types </h2> 45 46 <p> 47 <code> typedef ssize_t io_func (int fd, char *buf, size_t len) </code> <br /> 48 This is the simplified type of IO functions such as 49 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/read.html">read()</a> 50 and 51 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a>. 52 </p> 53 54 <p> 55 <code> typedef ssize_t iov_func (int fd, struct iovec const *v, unsigned int vlen) </code> <br /> 56 This is the simplified type of IO functions such as 57 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/readv.html">readv()</a> 58 and 59 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/writev.html">writev()</a>, 60 where the content to perform IO on is specified as a 61 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 62 elements instead of a single string. 63 </p> 64 65 66 <p> 67 <code> typedef size_t allio_func (int fd, char *buf, size_t len) </code> <br /> 68 This is the type of an IO operation that expects <em>all</em> of its 69 <em>len</em> bytes to be sent or received, and that will loop around a 70 lower-level IO function until either <em>len</em> bytes have been 71 transmitted or an error has occurred. The return value is the actual 72 number of transmitted bytes; if this value is lesser than <em>len</em>, 73 it means that an error has occurred and <tt>errno</tt> is set. 74 </p> 75 76 <h2> Functions </h2> 77 78 <p> 79 <code> ssize_t sanitize_read (ssize_t r) </code> <br /> 80 Reading functions such as <tt>read()</tt> and <tt>fd_read</tt> return 81 a positive number when they succeed, -1 when they fail, and 0 when they 82 read an EOF. No data available on the descriptor when reading in 83 non-blocking mode is treated as a failure: -1 EWOULDBLOCK. But sometimes 84 (namely, in asynchronous IO loops) it's preferrable to handle EOF as an 85 exception condition and EWOULDBLOCK as a normal condition. 86 <tt>sanitize_read()</tt>, when applied to the result of a basic reading 87 function, returns 0 if <em>r</em> is -1 and errno is EWOULDBLOCK (or 88 EAGAIN). If <em>r</em> is zero, it returns -1 EPIPE. Else it returns <em>r</em>. 89 </p> 90 91 <p> 92 (No system reading function can ever set errno to EPIPE, and the 93 semantics are appropriate, so EPIPE is a good candidate to signal EOF 94 on reading.) 95 </p> 96 97 <p> 98 <code> ssize_t unsanitize_read (ssize_t r) </code> <br /> 99 Returns the inverse of <code>sanitize_read</code>. 100 </p> 101 102 <p> 103 <code> size_t allreadwrite (io_func *f, int fd, char *s, size_t len) </code> <br /> 104 *<em>f</em> must be a basic reading or writing function such as 105 <tt>fd_read</tt> or <tt>fd_write</tt>. <tt>allreadwrite()</tt> performs 106 *<em>f</em> on <em>fd</em>, <em>s</em> and <em>len</em> until <em>len</em> 107 bytes have been read or written, or until an error occurs. It returns the 108 total number of handled bytes, and sets errno if this number is not 109 <em>len</em>. <tt>allreadwrite</tt> may block if <em>fd</em> is in 110 blocking mode; if <em>fd</em> is in non-blocking mode, it might 111 set errno to EWOULDBLOCK or EAGAIN. 112 </p> 113 114 <p> 115 <code> size_t allreadwritev (iov_func *f, int fd, struct iovec const *v, unsigned int vlen) </code> <br /> 116 Like <code> allreadwrite </code> 117 but the content to perform IO on is specified as a 118 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 119 elements instead of a single string. 120 </p> 121 122 <p> 123 <code> ssize_t fd_read (int fd, char *s, size_t len) </code> <br /> 124 <a href="safewrappers.html">Safe wrapper</a> around the 125 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/read.html">read()</a> 126 function. 127 </p> 128 129 <p> 130 <code> ssize_t fd_write (int fd, char const *s, size_t len) </code> <br /> 131 <a href="safewrappers.html">Safe wrapper</a> around the 132 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a> 133 function. 134 </p> 135 <p> 136 137 <code> ssize_t fd_readv (int fd, struct iovec const *v, unsigned int vlen) </code> <br /> 138 <a href="safewrappers.html">Safe wrapper</a> around the 139 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/readv.html">readv()</a> 140 function. 141 </p> 142 143 <p> 144 <code> ssize_t fd_writev (int fd, struct iovec const *v, unsigned int vlen) </code> <br /> 145 <a href="safewrappers.html">Safe wrapper</a> around the 146 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/writev.html">writev()</a> 147 function. 148 </p> 149 150 <p> 151 <code> ssize_t fd_recv (int fd, char *s, size_t len, unsigned int flags) </code> <br /> 152 <a href="safewrappers.html">Safe wrapper</a> around the 153 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/recv.html">recv()</a> 154 function. 155 </p> 156 157 <p> 158 <code> ssize_t fd_send (int fd, char const *s, size_t len, unsigned int flags) </code> <br /> 159 <a href="safewrappers.html">Safe wrapper</a> around the 160 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/send.html">send()</a> 161 function. 162 </p> 163 164 <p> 165 <code> size_t allread (int fd, char *s, size_t len) </code> <br /> 166 Equivalent to <code> allreadwrite(&fd_read, fd, s, len) </code>: attempts 167 to read <em>len</em> bytes from <em>fd</em> into <em>s</em>, looping around 168 <tt>fd_read()</tt> if necessary, until either <em>len</em> bytes are read or 169 an error occurs. 170 </p> 171 172 <p> 173 <code> size_t allwrite (int fd, char const *s, size_t len) </code> <br /> 174 Equivalent to <code> allreadwrite((io_func *)&fd_write, fd, s, len) </code>: 175 attempts to write <em>len</em> bytes from <em>s</em> to <em>fd</em>, looping 176 around <tt>fd_write()</tt> if necessary, until either <em>len</em> bytes are 177 written or an error occurs. 178 </p> 179 180 <p> 181 <code> size_t allreadv (int fd, struct iovec *v, unsigned int vlen) </code> <br /> 182 Like <tt>allread</tt>, but the bytes from <em>fd</em> are read into a 183 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 184 elements instead of a single string. 185 </p> 186 187 <p> 188 <code> size_t allwritev (int fd, struct iovec const *v, unsigned int vlen) </code> <br /> 189 Like <tt>allwrite</tt>, but the content to write is taken from a 190 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 191 elements instead of a single string. 192 </p> 193 194 </body> 195 </html>