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