siovec.html (6734B)
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 siovec header</title> 7 <meta name="Description" content="skalibs: the siovec header" /> 8 <meta name="Keywords" content="skalibs header siovec struct iovec scatter gather array I/O" /> 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>skalibs/siovec.h</tt> header </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/siovec.h</tt> header 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> Purpose </h2> 29 30 <p> 31 These functions manipulate arrays of <tt>struct iovec</tt> containing 32 ranges of bytes, handling them as contiguous arrays. They're used, for 33 instance, in the skalibs implementation of circular buffers. 34 </p> 35 36 <h2> Functions </h2> 37 38 <p> 39 <code> size_t siovec_len (struct iovec const *v, unsigned int n) </code> <br> 40 Returns the sum of the first <em>n</em> <tt>iov_len</tt> fields of the 41 <em>v</em> array - i.e. the total number of bytes contained in the 42 array represented by <em>v</em> of length <em>n</em>. 43 </p> 44 45 <p> 46 <code> size_t siovec_gather (struct iovec const *v, unsigned int n, char *s, size_t max) </code> <br> 47 Gathers all the data scattered in ranges described by <em>v</em> of length 48 <em>n</em> into the space pointed to by <em>s</em>. 49 Specifically: the first <tt>v[0].iov_len</tt> bytes pointed to by 50 <tt>v[0].iov_base</tt> bytes are copied to <em>s</em>, then the first 51 <tt>v[1].iov_len</tt> bytes pointed to by <tt>v[1].iov_base</tt> are 52 appended to it, and so on, <em>n</em> times. 53 The function copies no more than <tt>max</tt> bytes. It 54 returns the total amount of bytes copied. 55 </p> 56 57 <p> 58 <code> size_t siovec_scatter (struct iovec const *v, unsigned int n, char const *s, size_t len) </code> <br> 59 Scatters <em>len</em> bytes of data from <em>s</em> into the byte ranges 60 represented by array <em>v</em> of length <em>n</em>. (This is the opposite 61 of the <tt>siovec_gather()</tt> function.) 62 The first <tt>v[0].iov_len</tt> bytes of 63 <tt>s</tt> are copied to <tt>v[0].iov_base</tt>, then the following 64 <tt>v[1].iov_len</tt> bytes of <em>s</em> are copied to 65 <tt>v[1].iov_base</tt>, and so on up to <em>len</em> bytes or until 66 if the scatter array is full, i.e. <tt>siovec_len(v, n)</tt> bytes 67 have been copied. The function returns the total amount of bytes copied. 68 </p> 69 70 <p> 71 <code> size_t siovec_deal (struct iovec const *vj, unsigned int nj, struct iovec const *vi, unsigned int ni) </code> <br> 72 Copies the data contained in the ranges represented by the array <em>vi</em> of 73 length <em>ni</em> to the ranges represented by the array <em>vj</em> of length 74 <em>nj</em>. 75 The first <tt>vi[0].iov_len</tt> bytes pointed to by <tt>vi[0].iov_base</tt> 76 are copied to <tt>vj[0].iov_base</tt>, up to <tt>vj[0].iov_len</tt> bytes, 77 moving on to <tt>vj[1].iov_base</tt> if it overflows; then the bytes pointed 78 to by <tt>vi[1].iov_base</tt> are copied to what space remains wherever the 79 writing pointer is, and so on until all the bytes in the ranges described by 80 <em>vi</em> have been copied or there is no more room left in the ranges 81 described by <em>vj</em>. 82 The function returns the total amount of bytes copied. 83 </p> 84 85 <p> 86 <code> size_t siovec_seek (struct iovec *v, unsigned int n, size_t len) </code> <br> 87 Does the equivalent of <tt>p += len;</tt> if the byte ranges represented by 88 array <em>v</em> of size <em>n</em> were a single byte array pointed by <tt>p</tt>. 89 If <tt>v[0].iov_len</tt> is lesser than <em>len</em>, then <tt>v[0]</tt> is 90 zeroed out (set to <tt>{ .iov_base = 0, .iov_len = 0 }</tt>), <tt>v[0].iov_len</tt> 91 bytes are deduced from <em>len</em>, and the same operation is repeated with 92 <tt>v[1]</tt>, and so on. If every iovec gets zeroed out, the operation stops; 93 but if a <tt>v[i].iov_len</tt> is greater than the 94 remaining amount of bytes to deduce, that amount is substracted from 95 <tt>v[i].iov_len</tt> and added to <tt>v[i].iov_base</tt>. The function returns 96 the total number of bytes that have been deduced. 97 </p> 98 99 <p> 100 <code> unsigned int siovec_trunc (struct iovec *v, unsigned int n, size_t len) </code> <br> 101 Truncates the last fields of <em>v</em> of size <em>n</em> so that the byte 102 ranges it represents have a total length of <em>len</em> or less. The 103 <tt>iov_len</tt> field of <tt>v[n-1]</tt> is decreased by len; if it would 104 be negative, then it's zeroed out and the remainder is taken from <tt>v[n-2]</tt> 105 instead, and so on. The function returns the new size of array <em>v</em> 106 with the tailing zeroed out members removed. It can only return 0 if <em>len</em> 107 is 0, which means all of <em>v</em> has been zeroed out. 108 </p> 109 110 <p> 111 <code> size_t siovec_bytechr (struct iovec const *v, unsigned int n, char c) </code> <br> 112 Looks for the first occurence of <em>c</em> among the byte ranges represented by the members 113 of <em>v</em>. Returns its cumulative index, i.e. the position that <em>c</em> 114 would have if the byte ranges pointed to by members of <em>v</em> were a 115 single array. If there are no occurences of <em>c</em>, the function retunrs 116 <tt>siovec_len(v, n)</tt>. 117 </p> 118 119 <p> 120 <code> size_t siovec_bytein (struct iovec const *v, unsigned int n, char const *sep, size_t seplen) </code> <br> 121 Looks for the first occurence of any byte from the <em>sep</em> array of size 122 <em>seplen</em> among the byte ranges represented by the members of array <em>v</em> 123 of size <em>n</em>, and returns the cumulative index of the first one it finds. 124 </p> 125 126 <p> 127 <code> size_t siovec_search (struct iovec const *v, unsigned int n, char const *needle, size_t nlen) </code> <br> 128 Looks for the string (as in array of bytes: null characters are supported) 129 <em>needle</em> of size <em>nlen</em> in the byte ranges represented by the 130 members of array <em>v</em> of size <em>n</em>, and returns the cumulative 131 index of the first occurrence it finds, or <tt>siovec_len(v, n)</tt> if it 132 cannot find one. Split strings <strong>are</strong> supported: if <em>needle</em> 133 starts at position <tt>v[i].iov_base + pos</tt> but is cut because it 134 reaches <tt>v[i].iov_len</tt> midstring, and the rest of <em>needle</em> 135 is available at <tt>v[i+1].iov_base</tt>, then the function will find it 136 (and return <em>pos</em> plus the sum length of all the <em>v</em> members 137 before <em>i</em>). 138 </p> 139 140 </body> 141 </html>