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