| 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 |