venti-packet.3 (4573B)
1 .TH VENTI-PACKET 3 2 .SH NAME 3 Packet, 4 packetalloc, 5 packetappend, 6 packetasize, 7 packetcmp, 8 packetconcat, 9 packetconsume, 10 packetcopy, 11 packetdup, 12 packetforeign, 13 packetfragments, 14 packetfree, 15 packetheader, 16 packetpeek, 17 packetprefix, 18 packetsha1, 19 packetsize, 20 packetsplit, 21 packetstats, 22 packettrailer, 23 packettrim \- zero-copy network buffers 24 .SH SYNOPSIS 25 .ft L 26 #include <u.h> 27 .br 28 #include <libc.h> 29 .br 30 #include <venti.h> 31 .ta +\w'\fLPacket* 'u +\w'\fLxxxx'u 32 .PP 33 .B 34 .PP 35 .B 36 Packet* packetalloc(void); 37 .PP 38 .B 39 void packetappend(Packet *p, uchar *buf, int n) 40 .PP 41 .B 42 uint packetasize(Packet *p) 43 .PP 44 .B 45 int packetcmp(Packet *p, Packet *q) 46 .PP 47 .B 48 void packetconcat(Packet *p, Packet *q) 49 .PP 50 .B 51 int packetconsume(Packet *p, uchar *buf, int n) 52 .PP 53 .B 54 int packetcopy(Packet *p, uchar *buf, int offset, int n) 55 .PP 56 .B 57 Packet* packetdup(Packet *p, int offset, int n) 58 .PP 59 .B 60 Packet* packetforeign(uchar *buf, int n, 61 .br 62 .B 63 void (*free)(void *a), void *a) 64 .PP 65 .B 66 int packetfragments(Packet *p, IOchunk *io, int nio, 67 .br 68 .B 69 int offset) 70 .PP 71 .B 72 void packetfree(Packet *p) 73 .PP 74 .B 75 uchar* packetheader(Packet *p, int n) 76 .PP 77 .B 78 uchar* packetpeek(Packet *p, uchar *buf, int offset, int n) 79 .PP 80 .B 81 void packetprefix(Packet *p, uchar *buf, int n) 82 .PP 83 .B 84 void packetsha1(Packet *p, uchar sha1[20]) 85 .PP 86 .B 87 uint packetsize(Packet *p) 88 .PP 89 .B 90 Packet* packetsplit(Packet *p, int n) 91 .PP 92 .B 93 void packetstats(void) 94 .PP 95 .B 96 uchar* packettrailer(Packet *p, int n) 97 .PP 98 .B 99 int packettrim(Packet *p, int offset, int n) 100 .SH DESCRIPTION 101 A 102 .B Packet 103 is a chain of blocks of data. 104 Each block, called a fragment, 105 is contiguous in memory, but the entire packet 106 may not be. 107 This representation helps avoid unnecessary memory copies. 108 .PP 109 .I Packetalloc 110 allocates an empty packet. 111 .PP 112 .I Packetappend 113 appends the 114 .I n 115 bytes at 116 .I buf 117 to the end of 118 .IR p . 119 .PP 120 .I Packetasize 121 returns the number of data bytes allocated to 122 .IR p . 123 This may be larger than the number of bytes stored 124 in 125 .IR p 126 because fragments may not be filled completely. 127 .PP 128 .I Packetcmp 129 compares the data sections of two packets as 130 .I memcmp 131 (see 132 .MR memory (3) ) 133 would. 134 .PP 135 .I Packetconcat 136 removes all data from 137 .IR q , 138 appending it to 139 .IR p . 140 .PP 141 .I Packetconsume 142 removes 143 .I n 144 bytes from the beginning of 145 .IR p , 146 storing them into 147 .IR buf . 148 .PP 149 .I Packetcopy 150 copies 151 .I n 152 bytes at 153 .I offset 154 in 155 .I p 156 to 157 .IR buf . 158 .PP 159 .I Packetdup 160 creates a new packet initialized with 161 .I n 162 bytes from 163 .I offset 164 in 165 .IR p . 166 .PP 167 .I Packetforeign 168 allocates a packet containing `foreign' data: the 169 .I n 170 bytes pointed to by 171 .IR buf . 172 Once the bytes are no longer needed, they are freed by calling 173 .IB free ( a )\fR. 174 .PP 175 .I Packetfragments 176 initializes up to 177 .I nio 178 of the 179 .I io 180 structures with pointers to the data in 181 .IR p , 182 starting at 183 .IR offset . 184 It returns the total number of bytes represented 185 by the returned structures. 186 .I Packetfragments 187 initializes any unused 188 .I io 189 structures with nil pointer and zero length. 190 .PP 191 .I Packetfree 192 frees the packet 193 .IR p . 194 .PP 195 .I Packetheader 196 returns a pointer to the first 197 .I n 198 bytes of 199 .IR p , 200 making them contiguous in memory 201 if necessary. 202 .PP 203 .I Packetpeek 204 returns a pointer to the 205 .I n 206 bytes at 207 .I offset 208 in 209 .IR p . 210 If the requested bytes are already stored contiguously in memory, 211 the returned pointer points at the internal data storage for 212 .IR p . 213 Otherwise, the bytes are copied into 214 .IR buf , 215 and 216 .I packetpeek 217 returns 218 .IR buf . 219 .PP 220 .I Packetprefix 221 inserts a copy of the 222 .I n 223 bytes at 224 .I buf 225 at the beginning of 226 .IR p . 227 .PP 228 .I Packetsha1 229 computes the SHA1 hash of the data contained in 230 .IR p . 231 .PP 232 .I Packetsize 233 returns the length, in bytes, of the data contained in 234 .IR p . 235 .PP 236 .I Packetsplit 237 returns a new packet initialized with 238 .I n 239 bytes removed from the beginning of 240 .IR p . 241 .PP 242 .I Packetstats 243 prints run-time statistics to standard output. 244 .PP 245 .I Packettrailer 246 returns a pointer to the last 247 .I n 248 bytes of 249 .IR p , 250 making them contiguous in memory 251 if necessary. 252 .PP 253 .I Packettrim 254 deletes all bytes from the packet 255 .I p 256 except the 257 .I n 258 bytes at offset 259 .IR offset . 260 .SH SOURCE 261 .B \*9/src/libventi 262 .SH SEE ALSO 263 .MR venti (3) 264 .SH DIAGNOSTICS 265 These functions return errors only when passed 266 invalid inputs, 267 .IR e.g. , 268 requests for data at negative offsets or beyond the end of a packet. 269 .PP 270 Functions returning pointers return nil on error; 271 functions returning integers return \-1 on error. 272 Most functions returning integers return 0 on success. 273 The exceptions are 274 .I packetfragments 275 and 276 .IR packetcmp , 277 whose return values are described above. 278 .PP 279 When these functions run out of memory, they 280 print error messages and call 281 .IR sysfatal .