4e3819cf |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c |
3 | @c $Id: unet.texi,v 1.1 2001/01/25 22:03:39 mdw Exp $ |
4 | @c |
5 | @c Manual for usernet device |
6 | @c |
7 | @c (c) 1998 Mark Wooding |
8 | @c |
9 | |
10 | @c ----- Revision history --------------------------------------------------- |
11 | @c |
12 | @c $Log: unet.texi,v $ |
13 | @c Revision 1.1 2001/01/25 22:03:39 mdw |
14 | @c Initial check-in (somewhat belated). |
15 | @c |
16 | |
17 | @c ----- Standard boilerplate ----------------------------------------------- |
18 | |
19 | @c %**start of header |
20 | @setfilename unet.info |
21 | @settitle The Linux Usernet network interface |
22 | @setchapternewpage odd |
23 | @footnotestyle end |
24 | @paragraphindent 0 |
25 | @iftex |
26 | @input texinice |
27 | @afourpaper |
28 | @c @parindent=0pt |
29 | @end iftex |
30 | @c %**end of header |
31 | |
32 | @c ----- Useful macros ------------------------------------------------------ |
33 | |
34 | @set version 1.1 |
35 | |
36 | @c ----- Copyright matters -------------------------------------------------- |
37 | |
38 | @c --- The `Info' version --- |
39 | |
40 | @ifinfo |
41 | |
42 | This file documents the Linux Usernet network interface version |
43 | @value{version}. |
44 | |
45 | Copyright (c) 1998 Mark Wooding |
46 | |
47 | Permission is granted to make and distribute verbatim copies of this |
48 | manual provided the copyright notice and this permission notice are |
49 | preserved on all copies. |
50 | |
51 | @ignore |
52 | Permission is granted to process this file through TeX and print the |
53 | results, provided the printed document carries a copying permission |
54 | notice identical to this one except for the removal of this paragraph |
55 | (this paragraph not being relevant to the printed manual). |
56 | |
57 | @end ignore |
58 | Permission is granted to copy and distribute modified versions of this |
59 | manual under the conditions for verbatim copying, provided also that the |
60 | sections entitled `Copying' and `GNU General Public License' are |
61 | included exactly as in the original, and provided that the entire |
62 | resulting derived work is distributed under the terms of a permission |
63 | notice identical to this one. |
64 | |
65 | Permission is granted to copy and distribute translations of this manual |
66 | into another language, under the above conditions for modified versions, |
67 | except that this permission notice may be stated in a translation |
68 | approved by the copyright holder. |
69 | |
70 | @end ifinfo |
71 | |
72 | @c --- Printed title page --- |
73 | |
74 | @titlepage |
75 | |
76 | @title The Linux Usernet network interface. |
77 | @subtitle Transmitting Internet Protocol packets from user processes. |
78 | @author Mark Wooding (@email{mdw@@excessus.demon.co.uk}) |
79 | @page |
80 | |
81 | @vskip 0pt plus 1filll |
82 | |
83 | Copyright @copyright{} 1998 Mark Wooding |
84 | |
85 | Permission is granted to make and distribute verbatim copies of this |
86 | manual provided the copyright notice and this permission notice are |
87 | preserved on all copies. |
88 | |
89 | Permission is granted to copy and distribute modified versions of this |
90 | manual under the conditions for verbatim copying, provided also that the |
91 | sections entitled `Copying' and `GNU General Public License' are |
92 | included exactly as in the original, and provided that the entire |
93 | resulting derived work is distributed under the terms of a permission |
94 | notice identical to this one. |
95 | |
96 | Permission is granted to copy and distribute translations of this manual |
97 | into another language, under the above conditions for modified versions, |
98 | except that this permission notice may be stated in a translation |
99 | approved by the copyright holder. |
100 | |
101 | @end titlepage |
102 | |
103 | |
104 | @c -------------------------------------------------------------------------- |
105 | @ifinfo |
106 | @node Top, Copying, (dir), (dir) |
107 | @top The Linux Usernet network interface |
108 | |
109 | Usernet allows network interfaces to be attached to character devices. Any |
110 | packets sent through the network interface will be passed to the process |
111 | reading the device, and data written to the device will appear to have been |
112 | received from the network interface. |
113 | |
114 | This file documents Linux Usernet version @value{version}. |
115 | |
116 | @menu |
117 | * Copying:: You may modify and redistribute Usernet |
118 | * Introduction:: What Usernet actually does |
119 | * Technical details:: How Usernet does what it does |
120 | * Installing:: How to build and install Usernet |
121 | * Configuring attachments:: The provided configuration program |
122 | * Programming:: How to program the Usernet kernel module |
123 | |
124 | --- The Detailed Node Listing --- |
125 | |
126 | Overview and technical details |
127 | |
128 | * Attachments:: Attaching devices and network interfaces |
129 | * Usernet devices:: How Usernet's devices behave |
130 | |
131 | Configuring and installing |
132 | |
133 | * Autoconfiguring:: How Usernet configures itself |
134 | * Compiling and installing:: How to compile and install Usernet |
135 | |
136 | The @code{unetcfg} program |
137 | |
138 | * Invoking unetcfg:: Command line options |
139 | * Selecting attachments:: Setting the current attachment |
140 | * Attachment status:: Querying current status information |
141 | * Protocol settings:: Setting the protocol for outgoing packets |
142 | * Setting debugging options:: Various debugging settings |
143 | |
144 | Programming Usernet |
145 | |
146 | * Opening and closing:: Opening and closing attachments |
147 | * Configuring the interface:: How to configure an attached interface |
148 | * Sending and receiving:: Sending and receiving network packets |
149 | @end menu |
150 | |
151 | @end ifinfo |
152 | |
153 | |
154 | @c -------------------------------------------------------------------------- |
155 | @node Copying, Introduction, Top, Top |
156 | @unnumbered The GNU General Public License |
157 | |
158 | @include gpl.texi |
159 | |
160 | |
161 | @c -------------------------------------------------------------------------- |
162 | @node Introduction, Technical details, Copying, Top |
163 | @unnumbered Introduction |
164 | |
165 | Access to Linux's networking tends to be fairly high-level. A user process |
166 | can send and receive datagrams, or set up connections to other processes |
167 | easily enough. Privileged processes can build arbitrary IP packets and send |
168 | them, although raw IP sockets only receive packets for protocols unrecognised |
169 | by the kernel. Getting hold of all packets sent to a particular host is |
170 | rather more difficult, though. However, this can be a useful thing to want |
171 | to do. Usernet is a small kernel module which enables user processes to |
172 | attach to a network interface and read and write packets to it. |
173 | |
174 | Usernet works by creating pairs of character devices and network interfaces. |
175 | Any packet Linux sends to the network interface is sent unchanged to the |
176 | process reading the character device; similarly, when a block of data is |
177 | written to the character device, Usernet claims that it was received from the |
178 | corresponding network interface. |
179 | |
180 | The @samp{diald} program needs to be able to trap packets sent along a |
181 | particular route to know when to open a dialup connection. The current |
182 | implementation sets up a SLIP interface on a pseudoterminal, which is kludgy |
183 | at best. It could be modified to use a Usernet interface, and read and write |
184 | packets from there. |
185 | |
186 | The application which motivated the writing of Usernet was setting up a |
187 | virtual private network (VPN). Each end could set up a point-to-point |
188 | Usernet interface, and run a fairly small daemon, which would read packets |
189 | sent to the remote end, encrypt them and retransmit them as IP-in-IP |
190 | encapsulated datagrams, and decrypt any received IP-in-IP datagrams and |
191 | reinsert them through the Usernet interface. |
192 | |
193 | |
194 | @c -------------------------------------------------------------------------- |
195 | @node Technical details, Installing, Introduction, Top |
196 | @chapter Overview and technical details |
197 | |
198 | This chapter explains in more detail how Usernet is arranged and how it |
199 | works. |
200 | |
201 | @menu |
202 | * Attachments:: Attaching devices and network interfaces |
203 | * Usernet devices:: How Usernet's devices behave |
204 | @end menu |
205 | |
206 | |
207 | @node Attachments, Usernet devices, Technical details, Technical details |
208 | @section Attachments |
209 | |
210 | The Usernet kernel module creates @dfn{attachments} between character devices |
211 | and network interfaces. Any packet sent by the kernel through the network |
212 | interface can be read from the character device. Any buffers sent to the |
213 | device will appear to have been received by the attached interface. |
214 | |
215 | The Usernet module understands two types of attachments: |
216 | |
217 | @itemize @bullet |
218 | @item |
219 | @dfn{Persistent attachments} between character devices with low minor device |
220 | numbers are initialised when the module is loaded. The network interfaces |
221 | always exist, and can be configured at boot time if the module is loaded |
222 | early enough. |
223 | |
224 | @item |
225 | @dfn{Transient attachments} are set up dynamically when a process opens a |
226 | Usernet device with no preattached interface. The network interface is |
227 | created when the device is opened, and destroyed again when the device is |
228 | closed. Each open of the device creates a @emph{separate} attachment, so you |
229 | only need one device for any number of transient attachments. |
230 | @end itemize |
231 | |
232 | Usernet imposes a limitation on the number of attachments, mainly to stop |
233 | runaway processes from gobbling kernel resources; there aren't any |
234 | pre-allocated tables which would prevent you from hiking this parameter |
235 | upwards if you had a reason to. |
236 | |
237 | |
238 | @node Usernet devices, , Attachments, Technical details |
239 | @section Usernet devices |
240 | |
241 | Usernet claims a major device number (chosen at configuration time: |
242 | @xref{Installing}). |
243 | |
244 | The lowest numbered minor devices are persistently |
245 | attached to network interfaces: the network device @code{unet@var{n}} is |
246 | attached to minor device @var{n}, conventionally named |
247 | @code{/dev/unet@var{n}}. |
248 | |
249 | If a device is opened for which there is no persistent attachment, a new |
250 | network interface is allocated and a transient attachment is made. Each |
251 | separate @code{open}(2) call creates a new network interface and attachment, |
252 | which are destroyed again when the file descriptor on the device is closed. |
253 | It's normal to have one device with no persistent attachment, named |
254 | @code{/dev/unet}. |
255 | |
256 | |
257 | @c -------------------------------------------------------------------------- |
258 | @node Installing, Configuring attachments, Technical details, Top |
259 | @chapter Configuring and installing |
260 | |
261 | Usernet is meant to be both simple to set up for most people, and |
262 | sufficiently flexible to meet more advanced needs. |
263 | |
264 | @menu |
265 | * Autoconfiguring:: How Usernet configures itself |
266 | * Compiling and installing:: How to compile and install Usernet |
267 | @end menu |
268 | |
269 | |
270 | @node Autoconfiguring, Compiling and installing, Installing, Installing |
271 | @section Configuration options |
272 | |
273 | Configuration is performed using GNU Autoconf. Running the supplied |
274 | @code{configure} script without any options will configure Usernet to compile |
275 | properly under most Linux systems. |
276 | |
277 | The standard options accepted by Autoconf-generated configure scripts are |
278 | described in @ref{Invoking configure, , Running @code{configure} Scripts, |
279 | autoconf, Creating Automatic Configuration Scripts}. In addition to the |
280 | standard Autoconf options, Usernet's script understands these: |
281 | |
282 | @table @code |
283 | @item --with-linux-source=@var{dir} |
284 | Informs the configuration script that the Linux kernel sources are available |
285 | in directory @var{dir}. The configuration script will find your source code |
286 | in most sane installations. |
287 | |
288 | @item --with-module-dir=@var{dir} |
289 | Informs the configuration script that the compiled kernel module is to be |
290 | installed in directory @var{dir}. The configuration script will find |
291 | somewhere sensible in most sane installations. |
292 | |
293 | @item --with-major-device=@var{num} |
294 | Sets the major device of all Usernet character devices to @var{num}. Only |
295 | change this if you find that Usernet is conflicting with some other device. |
296 | |
297 | @item --with-persistent-devices=@var{num} |
298 | Sets the number of persistent attachment devices created by Usernet when it's |
299 | loaded to @var{num}. The default is 1. |
300 | |
301 | @item --with-transient-minor=@var{num} |
302 | Sets the minor device number of the device special file @code{/dev/unet}, |
303 | used to create transient attachments, to @var{num}. The default is 256; you |
304 | only need to change this if you've created a lot of persistent devices. |
305 | |
306 | @item --with-max-queue-length=@var{num} |
307 | Sets the maximum number of packets Usernet will queue for the process reading |
308 | from an attached character device to @var{num}. You probably don't need to |
309 | fiddle with this. |
310 | |
311 | @item --with-max-interfaces=@var{num} |
312 | Sets the maximum number of attached network interfaces Usernet will allow to |
313 | exist at any given time to @var{num}. The default is fairly generous, so you |
314 | shouldn't need to play with this unless you're doing something rather |
315 | strange. |
316 | |
317 | @item --with-debugging |
318 | Enables profuse logging of things Usernet is doing, including complete hex |
319 | dumps of all the network packets the module processes. |
320 | @end table |
321 | |
322 | |
323 | @node Compiling and installing, , Autoconfiguring, Installing |
324 | @section Compiling and installing |
325 | |
326 | Once Usernet has been autoconfigured, you should be able to type |
327 | @example |
328 | $ make |
329 | ... |
330 | $ su root |
331 | Password: |
332 | # make install |
333 | ... |
334 | @end example |
335 | @noindent |
336 | and the module will compile and install. |
337 | |
338 | You'll need to create the character devices to allow processes to talk to |
339 | Userdev. The script @code{makedev.unet} will create the appropriate |
340 | devices. Run without any options, it will create devices appropriate to the |
341 | configuration passed to @code{configure}. Type |
342 | @example |
343 | makedev.unet --help |
344 | @end example |
345 | @noindent |
346 | for information about the options it supports: they're not particularly |
347 | useful if you got the configuration right. |
348 | |
349 | If you later change your configuration, run @code{makedev.unet} again and it |
350 | will set everything straight. |
351 | |
352 | |
353 | @c -------------------------------------------------------------------------- |
354 | @node Configuring attachments, Programming, Installing, Top |
355 | @chapter The @code{unetcfg} program |
356 | |
357 | |
358 | A Usernet attachment can be interrogated and configured using the |
359 | @code{unetcfg} program supplied. |
360 | |
361 | @menu |
362 | * Invoking unetcfg:: Command line options |
363 | * Selecting attachments:: Setting the current attachment |
364 | * Attachment status:: Querying current status information |
365 | * Protocol settings:: Setting the protocol for outgoing packets |
366 | * Setting debugging options:: Various debugging settings |
367 | @end menu |
368 | |
369 | |
370 | @node Invoking unetcfg, Selecting attachments, Configuring attachments, Configuring attachments |
371 | @section Invoking @code{unetcfg} |
372 | |
373 | The @code{unetcfg} program is called as: |
374 | @example |
375 | unetcfg [@var{option}@dots{}] @var{command}@dots{} |
376 | @end example |
377 | |
378 | The various @var{option}s supported are as follows: |
379 | @table @samp |
380 | |
381 | @item -h |
382 | @itemx --help |
383 | Displays a helpful and informative summary of @code{unetcfg}'s option |
384 | syntax. |
385 | |
386 | @item -V |
387 | @itemx --version |
388 | Displays the version number of your copy of @code{unetcfg}. |
389 | |
390 | @item -v |
391 | @itemx --verbose |
392 | Enables output of largely useless status messages. These might be of use |
393 | when @code{unetcfg} doesn't seem to be doing what you want it to. |
394 | |
395 | @end table |
396 | |
397 | Each @var{command} is executed in turn, from left to right. The command |
398 | namees may be abbreviated, as long as the abbreviation is not ambiguous. |
399 | |
400 | Most of the commands work with a @dfn{current attachment}, which is assumed |
401 | to be standard input by default. The current attachment may be changed using |
402 | the @code{select} and @code{fd} commands (@pxref{Selecting attachments}). |
403 | |
404 | |
405 | @node Selecting attachments, Attachment status, Invoking unetcfg, Configuring attachments |
406 | @section Changing the current attachment |
407 | |
408 | These commands change the current attachment. You can use them as often as |
409 | you like in a single invocation of @code{unetcfg}. |
410 | |
411 | @deffn Command select @var{filename} |
412 | Selects @var{filename} as the current attachment. Further operations will be |
413 | performed on the named device. |
414 | |
415 | The command name @code{select} is optional: an argument which isn't a command |
416 | name is assumed to be a filename to select. |
417 | @end deffn |
418 | |
419 | @deffn Command fd @var{filedesc} |
420 | Selects an open file descriptor to be the current attachment. As well as |
421 | boring old file descriptor numbers, you can use the names @code{stdin}, |
422 | @code{stdout} and @code{stderr}. |
423 | |
424 | Note that it's really silly to set the current attachment to be standard |
425 | output and then perform commands which write to stdout: |
426 | @example |
427 | unetcfg fd stdout show |
428 | @end example |
429 | @noindent |
430 | Don't do this. |
431 | @end deffn |
432 | |
433 | |
434 | @node Attachment status, Protocol settings, Selecting attachments, Configuring attachments |
435 | @section Attachment status |
436 | |
437 | These commands write useful information about the current attachment to |
438 | standard output. |
439 | |
440 | @deffn Command show |
441 | Writes information about the current attachment to standard output. The |
442 | format of the information is not intended to be processed by other programs, |
443 | and may vary between releases of the software. |
444 | @end deffn |
445 | |
446 | @deffn Command ifname |
447 | Writes the name of the currently attached network interface to standard |
448 | error. This can be useful in configuration scripts. For example: |
449 | @example |
450 | ifname=`unetcfg fd 3 ifname` |
451 | ifconfig $ifname localend pointopoint remoteend |
452 | @end example |
453 | @end deffn |
454 | |
455 | @node Protocol settings, Setting debugging options, Attachment status, Configuring attachments |
456 | @section Protocol settings |
457 | |
458 | Each packet received by a network interface must have a protocol stamped on |
459 | it. Packets injected by writing to a Usernet-attached device are stamped |
460 | with the attachment's current protocol. The following command allows the |
461 | current attachment's protocol to be set. |
462 | |
463 | @deffn Command protocol @var{proto} |
464 | Sets the protocol stamped on packets injected through the current |
465 | attachment. A list of currently known protocols may be obtained by |
466 | specifying the special protocol name @code{help}. The default protocol is |
467 | always IP. |
468 | @end deffn |
469 | |
470 | |
471 | @node Setting debugging options, , Protocol settings, Configuring attachments |
472 | @section Setting debugging options |
473 | |
474 | |
475 | |
476 | @deffn Command help [@var{command}] |
477 | With no arguments, displays a summary of the commands available. With a |
478 | @var{command} argument, displays help on that command. |
479 | @end deffn |
480 | |
481 | |
482 | @c -------------------------------------------------------------------------- |
483 | @node Programming, , Configuring attachments, Top |
484 | @chapter Programming Usernet |
485 | |
486 | This chapter documents Usernet's programming interface. It's not |
487 | particularly complicated, you'll be glad to hear. |
488 | |
489 | @menu |
490 | * Opening and closing:: Opening and closing attachments |
491 | * Configuring the interface:: How to configure an attached interface |
492 | * Sending and receiving:: Sending and receiving network packets |
493 | @end menu |
494 | |
495 | |
496 | @node Opening and closing, Configuring the interface, Programming, Programming |
497 | @section Opening and closing |
498 | |
499 | Opening and closing Usernet devices is simple and obvious. Calling |
500 | @code{open}(2) on the appropriate special file opens the device. What |
501 | happens now depends on whether the device has a persistent attachment to a |
502 | network interface: |
503 | |
504 | @itemize @bullet |
505 | @item If the device has a persistent attachment, a check is made to see |
506 | whether the device has already been opened by another process. If this is |
507 | the case, @code{open} returns @code{EBUSY}. If the device was not already |
508 | opened, it is marked as open and a file descriptor is returned. |
509 | |
510 | @item If the device does not have a persistent attachment, a fresh network |
511 | interface is allocated and attached to the device. A file descriptor for the |
512 | opened device is returned. |
513 | @end itemize |
514 | |
515 | Closing a transiently attached device will release and destroy the attached |
516 | network interface. |
517 | |
518 | |
519 | @node Configuring the interface, Sending and receiving, Opening and closing, Programming |
520 | @section Configuring the interface |
521 | |
522 | Usernet interfaces can be configured using some simple @code{ioctl}(2) calls |
523 | supported by the Usernet character devices. The constants and data |
524 | structures required are defined in the header file @file{unet.h} provided in |
525 | the distribution. |
526 | |
527 | Most of the configuration work is performed on the network interface, and |
528 | this is done using the traditional @code{ioctl} calls on an open socket's |
529 | file descriptor. |
530 | |
531 | The following @code{ioctl} calls are provided for configuring Usernet |
532 | attachments. |
533 | |
534 | @deffn {@code{ioctl} call} UNIOCGINFO |
535 | Returns the a summary of the attachment's current configuration. The |
536 | argument is a pointer to a structure of type @code{struct |
537 | unet_info}, which contains the following members: |
538 | @table @code |
539 | |
540 | @item char uni_ifname[UNET_NAMEMAX]; |
541 | Interface name string. This may be passed to the @code{ifconfig} program, or |
542 | to the interface configuration @code{ioctl} calls to configure the attached |
543 | network interface. |
544 | |
545 | @item unsigned short uni_mtu; |
546 | Maximum transmission unit of the attached interface. This is also available |
547 | by calling @code{SIOCGIFMTU}, and may be set by calling @code{SIOCSIFMTU}. |
548 | |
549 | @item unsigned short uni_family; |
550 | Address family of the attached interface. This is usually @code{AF_UNIX}, |
551 | although it may be changed by calling @code{SIOCSIFADDR}. |
552 | |
553 | @item unsigned short uni_proto; |
554 | Network protocol number stamped onto packets to be sent from the attached |
555 | network interface. The default, which is probably good enough, is |
556 | @code{ETH_P_IP}. This field may be changed by calling @code{UNIOCSPROTO}. |
557 | |
558 | @item unsigned int uni_flags; |
559 | An inclusive-OR of the following possible values: |
560 | @table @code |
561 | @item UNIF_TRANS |
562 | Attachment is transient. |
563 | @item UNIF_OPEN |
564 | Currently always set. Ignore this bit. |
565 | @item UNIF_DEBUG |
566 | Debugging enabled on this interface. |
567 | @end table |
568 | |
569 | @end table |
570 | |
571 | Example: |
572 | @example |
573 | struct unet_info uni; |
574 | int fd = open("/dev/unet", O_RDWR); |
575 | if (fd < 0) |
576 | die("couldn't open /dev/unet: %s", strerror(errno)); |
577 | if (ioctl(fd, UNIOCGINFO, &uni) < 0) |
578 | die("couldn't get config information: %s", strerror(errno)); |
579 | printf("interface name = `%s'\n", uni.uni_ifname); |
580 | @end example |
581 | |
582 | @end deffn |
583 | |
584 | @deffn {@code{ioctl} call} UNIOCSDEBUG |
585 | Sets or clears the debug state for a Usernet attachment. If the argument is |
586 | nonzero, the debug flag is set; if zero, the flag is cleared. When debugging |
587 | is enabled for an attachment, Usernet logs packets sent and received through |
588 | it, and most changes to the attachment's state, to the kernel log. |
589 | @end deffn |
590 | |
591 | @deffn {@code{ioctl} call} UNIOCGPROTO |
592 | Reads the protocol number stamped onto packets submitted by an attached |
593 | Usernet interface. The value returned by the @code{ioctl} call is identical |
594 | to the @code{uni_proto} member returned by @code{UNIOCGINFO}. |
595 | @end deffn |
596 | |
597 | @deffn {@code{ioctl} call} UNIOCSPROTO |
598 | Sets the protocl number stamped onto outgoing packets. The protocol number, |
599 | passed as the @code{ioctl}'s argument, must be one of the constants defined |
600 | in @file{linux/if_ether.h}. |
601 | @end deffn |
602 | |
603 | @deffn {@code{ioctl} call} UNIOCGGDEBUG |
604 | Reads the global debug flag. When global debugging is enabled, all newly |
605 | created attachments have debugging turned on automatically, and various |
606 | global events are logged to the kernel log. |
607 | @end deffn |
608 | |
609 | @deffn {@code{ioctl} call} UNIOCSGDEBUG |
610 | Sets the global debug flag; if the argument is nonzero, the global debug flag |
611 | is set; if zero, the flag is cleared. |
612 | @end deffn |
613 | |
614 | @deffn {@code{ioctl} call} UNIOCDUMP |
615 | Dumps an attachment's information to the kernel log device. |
616 | @end deffn |
617 | |
618 | |
619 | @node Sending and receiving, , Configuring the interface, Programming |
620 | @section Sending and receiving |
621 | |
622 | A packet may be sent through a Usernet interface using the standard |
623 | @code{write}(2) system call. The buffer passed to @code{write} must be a |
624 | complete packet; no coalescing or buffering is performed by Usernet. It's |
625 | always possible to write to a Usernet device and writing always succeeds |
626 | without blocking. However, packets may be silently rejected by the network |
627 | stack. |
628 | |
629 | Packets received by a Usernet interface are available to programs via the |
630 | standard @code{read}(2) system call. If the destination buffer is too small |
631 | for a complete packet, the remainder of the packet is silently discarded. If |
632 | no packets are available for reading, the process is blocked (unless |
633 | nonblocking I/O was explicitly requested). |
634 | |
635 | Programs may call @code{select}(2) to wait for packets to arrive from an |
636 | attached Usernet device. |
637 | |
638 | |
639 | @c @node Hints, , Sending and receiving, Programming |
640 | @c @section Hints |
641 | |
642 | @c -------------------------------------------------------------------------- |
643 | @contents |
644 | @bye |