diff options
60 files changed, 1294 insertions, 792 deletions
diff --git a/share/man/man4/aac.4 b/share/man/man4/aac.4 index 6d486f3..bfe6965 100644 --- a/share/man/man4/aac.4 +++ b/share/man/man4/aac.4 @@ -98,7 +98,8 @@ The device enables the SCSI pass-thru interface and allows devices connected to the card such as cdroms to be available via the CAM .Xr scsi 4 -subsystem. Note that not all cards allow this interface to be enabled. +subsystem. +Note that not all cards allow this interface to be enabled. .Ss Tuning The read-only sysctl .Va hw.aac.iosize_max diff --git a/share/man/man4/aha.4 b/share/man/man4/aha.4 index 91e9a0b..a9ee4eb 100644 --- a/share/man/man4/aha.4 +++ b/share/man/man4/aha.4 @@ -43,20 +43,26 @@ In This driver provides access to the .Tn SCSI bus connected to an Adaptec 154xA, 154xB, 154xC, 154xCF, or 154xCP -host adapter. Host adapters supporting a 154X compatible interface, +host adapter. +Host adapters supporting a 154X compatible interface, such as some Tekram controllers and the Adaptec 174x in 154x -emulation mode can, also be attached with this driver. For optimum +emulation mode can, also be attached with this driver. +For optimum performance, Adaptec 174x controllers should be configured in enhanced mode and attached via the .Xr ahb 4 driver. .Pp One kernel config entry for every card to be attached by the system is -required. Specific values for the port address, irq, and drq may be -specified. If wildcard values are used, the driver will query the -device for its current settings and use those. If the port address +required. +Specific values for the port address, irq, and drq may be +specified. +If wildcard values are used, the driver will query the +device for its current settings and use those. +If the port address is a wildcard, the driver consults an internal table of possible port address -locations and attaches to the first unattached card it finds. The possible +locations and attaches to the first unattached card it finds. +The possible port addresses for this card are 0x330, 0x334, 0x230, 0x234, 0x130, and 0x134. .Sh SEE ALSO diff --git a/share/man/man4/ahb.4 b/share/man/man4/ahb.4 index f0fca3c..42d636a 100644 --- a/share/man/man4/ahb.4 +++ b/share/man/man4/ahb.4 @@ -45,9 +45,10 @@ mode. Tagged queueing and synchronous SCSI transfers are supported. .Sh CAVEATS The Adaptec 174X is very sensitive to SCSI bus termination and cable -length. It may also have difficulties operating with some modern devices -that, due to their speed, expose timing problems in the controller. There -are no known mechanisms for working around device incompatibilities of +length. +It may also have difficulties operating with some modern devices +that, due to their speed, expose timing problems in the controller. +There are no known mechanisms for working around device incompatibilities of this nature. .Sh SEE ALSO .Xr aha 4 , diff --git a/share/man/man4/ahc.4 b/share/man/man4/ahc.4 index 871bc74..ec30c5e 100644 --- a/share/man/man4/ahc.4 +++ b/share/man/man4/ahc.4 @@ -124,7 +124,8 @@ with this option enabled. Individual controllers may be configured to operate in the target role through the .Dq Dv AHC_TMODE_ENABLE -configuration option. The value assigned to this option should be a bitmap +configuration option. +The value assigned to this option should be a bitmap of all units where target mode is desired. For example, a value of 0x25, would enable target mode on units 0, 2, and 5. A value of 0x8a enables it for units 1, 3, and 7. @@ -165,7 +166,8 @@ but care should be taken when using a 284x .Pq Tn VESA No local bus controller in an .Tn EISA -system. The jumpers setting the I/O area for the 284x should match the +system. +The jumpers setting the I/O area for the 284x should match the .Tn EISA slot into which the card is inserted to prevent conflicts with other .Tn EISA @@ -175,7 +177,8 @@ Performance and feature sets vary throughout the aic7xxx product line. The following table provides a comparison of the different chips supported by the .Nm -driver. Note that wide and twin channel features, although always supported +driver. +Note that wide and twin channel features, although always supported by a particular chip, may be disabled in a particular motherboard or card design. .Pp @@ -224,9 +227,12 @@ target on multiple SCSI IDs. .Sh SCSI CONTROL BLOCKS (SCBs) Every transaction sent to a device on the SCSI bus is assigned a .Sq SCSI Control Block -(SCB). The SCB contains all of the information required by the -controller to process a transaction. The chip feature table lists -the number of SCBs that can be stored in on-chip memory. All chips +(SCB). +The SCB contains all of the information required by the +controller to process a transaction. +The chip feature table lists +the number of SCBs that can be stored in on-chip memory. +All chips with model numbers greater than or equal to 7870 allow for the on chip SCB space to be augmented with external SRAM up to a maximum of 255 SCBs. Very few Adaptec controller configurations have external SRAM. @@ -238,40 +244,47 @@ To fully utilize the SCSI bus and the devices on it, requires much more concurrency. The solution to this problem is .Em SCB Paging , -a concept similar to memory paging. SCB paging takes advantage of +a concept similar to memory paging. +SCB paging takes advantage of the fact that devices usually disconnect from the SCSI bus for long -periods of time without talking to the controller. The SCBs -for disconnected transactions are only of use to the controller -when the transfer is resumed. When the host queues another transaction +periods of time without talking to the controller. +The SCBs for disconnected transactions are only of use to the controller +when the transfer is resumed. +When the host queues another transaction for the controller to execute, the controller firmware will use a -free SCB if one is available. Otherwise, the state of the most recently +free SCB if one is available. +Otherwise, the state of the most recently disconnected (and therefore most likely to stay disconnected) SCB is saved, via dma, to host memory, and the local SCB reused to start -the new transaction. This allows the controller to queue up to -255 transactions regardless of the amount of SCB space. Since the +the new transaction. +This allows the controller to queue up to +255 transactions regardless of the amount of SCB space. +Since the local SCB space serves as a cache for disconnected transactions, the more SCB space available, the less host bus traffic consumed saving and restoring SCB data. .Sh BUGS Some Quantum drives (at least the Empire 2100 and 1080s) will not run on an .Tn AIC7870 -Rev B in synchronous mode at 10MHz. Controllers with this problem have a -42 MHz clock crystal on them and run slightly above 10MHz. This confuses -the drive and hangs the bus. Setting a maximum synchronous negotiation rate -of 8MHz in the +Rev B in synchronous mode at 10MHz. +Controllers with this problem have a +42 MHz clock crystal on them and run slightly above 10MHz. +This confuses the drive and hangs the bus. +Setting a maximum synchronous negotiation rate of 8MHz in the .Tn SCSI-Select utility will allow normal operation. .Pp Although the Ultra2 and Ultra160 products have sufficient instruction ram space to support both the initiator and target roles concurrently, this configuration is disabled in favor of allowing the target role -to respond on multiple target ids. A method for configuring dual -role mode should be provided. +to respond on multiple target ids. +A method for configuring dual role mode should be provided. .Pp Tagged Queuing is not supported in target mode. .Pp Reselection in target mode fails to function correctly on all high -voltage differential boards as shipped by Adaptec. Information on +voltage differential boards as shipped by Adaptec. +Information on how to modify HVD board to work correctly in target mode is available from Adaptec. .Sh SEE ALSO diff --git a/share/man/man4/atkbd.4 b/share/man/man4/atkbd.4 index 763a94a..487afd6 100644 --- a/share/man/man4/atkbd.4 +++ b/share/man/man4/atkbd.4 @@ -57,8 +57,8 @@ and .Pp There can be only one .Nm -device defined in the kernel configuration file. This device also -requires the +device defined in the kernel configuration file. +This device also requires the .Nm atkbdc keyboard controller to be present. The diff --git a/share/man/man4/awi.4 b/share/man/man4/awi.4 index 0f3c2c2..f227df2 100644 --- a/share/man/man4/awi.4 +++ b/share/man/man4/awi.4 @@ -28,7 +28,8 @@ BSS) mode. .Pp In infrastructure mode, it communicates with an Access Point which serves as a link-layer bridge between an Ethernet and -the wireless network. An access point also provides roaming capability +the wireless network. +An access point also provides roaming capability which allows wireless node to move between access points. .Pp In adhoc mode, it communicates peer to peer. @@ -40,7 +41,8 @@ In addition to these two mode in IEEE 802.11 specification, the driver also supports a variant of adhoc mode out of spec for DS radio cards, which makes possible to communicate with adhoc mode of .Xr wi 8 -driver. The NWID doesn't affect in this mode. +driver. +The NWID doesn't affect in this mode. .Pp For more information on configuring this device, see .Xr ifconfig 8 @@ -78,7 +80,8 @@ and .Em DS2 media types, while the FH cards support .Em FH1 -media type. For each media type, +media type. +For each media type, .Em adhoc mediaopt can be used to indicate the driver to operate in adhoc mode. For DS radio cards, @@ -92,7 +95,8 @@ compatible adhoc mode. Indicates that the driver was not able to allocate 32kb of PCMCIA bus address space into which to map the device; the driver will use the (slightly slower) i/o-space only access methods to read and write to -the shared memory. Since by default, +the shared memory. +Since by default, .Nx , only allocates 16kb of address space per PCMCIA controller, this message is in some sense to diff --git a/share/man/man4/bktr.4 b/share/man/man4/bktr.4 index bbb7f28..7ef6dcb 100644 --- a/share/man/man4/bktr.4 +++ b/share/man/man4/bktr.4 @@ -20,8 +20,9 @@ driver provides support for PCI .Em video capture and .Em VBI -capture on low cost, high performance boards. The driver is based on -the Matrox Meteor driver and uses the same API. The bktr driver should support most video cards +capture on low cost, high performance boards. +The driver is based on the Matrox Meteor driver and uses the same API. +The bktr driver should support most video cards based on the .Em "Brooktree Bt848/849/878/879 Video Capture Chip" . The driver also supports @@ -62,7 +63,8 @@ The following kernel parameters may be used to further configure the driver: .Pp .Em options "BROOKTREE_ALLOC_PAGES=xxx" specifies the number of contiguous pages to allocate when successfully -probed. The default number of pages allocated by the kernel is 216. +probed. +The default number of pages allocated by the kernel is 216. This means that there are (216*4096) bytes available for use. .Bd -unfilled .Em options BROOKTREE_SYSTEM_DEFAULT=BROOKTREE_PAL diff --git a/share/man/man4/blackhole.4 b/share/man/man4/blackhole.4 index 1c9029e..1f0e3db 100644 --- a/share/man/man4/blackhole.4 +++ b/share/man/man4/blackhole.4 @@ -33,18 +33,22 @@ are received on TCP or UDP ports where there is no socket listening. .Pp Normal behaviour, when a TCP SYN segment is received on a port where there is no socket accepting connections, is for the system to return -a RST segment, and drop the connection. The connecting system will -see this as a "Connection refused". By setting the TCP blackhole +a RST segment, and drop the connection. +The connecting system will +see this as a +.Dq Connection refused . +By setting the TCP blackhole MIB to a numeric value of one, the incoming SYN segment is merely dropped, and no RST is sent, making the system appear -as a blackhole. By setting the MIB value to two, any segment arriving -on a closed port is dropped without returning a RST. This provides -some degree of protection against stealth port scans. +as a blackhole. +By setting the MIB value to two, any segment arriving +on a closed port is dropped without returning a RST. +This provides some degree of protection against stealth port scans. .Pp In the UDP instance, enabling blackhole behaviour turns off the sending of an ICMP port unreachable message in response to a UDP datagram which -arrives on a port where there is no socket listening. It must be noted -that this behaviour will prevent remote systems from running +arrives on a port where there is no socket listening. +It must be noted that this behaviour will prevent remote systems from running .Xr traceroute 8 to a system. .Pp @@ -56,8 +60,8 @@ of service attack. The TCP and UDP blackhole features should not be regarded as a replacement for .Xr ipfw 8 -as a tool for firewalling a system. In order to create a highly -secure system, +as a tool for firewalling a system. +In order to create a highly secure system, .Xr ipfw 8 should be used for protection, not the blackhole feature. .Pp diff --git a/share/man/man4/bpf.4 b/share/man/man4/bpf.4 index 80e84d5..0dfc8c3 100644 --- a/share/man/man4/bpf.4 +++ b/share/man/man4/bpf.4 @@ -75,7 +75,8 @@ Note that an individual packet larger than this size is necessarily truncated. .Pp The packet filter will support any link level protocol that has fixed length -headers. Currently, only Ethernet, +headers. +Currently, only Ethernet, .Tn SLIP , and .Tn PPP @@ -88,8 +89,8 @@ macros to extract multi-byte values. .Pp A packet can be sent out on the network by writing to a .Nm -file descriptor. The writes are unbuffered, meaning only one -packet can be processed per write. +file descriptor. +The writes are unbuffered, meaning only one packet can be processed per write. Currently, only writes to Ethernets and .Tn SLIP links are supported. @@ -136,7 +137,8 @@ files. .Pq Li u_int Sets the buffer length for reads on .Nm -files. The buffer must be set before the file is attached to an interface +files. +The buffer must be set before the file is attached to an interface with .Dv BIOCSETIF . If the requested buffer size cannot be accommodated, the closest @@ -158,8 +160,8 @@ Forces the interface into promiscuous mode. All packets, not just those destined for the local host, are processed. Since more than one file can be listening on a given interface, a listener that opened its interface non-promiscuously may receive -packets promiscuously. This problem can be remedied with an -appropriate filter. +packets promiscuously. +This problem can be remedied with an appropriate filter. .It Dv BIOCFLUSH Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. @@ -219,7 +221,8 @@ Enable or disable .Dq immediate mode , based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet -reception. Otherwise, a read will block until either the kernel buffer +reception. +Otherwise, a read will block until either the kernel buffer becomes full or a timeout occurs. This is useful for programs like .Xr rarpd 8 @@ -228,7 +231,8 @@ The default for a new file is off. .It Dv BIOCSETF .Pq Li "struct bpf_program" Sets the filter program used by the kernel to discard uninteresting -packets. An array of instructions and its length is passed in using +packets. +An array of instructions and its length is passed in using the following structure: .Bd -literal struct bpf_program { @@ -253,11 +257,12 @@ for an explanation of the filter language. .It Dv BIOCVERSION .Pq Li "struct bpf_version" Returns the major and minor version numbers of the filter language currently -recognized by the kernel. Before installing a filter, applications must check -that the current version is compatible with the running kernel. Version -numbers are compatible if the major numbers match and the application minor -is less than or equal to the kernel minor. The kernel version number is -returned in the following structure: +recognized by the kernel. +Before installing a filter, applications must check +that the current version is compatible with the running kernel. +Version numbers are compatible if the major numbers match and the application minor +is less than or equal to the kernel minor. +The kernel version number is returned in the following structure: .Bd -literal struct bpf_version { u_short bv_major; @@ -282,16 +287,18 @@ Set or get the status of the .Dq header complete flag. Set to zero if the link level source address should be filled in automatically -by the interface output routine. Set to one if the link level source -address will be written, as provided, to the wire. This flag is initialized -to zero by default. +by the interface output routine. +Set to one if the link level source +address will be written, as provided, to the wire. +This flag is initialized to zero by default. .It Dv BIOCSSEESENT .It Dv BIOCGSEESENT .Pq Li u_int Set or get the flag determining whether locally generated packets on the -interface should be returned by BPF. Set to zero to see only incoming -packets on the interface. Set to one to see packets originating -locally and remotely on the interface. This flag is initialized to one by +interface should be returned by BPF. +Set to zero to see only incoming packets on the interface. +Set to one to see packets originating locally and remotely on the interface. +This flag is initialized to one by default. .El .Sh BPF HEADER @@ -313,7 +320,8 @@ The fields, whose values are stored in host order, and are: .It Li bh_tstamp The time at which the packet was processed by the packet filter. .It Li bh_caplen -The length of the captured portion of the packet. This is the minimum of +The length of the captured portion of the packet. +This is the minimum of the truncation amount specified by the filter and the length of the packet. .It Li bh_datalen The length of the packet off the wire. @@ -336,22 +344,25 @@ architectures and improves performance on many other architectures. The packet filter insures that the .Li bpf_hdr and the network layer -header will be word aligned. Suitable precautions +header will be word aligned. +Suitable precautions must be taken when accessing the link layer protocol fields on alignment -restricted machines. (This isn't a problem on an Ethernet, since +restricted machines. +(This isn't a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). .Pp Additionally, individual packets are padded so that each starts -on a word boundary. This requires that an application +on a word boundary. +This requires that an application has some knowledge of how to get from packet to packet. The macro .Dv BPF_WORDALIGN is defined in .Aq Pa net/bpf.h to facilitate -this process. It rounds up its argument -to the nearest word aligned value (where a word is +this process. +It rounds up its argument to the nearest word aligned value (where a word is .Dv BPF_ALIGNMENT bytes wide). .Pp @@ -424,7 +435,8 @@ in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only -addressed in word units. The memory store is indexed from 0 to +addressed in word units. +The memory store is indexed from 0 to .Dv BPF_MEMWORDS - 1. .Li k , @@ -438,8 +450,8 @@ refers to the length of the packet. .Pp .Bl -tag -width BPF_STXx .It Dv BPF_LD -These instructions copy a value into the accumulator. The type of the -source operand is specified by an +These instructions copy a value into the accumulator. +The type of the source operand is specified by an .Dq addressing mode and can be a constant .Pq Dv BPF_IMM , @@ -486,7 +498,8 @@ A <- k A <- M[k] .El .It Dv BPF_LDX -These instructions load a value into the index register. Note that +These instructions load a value into the index register. +Note that the addressing modes are more restrictive than those of the accumulator loads, but they include .Dv BPF_MSH , @@ -563,7 +576,8 @@ A <- A >> X A <- -A .El .It Dv BPF_JMP -The jump instructions alter flow of control. Conditional jumps +The jump instructions alter flow of control. +Conditional jumps compare the accumulator against a constant .Pq Dv BPF_K or the index register @@ -600,8 +614,8 @@ pc += (A & X) ? jt : jf .El .It Dv BPF_RET The return instructions terminate the filter program and specify the amount -of packet to accept (i.e., they return the truncation amount). A return -value of zero indicates that the packet should be ignored. +of packet to accept (i.e., they return the truncation amount). +A return value of zero indicates that the packet should be ignored. The return value is either a constant .Pq Dv BPF_K or the accumulator @@ -616,7 +630,8 @@ accept k bytes .It Dv BPF_MISC The miscellaneous category was created for anything that doesn't fit into the above classes, and for any new instructions that might need to -be added. Currently, these are the register transfer instructions +be added. +Currently, these are the register transfer instructions that copy the index register to the accumulator or vice versa. .Pp .Bl -tag -width "BPF_MISC+BPF_TAX" -compact @@ -635,8 +650,8 @@ array initializers: and .Fn BPF_JUMP opcode operand true_offset false_offset . .Sh EXAMPLES -The following filter is taken from the Reverse ARP Daemon. It accepts -only Reverse ARP requests. +The following filter is taken from the Reverse ARP Daemon. +It accepts only Reverse ARP requests. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), @@ -667,8 +682,9 @@ struct bpf_insn insns[] = { }; .Ed .Pp -Finally, this filter returns only TCP finger packets. We must parse -the IP header to reach the TCP header. The +Finally, this filter returns only TCP finger packets. +We must parse the IP header to reach the TCP header. +The .Dv BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure @@ -712,8 +728,9 @@ ioctl). .Pp A file that does not request promiscuous mode may receive promiscuously received packets as a side effect of another file requesting this -mode on the same hardware interface. This could be fixed in the kernel -with additional processing overhead. However, we favor the model where +mode on the same hardware interface. +This could be fixed in the kernel with additional processing overhead. +However, we favor the model where all files must assume that the interface is promiscuous, and if so desired, must utilize a filter to reject foreign packets. .Pp @@ -723,16 +740,18 @@ The .Dv SEESENT flag has been observed to work incorrectly on some interface types, including those with hardware loopback rather than software loopback, -and point-to-point interfaces. It appears to function correctly on a +and point-to-point interfaces. +It appears to function correctly on a broad range of ethernet-style interfaces. .Sh HISTORY The Enet packet filter was created in 1980 by Mike Accetta and -Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at +Rick Rashid at Carnegie-Mellon University. +Jeffrey Mogul, at Stanford, ported the code to .Bx and continued its development from -1983 on. Since then, it has evolved into the Ultrix Packet Filter -at +1983 on. +Since then, it has evolved into the Ultrix Packet Filter at .Tn DEC , a .Tn STREAMS diff --git a/share/man/man4/bt.4 b/share/man/man4/bt.4 index d67cd66..7c5d27b 100644 --- a/share/man/man4/bt.4 +++ b/share/man/man4/bt.4 @@ -99,7 +99,8 @@ with firmware of rev 4.42 and higher, and 'S' series adapters with firmware of rev 3.35 and higher. .Pp Boards with certain firmware revisions may lock up under heavy load to -certain devices, especially if tagged queueing is used. Should you encounter +certain devices, especially if tagged queueing is used. +Should you encounter a problem with your adapter, contact Mylex technical support and ensure you have the latest firmware for your controller. .Sh SEE ALSO @@ -112,7 +113,8 @@ have the latest firmware for your controller. .An Julian Elischer wrote a driver for the Multimaster cards that appeared in the .Bx 386 -patch kit. The driver was rewritten by +patch kit. +The driver was rewritten by .An Justin T. Gibbs to take advantage of new board features and work with the CAM SCSI framework in .Fx 3.0 . @@ -120,7 +122,8 @@ to take advantage of new board features and work with the CAM SCSI framework in Special thanks to .An Leonard N. Zubkoff for writing such a complete and well documented Mylex/BusLogic MultiMaster -driver for Linux. Support in this driver for the wide range of MultiMaster +driver for Linux. +Support in this driver for the wide range of MultiMaster controllers and firmware revisions, with their otherwise undocumented quirks, would not have been possible without his efforts. .Sh FILES diff --git a/share/man/man4/cd.4 b/share/man/man4/cd.4 index 9950f937..579fcea 100644 --- a/share/man/man4/cd.4 +++ b/share/man/man4/cd.4 @@ -313,7 +313,8 @@ Tell the drive to spin-up (-down) the .It Dv CDIOCPREVENT Tell the drive to allow (prevent) manual ejection of the .Tn CD-ROM -disc. Not all drives support this feature. +disc. +Not all drives support this feature. .It Dv CDIOCEJECT Eject the .Tn CD-ROM . @@ -360,7 +361,7 @@ The audio code in the driver only support .Tn SCSI-2 standard audio commands. -Because many +As many .Tn CD-ROM manufacturers have not followed the standard, there are many .Tn CD-ROM @@ -377,7 +378,8 @@ player mechanism. Each CD in the drive shows up as a separate logical unit on the .Tn SCSI -bus. The +bus. +The .Nm driver automatically recognizes LUN-based changers, and routes commands for changers through an internal scheduler. diff --git a/share/man/man4/ch.4 b/share/man/man4/ch.4 index de67026..9bad5b2 100644 --- a/share/man/man4/ch.4 +++ b/share/man/man4/ch.4 @@ -40,7 +40,8 @@ driver provides support for a .Em SCSI media changer. It allows many slots of media to be multiplexed between -a number of drives. The changer device may optionally be equipped +a number of drives. +The changer device may optionally be equipped with a bar code reader, which reads label information attached to the media. .Pp @@ -75,10 +76,11 @@ so a large number of configured devices is cheap. has included the driver). .Sh IOCTLS User mode programs communicate with the changer driver through a -number of ioctls which are described below. Changer element addresses +number of ioctls which are described below. +Changer element addresses used in the communication between the kernel and the changer device are -mapped to zero-based logical addresses. Element types are specified -as follows: +mapped to zero-based logical addresses. +Element types are specified as follows: .Bl -tag -width CHET_MT .It Dv CHET_MT Medium transport element (picker). @@ -99,9 +101,11 @@ in the header file .Pp .Bl -tag -width CHIOEXCHANGE .It Dv CHIOMOVE -.Pq Li "struct changer_move" -Move a medium from one element to another (\fBMOVE MEDIUM\fR) using -the current picker. The source and destination elements are specified +.Pq Vt "struct changer_move" +Move a medium from one element to another +.Pq Sy "MOVE MEDIUM" +using the current picker. +The source and destination elements are specified in a changer_move structure, which includes at least the following fields: .Bd -literal -offset indent @@ -111,17 +115,24 @@ u_int cm_totype; /* element type to move to */ u_int cm_tounit; /* logical unit of to element */ u_int cm_flags; /* misc. flags */ .Ed -If the \fBCM_INVERT\fR in the \fBcm_flags\fR field is set, the medium +If the +.Dv CM_INVERT +in the +.Va cm_flags +field is set, the medium changer is instructed to flip the medium while moving it. .It Dv CHIOEXCHANGE -.Pq Li "struct changer_exchange" +.Pq Vt "struct changer_exchange" Move the medium located in the source element to the first destination element, and move the medium that had been in the first destination -element to the second destination element. In case of a simple +element to the second destination element. +In case of a simple exchange, the source and second destination elements should be the -same. The current picker is used to perform the operation. The -addresses of the affected elements is specified to the ioctl in a -changer_exchange structure which includes at least the following +same. +The current picker is used to perform the operation. +The addresses of the affected elements is specified to the ioctl in a +.Vt changer_exchange +structure which includes at least the following fields: .Bd -literal -offset indent u_int ce_srctype; /* element type of source */ @@ -132,32 +143,41 @@ u_int ce_sdsttype; /* element type of second destination */ u_int ce_sdstunit; /* logical unit of second destination */ u_int ce_flags; /* misc. flags */ .Ed -In \fBce_flags\fR, \fBCM_INVERT1\fR and/or \fBCM_INVERT2\fR may be set +In +.Va ce_flags , +.Dv CM_INVERT1 +and/or +.Dv CM_INVERT2 +may be set to flip the first or second medium during the exchange operation, respectively. .Pp -\fIThis operation is untested.\fR +.Em This operation is untested . .It Dv CHIOPOSITION -.Pq Li "struct changer_position" -Position the current picker in front of the specified element. The -element is specified with a changer_position structure, which includes +.Pq Vt "struct changer_position" +Position the current picker in front of the specified element. +The element is specified with a changer_position structure, which includes at least the following elements: .Bd -literal -offset indent u_int cp_type; /* element type */ u_int cp_unit; /* logical unit of element */ u_int cp_flags; /* misc. flags */ .Ed -The \fBcp_flags\fR field may be set to \fBCP_INVERT\fR to invert the -picker during the operation. +The +.Va cp_flags +field may be set to +.Dv CP_INVERT +to invert the picker during the operation. .It Dv CHIOGPICKER -.Pq Li "int" +.Pq Vt int Return the logical address of the current picker. .It Dv CHIOSPICKER -.Pq Li "int" +.Pq Vt int Select the picker specified by the given logical address. .It Dv CHIOGPARAMS -.Pq Li "struct changer_params" -Return the configuration parameters for the media changer. This ioctl +.Pq Vt "struct changer_params" +Return the configuration parameters for the media changer. +This ioctl fills the changer_params structure passed by the user with at least the following fields: .Bd -literal -offset indent @@ -168,27 +188,36 @@ u_int cp_ndrives; /* number of drives */ .Ed .Pp This call can be used by applications to query the dimensions of -the jukebox before using the \fBCHIGSTATUS\fR +the jukebox before using the +.Dv CHIGSTATUS ioctl to query the jukebox' status. .It Dv CHIOIELEM -Perform the \fBINITIALIZE ELEMENT STATUS\fR call on the media changer -device. This forces the media changer to update its internal status -information with respect to loaded media. It also scans any barcode -labels provided that it has a label reader. The +Perform the +.Sy INITIALIZE ELEMENT STATUS +call on the media changer device. +This forces the media changer to update its internal status +information with respect to loaded media. +It also scans any barcode labels provided that it has a label reader. +The .Nm driver's status is not affected by this call. .It Dv CHIOGSTATUS -.Pq Li "struct changer_element_status_request" -Perform the \fBREAD ELEMENT STATUS\fR call on the media changer -device. This call reads the element status information of the media -changer and converts it to an array of \fBchanger_element_status\fR +.Pq Vt "struct changer_element_status_request" +Perform the +.Sy READ ELEMENT STATUS +call on the media changer device. +This call reads the element status information of the media +changer and converts it to an array of +.Vt changer_element_status structures. .Pp With each call to .Dv CHIOGSTATUS , the status of one or more elements of one type may be queried. .Pp -The application passes a changer_element_status_request structure to the +The application passes a +.Vt changer_element_status_request +structure to the .Nm driver which contains the following fields: .Bd -literal -offset indent @@ -201,25 +230,36 @@ struct changer_element_status *cesr_element_status; .Pp This structure is read by the driver to determine the type, logical base address and number of elements for which information is to be -returned in the array of changer_element_status structures pointed to -by the cesr_element_status field. The application must allocate enough -memory for cesr_element_count status structures (see below). -The cesr_flags can optionally be set to +returned in the array of +.Vt changer_element_status +structures pointed to by the +.Va cesr_element_status field . +The application must allocate enough +memory for +.Va cesr_element_count +status structures (see below). +The +.Va cesr_flags +can optionally be set to .Dv CESR_VOLTAGS to indicate that volume tag (bar code) information is to be read from the jukebox and returned. .Pp -The cesr_element_base and cesr_element_count fields must be valid with -respect to the physical configuration of the changer. If they are -not, the +The +.Va cesr_element_base +and +.Va cesr_element_count +fields must be valid with respect to the physical configuration of the changer. +If they are not, the .Dv CHIOGSTATUS ioctl returns the .Er EINVAL error code. .Pp The information about the elements is returned in an array of -changer_element_status structures. This structure include at least -the following fields: +.Vt changer_element_status +structures. +This structure include at least the following fields: .Bd -literal -offset indent u_int ces_addr; /* element address in media changer */ u_char ces_flags; /* see CESTATUS definitions below */ @@ -236,11 +276,16 @@ u_char ces_lunvalid; /* ces_scsi_lun is valid */ u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */ .Ed .Pp -The ces_addr field contains the address of the element in the -coordinate system of the media changer. It is not used by the driver, +The +.Va ces_addr +field contains the address of the element in the +coordinate system of the media changer. +It is not used by the driver, and should be used for diagnostic purposes only. .Pp -The following flags are defined for the \fBces_flags\fR field: +The following flags are defined for the +.Va ces_flags +field: .Bl -tag -width CESTATUS_IMPEXP .It Dv CESTATUS_FULL A medium is present. diff --git a/share/man/man4/da.4 b/share/man/man4/da.4 index d337ee1..835f4fd 100644 --- a/share/man/man4/da.4 +++ b/share/man/man4/da.4 @@ -77,7 +77,8 @@ respectively. If an uninitialized disk is opened, the slice table will be initialized with a fictitious .Fx -slice spanning the entire disk. Similarly, if an uninitialized +slice spanning the entire disk. +Similarly, if an uninitialized (or .No non- Ns Fx ) slice is opened, its disklabel will be initialized with parameters returned @@ -87,51 +88,61 @@ partition encompassing the entire slice. .Sh CACHE EFFECTS Many direct access devices are equipped with read and/or write caches. Parameters affecting the device's cache are stored in mode page 8, -the caching control page. Mode pages can be examined and modified -via the +the caching control page. +Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Pp The read cache is used to store data from device-initiated read ahead -operations as well as frequently used data. The read cache is transparent +operations as well as frequently used data. +The read cache is transparent to the user and can be enabled without any adverse effect. Most devices -with a read cache come from the factory with it enabled. The read cache -can be disabled by setting the +with a read cache come from the factory with it enabled. +The read cache can be disabled by setting the .Tn RCD (Read Cache Disable) bit in the caching control mode page. .Pp The write cache can greatly decrease the latency of write operations and allows the device to reorganize writes to increase efficiency and -performance. This performance gain comes at a price. Should the device +performance. +This performance gain comes at a price. +Should the device lose power while its cache contains uncommitted write operations, these -writes will be lost. The effect of a loss of write transactions on -a file system is non-deterministic and can cause corruption. Most +writes will be lost. +The effect of a loss of write transactions on +a file system is non-deterministic and can cause corruption. +Most devices age write transactions to limit vulnerability to a few transactions recently reported as complete, but it is none-the-less recommended that systems with write cache enabled devices reside on an Uninterruptible -Power Supply (UPS). The +Power Supply (UPS). +The .Nm device driver ensures that the cache and media are synchronized upon -final close of the device or an unexpected shutdown (panic) event. This -ensures that it is safe to disconnect power once the operating system -has reported that it has halted. The write cache can be enabled by -setting the +final close of the device or an unexpected shutdown (panic) event. +This ensures that it is safe to disconnect power once the operating system +has reported that it has halted. +The write cache can be enabled by setting the .Tn WCE (Write Cache Enable) bit in the caching control mode page. .Sh TAGGED QUEUING The .Nm device driver will take full advantage of the SCSI feature known as tagged -queueing. Tagged queueing allows the device to process multiple transactions +queueing. +Tagged queueing allows the device to process multiple transactions concurrently, often re-ordering them to reduce the number and length of -seeks. To ensure that transactions to distant portions of the media, +seeks. +To ensure that transactions to distant portions of the media, which may be deferred indefinitely by servicing requests nearer the current head position, are completed in a timely fashion, an ordered tagged transaction is sent every 15 seconds during continuous device operation. .Sh BAD BLOCK RECOVERY Direct Access devices have the capability of mapping out portions of -defective media. Media recovery parameters are located in mode page 1, -the Read-Write Error Recovery mode page. The most important media +defective media. +Media recovery parameters are located in mode page 1, +the Read-Write Error Recovery mode page. +The most important media remapping features are 'Auto Write Reallocation' and 'Auto Read Reallocation' which can be enabled via the AWRE and ARRE bits, respectively, of the Read-Write Error Recovery page. @@ -152,7 +163,8 @@ The following .Xr ioctl 2 calls apply to .Tn SCSI -disks as well as to other disks. They are defined in the header file +disks as well as to other disks. +They are defined in the header file .Aq Pa sys/disklabel.h . .Pp .Bl -tag -width DIOCSDINFO @@ -187,10 +199,11 @@ write the new disklabel to the disk. .Sh NOTES If a device becomes invalidated (media is removed, device becomes unresponsive) the disklabel and information held within the kernel about the device will -be invalidated. To avoid corruption of a newly inserted piece of media or +be invalidated. +To avoid corruption of a newly inserted piece of media or a replacement device, all accesses to the device will be discarded until -the last file descriptor referencing the old device is closed. During this -period, all new open attempts will be rejected. +the last file descriptor referencing the old device is closed. +During this period, all new open attempts will be rejected. .Sh FILES .Bl -tag -width /dev/rsdXXXXX -compact .It Pa /dev/rda Ns Ar u diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index 7d47f91..f84982f 100644 --- a/share/man/man4/ddb.4 +++ b/share/man/man4/ddb.4 @@ -93,7 +93,8 @@ unless the .Dv DDB_UNATTENDED option is specified. .Pp -The current location is called `dot'. The `dot' is displayed with +The current location is called `dot'. +The `dot' is displayed with a hexadecimal format at a prompt. Examine and write commands update `dot' to the address of the last line examined or the last location modified, and set `next' to the address of @@ -105,12 +106,15 @@ The general command syntax is: .Ar address Ns Op Li , Ns Ar count .Pp A blank line repeats the previous command from the address `next' with -count 1 and no modifiers. Specifying +count 1 and no modifiers. +Specifying .Ar address sets `dot' to the -address. Omitting +address. +Omitting .Ar address -uses `dot'. A missing +uses `dot'. +A missing .Ar count is taken to be 1 for printing commands or infinity for stack traces. @@ -120,7 +124,8 @@ The debugger has a feature like the .Xr more 1 command -for the output. If an output line exceeds the number set in the +for the output. +If an output line exceeds the number set in the .Li \&$lines variable, it displays .Dq Em --db_more-- @@ -139,7 +144,8 @@ abort the current command, and return to the command input mode Finally, .Nm provides a small (currently 10 items) command history, and offers -simple emacs-style command line editing capabilities. In addition to +simple emacs-style command line editing capabilities. +In addition to the emacs control keys, the usual ANSI arrow keys might be used to browse through the history buffer, and move the cursor within the current line. @@ -225,7 +231,8 @@ and .Li c . If no modifier is specified, the last one specified to it is used. .Ar addr -can be a string, in which case it is printed as it is. For example: +can be a string, in which case it is printed as it is. +For example: .Bd -literal -offset indent print/x \&"eax = \&" $eax \&"\enecx = \&" $ecx \&"\en\&" .Ed @@ -249,7 +256,8 @@ The write unit size can be specified in the modifier with a letter .Li h (half word) or .Li l -(long word) respectively. If omitted, +(long word) respectively. +If omitted, long word is assumed. .Pp .Sy Warning : @@ -273,7 +281,8 @@ If is supplied, continues .Ar count - 1 times before stopping at the -break point. If the break point is set, a break point number is +break point. +If the break point is set, a break point number is printed with .Sq Li \&# . This number can be used in deleting the break point @@ -282,7 +291,8 @@ or adding conditions to it. If the .Li u modifier is specified, this command sets a break point in user space -address. Without the +address. +Without the .Li u option, the address is considered in the kernel space, and wrong space address is rejected with an error message. @@ -291,7 +301,8 @@ routines. .Pp .Sy Warning : If a user text is shadowed by a normal user space debugger, -user space break points may not work correctly. Setting a break +user space break points may not work correctly. +Setting a break point at the low-level code paths may also cause strange behavior. .It Cm delete Ar addr .It Cm delete Li \&# Ns Ar number @@ -334,7 +345,8 @@ Stop at the next call or return instruction. If the .Li p modifier is specified, print the call nesting depth and the -cumulative instruction count at each call or return. Otherwise, +cumulative instruction count at each call or return. +Otherwise, only print when the matching return is hit. .It Cm next Ns Op Cm /p .It Cm match Ns Op Cm /p @@ -342,14 +354,15 @@ Stop at the matching return instruction. If the .Li p modifier is specified, print the call nesting depth and the -cumulative instruction count at each call or return. Otherwise, -only print when the matching return is hit. +cumulative instruction count at each call or return. +Otherwise, only print when the matching return is hit. .It Xo .Cm trace Ns Op Cm /u .Op Ar frame .Op , Ns Ar count .Xc -Stack trace. The +Stack trace. +The .Li u option traces user space; if omitted, .Cm trace @@ -374,8 +387,9 @@ only if the machine dependent code supports it. Search memory for .Ar value . This command might fail in interesting -ways if it doesn't find the searched-for value. This is because -ddb doesn't always recover from touching bad memory. The optional +ways if it doesn't find the searched-for value. +This is because ddb doesn't always recover from touching bad memory. +The optional .Ar count argument limits the search. .It Cm show all procs Ns Op Cm /m @@ -398,8 +412,8 @@ kernel or currently saved one. .Sy Warning : The support of the .Li u -modifier depends on the machine. If -not supported, incorrect information will be displayed. +modifier depends on the machine. +If not supported, incorrect information will be displayed. .It Xo .Cm show map Ns Op Cm /f .Ar addr @@ -428,8 +442,8 @@ Hard reset the system. .Cm watch .Ar addr Ns Li \&, Ns Ar size .Xc -Set a watchpoint for a region. Execution stops -when an attempt to modify the region occurs. +Set a watchpoint for a region. +Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. @@ -445,14 +459,16 @@ Watchpoints on user addresses work best. .Ar addr Ns Li \&, Ns Ar size .Xc Set a hardware watchpoint for a region if supported by the -architecture. Execution stops when an attempt to modify the region -occurs. The +architecture. +Execution stops when an attempt to modify the region occurs. +The .Ar size argument defaults to 4. .Pp .Sy Warning : The hardware debug facilities do not have a concept of separate -address spaces like the watch command does. Use +address spaces like the watch command does. +Use .Cm hwatch for setting watchpoints on kernel address locations only, and avoid its use on user mode address spaces. @@ -462,11 +478,12 @@ its use on user mode address spaces. .Xc Delete specified hardware watchpoint. .It Cm gdb -Toggles between remote GDB and DDB mode. In remote GDB mode, another -machine is required that runs +Toggles between remote GDB and DDB mode. +In remote GDB mode, another machine is required that runs .Xr gdb 1 using the remote debug feature, with a connection to the serial -console port on the target machine. Currently only available on the +console port on the target machine. +Currently only available on the .Em i386 and .Em Alpha diff --git a/share/man/man4/divert.4 b/share/man/man4/divert.4 index 6fa7a3b..0087ace 100644 --- a/share/man/man4/divert.4 +++ b/share/man/man4/divert.4 @@ -67,7 +67,8 @@ is used to deliver the packet, or if is used with a destination IP address of .Dv INADDR_ANY , then the packet is treated as if it were outgoing, i.e., destined -for a non-local address. Otherwise, the packet is assumed to be +for a non-local address. +Otherwise, the packet is assumed to be incoming and full packet routing is done. .Pp In the latter case, the @@ -78,10 +79,12 @@ If an interface name is found, that interface will be used and the value of the IP address will be ignored (other than the fact that it is not .Dv INADDR_ANY ) . -This is to indicate on which interface the packet ``arrived.'' +This is to indicate on which interface the packet +.Dq arrived . .Pp Normally, packets read as incoming should be written as incoming; -similarly for outgoing packets. When reading and then writing back +similarly for outgoing packets. +When reading and then writing back packets, passing the same socket address supplied by .Xr recvfrom 2 unmodified to diff --git a/share/man/man4/fpa.4 b/share/man/man4/fpa.4 index 72cf91d..dc1acfe 100644 --- a/share/man/man4/fpa.4 +++ b/share/man/man4/fpa.4 @@ -24,7 +24,8 @@ The and .Nm fea device driver provides support for the DEC DEFPA PCI FDDI Controller and -the DEC DEFEA EISA FDDI Controller, respectively. All variants of either +the DEC DEFEA EISA FDDI Controller, respectively. +All variants of either controller are supported including the DAS and SAS configurations. .Sh DIAGNOSTICS .Bl -diag @@ -33,8 +34,10 @@ The device probe detected that the DEFEA board is configured for a different interrupt than the one specified in the kernel configuration file. .It "fea%d: error: memory not enabled! ECU reconfiguration required" The device probe found that no device memory had been configured on the -DEFEA. Also the DEFEA can be configured with no device memory, this driver -requires a minimum of 1K device memory be setup. The ECU (EISA Configuration +DEFEA. +Also the DEFEA can be configured with no device memory, this driver +requires a minimum of 1K device memory be setup. +The ECU (EISA Configuration Utility) will need to be run to change the settings. .El .Sh CAVEATS diff --git a/share/man/man4/icmp.4 b/share/man/man4/icmp.4 index d5a5b13..dc9c3de 100644 --- a/share/man/man4/icmp.4 +++ b/share/man/man4/icmp.4 @@ -49,7 +49,8 @@ is the error and control message protocol used by .Tn IP -and the Internet protocol family. It may be accessed +and the Internet protocol family. +It may be accessed through a .Dq raw socket for network monitoring diff --git a/share/man/man4/ifmib.4 b/share/man/man4/ifmib.4 index fe5bdbf..f4a106c 100644 --- a/share/man/man4/ifmib.4 +++ b/share/man/man4/ifmib.4 @@ -51,14 +51,16 @@ to client applications such as .Xr slstat 8 , and .Tn SNMP -management agents. This information is structured as a table, where +management agents. +This information is structured as a table, where each row in the table represents a logical network interface (either a hardware device or a software pseudo-device like .Xr lo 4 ) . There are two columns in the table, each containing a single structure: one column contains generic information relevant to all interfaces, and the other contains information specific to the -particular class of interface. (Generally the latter will implement +particular class of interface. +(Generally the latter will implement the .Tn SNMP .Tn MIB @@ -71,7 +73,8 @@ facility is accessed via the .Dq Li net.link.generic branch of the .Xr sysctl 3 -MIB. The manifest constants for each level in the +MIB. +The manifest constants for each level in the .Xr sysctl 3 .Ar name are defined in @@ -147,8 +150,10 @@ more information from a structure defined in .Pp Class-specific information can be retrieved by examining the .Dv IFDATA_LINKSPECIFIC -column instead. Note that the form and length of the structure will -depend on the class of interface. For +column instead. +Note that the form and length of the structure will +depend on the class of interface. +For .Dv IFT_ETHER , .Dv IFT_ISO88023 , and diff --git a/share/man/man4/inet.4 b/share/man/man4/inet.4 index d15c204..3296a39 100644 --- a/share/man/man4/inet.4 +++ b/share/man/man4/inet.4 @@ -61,7 +61,8 @@ Internet addresses are four byte quantities, stored in network standard format (on the .Tn VAX these are word and byte -reversed). The include file +reversed). +The include file .Aq Pa netinet/in.h defines this address as a discriminated union. @@ -116,7 +117,8 @@ abstraction while .Tn UDP is used to support the .Dv SOCK_DGRAM -abstraction. A raw interface to +abstraction. +A raw interface to .Tn IP is available by creating an Internet socket of type @@ -126,7 +128,8 @@ The message protocol is accessible from a raw socket. .Pp The 32-bit Internet address contains both network and host parts. -However, direct examination of addresses is discouraged. For those +However, direct examination of addresses is discouraged. +For those programs which absolutely need to break addresses into their component parts, the following .Xr ioctl 2 @@ -148,7 +151,8 @@ Get interface network mask. .Sh ROUTING The current implementation of Internet protocols includes some routing-table adaptations to provide enhanced caching of certain end-to-end -information necessary for Transaction TCP and Path MTU Discovery. The +information necessary for Transaction TCP and Path MTU Discovery. +The following changes are the most significant: .Bl -enum .It @@ -160,11 +164,12 @@ flag forcibly enabled (they are thus said to be .Dq "protocol cloning" ) . .It When the last reference to an IP route is dropped, the route is -examined to determine if it was created by cloning such a route. If -this is the case, the +examined to determine if it was created by cloning such a route. +If this is the case, the .Dv RTF_PROTO3 flag is turned on, and the expiration timer is initialized to go off -in net.inet.ip.rtexpire seconds. If such a route is re-referenced, +in net.inet.ip.rtexpire seconds. +If such a route is re-referenced, the flag and expiration timer are reset. .It A kernel timeout runs once every ten minutes, or sooner if there are @@ -177,13 +182,15 @@ net.inet.ip.rtexpire if the number of cached routes grows too large. If after an expiration run there are still more than net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire value is multiplied by 3/4, and any routes which have longer -expiration times have those times adjusted. This process is damped -somewhat by specification of a minimum rtexpire value +expiration times have those times adjusted. +This process is damped somewhat by specification of a minimum rtexpire value (net.inet.ip.rtminexpire), and by restricting the reduction to once in a ten-minute period. .Pp If some external process deletes the original route from which a -protocol-cloned route was generated, the ``child route'' is deleted. +protocol-cloned route was generated, the +.Dq child route +is deleted. (This is actually a generic mechanism in the routing code support for protocol-requested cloning.) .Pp @@ -195,7 +202,8 @@ external routing process, or under the management of a link layer for Ethernets). .Pp Only certain types of network activity will result in the cloning of a -route using this mechanism. Specifically, those protocols (such as +route using this mechanism. +Specifically, those protocols (such as .Tn TCP and .Tn UDP ) @@ -221,7 +229,8 @@ Boolean: enable/disable the use of fast IP forwarding code. Defaults to off. When fast forwarding is enabled, IP packets are forwarded directly to the appropriate network interface with a minimal validity checking, which -greatly improves the throughput. On the other hand, they bypass the +greatly improves the throughput. +On the other hand, they bypass the standard procedures, such as IP option processing and .Xr ipfirewall 4 checking. @@ -250,12 +259,12 @@ Boolean: enable/disable forwarding of source-routed IP packets (default false). .Pq ip.rtexpire Integer: lifetime in seconds of protocol-cloned .Tn IP -routes after the last reference drops (default one hour). This value -varies dynamically as described above. +routes after the last reference drops (default one hour). +This value varies dynamically as described above. .It Dv IPCTL_RTMINEXPIRE .Pq ip.rtminexpire -Integer: minimum value of ip.rtexpire (default ten seconds). This -value has no effect on user modifications, but restricts the dynamic +Integer: minimum value of ip.rtexpire (default ten seconds). +This value has no effect on user modifications, but restricts the dynamic adaptation described above. .It Dv IPCTL_RTMAXCACHE .Pq ip.rtmaxcache diff --git a/share/man/man4/intro.4 b/share/man/man4/intro.4 index 35d3058..67964c8 100644 --- a/share/man/man4/intro.4 +++ b/share/man/man4/intro.4 @@ -37,10 +37,12 @@ and miscellaneous hardware. .Ss The device abstraction Device is a term used mostly for hardware-related stuff that belongs to the system, like disks, printers, or a graphics display with its -keyboard. There are also so-called +keyboard. +There are also so-called .Em pseudo-devices where a device driver emulates the behaviour of a device in software -without any particular underlying hardware. A typical example for +without any particular underlying hardware. +A typical example for the latter class is .Pa /dev/mem , a loophole where the physical memory can be accessed using the regular @@ -48,7 +50,8 @@ file access semantics. .Pp The device abstraction generally provides a common set of system calls layered on top of them, which are dispatched to the corresponding -device driver by the upper layers of the kernel. The set of system +device driver by the upper layers of the kernel. +The set of system calls available for devices is chosen from .Xr open 2 , .Xr close 2 , @@ -79,7 +82,8 @@ Note that this could lead to an inconsistent state, where either there are device nodes that do not have a configured driver associated with them, or there may be drivers that have successfully probed for their devices, but cannot be accessed since the corresponding device node is -still missing. In the first case, any attempt to reference the device +still missing. +In the first case, any attempt to reference the device through the device node will result in an error, returned by the upper layers of the kernel, usually .Er ENXIO . @@ -92,7 +96,8 @@ and .Em character devices, or to use better terms, buffered and unbuffered (raw) -devices. The traditional names are reflected by the letters +devices. +The traditional names are reflected by the letters .Ql b and .Ql c @@ -100,11 +105,13 @@ as the file type identification in the output of .Ql ls -l . Buffered devices are being accessed through the buffer cache of the operating system, and they are solely intended to layer a file system -on top of them. They are normally implemented for disks and disk-like +on top of them. +They are normally implemented for disks and disk-like devices only and, for historical reasons, for tape devices. .Pp Raw devices are available for all drivers, including those that also -implement a buffered device. For the latter group of devices, the +implement a buffered device. +For the latter group of devices, the differentiation is conventionally done by prepending the letter .Ql r to the path name of the device node, for example @@ -115,7 +122,8 @@ is the corresponding device node for the buffered device. .Pp Unbuffered devices should be used for all actions that are not related to file system operations, even if the device in question is a disk -device. This includes making backups of entire disk partitions, or +device. +This includes making backups of entire disk partitions, or to .Em raw floppy disks @@ -126,7 +134,8 @@ file permissions of the device node entry, instead of being enforced directly by the drivers in the kernel. .Ss Drivers without device nodes Drivers for network devices do not use device nodes in order to be -accessed. Their selection is based on other decisions inside the +accessed. +Their selection is based on other decisions inside the kernel, and instead of calling .Xr open 2 , use of a network device is generally introduced by using the system @@ -135,10 +144,11 @@ call .Ss Configuring a driver into the kernel For each kernel, there is a configuration file that is used as a base to select the facilities and drivers for that kernel, and to tune -several options. See +several options. +See .Xr config 8 -for a detailed description of the files involved. The individual -manual pages in this section provide a sample line for the +for a detailed description of the files involved. +The individual manual pages in this section provide a sample line for the configuration file in their synopsis portion. See also the sample config file .Pa /sys/i386/conf/LINT @@ -157,13 +167,12 @@ architecture). .Xr devfs 5 , .Xr hier 7 , .Xr config 8 +.Sh HISTORY +This manual page first appeared in +.Fx 2.1 . .Sh AUTHORS .An -nosplit This man page has been written by .An J\(:org Wunsch with initial input by .An David E. O'Brien . -.Sh HISTORY -.Nm Intro -appeared in -.Fx 2.1 . diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 index 8222ed7..52c7774 100644 --- a/share/man/man4/ip6.4 +++ b/share/man/man4/ip6.4 @@ -566,7 +566,8 @@ socket option. .Pp When writing to a raw socket the kernel will automatically fragment the packet if its size exceeds the path MTU, inserting the required -fragmentation headers. On input the kernel reassembles received +fragmentation headers. +On input the kernel reassembles received fragments, so the reader of a raw socket never sees any fragment headers. .Pp @@ -607,8 +608,10 @@ int offset = 2; setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); .Ed .Pp -By default, this socket option is disabled. Setting the offset to -1 -also disables the option. By disabled we mean (1) the kernel will +By default, this socket option is disabled. +Setting the offset to -1 +also disables the option. +By disabled we mean (1) the kernel will not calculate and store a checksum for outgoing packets, and (2) the kernel will not verify a checksum for received packets. .Pp diff --git a/share/man/man4/kld.4 b/share/man/man4/kld.4 index f8f7a6e..c0a210c 100644 --- a/share/man/man4/kld.4 +++ b/share/man/man4/kld.4 @@ -39,13 +39,15 @@ and above in favor of the interface. This interface, like its predecessor, allows the system administrator to dynamically add and remove -functionality from a running system. This ability also helps software +functionality from a running system. +This ability also helps software developers to develop new parts of the kernel without constantly rebooting to test their changes. .Pp Various types of modules can be loaded into the system. There are several defined module types, listed below, which can -be added to the system in a predefined way. In addition, there +be added to the system in a predefined way. +In addition, there is a generic type, for which the module itself handles loading and unloading. .Pp @@ -150,11 +152,6 @@ for any error encountered while loading a module. When system internal interfaces change, old modules often cannot detect this, and such modules when loaded will often cause crashes or mysterious failures. -.Sh AUTHORS -The -.Nm -facility was originally implemented by -.An Doug Rabson Aq dfr@FreeBSD.org . .Sh HISTORY The .Nm @@ -166,3 +163,8 @@ facility, which was similar in functionality to the loadable kernel modules facility provided by .Tn SunOS 4.1.3. +.Sh AUTHORS +The +.Nm +facility was originally implemented by +.An Doug Rabson Aq dfr@FreeBSD.org . diff --git a/share/man/man4/lp.4 b/share/man/man4/lp.4 index 477b1e3..4d0ff79 100644 --- a/share/man/man4/lp.4 +++ b/share/man/man4/lp.4 @@ -79,14 +79,17 @@ flag: .It Fl link0 (default) Use .Fx -mode (LPIP). This is the simpler of the two modes +mode (LPIP). +This is the simpler of the two modes and therefore slightly more efficient. .It Cm link0 -Use Crynwr/Linux compatible mode (CLPIP). This mode has a simulated ethernet +Use Crynwr/Linux compatible mode (CLPIP). +This mode has a simulated ethernet packet header, and is easier to interface to other types of equipment. .El .Pp -The interface MTU defaults to 1500, but may be set to any value. Both ends +The interface MTU defaults to 1500, but may be set to any value. +Both ends of the link must be configured with the same MTU. .Ss Cable Connections The cable connecting the two parallel ports should be wired as follows: @@ -109,7 +112,8 @@ Cables with this wiring are widely available as 'Laplink' cables, and are often coloured yellow. .Pp The connections are symmetric, and provide 5 lines in each direction (four -data plus one handshake). The two modes use the same wiring, but make a +data plus one handshake). +The two modes use the same wiring, but make a different choice of which line to use as handshake. .Ss FreeBSD LPIP mode The signal lines are used as follows: @@ -136,7 +140,8 @@ Data in, bit 3. Handshake in. .El .Pp -When idle, all data lines are at zero. Each byte is signalled in four steps: +When idle, all data lines are at zero. +Each byte is signalled in four steps: sender writes the 4 most significant bits and raises the handshake line; receiver reads the 4 bits and raises its handshake to acknowledge; sender places the 4 least significant bits on the data lines and lowers @@ -146,14 +151,16 @@ The packet format has a two-byte header, comprising the fixed values 0x08, 0x00, immediately followed by the IP header and data. .Pp The start of a packet is indicated by simply signalling the first byte -of the header. The end of the packet is indicated by inverting +of the header. +The end of the packet is indicated by inverting the data lines (ie. writing the ones-complement of the previous nibble to be transmitted) without changing the state of the handshake. .Pp Note that the end-of-packet marker assumes that the handshake signal and the data-out bits can be written in a single instruction - otherwise certain byte values in the packet data would falsely be interpreted -as end-of-packet. This is not a problem for the PC printer port, +as end-of-packet. +This is not a problem for the PC printer port, but requires care when implementing this protocol on other equipment. .Ss Crynwr/Linux CLPIP mode The signal lines are used as follows: @@ -180,7 +187,8 @@ Data in, bit 3. Handshake in. .El .Pp -When idle, all data lines are at zero. Each byte is signalled in four steps: +When idle, all data lines are at zero. +Each byte is signalled in four steps: sender writes the 4 least significant bits and raises the handshake line; receiver reads the 4 bits and raises its handshake to acknowledge; sender places the 4 most significant bits on the data lines and lowers @@ -208,9 +216,10 @@ calculates outgoing checksums, but does not validate incoming ones. .Pp The start of packet has to be signalled specially, since the line chosen -for handshake-in cannot be used to generate an interrupt. The sender -writes the value 0x08 to the data lines, and waits for the receiver -to respond by writing 0x01 to its data lines. The sender then starts +for handshake-in cannot be used to generate an interrupt. +The sender writes the value 0x08 to the data lines, and waits for the receiver +to respond by writing 0x01 to its data lines. +The sender then starts signalling the first byte of the packet (the length byte). .Pp End of packet is deduced from the packet length and is not signalled @@ -223,11 +232,14 @@ state to avoid spuriously indicating the start of the next packet). .Sh BUGS Busy-waiting loops are used while handshaking bytes, (and worse still when waiting for the receiving system to respond to an interrupt for the start -of a packet). Hence a fast system talking to a slow one will consume -excessive amounts of CPU. This is unavoidable in the case of CLPIP mode +of a packet). +Hence a fast system talking to a slow one will consume +excessive amounts of CPU. +This is unavoidable in the case of CLPIP mode due to the choice of handshake lines; it could theoretically be improved in the case of LPIP mode. .Pp Polling timeouts are controlled by counting loop iterations rather than -timers, and so are dependent on CPU speed. This is somewhat stabilised +timers, and so are dependent on CPU speed. +This is somewhat stabilised by the need to perform (slow) ISA bus cycles to actually read the port. diff --git a/share/man/man4/lpt.4 b/share/man/man4/lpt.4 index 7990d80..121fda2 100644 --- a/share/man/man4/lpt.4 +++ b/share/man/man4/lpt.4 @@ -58,7 +58,8 @@ and released only when the transfer is completed: either when the device is closed or when the entire buffer is sent in interrupt driven mode. .Pp The driver can be configured to be either interrupt-driven, or -to poll the printer. Ports that are configured to be +to poll the printer. +Ports that are configured to be interrupt-driven can be switched to polled mode by using the .Xr lptcontrol 8 command. diff --git a/share/man/man4/man4.i386/pae.4 b/share/man/man4/man4.i386/pae.4 index 6ec0306..32285ba 100644 --- a/share/man/man4/man4.i386/pae.4 +++ b/share/man/man4/man4.i386/pae.4 @@ -58,7 +58,8 @@ window or otherwise. .Sh SEE ALSO .Xr smp 4 , .Xr tuning 7 , -.Xr config 8 +.Xr config 8 , +.Xr bus_dma 9 .Sh HISTORY The .Dv PAE diff --git a/share/man/man4/matcd.4 b/share/man/man4/matcd.4 index 94fd2bf..c7db228 100644 --- a/share/man/man4/matcd.4 +++ b/share/man/man4/matcd.4 @@ -291,7 +291,7 @@ The driver supports block and character access. Partition "a" returns 2048-byte User Data blocks from data CDs. Partition "c" returns the full 2352-byte Frames from any type of CD, including audio CDs. (Partition -"c" cannot be "mounted" with cd9660 or other standard filesystem emulators.) +"c" cannot be "mounted" with cd9660 or other standard file system emulators.) No other partitions are supported. .Pp The diff --git a/share/man/man4/mem.4 b/share/man/man4/mem.4 index 6f04970..4387a7d 100644 --- a/share/man/man4/mem.4 +++ b/share/man/man4/mem.4 @@ -41,19 +41,19 @@ .Nd memory files .Sh DESCRIPTION The special file -.Nm /dev/mem +.Pa /dev/mem is an interface to the physical memory of the computer. Byte offsets in this file are interpreted as physical memory addresses. Reading and writing this file is equivalent to reading and writing memory itself. Only offsets within the bounds of -.Nm /dev/mem +.Pa /dev/mem are allowed. .Pp Kernel virtual memory is accessed through the interface -.Nm /dev/kmem +.Pa /dev/kmem in the same manner as -.Nm /dev/mem . +.Pa /dev/mem . Only kernel virtual addresses that are currently mapped to memory are allowed. .Pp On @@ -72,30 +72,32 @@ long, and ends at virtual address 0xf0000000. .Sh IOCTL INTERFACE Several architectures allow attributes to be associated with ranges of physical -memory. These attributes can be manipulated via +memory. +These attributes can be manipulated via .Fn ioctl calls performed on -.Nm /dev/mem . +.Pa /dev/mem . Declarations and data types are to be found in -.Pa <sys/memrange.h> +.Aq Pa sys/memrange.h . .Pp The specific attributes, and number of programmable ranges may vary between -architectures. The full set of supported attributes is: +architectures. +The full set of supported attributes is: .Bl -tag -width indent -.It MDF_UNCACHEABLE +.It Dv MDF_UNCACHEABLE The region is not cached. -.It MDF_WRITECOMBINE +.It Dv MDF_WRITECOMBINE Writes to the region may be combined or performed out of order. -.It MDF_WRITETHROUGH +.It Dv MDF_WRITETHROUGH Writes to the region are committed synchronously. -.It MDF_WRITEBACK +.It Dv MDF_WRITEBACK Writes to the region are committed asynchronously. -.It MDF_WRITEPROTECT +.It Dv MDF_WRITEPROTECT The region cannot be written to. .El .Pp Memory ranges are described by -.Fa struct mem_range_desc : +.Vt struct mem_range_desc : .Bd -literal -offset indent u_int64_t mr_base; /\(** physical base address \(**/ u_int64_t mr_len; /\(** physical length of region \(**/ @@ -133,25 +135,32 @@ int mo_arg[2]; .Ed .Pp The -.Fa MEMRANGE_GET +.Dv MEMRANGE_GET ioctl is used to retrieve current memory range attributes. If -.Fa mo_arg[0] +.Va mo_arg[0] is set to 0, it will be updated with the total number of memory range -descriptors. If greater than 0, the array at -.Fa mo_desc +descriptors. +If greater than 0, the array at +.Va mo_desc will be filled with a corresponding number of descriptor structures, or the maximum, whichever is less. .Pp The -.Fa MEMRANGE_SET +.Dv MEMRANGE_SET ioctl is used to add, alter and remove memory range attributes. A range -with the MDF_FIXACTIVE flag may not be removed; a range with the MDF_BUSY +with the +.Dv MDF_FIXACTIVE +flag may not be removed; a range with the +.Dv MDF_BUSY flag may not be removed or updated. .Pp -.Fa mo_arg[0] -should be set to MEMRANGE_SET_UPDATE to update an existing -or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range. +.Va mo_arg[0] +should be set to +.Dv MEMRANGE_SET_UPDATE +to update an existing or establish a new range, or to +.Dv MEMRANGE_SET_REMOVE +to remove a range. .Sh RETURN VALUES .Bl -tag -width Er .It Bq Er EOPNOTSUPP @@ -185,7 +194,8 @@ Busy range attributes are not yet managed correctly. .Xr memcontrol 8 .Sh HISTORY The -.Nm , +.Nm mem +and .Nm kmem files appeared in .At v6 . diff --git a/share/man/man4/mtio.4 b/share/man/man4/mtio.4 index 036a3ca..31d3358 100644 --- a/share/man/man4/mtio.4 +++ b/share/man/man4/mtio.4 @@ -64,7 +64,8 @@ the name of the no-rewind devices. Tapes can be written with either fixed length records or variable length records. See .Xr sa 4 -for more information. Two end-of-file markers mark the end of a tape, and +for more information. +Two end-of-file markers mark the end of a tape, and one end-of-file marker marks the end of a tape file. If the tape is not to be rewound it is positioned with the head in between the two tape marks, where the next write diff --git a/share/man/man4/natm.4 b/share/man/man4/natm.4 index 622ccce..75a2c57 100644 --- a/share/man/man4/natm.4 +++ b/share/man/man4/natm.4 @@ -19,7 +19,7 @@ to do .Dq make clean ) . .Sh NATM API The NATM layer uses a -.Dv struct sockaddr_natm +.Vt struct sockaddr_natm to specify a virtual circuit: .Bd -literal -offset indent struct sockaddr_natm { @@ -52,11 +52,13 @@ one would use the following: .Pp The .Fn socket -call simply creates an unconnected NATM socket. The +call simply creates an unconnected NATM socket. +The .Fn connect call associates an unconnected NATM socket with a virtual circuit and tells the driver to enable that virtual circuit -for receiving data. After the +for receiving data. +After the .Fn connect call one can .Fn read @@ -75,19 +77,21 @@ protocol layer passes the address of the protocol control block down to the driver as a receive .Dq handle . When inbound data arrives, the driver passes the data back with the -appropriate receive handle. The NATM layer uses this to avoid the -overhead of a protocol control block lookup. This allows us to take +appropriate receive handle. +The NATM layer uses this to avoid the +overhead of a protocol control block lookup. +This allows us to take advantage of the fact that ATM has already demultiplexed the data for us. .Sh CAVEAT The NATM protocol support is subject to change as -the ATM protocols develop. Users should not depend -on details of the current implementation, but rather +the ATM protocols develop. +Users should not depend on details of the current implementation, but rather the services exported. .Sh SEE ALSO .Xr en 4 , -.Xr hatm 4 , .Xr fatm 4 , +.Xr hatm 4 , .Xr natmip 4 .Sh AUTHORS .An Chuck Cranor diff --git a/share/man/man4/netgraph.4 b/share/man/man4/netgraph.4 index 1bcba31..0c0ba98 100644 --- a/share/man/man4/netgraph.4 +++ b/share/man/man4/netgraph.4 @@ -57,7 +57,8 @@ Nodes communicate along the edges to process data, implement protocols, etc. The aim of .Nm is to supplement rather than replace the existing kernel networking -infrastructure. It provides: +infrastructure. +It provides: .Pp .Bl -bullet -compact -offset 2n .It @@ -69,7 +70,7 @@ A common framework for kernel entities to inter-communicate .It A reasonably fast, kernel-based implementation .El -.Sh Nodes and Types +.Ss Nodes and Types The most fundamental concept in .Nm is that of a @@ -107,15 +108,16 @@ characters (including NUL byte). .Pp Each node instance has a unique .Em ID number -which is expressed as a 32-bit hex value. This value may be used to -refer to a node when there is no +which is expressed as a 32-bit hex value. +This value may be used to refer to a node when there is no .Tn ASCII name assigned to it. -.Sh Hooks +.Ss Hooks Nodes are connected to other nodes by connecting a pair of .Em hooks , one from each node. Data flows bidirectionally between nodes along -connected pairs of hooks. A node may have as many hooks as it +connected pairs of hooks. +A node may have as many hooks as it needs, and may assign whatever meaning it wants to a hook. .Pp Hooks have these properties: @@ -135,14 +137,15 @@ limited to .Dv "NG_HOOKLEN + 1" characters (including NUL byte). .It -A hook is always connected to another hook. That is, hooks are +A hook is always connected to another hook. +That is, hooks are created at the time they are connected, and breaking an edge by removing either hook destroys both hooks. .It A hook can be set into a state where incoming packets are always queued -by the input queueing system, rather than being delivered directly. This -is used when the two joined nodes need to be decoupled, e.g. if they are -running at different processor priority levels. (spl) +by the input queueing system, rather than being delivered directly. +This is used when the two joined nodes need to be decoupled, e.g. if they are +running at different processor priority levels. (spl) .It A hook may supply over-riding receive data and receive message functions which should be used for data and messages received through that hook @@ -154,41 +157,48 @@ For example, connecting to the hook named .Dq debug might trigger the node to start sending debugging information to that hook. -.Sh Data Flow +.Ss Data Flow Two types of information flow between nodes: data messages and -control messages. Data messages are passed in mbuf chains along the edges -in the graph, one edge at a time. The first mbuf in a chain must have the +control messages. +Data messages are passed in mbuf chains along the edges +in the graph, one edge at a time. +The first mbuf in a chain must have the .Dv M_PKTHDR flag set. Each node decides how to handle data coming in on its hooks. .Pp Control messages are type-specific C structures sent from one node -directly to some arbitrary other node. Control messages have a common +directly to some arbitrary other node. +Control messages have a common header format, followed by type-specific data, and are binary structures -for efficiency. However, node types also may support conversion of the +for efficiency. +However, node types also may support conversion of the type specific data between binary and .Tn ASCII for debugging and human interface purposes (see the .Dv NGM_ASCII2BINARY and .Dv NGM_BINARY2ASCII -generic control messages below). Nodes are not required to support -these conversions. +generic control messages below). +Nodes are not required to support these conversions. .Pp -There are three ways to address a control message. If -there is a sequence of edges connecting the two nodes, the message +There are three ways to address a control message. +If there is a sequence of edges connecting the two nodes, the message may be .Dq source routed by specifying the corresponding sequence of .Tn ASCII hook names as the destination address for the message (relative -addressing). If the destination is adjacent to the source, then the source +addressing). +If the destination is adjacent to the source, then the source node may simply specify (as a pointer in the code) the hook across which the -message should be sent. Otherwise, the recipient node global +message should be sent. +Otherwise, the recipient node global .Tn ASCII name (or equivalent ID based name) is used as the destination address -for the message (absolute addressing). The two types of +for the message (absolute addressing). +The two types of .Tn ASCII addressing may be combined, by specifying an absolute start node and a sequence @@ -198,7 +208,8 @@ addressing modes are available to control programs outside the kernel, as use of direct pointers is limited of course to kernel modules. .Pp Messages often represent commands that are followed by a reply message -in the reverse direction. To facilitate this, the recipient of a +in the reverse direction. +To facilitate this, the recipient of a control message is supplied with a .Dq return address that is suitable for addressing a reply. @@ -207,42 +218,50 @@ Each control message contains a 32 bit value called a .Em typecookie indicating the type of the message, i.e., how to interpret it. Typically each type defines a unique typecookie for the messages -that it understands. However, a node may choose to recognize and +that it understands. +However, a node may choose to recognize and implement more than one type of message. .Pp If a message is delivered to an address that implies that it arrived at that node through a particular hook, (as opposed to having been directly addressed using its ID or global name), then that hook is identified to the -receiving node. This allows a message to be rerouted or passed on, should +receiving node. +This allows a message to be rerouted or passed on, should a node decide that this is required, in much the same way that data packets are passed around between nodes. A set of standard messages for flow control and link management purposes are defined by the base system that are usually -passed around in this manner. Flow control message would usually travel +passed around in this manner. +Flow control message would usually travel in the opposite direction to the data to which they pertain. -.Sh Netgraph is (usually) Functional +.Ss Netgraph is (usually) Functional In order to minimize latency, most .Nm operations are functional. That is, data and control messages are delivered by making function -calls rather than by using queues and mailboxes. For example, if node +calls rather than by using queues and mailboxes. +For example, if node A wishes to send a data mbuf to neighboring node B, it calls the generic .Nm -data delivery function. This function in turn locates +data delivery function. +This function in turn locates node B and calls B's .Dq receive data -method. There are exceptions to this. +method. +There are exceptions to this. .Pp Each node has an input queue, and some operations can be considered to -be 'writers' in that they alter the state of the node. Obviously in an SMP +be 'writers' in that they alter the state of the node. +Obviously in an SMP world it would be bad if the state of a node were changed while another -data packet were transiting the node. For this purpose, the input queue -implements a +data packet were transiting the node. +For this purpose, the input queue implements a .Em reader/writer semantic so that when there is a writer in the node, all other requests are queued, and while there are readers, a writer, and any following -packets are queued. In the case where there is no reason to queue the +packets are queued. +In the case where there is no reason to queue the data, the input method is called directly, as mentioned above. .Pp A node may declare that all requests should be considered as writers, @@ -252,7 +271,8 @@ hook should always be queued, rather than delivered directly (often useful for interrupt routines who want to get back to the hardware quickly). By default, all control message packets are considered to be writers unless specifically declared to be a reader in their definition. (see -NGM_READONLY in ng_message.h) +NGM_READONLY in +.Pa ng_message.h ) .Pp While this mode of operation results in good performance, it has a few implications for node @@ -267,7 +287,8 @@ message before the original delivery function call returns. Netgraph nodes and support routines generally run at .Fn splnet . However, some nodes may want to send data and control messages -from a different priority level. Netgraph supplies a mechanism which +from a different priority level. +Netgraph supplies a mechanism which utilizes the NETISR system to move message and data delivery to .Fn splnet . Nodes that run at other priorities (e.g. interfaces) can be directly @@ -283,7 +304,7 @@ It's possible for an infinite loop to occur if the graph contains cycles. .El .Pp So far, these issues have not proven problematical in practice. -.Sh Interaction With Other Parts of the Kernel +.Ss Interaction With Other Parts of the Kernel A node may have a hidden interaction with other components of the kernel outside of the .Nm @@ -308,7 +329,7 @@ cooperating user process. .Pp Another example is a device driver that presents a node interface to the hardware. -.Sh Node Methods +.Ss Node Methods Nodes are notified of the following actions via function calls to the following node methods (all at .Fn splnet ) @@ -360,7 +381,7 @@ removal or unloading, (via ng_rmnode_self()) it should set the .Em NG_REALLY_DIE flag to signal to its own shutdown method that it is not to persist. .El -.Sh Sending and Receiving Data +.Ss Sending and Receiving Data Two other methods are also supported by all nodes: .Bl -tag -width xxx .It Receive data message @@ -504,7 +525,7 @@ has been tested and debugged to present a consistent and trustworthy framework for the .Dq type module writer to use. -.Sh Addressing +.Ss Addressing The .Nm framework provides an unambiguous and simple to use method of specifically @@ -620,7 +641,7 @@ over an ISDN line: +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ] [ (no name) ] [ (no name) ] .Ed -.Sh Netgraph Structures +.Ss Netgraph Structures Structures are defined in .Pa sys/netgraph/netgraph.h (for kernel structures only of interest to nodes) @@ -791,7 +812,7 @@ A current example of how to define a node can always be seen in .Em sys/netgraph/ng_sample.c and should be used as a starting point for new node writers. .El -.Sh Netgraph Message Structure +.Ss Netgraph Message Structure Control messages have the following structure: .Bd -literal #define NG_CMDSTRLEN 15 /* Max command string (16 with null) */ @@ -871,7 +892,7 @@ Room for a short human readable version of .Pp Some modules may choose to implement messages from more than one of the header files and thus recognize more than one type cookie. -.Sh Control Message ASCII Form +.Ss Control Message ASCII Form Control messages are in binary format for efficiency. However, for debugging and human interface purposes, and if the node type supports it, control messages may be converted to and from an equivalent @@ -936,7 +957,7 @@ the necessary routines to parse and unparse. forms defined for a specific node type are documented in the documentation for that node type. -.Sh Generic Control Messages +.Ss Generic Control Messages There are a number of standard predefined messages that will work for any node, as they are supported directly by the framework itself. These are defined in @@ -1028,7 +1049,7 @@ header fields filled in, plus the NUL-terminated string version of the arguments in the arguments field. If successful, the reply contains the binary version of the control message. .El -.Sh Flow Control Messages +.Ss Flow Control Messages In addition to the control messages that affect nodes with respect to the graph, there are also a number of .Em Flow-control @@ -1036,19 +1057,22 @@ messages defined. At present these are .Em NOT handled automatically by the system, so nodes need to handle them if they are going to be used in a graph utilising -flow control, and will be in the likely path of these messages. The -default action of a node that doesn't understand these messages should -be to pass them onto the next node. Hopefully some helper functions -will assist in this eventually. These messages are also defined in +flow control, and will be in the likely path of these messages. +The default action of a node that doesn't understand these messages should +be to pass them onto the next node. +Hopefully some helper functions will assist in this eventually. +These messages are also defined in .Pa sys/netgraph/ng_message.h and have a separate cookie .Em NG_FLOW_COOKIE -to help identify them. They will not be covered in depth here. -.Sh Metadata +to help identify them. +They will not be covered in depth here. +.Ss Metadata Data moving through the .Nm system can be accompanied by meta-data that describes some -aspect of that data. The form of the meta-data is a fixed header, +aspect of that data. +The form of the meta-data is a fixed header, which contains enough information for most uses, and can optionally be supplemented by trailing .Em option @@ -1059,8 +1083,10 @@ data. If a node does not recognize the cookie associated with an option, it should ignore that option. .Pp Meta data might include such things as priority, discard eligibility, -or special processing requirements. It might also mark a packet for -debug status, etc. The use of meta-data is still experimental. +or special processing requirements. +It might also mark a packet for +debug status, etc. +The use of meta-data is still experimental. .Sh INITIALIZATION The base .Nm @@ -1071,7 +1097,8 @@ In the former case, include .Pp .Dl options NETGRAPH .Pp -in your kernel configuration file. You may also include selected +in your kernel configuration file. +You may also include selected node types in the kernel compilation, for example: .Bd -literal -offset indent options NETGRAPH @@ -1108,8 +1135,8 @@ The .Fn NETGRAPH_INIT macro automates this process by using a linker set. .Sh EXISTING NODE TYPES -Several node types currently exist. Each is fully documented -in its own man page: +Several node types currently exist. +Each is fully documented in its own man page: .Bl -tag -width xxx .It SOCKET The socket type implements two new sockets in the new protocol domain @@ -1121,7 +1148,8 @@ and both of type .Dv SOCK_DGRAM . Typically one of each is associated with a socket node. -When both sockets have closed, the node will shut down. The +When both sockets have closed, the node will shut down. +The .Dv NG_DATA socket is used for sending and receiving data, while the .Dv NG_CONTROL diff --git a/share/man/man4/netintro.4 b/share/man/man4/netintro.4 index dc869ba..a3df475 100644 --- a/share/man/man4/netintro.4 +++ b/share/man/man4/netintro.4 @@ -59,15 +59,18 @@ All network protocols are associated with a specific .Em protocol family . A protocol family provides basic services to the protocol implementation to allow it to function within a specific -network environment. These services may include +network environment. +These services may include packet fragmentation and reassembly, routing, addressing, and -basic transport. A protocol family may support multiple +basic transport. +A protocol family may support multiple methods of addressing, though the current protocol implementations -do not. A protocol family is normally comprised of a number -of protocols, one per +do not. +A protocol family is normally comprised of a number of protocols, one per .Xr socket 2 -type. It is not required that a protocol family support -all socket types. A protocol family may contain multiple +type. +It is not required that a protocol family support all socket types. +A protocol family may contain multiple protocols supporting the same socket abstraction. .Pp A protocol supports one of the socket abstractions detailed in @@ -79,10 +82,12 @@ Protocols normally accept only one type of address format, usually determined by the addressing structure inherent in the design of the protocol family/network architecture. Certain semantics of the basic socket abstractions are -protocol specific. All protocols are expected to support +protocol specific. +All protocols are expected to support the basic model for their particular socket type, but may, in addition, provide non-standard facilities or extensions -to a mechanism. For example, a protocol supporting the +to a mechanism. +For example, a protocol supporting the .Dv SOCK_STREAM abstraction may allow more than one byte of out-of-band data to be transmitted per out-of-band message. @@ -90,8 +95,8 @@ data to be transmitted per out-of-band message. A network interface is similar to a device interface. Network interfaces comprise the lowest layer of the networking subsystem, interacting with the actual transport -hardware. An interface may support one or more protocol -families and/or address formats. +hardware. +An interface may support one or more protocol families and/or address formats. The SYNOPSIS section of each network interface entry gives a sample specification of the related drivers for use in providing @@ -123,7 +128,8 @@ Consult the appropriate manual pages in this section for more information regarding the support for each protocol family. .Sh ADDRESSING Associated with each protocol family is an address -format. All network addresses adhere to a general structure, +format. +All network addresses adhere to a general structure, called a sockaddr, described below. However, each protocol imposes finer and more specific structure, generally renaming @@ -171,8 +177,8 @@ This facility is described in .Xr route 4 . .Sh INTERFACES Each network interface in a system corresponds to a -path through which messages may be sent and received. A network -interface usually has a hardware device associated with it, though +path through which messages may be sent and received. +A network interface usually has a hardware device associated with it, though certain interfaces such as the loopback interface, .Xr lo 4 , do not. @@ -188,7 +194,8 @@ in the desired domain. Most of the requests supported in earlier releases take an .Vt ifreq -structure as its parameter. This structure has the form +structure as its parameter. +This structure has the form .Bd -literal struct ifreq { #define IFNAMSIZ 16 @@ -218,9 +225,10 @@ struct ifreq { Calls which are now deprecated are: .Bl -tag -width SIOCGIFBRDADDR .It Dv SIOCSIFADDR -Set interface address for protocol family. Following the address -assignment, the ``initialization'' routine for -the interface is called. +Set interface address for protocol family. +Following the address assignment, the +.Dq initialization +routine for the interface is called. .It Dv SIOCSIFDSTADDR Set point to point address for protocol family and interface. .It Dv SIOCSIFBRDADDR @@ -241,7 +249,8 @@ Get point to point address for protocol family and interface. .It Dv SIOCGIFBRDADDR Get broadcast address for protocol family and interface. .It Dv SIOCSIFFLAGS -Set interface flags field. If the interface is marked down, +Set interface flags field. +If the interface is marked down, any processes currently routing packets through the interface are notified; some interfaces may be reset so that incoming packets are no longer received. @@ -268,10 +277,12 @@ There are two requests that make use of a new structure: .Bl -tag -width SIOCGIFBRDADDR .It Dv SIOCAIFADDR An interface may have more than one address associated with it -in some protocols. This request provides a means to +in some protocols. +This request provides a means to add additional addresses (or modify characteristics of the primary address if the default address for the address family -is specified). Rather than making separate calls to +is specified). +Rather than making separate calls to set destination or broadcast addresses, or network masks (now an integral feature of multiple protocols) a separate structure is used to specify all three facets simultaneously @@ -286,7 +297,8 @@ identifier itself to include the total size, as described in .Fn ioctl . .It Dv SIOCDIFADDR This requests deletes the specified address from the list -associated with an interface. It also uses the +associated with an interface. +It also uses the .Vt ifaliasreq structure to allow for the possibility of protocols allowing multiple masks or destination addresses, and also adopts the @@ -294,9 +306,11 @@ convention that specification of the default address means to delete the first address for the interface belonging to the address family in which the original socket was opened. .It Dv SIOCGIFCONF -Get interface configuration list. This request takes an +Get interface configuration list. +This request takes an .Vt ifconf -structure (see below) as a value-result parameter. The +structure (see below) as a value-result parameter. +The .Va ifc_len field should be initially set to the size of the buffer pointed to by @@ -366,7 +380,8 @@ struct if_clonereq { .Xr socket 2 , .Xr intro 4 , .Xr config 8 , -.Xr routed 8 +.Xr routed 8 , +.Xr ifnet 9 .Sh HISTORY The .Nm netintro diff --git a/share/man/man4/ng_ksocket.4 b/share/man/man4/ng_ksocket.4 index 96d6383..3f2d3b2 100644 --- a/share/man/man4/ng_ksocket.4 +++ b/share/man/man4/ng_ksocket.4 @@ -47,10 +47,12 @@ A .Nm ksocket node is both a netgraph node and a .Bx -socket. The +socket. +The .Nm node type allows one to open a socket inside the kernel and have -it appear as a Netgraph node. The +it appear as a Netgraph node. +The .Nm node type is the reverse of the socket node type (see .Xr ng_socket 4 ) : @@ -63,8 +65,10 @@ what is normally a user-level entity (the associated socket). .Pp A .Nm -node allows at most one hook connection. Connecting to the node is -equivalent to opening the associated socket. The name given to the hook +node allows at most one hook connection. +Connecting to the node is +equivalent to opening the associated socket. +The name given to the hook determines what kind of socket the node will open (see below). When the hook is disconnected and/or the node is shutdown, the associated socket is closed. @@ -90,19 +94,22 @@ This node type supports the generic control messages, plus the following: .It Dv NGM_KSOCKET_BIND This functions exactly like the .Xr bind 2 -system call. The +system call. +The .Dv "struct sockaddr" socket address parameter should be supplied as an argument. .It Dv NGM_KSOCKET_LISTEN This functions exactly like the .Xr listen 2 -system call. The backlog parameter (a single 32 bit +system call. +The backlog parameter (a single 32 bit .Dv int ) should be supplied as an argument. .It Dv NGM_KSOCKET_CONNECT This functions exactly like the .Xr connect 2 -system call. The +system call. +The .Dv "struct sockaddr" destination address parameter should be supplied as an argument. .It Dv NGM_KSOCKET_ACCEPT @@ -110,13 +117,15 @@ Currently unimplemented. .It Dv NGM_KSOCKET_GETNAME Equivalent to the .Xr getsockname 2 -system call. The name is returned as a +system call. +The name is returned as a .Dv "struct sockaddr" in the arguments field of the reply. .It Dv NGM_KSOCKET_GETPEERNAME Equivalent to the .Xr getpeername 2 -system call. The name is returned as a +system call. +The name is returned as a .Dv "struct sockaddr" in the arguments field of the reply. .It Dv NGM_KSOCKET_SETOPT @@ -140,13 +149,15 @@ For control messages that pass a in the argument field, the normal .Tn ASCII equivalent of the C structure -is an acceptable form. For the +is an acceptable form. +For the .Dv PF_INET and .Dv PF_LOCAL address families, a more convenient form is also used, which is the protocol family name, followed by a slash, followed by the actual -address. For +address. +For .Dv PF_INET , the address is an IP address followed by an optional colon and port number. For @@ -167,7 +178,8 @@ For control messages that pass a .Dv "struct ng_ksocket_sockopt" , the normal .Tn ASCII -form for that structure is used. In the future, more +form for that structure is used. +In the future, more convenient encoding of the more common socket options may be supported. .Sh SHUTDOWN This node shuts down upon receipt of a diff --git a/share/man/man4/ng_l2cap.4 b/share/man/man4/ng_l2cap.4 index 38f3ce5..5e9d9e9 100644 --- a/share/man/man4/ng_l2cap.4 +++ b/share/man/man4/ng_l2cap.4 @@ -71,7 +71,7 @@ Baseband layer. The Baseband always performs data integrity checks when requested and resends data until it has been successfully acknowledged or a timeout occurs. -Because acknowledgements may be lost, timeouts may +As acknowledgements may be lost, timeouts may occur even after the data has been successfully sent. .El .Sh L2CAP GENERAL OPERATION diff --git a/share/man/man4/ng_ppp.4 b/share/man/man4/ng_ppp.4 index 677c1d2..1f04571 100644 --- a/share/man/man4/ng_ppp.4 +++ b/share/man/man4/ng_ppp.4 @@ -46,26 +46,30 @@ .Sh DESCRIPTION The .Nm ppp -node type performs multiplexing for the PPP protocol. It handles -only packets that contain data, and forwards protocol negotiation +node type performs multiplexing for the PPP protocol. +It handles only packets that contain data, and forwards protocol negotiation and control packets to a separate controlling entity (e.g., a -user-land daemon). This approach combines the fast dispatch of +user-land daemon). +This approach combines the fast dispatch of kernel implementations with the configuration flexibility of a -user-land implementations. The PPP node type directly supports +user-land implementations. +The PPP node type directly supports multi-link PPP, Van Jacobson compression, PPP compression, PPP -encryption, and the IP, IPX, and AppleTalk protocols. A single -PPP node corresponds to one PPP multi-link bundle. +encryption, and the IP, IPX, and AppleTalk protocols. +A single PPP node corresponds to one PPP multi-link bundle. .Pp There is a separate hook for each PPP link in the bundle, plus several hooks corresponding to the directly supported protocols. For compression and encryption, separate attached nodes are required -to do the actual work. The node type used will of course depend -on the algorithm negotiated. There is also a +to do the actual work. +The node type used will of course depend on the algorithm negotiated. +There is also a .Dv bypass hook which is used to handle any protocol not directly supported -by the node. This includes all of the control protocols: LCP, IPCP, -CCP, etc. Typically this node is connected to a user-land daemon -via a +by the node. +This includes all of the control protocols: LCP, IPCP, +CCP, etc. +Typically this node is connected to a user-land daemon via a .Xr ng_socket 4 type node. .Sh ENABLING FUNCTIONALITY @@ -94,11 +98,14 @@ information fields, but no checksum or other link-specific fields. On outgoing frames, when protocol compression has been enabled and the protocol number is suitable for compression, the protocol field will be compressed (i.e., sent as one byte -instead of two). Either compressed or uncompressed protocol fields -are accepted on incoming frames. Similarly, if address and control +instead of two). +Either compressed or uncompressed protocol fields +are accepted on incoming frames. +Similarly, if address and control field compression has been enabled for the link, the address and control fields will be omitted (except for LCP frames as required -by the standards). Incoming frames have the address and control fields +by the standards). +Incoming frames have the address and control fields stripped automatically if present. .Pp Since all negotiation is handled outside the PPP node, the links @@ -114,7 +121,8 @@ directly out the .Dv bypass hook, and conversely, frames may be transmitted via the .Dv bypass -hook as well. This mode is appropriate for the link authentication phase. +hook as well. +This mode is appropriate for the link authentication phase. As soon as the link is enabled, the PPP node will begin processing frames received on the link. .Sh COMPRESSION AND ENCRYPTION @@ -136,7 +144,8 @@ Encryption works exactly analogously via the .Dv encrypt and .Dv decrypt -nodes. Data is always compressed before being encrypted, +nodes. +Data is always compressed before being encrypted, and decrypted before being decompressed. .Pp Only bundle-level compression and encryption is directly supported; @@ -163,7 +172,8 @@ When a frame is received on a link with an unsupported protocol, or a protocol which is disabled or for which the corresponding hook is unconnected, the PPP node forwards the frame out the .Dv bypass -hook, prepended with a four byte prefix. This first two bytes of +hook, prepended with a four byte prefix. +This first two bytes of the prefix indicate the link number on which the frame was received (in network order). For such frames received over the bundle (i.e., encapsulated in the @@ -176,7 +186,8 @@ was protocol compressed. .Pp Conversely, any data written to the .Dv bypass -hook is assumed to be in this same format. The four byte header is +hook is assumed to be in this same format. +The four byte header is stripped off, the PPP protocol number is prepended (possibly compressed), and the frame is delivered over the desired link. If the link number is @@ -191,12 +202,13 @@ the protocol) or with an LCP protocol reject (if it doesn't recognize or expect the protocol). .Sh MULTILINK OPERATION To enable multi-link PPP, the corresponding configuration flag must be set -and at least one link connected. The PPP node will not allow more than +and at least one link connected. +The PPP node will not allow more than one link to be connected if multi-link is not enabled, nor will it allow certain multi-link settings to be changed while multi-link operation is active (e.g., short sequence number header format). .Pp -Because packets are sent as fragments across multiple individual links, +Since packets are sent as fragments across multiple individual links, it is important that when a link goes down the PPP node is notified immediately, either by disconnecting the corresponding hook or disabling the link via the @@ -214,18 +226,21 @@ packet delivery. When configured for round-robin delivery, the latency and bandwidth values are ignored and the PPP node simply sends each frame as a single fragment, alternating frames across all the links in the -bundle. This scheme has the advantage that even if one link fails -silently, some packets will still get through. It has the disadvantage +bundle. +This scheme has the advantage that even if one link fails +silently, some packets will still get through. +It has the disadvantage of sub-optimal overall bundle latency, which is important for interactive response time, and sub-optimal overall bundle bandwidth when links with different bandwidths exist in the same bundle. .Pp When configured for optimal delivery, the PPP node distributes the packet across the links in a way that minimizes the time it takes -for the completed packet to be received by the far end. This -involves taking into account each link's latency, bandwidth, and -current queue length. Therefore these numbers should be -configured as accurately as possible. The algorithm does require +for the completed packet to be received by the far end. +This involves taking into account each link's latency, bandwidth, and +current queue length. +Therefore these numbers should be configured as accurately as possible. +The algorithm does require some computation, so may not be appropriate for very slow machines and/or very fast links. .Pp @@ -282,11 +297,14 @@ a link number and a PPP protocol number. This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_PPP_SET_CONFIG -This command configures all aspects of the node. This includes enabling +This command configures all aspects of the node. +This includes enabling multi-link PPP, encryption, compression, Van Jacobson compression, and IP, -AppleTalk, and IPX packet delivery. It includes per-link configuration, +AppleTalk, and IPX packet delivery. +It includes per-link configuration, including enabling the link, setting latency and bandwidth parameters, -and enabling protocol field compression. Note that no link or functionality +and enabling protocol field compression. +Note that no link or functionality is active until the corresponding hook is also connected. This command takes a .Dv "struct ng_ppp_node_config" diff --git a/share/man/man4/ng_pppoe.4 b/share/man/man4/ng_pppoe.4 index 2a9917a..adfc9d8 100644 --- a/share/man/man4/ng_pppoe.4 +++ b/share/man/man4/ng_pppoe.4 @@ -56,7 +56,8 @@ The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPOE module. The only statistics presently available are the -total packet counts for input and output. This node does not yet support +total packet counts for input and output. +This node does not yet support the .Dv NGM_TEXT_STATUS control message. @@ -89,35 +90,43 @@ This generic message returns is a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a client. It must be newly created and +the state machine in a manner to become a client. +It must be newly created and a service name can be given as an argument. It is legal to specify a zero length -service name. This is common on some DSL setups. A session request packet +service name. +This is common on some DSL setups. A session request packet will be broadcast on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_LISTEN Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a server listener. The argument -given is the name of the service to listen on behalf of. A zero length service -length will match all requests for service. A matching service request +the state machine in a manner to become a server listener. +The argument +given is the name of the service to listen on behalf of +a zero length service length will match all requests for service. +A matching service request packet will be passed unmodified back to the process responsible -for starting the service. It can then examine it and pass it on to +for starting the service. +It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a server. The argument -given is the name of the service to offer. A zero length service -is legal. The State machine will progress to a state where it will await +the state machine in a manner to become a server. +The argument given is the name of the service to offer. +A zero length service +is legal. +The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook ( see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine -that eventually answers the request. When the Session request packet is +that eventually answers the request. +When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data @@ -133,22 +142,26 @@ struct ngpppoe_init_data { .Ed .It Dv NGM_PPPOE_SUCCESS This command is sent to the node that started this session with one of the -above messages, and reports a state change. This message reports -successful Session negotiation. It uses the structure shown below, and +above messages, and reports a state change. +This message reports successful Session negotiation. +It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_NGM_PPPOE_FAIL This command is sent to the node that started this session with one of the -above messages, and reports a state change. This message reports -failed Session negotiation. It uses the structure shown below, and +above messages, and reports a state change. +This message reports failed Session negotiation. +It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message .It Dv NGM_NGM_PPPOE_CLOSE This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports -a request to close a session. It uses the structure shown below, and +a request to close a session. +It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this -message. At present this message is not yet used and a 'failed' message +message. +At present this message is not yet used and a 'failed' message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the @@ -187,10 +200,11 @@ The following code uses .Dv libnetgraph to set up a .Nm -node and connect it to both a socket node and an Ethernet node. It can handle -the case of when a +node and connect it to both a socket node and an Ethernet node. +It can handle the case of when a .Nm -node is already attached to the Ethernet. It then starts a client session. +node is already attached to the Ethernet. +It then starts a client session. .Bd -literal #include <stdio.h> #include <stdlib.h> diff --git a/share/man/man4/ng_socket.4 b/share/man/man4/ng_socket.4 index 6053ff1..04788dd 100644 --- a/share/man/man4/ng_socket.4 +++ b/share/man/man4/ng_socket.4 @@ -55,7 +55,8 @@ node type allows user-mode processes to participate in the kernel .Xr netgraph 4 networking subsystem using the .Bx -socket interface. The process must have +socket interface. +The process must have root privileges to be able to create netgraph sockets however once created, any process that has one may use it. .Pp @@ -75,8 +76,8 @@ are received by the process, using .Xr recvfrom 2 ; the socket address argument is a .Dv "struct sockaddr_ng" -containing the sender's netgraph address. Conversely, control messages -can be sent to any node by calling +containing the sender's netgraph address. +Conversely, control messages can be sent to any node by calling .Xr sendto 2 , supplying the recipient's address in a .Dv "struct sockaddr_ng" . @@ -94,9 +95,11 @@ node. .Dv NG_DATA sockets do not automatically have nodes associated with them; they are bound to a specific node via the .Xr connect 2 -system call. The address argument is the netgraph address of the +system call. +The address argument is the netgraph address of the .Nm -node already created. Once a data socket is associated with a node, +node already created. +Once a data socket is associated with a node, any data packets received by the node are read using .Xr recvfrom 2 and any packets to be sent out from the node are written using @@ -132,7 +135,8 @@ if it had received a message. Attempts to access the sockets associated will return .Er ENOTCONN . .It Dv NGM_SOCK_CMD_LINGER -This is the default mode. When the last hook is removed, the node will +This is the default mode. +When the last hook is removed, the node will continue to exist, ready to accept new hooks until it is explicitly shut down. .El @@ -152,7 +156,8 @@ and .Dv NG_DATA sockets have been closed, or a .Dv NGM_SHUTDOWN -control message is received. In the latter case, attempts to write +control message is received. +In the latter case, attempts to write to the still-open sockets will return .Er ENOTCONN . If the @@ -164,9 +169,9 @@ It is not possible to reject the connection of a hook, though any data received on that hook can certainly be ignored. .Pp The controlling process is not notified of all events that an in-kernel node -would be notified of, e.g. a new hook, or hook removal. We should define -some node-initiated messages for this purpose (to be sent up the control -socket). +would be notified of, e.g. a new hook, or hook removal. +Some node-initiated messages should be defined for this purpose (to be +sent up the control socket). .Sh SEE ALSO .Xr socket 2 , .Xr netgraph 3 , diff --git a/share/man/man4/ng_vjc.4 b/share/man/man4/ng_vjc.4 index 8a7bd16..cadffd0 100644 --- a/share/man/man4/ng_vjc.4 +++ b/share/man/man4/ng_vjc.4 @@ -56,10 +56,11 @@ hook represents the uncompressed side of the node, while the .Dv vjuncomp , and .Dv vjip -hooks represent the compressed side of the node. Packets received on the +hooks represent the compressed side of the node. +Packets received on the .Dv ip -will be compressed or passed through as appropriate. Packets received -on the other three hooks will be uncompressed as appropriate. +will be compressed or passed through as appropriate. +Packets received on the other three hooks will be uncompressed as appropriate. This node also supports .Dq always pass through mode in either direction. @@ -70,7 +71,8 @@ Only (i.e., common case) TCP packets are actually compressed. These are output on the .Dv vjcomp -hook. Other TCP packets are run through the state machine but not +hook. +Other TCP packets are run through the state machine but not compressed; these appear on the .Dv vjuncomp hook. @@ -150,10 +152,12 @@ mode. When enabling compression, .Dv maxChannel should be set to the number of outgoing compression channels minus one, -and is a value between 3 and 15, inclusive. The +and is a value between 3 and 15, inclusive. +The .Dv compressCID field indicates whether it is OK to compress the CID header field for -outgoing compressed TCP packets. This value should be zero unless +outgoing compressed TCP packets. +This value should be zero unless either (a) it is not possible for an outgoing frame to be lost, or (b) lost frames can be reliably detected and immediately reported to the peer's decompression engine (see @@ -165,7 +169,8 @@ This command returns the node's current state described by the structure, which is defined in .Pa net/slcompress.h . .It Dv NGM_VJC_CLR_STATS -Clears the node statistics counters. Statistics are also cleared whenever the +Clears the node statistics counters. +Statistics are also cleared whenever the .Dv enableComp or .Dv enableDecomp @@ -178,21 +183,23 @@ this message must be sent to the local .Nm vjc node immediately after detecting that a received frame has been lost, due to a bad -checksum or for any other reason. Failing to do this can result -in corrupted TCP stream data. +checksum or for any other reason. +Failing to do this can result in corrupted TCP stream data. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh BUGS -Because the initialization routine in the kernel implementation of +As the initialization routine in the kernel implementation of Van Jacobson compression initializes both compression and decompression at once, this node does not allow compression and decompression to -be enabled in separate operations. In order to enable one when +be enabled in separate operations. +In order to enable one when the other is already enabled, first both must be disabled, then -both enabled. This of course resets the node state. This restriction -may be lifted in a later version. +both enabled. +This of course resets the node state. +This restriction may be lifted in a later version. .Pp When built as a loadable kernel module, this module includes the file .Pa net/slcompress.c . diff --git a/share/man/man4/pass.4 b/share/man/man4/pass.4 index 41d06db..e3f8c01 100644 --- a/share/man/man4/pass.4 +++ b/share/man/man4/pass.4 @@ -44,7 +44,8 @@ kernel. Since the .Nm driver allows direct access to the CAM subsystem, system administrators -should exercise caution when granting access to this driver. If used +should exercise caution when granting access to this driver. +If used improperly, this driver can allow userland applications to crash a machine or cause data loss. .Pp @@ -69,21 +70,24 @@ devices are found. .Bl -tag -width 012345678901234 .It CAMIOCOMMAND This ioctl takes most kinds of CAM CCBs and passes them through to the CAM -transport layer for action. Note that some CCB types are not allowed +transport layer for action. +Note that some CCB types are not allowed through the passthrough device, and must be sent through the .Xr xpt 4 -device instead. Some examples of xpt-only CCBs are XPT_SCAN_BUS, +device instead. +Some examples of xpt-only CCBs are XPT_SCAN_BUS, XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. These CCB types have various attributes that make it illogical or impossible to service them through the passthrough interface. .It CAMGETPASSTHRU This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device -corresponding to the device in question. Although this ioctl is available -through the +corresponding to the device in question. +Although this ioctl is available through the .Nm driver, it is of limited use, since the caller must already know that the device in question is a passthrough device if they're issuing this -ioctl. It is probably more useful to issue this ioctl through the +ioctl. +It is probably more useful to issue this ioctl through the .Xr xpt 4 device. .El @@ -92,7 +96,8 @@ device. .It Pa /dev/pass Ns Ar n Character device nodes for the .Nm -driver. There should be one of these for each device accessed through the +driver. +There should be one of these for each device accessed through the CAM subsystem. .El .Sh DIAGNOSTICS @@ -109,5 +114,6 @@ The CAM passthrough driver first appeared in .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS It might be nice to have a way to asynchronously send CCBs through the -passthrough driver. This would probably require some sort of read/write +passthrough driver. +This would probably require some sort of read/write interface or an asynchronous ioctl interface. diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 index 4701671..86e463e 100644 --- a/share/man/man4/pci.4 +++ b/share/man/man4/pci.4 @@ -37,8 +37,8 @@ The .Nm driver provides a way for userland programs to read and write .Tn PCI -configuration registers. It also provides a way for userland programs to -get a list of all +configuration registers. +It also provides a way for userland programs to get a list of all .Tn PCI devices, or all .Tn PCI @@ -51,12 +51,14 @@ driver provides a write interface for configuration registers, system administrators should exercise caution when granting access to the .Nm -device. If used improperly, this driver can allow userland applications to +device. +If used improperly, this driver can allow userland applications to crash a machine or cause data loss. .Sh KERNEL CONFIGURATION It is only necessary to specify one .Nm -controller in the kernel. Additional +controller in the kernel. +Additional .Tn PCI busses are handled automatically as they are encountered. .Sh IOCTLS @@ -64,7 +66,8 @@ The following .Xr ioctl 2 calls are supported by the .Nm -driver. They are defined in the header file +driver. +They are defined in the header file .Aq Pa sys/pciio.h . .Bl -tag -width 012345678901234 .Pp @@ -73,7 +76,8 @@ This .Xr ioctl 2 takes a .Va pci_conf_io -structure. It allows the user to retrieve information on all +structure. +It allows the user to retrieve information on all .Tn PCI devices in the system, or on .Tn PCI @@ -121,8 +125,8 @@ device ID. device class. .It flags The flags describe which of the fields the kernel should match against. -A device must match all specified fields in order to be returned. The -match flags are enumerated in the +A device must match all specified fields in order to be returned. +The match flags are enumerated in the .Va pci_getconf_flags structure. Hopefully the flag values are obvious enough that they don't need to @@ -137,8 +141,8 @@ query. .It num_matches Number of matches returned by the kernel. .It matches -Buffer containing matching devices returned by the kernel. The items in -this buffer are of type +Buffer containing matching devices returned by the kernel. +The items in this buffer are of type .Va pci_conf , which consists of the following items: .Bl -tag -width pc_subvendor @@ -179,20 +183,24 @@ Driver unit number. .El .It offset The offset is passed in by the user to tell the kernel where it should -start traversing the device list. The value passed out by the kernel -points to the record immediately after the last one returned. The user may +start traversing the device list. +The value passed out by the kernel +points to the record immediately after the last one returned. +The user may pass the value returned by the kernel in subsequent calls to the .Dv PCIOCGETCONF -ioctl. If the user does not intend to use the offset, it must be set to -zero. +ioctl. +If the user does not intend to use the offset, it must be set to zero. .It generation .Tn PCI -configuration generation. This value only needs to be set if the offset is -set. The kernel will compare the current generation number of its internal +configuration generation. +This value only needs to be set if the offset is set. +The kernel will compare the current generation number of its internal device list to the generation passed in by the user to determine whether its device list has changed since the user last called the .Dv PCIOCGETCONF -ioctl. If the device list has changed, a status of +ioctl. +If the device list has changed, a status of .Va PCI_GETCONF_LIST_CHANGED will be passed back. .It status @@ -216,17 +224,20 @@ and to zero to start over at the beginning of the list. .It PCI_GETCONF_MORE_DEVS This tells the user that his buffer was not large enough to hold all of the -remaining devices in the device list that possibly match his criteria. It -is possible for this status to be returned, even when none of the remaining +remaining devices in the device list that possibly match his criteria. +It is possible for this status to be returned, even when none of the remaining devices in the list would match the user's criteria. .It PCI_GETCONF_ERROR -This indicates a general error while servicing the user's request. If the +This indicates a general error while servicing the user's request. +If the .Va pat_buf_len is not equal to .Va num_patterns times -.Va sizeof(struct pci_match_conf) , errno -will be set to EINVAL. +.Fn sizeof "struct pci_match_conf" , +.Va errno +will be set to +.Er EINVAL . .El .El .It PCIOCREAD @@ -250,7 +261,8 @@ The .Tn PCI configuration register the user would like to access. .It pi_width -The width, in bytes, of the data the user would like to read. This value +The width, in bytes, of the data the user would like to read. +This value may be either 1, 2, or 4. 3-byte reads and reads larger than 4 bytes are not supported. If an invalid width is passed, errno will be set to EINVAL. .It pi_data @@ -265,7 +277,8 @@ specified in the passed-in .Va pci_io structure. The .Va pci_io -structure is described above. The limitations on data width described for +structure is described above. +The limitations on data width described for reading registers, above, also apply to writing .Tn PCI configuration registers. @@ -299,6 +312,7 @@ It isn't possible for users to specify an accurate offset into the device list without calling the .Dv PCIOCGETCONF at least once, since they have no way of knowing the current generation -number otherwise. This probably isn't a serious problem, though, since +number otherwise. +This probably isn't a serious problem, though, since users can easily narrow their search by specifying a pattern or patterns for the kernel to match against. diff --git a/share/man/man4/pcm.4 b/share/man/man4/pcm.4 index a6cc530..b6e167c 100644 --- a/share/man/man4/pcm.4 +++ b/share/man/man4/pcm.4 @@ -83,8 +83,10 @@ binaries). A few differences exist (the most important one is the ability to use memory-mapped access to the audio buffers). As a consequence, some applications may need to be recompiled with a slightly modified -audio module. See /usr/include/sys/soundcard.h for a complete -list of the supported ioctls. +audio module. +See +.Aq Pa sys/soundcard.h +for a complete list of the supported ioctls. .Sh SUPPORTED CARDS Below we include a list of supported codecs/cards. If your sound card diff --git a/share/man/man4/polling.4 b/share/man/man4/polling.4 index 949726a..73d5f8c 100644 --- a/share/man/man4/polling.4 +++ b/share/man/man4/polling.4 @@ -105,7 +105,7 @@ See the conditionally compiled sections of the devices mentioned above for more details. .Pp -Because in the worst case devices are only polled on +As in the worst case devices are only polled on clock interrupts, in order to reduce the latency in processing packets, it is advisable to increase the frequency of the clock to at least 1000 HZ. diff --git a/share/man/man4/ppi.4 b/share/man/man4/ppi.4 index 4609bfa..65b4135 100644 --- a/share/man/man4/ppi.4 +++ b/share/man/man4/ppi.4 @@ -51,10 +51,11 @@ All I/O on the .Nm interface is performed using .Fn ioctl -calls. Each command takes a single +calls. +Each command takes a single .Ft u_int8_t -argument, transferring one byte of data. The following commands are -available: +argument, transferring one byte of data. +The following commands are available: .Bl -tag -width indent .It Dv PPIGDATA , PPISDATA Get and set the contents of the data register. @@ -62,8 +63,8 @@ Get and set the contents of the data register. Get and set the contents of the status register. .It Dv PPIGCTRL , PPISCTRL Get and set the contents of the control register. -The following defines correspond to bits in this register. Setting -a bit in the control register drives the corresponding output low. +The following defines correspond to bits in this register. +Setting a bit in the control register drives the corresponding output low. .Bl -tag -width indent -compact .It Dv STROBE .It Dv AUTOFEED diff --git a/share/man/man4/ppp.4 b/share/man/man4/ppp.4 index c99ae20a..4e9ad61 100644 --- a/share/man/man4/ppp.4 +++ b/share/man/man4/ppp.4 @@ -47,7 +47,8 @@ The .Nm interface allows serial lines to be used as network interfaces using the .Em point-to-point -protocol. The +protocol. +The .Nm interface can use various types of compression and has many features over the diff --git a/share/man/man4/psm.4 b/share/man/man4/psm.4 index 2248f3e..e54aaef 100644 --- a/share/man/man4/psm.4 +++ b/share/man/man4/psm.4 @@ -496,7 +496,8 @@ The field holds a value to control acceleration feature (see .Sx Acceleration ) . -It must be zero or greater. If it is zero, acceleration is disabled. +It must be zero or greater. +If it is zero, acceleration is disabled. .Pp The .Dv packetsize diff --git a/share/man/man4/pt.4 b/share/man/man4/pt.4 index 81ef4e7..112b561 100644 --- a/share/man/man4/pt.4 +++ b/share/man/man4/pt.4 @@ -38,8 +38,8 @@ The .Nm driver provides support for a .Tn SCSI -processor type device. These are usually scanners and other -devices using the +processor type device. +These are usually scanners and other devices using the .Tn SCSI link as a communication interface with device specific commands embedded in the data stream. @@ -68,11 +68,13 @@ driver. They are defined in the header file .It PTIOCGETTIMEOUT This ioctl allows userland applications to fetch the current .Nm -driver read and write timeout. The value returned is in seconds. +driver read and write timeout. +The value returned is in seconds. .It PTIOCSETTIMEOUT This ioctl allows userland applications to set the current .Nm -driver read and write timeouts. The value should be in seconds. +driver read and write timeouts. +The value should be in seconds. .El .Sh FILES .Bl -tag -width /dev/ptQQQ -compact diff --git a/share/man/man4/pty.4 b/share/man/man4/pty.4 index 7acc436..925bd73 100644 --- a/share/man/man4/pty.4 +++ b/share/man/man4/pty.4 @@ -49,8 +49,8 @@ A pseudo terminal is a pair of character devices, a .Em master device and a .Em slave -device. The slave device provides to a process -an interface identical +device. +The slave device provides to a process an interface identical to that described in .Xr tty 4 . However, whereas all other devices which provide the @@ -82,10 +82,11 @@ Takes no parameter. .It Dv TIOCPKT Enable/disable .Em packet -mode. Packet mode is enabled by specifying (by reference) +mode. +Packet mode is enabled by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) -a zero parameter. When applied to the master side of a pseudo -terminal, each subsequent +a zero parameter. +When applied to the master side of a pseudo terminal, each subsequent .Xr read 2 from the terminal will return data written on the slave part of the pseudo terminal preceded by a zero byte (symbolically @@ -180,9 +181,10 @@ of .Dv TIOCPKT . This mode causes input to the pseudo terminal to be flow controlled and not input edited (regardless of the -terminal mode). Each write to the control terminal produces -a record boundary for the process reading the terminal. In -normal usage, a write of data is like the data typed as a line +terminal mode). +Each write to the control terminal produces +a record boundary for the process reading the terminal. +In normal usage, a write of data is like the data typed as a line on the terminal; a write of 0 bytes is like typing an end-of-file character. .Dv TIOCREMOTE diff --git a/share/man/man4/route.4 b/share/man/man4/route.4 index 6f4915f..2db2f8d 100644 --- a/share/man/man4/route.4 +++ b/share/man/man4/route.4 @@ -79,9 +79,11 @@ Normally the protocol specifies the route through each interface as a .Dq direct connection to the destination host -or network. If the route is direct, the transport layer of +or network. +If the route is direct, the transport layer of a protocol family usually requests the packet be sent to the -same host specified in the packet. Otherwise, the interface +same host specified in the packet. +Otherwise, the interface is requested to address the packet to the gateway listed in the routing entry (i.e. the packet is forwarded). .Pp @@ -100,7 +102,8 @@ A wildcard routing entry is specified with a zero destination address value, and a mask of all zeroes. Wildcard routes will be used when the system fails to find other routes matching the -destination. The combination of wildcard +destination. +The combination of wildcard routes and routing redirects can provide an economical mechanism for routing traffic. .Pp @@ -131,10 +134,11 @@ bit mask within the header, and the sequence is least significant to most significant bit within the vector. .Pp Any messages sent to the kernel are returned, and copies are sent -to all interested listeners. The kernel will provide the process +to all interested listeners. +The kernel will provide the process ID for the sender, and the sender may use an additional sequence -field to distinguish between outstanding messages. However, -message replies may be lost when kernel buffers are exhausted. +field to distinguish between outstanding messages. +However, message replies may be lost when kernel buffers are exhausted. .Pp The kernel may reject certain messages, and will indicate this by filling in the diff --git a/share/man/man4/sa.4 b/share/man/man4/sa.4 index 9bf36f0..529bb46 100644 --- a/share/man/man4/sa.4 +++ b/share/man/man4/sa.4 @@ -57,11 +57,13 @@ The driver is based around the concept of a .Dq Em mount session , which is defined as the period between the time that a tape is -mounted, and the time when it is unmounted. Any parameters set during +mounted, and the time when it is unmounted. +Any parameters set during a mount session remain in effect for the remainder of the session or until replaced. The tape can be unmounted, bringing the session to a -close in several ways. These include: +close in several ways. +These include: .Bl -enum .It Closing a `rewind device', @@ -112,16 +114,17 @@ or block-size modes. Most .Tn QIC Ns -type devices run in fixed block-size mode, where most nine-track tapes and -many new cartridge formats allow variable block-size. The difference -between the two is as follows: +many new cartridge formats allow variable block-size. +The difference between the two is as follows: .Bl -inset .It Variable block-size: Each write made to the device results in a single logical record -written to the tape. One can never read or write +written to the tape. +One can never read or write .Em part of a record from tape (though you may request a larger block and read -a smaller record); nor can one read multiple blocks. Data from a -single write is therefore read by a single read. +a smaller record); nor can one read multiple blocks. +Data from a single write is therefore read by a single read. The block size used may be any value supported by the device, the .Tn SCSI @@ -136,19 +139,23 @@ but it was never read, then the next process to read will immediately hit the file mark and receive an end-of-file notification. .It Fixed block-size: Data written by the user is passed to the tape as a succession of -fixed size blocks. It may be contiguous in memory, but it is +fixed size blocks. +It may be contiguous in memory, but it is considered to be a series of independent blocks. One may never write -an amount of data that is not an exact multiple of the blocksize. One -may read and write the same data as a different set of records, In -other words, blocks that were written together may be read separately, +an amount of data that is not an exact multiple of the blocksize. +One may read and write the same data as a different set of records. +In other words, blocks that were written together may be read separately, and vice-versa. .Pp If one requests more blocks than remain in the file, the drive will -encounter the file mark. Because there is some data to return (unless +encounter the file mark. +As there is some data to return (unless there were no records before the file mark), the read will succeed, -returning that data, The next read will return immediately with a value -of 0. (As above, if the file mark is never read, it remains for the next +returning that data. +The next read will return immediately with a value +of 0. +(As above, if the file mark is never read, it remains for the next process to read if in no-rewind mode.) .El .Sh FILE MARK HANDLING @@ -156,15 +163,19 @@ The handling of file marks on write is automatic. If the user has written to the tape, and has not done a read since the last write, then a file mark will be written to the tape when the device is -closed. If a rewind is requested after a write, then the driver +closed. +If a rewind is requested after a write, then the driver assumes that the last file on the tape has been written, and ensures -that there are two file marks written to the tape. The exception to +that there are two file marks written to the tape. +The exception to this is that there seems to be a standard (which we follow, but don't understand why) that certain types of tape do not actually write two file marks to tape, but when read, report a `phantom' file mark when the -last file is read. These devices include the QIC family of devices. +last file is read. +These devices include the QIC family of devices. (It might be that this set of devices is the same set as that of fixed -block devices. This has not been determined yet, and they are treated +block devices. +This has not been determined yet, and they are treated as separate behaviors by the driver at this time.) .Sh IOCTLS The @@ -210,13 +221,17 @@ None. .Sh SEE ALSO .Xr mt 1 , .Xr scsi 4 -.Sh HISTORY +.Sh AUTHORS +.An -nosplit The .Nm driver was written for the .Tn CAM .Tn SCSI -subsystem by Justin T. Gibbs and Kenneth Merry. +subsystem by +.An Justin T. Gibbs +and +.An Kenneth Merry . Many ideas were gleaned from the .Nm st device driver written and ported from diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4 index 4e25a20..c8e125d 100644 --- a/share/man/man4/scsi.4 +++ b/share/man/man4/scsi.4 @@ -61,7 +61,8 @@ host adapters through host adapter drivers. When the system probes the .Tn SCSI busses, it attaches any devices it finds to the appropriate -drivers. The +drivers. +The .Xr pass 4 driver, if it is configured in the kernel, will attach to all .Tn SCSI @@ -73,27 +74,34 @@ CAM subsystem: .Bl -tag -width SCSI_NO_SENSE_STRINGS .It Dv CAMDEBUG -This option enables the CAM debugging printf code. This won't actually +This option enables the CAM debugging printf code. +This won't actually cause any debugging information to be printed out when included by itself. -Enabling printouts requires additional configuration. See below for -details. +Enabling printouts requires additional configuration. +See below for details. .It Dv "CAM_MAX_HIGHPOWER=4" This sets the maximum allowable number of concurrent "high power" commands. A "high power" command is a command that takes more electrical power than -most to complete. An example of this (and the only command currently +most to complete. +An example of this (and the only command currently tagged as "high power") is the .Tn SCSI -START UNIT command. Starting a SCSI disk often takes significantly more -electrical power than normal operation of the disk. This option allows the +START UNIT command. +Starting a SCSI disk often takes significantly more +electrical power than normal operation of the disk. +This option allows the user to specify how many concurrent high power commands may be outstanding without overloading the power supply on his computer. .It Dv SCSI_NO_SENSE_STRINGS This eliminates text descriptions of each .Tn SCSI -Additional Sense Code and Additional Sense Code Qualifier pair. Since this +Additional Sense Code and Additional Sense Code Qualifier pair. +Since this is a fairly large text database, eliminating it reduces the size of the -kernel somewhat. This is primarily necessary for boot floppies and other -low disk space or low memory space environments. In most cases, though, +kernel somewhat. +This is primarily necessary for boot floppies and other +low disk space or low memory space environments. +In most cases, though, this should be enabled, since it speeds the interpretation of .Tn SCSI error messages. Don't let the "kernel bloat" zealots get to you -- leave @@ -101,7 +109,8 @@ the sense descriptions in your kernel! .It Dv SCSI_NO_OP_STRINGS This disables text descriptions of each .Tn SCSI -opcode. This option, like the sense string option above, is primarily +opcode. +This option, like the sense string option above, is primarily useful for environments like a boot floppy where kernel size is critical. Enabling this option for normal use isn't recommended, since it slows debugging of @@ -110,25 +119,31 @@ problems. .It Dv SCSI_DELAY=8000 This is the .Tn SCSI -"bus settle delay." In CAM, it is specified in +"bus settle delay." +In CAM, it is specified in .Em milliseconds , not seconds like the old .Tn SCSI -layer used to do. When the kernel boots, it sends a bus reset to each +layer used to do. +When the kernel boots, it sends a bus reset to each .Tn SCSI bus to tell each device to reset itself to a default set of transfer -negotiations and other settings. Most +negotiations and other settings. +Most .Tn SCSI -devices need some amount of time to recover from a bus reset. Newer disks +devices need some amount of time to recover from a bus reset. +Newer disks may need as little as 100ms, while old, slow devices may need much longer. If the .Dv SCSI_DELAY -isn't specified, it defaults to 2 seconds. The minimum allowable value for +isn't specified, it defaults to 2 seconds. +The minimum allowable value for .Dv SCSI_DELAY -is "100", or 100ms. One special case is that if the +is "100", or 100ms. +One special case is that if the .Dv SCSI_DELAY -is set to 0, that will be taken to mean the "lowest possible value." In -that case, the +is set to 0, that will be taken to mean the "lowest possible value." +In that case, the .Dv SCSI_DELAY will be reset to 100ms. .El @@ -164,7 +179,8 @@ which assigns scbus 1 to the second bus probed on the ahc1 device. .Pp When you have a mixture of wired down and counted devices then the counting begins with the first non-wired down unit for a particular -type. That is, if you have a disk wired down as +type. +That is, if you have a disk wired down as .Em "device da1" , then the first non-wired disk shall come on line as .Em da2 . @@ -215,34 +231,41 @@ Some of these flags, most notably .Dv CAM_DEBUG_TRACE and .Dv CAM_DEBUG_SUBTRACE -will produce kernel printfs in EXTREME numbers. Because of that, they -aren't especially useful. There aren't many things logged at the +will produce kernel printfs in EXTREME numbers, +and because of that, they aren't especially useful. +There aren't many things logged at the .Dv CAM_DEBUG_INFO -level, so it isn't especially useful. The most useful debugging flag is -the +level, so it isn't especially useful. +The most useful debugging flag is the .Dv CAM_DEBUG_CDB flag. Users can enable debugging from their kernel config file, by using the following kernel config options: .Bl -tag -width CAM_DEBUG_TARGET .It Dv CAMDEBUG -This enables CAM debugging. Without this option, users will not even be able +This enables CAM debugging. +Without this option, users will not even be able to turn on debugging from userland via .Xr camcontrol 8 . .It Dv CAM_DEBUG_FLAGS This allows the user to set the various debugging flags described above -in a kernel config file. Flags may be ORed together if the user wishes to +in a kernel config file. +Flags may be ORed together if the user wishes to see printfs for multiple debugging levels. .It Dv CAM_DEBUG_BUS -Specify a bus to debug. To debug all busses, set this to -1. +Specify a bus to debug. +To debug all busses, set this to -1. .It Dv CAM_DEBUG_TARGET -Specify a target to debug. To debug all targets, set this to -1. +Specify a target to debug. +To debug all targets, set this to -1. .It Dv CAM_DEBUG_LUN -Specify a lun to debug. To debug all luns, set this to -1. +Specify a lun to debug. +To debug all luns, set this to -1. .El .Pp When specifying a bus, target or lun to debug, you .Em MUST -specify all three bus/target/lun options above. Using wildcards, you +specify all three bus/target/lun options above. +Using wildcards, you should be able to enable debugging on most anything. .Pp Users may also enable debugging printfs on the fly, if the diff --git a/share/man/man4/si.4 b/share/man/man4/si.4 index d2260bb..8b6c357 100644 --- a/share/man/man4/si.4 +++ b/share/man/man4/si.4 @@ -21,8 +21,9 @@ The system uses two components: A "Host adapter", which is plugged into an ISA, EISA or PCI slot and provides intelligence and buffering/processing capabilities, as well as an external bus in the form of a 37 pin cable. .Pp -On this cable, "modules" are connected. The "SI" module comes in a 4 and 8 -port version. The "XIO" and "SX" modules come only in +On this cable, "modules" are connected. +The "SI" module comes in a 4 and 8 port version. +The "XIO" and "SX" modules come only in 8 port versions. .Pp The host adapter polls and transfers data between the modules and the rest @@ -40,9 +41,10 @@ SI or XIO modules are supported on any host card. .Pp The host adapter uses a shared memory block in the traditional ISA bus -"hole" between 0xA0000 and 0xEFFFF. The adapter can be configured outside -range, but requires the memory range to be explicitly non-cached. The -driver does not yet support this mode of operation. +"hole" between 0xA0000 and 0xEFFFF. +The adapter can be configured outside +range, but requires the memory range to be explicitly non-cached. +The driver does not yet support this mode of operation. .Pp SX ISA Host cards have an 8/16 bit mode switch or jumper on them. This switch @@ -71,8 +73,10 @@ poll intervals as if they were interrupts. An open on a /dev device node controlled by the si driver obeys the same semantics as the .Xr sio 4 -driver. It fully supports the usual semantics of the cua ports, and the -"initial termios" and "locked termios" settings. In summary, an open on a +driver. +It fully supports the usual semantics of the cua ports, and the +"initial termios" and "locked termios" settings. +In summary, an open on a tty port will block until DCD is raised, unless O_NONBLOCK is specified. CLOCAL is honored. An open on a cua port will always succeed, but DCD transitions will be honored after DCD rises for the first time. @@ -105,7 +109,8 @@ settings from being changed. .Pp To manipulate the initial/locked settings, the .Xr stty 1 -command is useful. When setting the "locked" variables, enabling the mode +command is useful. +When setting the "locked" variables, enabling the mode on the lock device will lock the termios mode, while disabling the mode will unlock it. .Sh FILES @@ -158,7 +163,8 @@ The interrupt tuning rate is not believed to be optimal at this time for maximum efficiency. .Pp Polled mode (a feature of standard Specialix drivers) is not implemented, -but it can be approximated by turning on machdep.si_realpoll. The poll +but it can be approximated by turning on machdep.si_realpoll. +The poll frequency is set by machdep.si_pollrate (in units of 1/100th of a second). .Pp The driver does not yet support baud rates higher than 115,200 on SX diff --git a/share/man/man4/sio.4 b/share/man/man4/sio.4 index adf623f..864714c 100644 --- a/share/man/man4/sio.4 +++ b/share/man/man4/sio.4 @@ -196,13 +196,14 @@ driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based .Tn RS-232C .Pf ( Tn CCITT .Tn V.24 ) -communications interfaces. The NS8250 and NS16450 have single character +communications interfaces. +The NS8250 and NS16450 have single character buffers, the NS16550A has 16 character FIFO input and output buffers. .Pp Input and output for each line may set to one of following baud rates; 50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600, -19200, 28800, 38400, 57600, or 115200. Your hardware may limit your baud -rate choices. +19200, 28800, 38400, 57600, or 115200. +Your hardware may limit your baud rate choices. .Pp The driver supports `multiport' cards. Multiport cards are those that have one or more groups of ports @@ -313,10 +314,11 @@ in the normal way on the initial-state devices to program initial termios states suitable for your setup. .Pp The lock termios state acts as flags to disable changing -the termios state. E.g., to lock a flag variable such as -CRTSCTS, use +the termios state. +E.g., to lock a flag variable such as CRTSCTS, use .Em stty crtscts -on the lock-state device. Speeds and special characters +on the lock-state device. +Speeds and special characters may be locked by setting the corresponding value in the lock-state device to any nonzero value. .Pp @@ -329,12 +331,14 @@ should be set to suit the devices attached and may need to be locked to prevent buggy programs from changing them. E.g., CRTSCTS should be locked on for devices that support RTS/CTS handshaking at all times and off for devices that don't -support it at all. CLOCAL should be locked on for devices -that don't support carrier. HUPCL may be locked off if you don't -want to hang up for some reason. In general, very bad things happen +support it at all. +CLOCAL should be locked on for devices that don't support carrier. +HUPCL may be locked off if you don't +want to hang up for some reason. +In general, very bad things happen if something is locked to the wrong state, and things should not -be locked for devices that support more than one setting. The -CLOCAL flag on callin ports should be locked off for logins +be locked for devices that support more than one setting. +The CLOCAL flag on callin ports should be locked off for logins to avoid certain security holes, but this needs to be done by getty if the callin port is used for anything else. .Sh FILES @@ -397,8 +401,8 @@ or with too many ports on any system, or on heavily loaded systems when crtscts cannot be used. The use of NS16550A's reduces system load and helps to avoid data loss. .Pp -Stay away from plain NS16550's. These are early -implementations of the chip with non-functional FIFO hardware. +Stay away from plain NS16550's. +These are early implementations of the chip with non-functional FIFO hardware. .Pp The constants which define the locations of the various serial ports are holdovers from @@ -410,7 +414,9 @@ Note that on the AST/4 the card's dipswitches should be set to use interrupt sharing. AST/4-like interrupt sharing is only used when .Em multiple -AST/4 cards are installed in the same system. The sio driver does not -support more than 1 AST/4 on one IRQ. +AST/4 cards are installed in the same system. +The +.Nm +driver does not support more than 1 AST/4 on one IRQ. .Pp The examples in the synopsis are too vendor-specific. diff --git a/share/man/man4/sl.4 b/share/man/man4/sl.4 index c25ebab..a861b4e 100644 --- a/share/man/man4/sl.4 +++ b/share/man/man4/sl.4 @@ -47,7 +47,8 @@ The .Nm interface allows serial lines to be used as network interfaces using the .Em slip -protocol. The +protocol. +The .Nm interface can use Van Jacobson TCP header compression and ICMP filtering. This is arranged by using the various link-level flags to the @@ -60,7 +61,8 @@ Enable VJ header compression. .It Em link1 Suppress ICMP traffic. .It Em link2 -Enable VJ header compression autodetection. This will turn on the +Enable VJ header compression autodetection. +This will turn on the .Em link0 flag as soon as the first VJ-compressed packet has been seen by the driver. diff --git a/share/man/man4/smp.4 b/share/man/man4/smp.4 index 1913a1f..7877fd3 100644 --- a/share/man/man4/smp.4 +++ b/share/man/man4/smp.4 @@ -77,9 +77,11 @@ sysctl by setting its value to zero. .Sh HISTORY The .Nm -kernel's early history is not (properly) recorded. It was developed +kernel's early history is not (properly) recorded. +It was developed in a separate CVS branch until April 26, 1997, at which point it was -merged into 3.0-current. By this date 3.0-current had already been +merged into 3.0-current. +By this date 3.0-current had already been merged with Lite2 kernel code. .Pp .Fx 5.0 diff --git a/share/man/man4/syncer.4 b/share/man/man4/syncer.4 index bff7a77..30b38e4 100644 --- a/share/man/man4/syncer.4 +++ b/share/man/man4/syncer.4 @@ -87,5 +87,6 @@ process first appeared in It is possible on some systems that a .Xr sync 2 occurring simultaneously with a crash may cause -file system damage. See +file system damage. +See .Xr fsck 8 . diff --git a/share/man/man4/sysmouse.4 b/share/man/man4/sysmouse.4 index e16638d..1b8c4be 100644 --- a/share/man/man4/sysmouse.4 +++ b/share/man/man4/sysmouse.4 @@ -144,7 +144,8 @@ These commands manipulate the operation level of the mouse driver. .Pp .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw Returns the hardware information of the attached device in the following -structure. Only the +structure. +Only the .Dv iftype field is guaranteed to be filled with the correct value in the current version of the @@ -358,7 +359,8 @@ to pass mouse data to the console driver. .It Dv MOUSE_MOTIONEVENT These operations take the information in .Dv u.data -and act upon it. Mouse data will be sent to the +and act upon it. +Mouse data will be sent to the .Nm driver if it is open. .Dv MOUSE_ACTION @@ -403,7 +405,8 @@ represent movement of the mouse along respective directions. .Dv buttons tells the state of buttons. It encodes up to 31 buttons in the bit 0 though -the bit 30. If a button is held down, the corresponding bit is set. +the bit 30. +If a button is held down, the corresponding bit is set. .Pp .It Dv mode .Bd -literal diff --git a/share/man/man4/termios.4 b/share/man/man4/termios.4 index aca1194..440b66a 100644 --- a/share/man/man4/termios.4 +++ b/share/man/man4/termios.4 @@ -45,7 +45,8 @@ This describes a general terminal line discipline that is supported on tty asynchronous communication ports. .Ss Opening a Terminal Device File When a terminal file is opened, it normally causes the process to wait -until a connection is established. For most hardware, the presence +until a connection is established. +For most hardware, the presence of a connection is indicated by the assertion of the hardware .Dv CARRIER line. @@ -69,7 +70,8 @@ an application's standard input, output, and error files. .Ss Job Control in a Nutshell Every process is associated with a particular process group and session. The grouping is hierarchical: every member of a particular process group is a -member of the same session. This structuring is used in managing groups +member of the same session. +This structuring is used in managing groups of related processes for purposes of .\" .Gw "job control" ; .Em "job control" ; @@ -77,12 +79,16 @@ that is, the ability from the keyboard (or from program control) to simultaneously stop or restart a complex command (a command composed of one or more related -processes). The grouping into process groups allows delivering +processes). +The grouping into process groups allows delivering of signals that stop or start the group as a whole, along with arbitrating which process group has access to the single controlling -terminal. The grouping at a higher layer into sessions is to restrict +terminal. +The grouping at a higher layer into sessions is to restrict the job control related signals and system calls to within processes -resulting from a particular instance of a "login". Typically, a session +resulting from a particular instance of a +.Dq login . +Typically, a session is created when a user logs in, and the login terminal is setup to be the controlling terminal; all processes spawned from that login shell are in the same session, and inherit the controlling @@ -91,23 +97,32 @@ terminal. A job control shell operating interactively (that is, reading commands from a terminal) normally groups related processes together by placing them into the -same process group. A set of processes in the same process group -is collectively referred to as a "job". When the foreground process +same process group. +A set of processes in the same process group +is collectively referred to as a +.Dq job . +When the foreground process group of the terminal is the same as the process group of a particular -job, that job is said to be in the "foreground". When the process -group of the terminal is different from the process group of +job, that job is said to be in the +.Dq foreground . +When the process group of the terminal is different from the process group of a job (but is still the controlling terminal), that job is said -to be in the "background". Normally the +to be in the +.Dq background . +Normally the shell reads a command and starts the job that implements that -command. If the command is to be started in the foreground (typical), it +command. +If the command is to be started in the foreground (typical), it sets the process group of the terminal to the process group of the started job, waits for the job to complete, and then sets the process group of the terminal back to its own process -group (it puts itself into the foreground). If the job is to +group (it puts itself into the foreground). +If the job is to be started in the background (as denoted by the shell operator "&"), it never changes the process group of the terminal and doesn't wait for the job to complete (that is, it immediately attempts to read the next -command). If the job is started in the foreground, the user may +command). +If the job is started in the foreground, the user may type a key (usually .Ql \&^Z ) which generates the terminal stop signal @@ -120,17 +135,22 @@ and for placing stopped or background jobs into the foreground. .Ss Orphaned Process Groups An orphaned process group is a process group that has no process whose parent is in a different process group, yet is in the same -session. Conceptually it means a process group that doesn't have -a parent that could do anything if it were to be stopped. For example, +session. +Conceptually it means a process group that doesn't have +a parent that could do anything if it were to be stopped. +For example, the initial login shell is typically in an orphaned process group. Orphaned process groups are immune to keyboard generated stop signals and job control signals resulting from reads or writes to the controlling terminal. .Ss The Controlling Terminal -A terminal may belong to a process as its controlling terminal. Each +A terminal may belong to a process as its controlling terminal. +Each process of a session that has a controlling terminal has the same -controlling terminal. A terminal may be the controlling terminal for at -most one session. The controlling terminal for a session is allocated by +controlling terminal. +A terminal may be the controlling terminal for at +most one session. +The controlling terminal for a session is allocated by the session leader by issuing the .Dv TIOCSCTTY ioctl. A controlling terminal @@ -141,7 +161,8 @@ the process group of the session leader. .Pp The controlling terminal is inherited by a child process during a .Xr fork 2 -function call. A process relinquishes its controlling terminal when it +function call. +A process relinquishes its controlling terminal when it creates a new session with the .Xr setsid 2 function; other processes @@ -154,7 +175,8 @@ have it open. .Pp When a controlling process terminates, the controlling terminal is disassociated from the current session, allowing it to be acquired by a -new session leader. Subsequent access to the terminal by other processes +new session leader. +Subsequent access to the terminal by other processes in the earlier session will be denied, with attempts to access the terminal treated as if modem disconnect had been sensed. .Ss Terminal Access Control @@ -196,7 +218,8 @@ is set and the process is ignoring or blocking the .Dv SIGTTOU signal, the process is allowed to write to the terminal and the .Dv SIGTTOU -signal is not sent. If +signal is not sent. +If .Dv TOSTOP is set, and the process group of the writing process is orphaned, and the writing process is not ignoring @@ -224,7 +247,8 @@ which incoming data is stored by the system before being read by a process. The system imposes a limit, .Pf \&{ Dv MAX_INPUT Ns \&} , on the number of -bytes that may be stored in the input queue. The behavior of the system +bytes that may be stored in the input queue. +The behavior of the system when this limit is exceeded depends on the setting of the .Dv IMAXBEL flag in the termios @@ -234,8 +258,8 @@ is sent an .Tn ASCII .Dv BEL character each time a character is received -while the input queue is full. Otherwise, the input queue is flushed -upon receiving the character. +while the input queue is full. +Otherwise, the input queue is flushed upon receiving the character. .Pp Two general kinds of input processing are available, determined by whether the terminal device file is in canonical mode or noncanonical @@ -247,8 +271,8 @@ and .Fa c_lflag fields. Such processing can include echoing, which in general means transmitting input characters immediately back to the -terminal when they are received from the terminal. This is useful for -terminals that can operate in full-duplex mode. +terminal when they are received from the terminal. +This is useful for terminals that can operate in full-duplex mode. .Pp The manner in which data is provided to a process reading from a terminal device file is dependent on whether the terminal device file is in @@ -263,7 +287,8 @@ or If the .Dv O_NONBLOCK flag is clear, then the read request is -blocked until data is available or a signal has been received. If the +blocked until data is available or a signal has been received. +If the .Dv O_NONBLOCK flag is set, then the read request is completed, without blocking, in one of three ways: @@ -301,8 +326,10 @@ and .Dv EOL . This means that a read request will not return until an entire line has been typed, or a signal has been -received. Also, no matter how many bytes are requested in the read call, -at most one line is returned. It is not, however, necessary to +received. +Also, no matter how many bytes are requested in the read call, +at most one line is returned. +It is not, however, necessary to read a whole line at once; any number of bytes, even one, may be requested in a read without losing information. .Pp @@ -329,13 +356,16 @@ delimited by a newline or .Dv EOL character. This un-delimited -data makes up the current line. The +data makes up the current line. +The .Dv ERASE character deletes the last -character in the current line, if there is any. The +character in the current line, if there is any. +The .Dv KILL character -deletes all data in the current line, if there is any. The +deletes all data in the current line, if there is any. +The .Dv ERASE and .Dv KILL @@ -348,7 +378,8 @@ characters themselves are not placed in the input queue. .Ss Noncanonical Mode Input Processing In noncanonical mode input processing, input bytes are not assembled into -lines, and erase and kill processing does not occur. The values of the +lines, and erase and kill processing does not occur. +The values of the .Dv VMIN and .Dv VTIME @@ -370,7 +401,8 @@ transmissions. If is greater than .Dv \&{ Dv MAX_INPUT Ns \&} , the response to the -request is undefined. The four possible values for +request is undefined. +The four possible values for .Dv MIN and .Dv TIME @@ -380,8 +412,10 @@ their interactions are described below. In this case .Dv TIME serves as an inter-byte timer and is activated after -the first byte is received. Since it is an inter-byte timer, it is reset -after a byte is received. The interaction between +the first byte is received. +Since it is an inter-byte timer, it is reset +after a byte is received. +The interaction between .Dv MIN and .Dv TIME @@ -391,13 +425,16 @@ started. If .Dv MIN bytes are received before the inter-byte timer expires (remember that the timer is reset upon receipt of each byte), the read is -satisfied. If the timer expires before +satisfied. +If the timer expires before .Dv MIN bytes are received, the -characters received to that point are returned to the user. Note that if +characters received to that point are returned to the user. +Note that if .Dv TIME expires at least one byte is returned because the timer would -not have been enabled unless a byte was received. In this case +not have been enabled unless a byte was received. +In this case .Pf \&( Dv MIN > 0, .Dv TIME @@ -406,8 +443,8 @@ not have been enabled unless a byte was received. In this case and .Dv TIME mechanisms are -activated by the receipt of the first byte, or a signal is received. If -data is in the buffer at the time of the +activated by the receipt of the first byte, or a signal is received. +If data is in the buffer at the time of the .Fn read , the result is as if data had been received immediately after the @@ -418,13 +455,14 @@ In this case, since the value of is zero, the timer plays no role and only .Dv MIN -is significant. A pending read is not satisfied until +is significant. +A pending read is not satisfied until .Dv MIN bytes are received (i.e., the pending read blocks until .Dv MIN bytes -are received), or a signal is received. A program that uses this case to -read record-based terminal +are received), or a signal is received. +A program that uses this case to read record-based terminal .Dv I/O may block indefinitely in the read operation. @@ -434,22 +472,27 @@ In this case, since = 0, .Dv TIME no longer represents an inter-byte -timer. It now serves as a read timer that is activated as soon as the -read function is processed. A read is satisfied as soon as a single -byte is received or the read timer expires. Note that in this case if -the timer expires, no bytes are returned. If the timer does not +timer. +It now serves as a read timer that is activated as soon as the +read function is processed. +A read is satisfied as soon as a single +byte is received or the read timer expires. +Note that in this case if the timer expires, no bytes are returned. +If the timer does not expire, the only way the read can be satisfied is if a byte is received. In this case the read will not block indefinitely waiting for a byte; if no byte is received within .Dv TIME Ns *0.1 seconds after the read is initiated, -the read returns a value of zero, having read no data. If data is +the read returns a value of zero, having read no data. +If data is in the buffer at the time of the read, the timer is started as if data had been received immediately after the read. .Ss Case D: MIN = 0, TIME = 0 The minimum of either the number of bytes requested or the number of bytes currently available is returned without waiting for more -bytes to be input. If no characters are available, read returns a +bytes to be input. +If no characters are available, read returns a value of zero, having read no data. .Ss Writing Data and Output Processing When a process writes one or more bytes to a terminal device file, they @@ -475,7 +518,8 @@ Special character on input and is recognized if the .Dv ISIG flag (see the .Sx "Local Modes" -section) is enabled. Generates a +section) is enabled. +Generates a .Dv SIGINT signal which is sent to all processes in the foreground process group for which the terminal is the controlling @@ -488,11 +532,13 @@ discarded when processed. .It Dv QUIT Special character on input and is recognized if the .Dv ISIG -flag is enabled. Generates a +flag is enabled. +Generates a .Dv SIGQUIT signal which is sent to all processes in the foreground process group -for which the terminal is the controlling terminal. If +for which the terminal is the controlling terminal. +If .Dv ISIG is set, the .Dv QUIT @@ -501,7 +547,8 @@ processed. .It Dv ERASE Special character on input and is recognized if the .Dv ICANON -flag is set. Erases the last character in the +flag is set. +Erases the last character in the current line; see .Sx "Canonical Mode Input Processing" . It does not erase beyond @@ -510,7 +557,8 @@ the start of a line, as delimited by an .Dv EOF , or .Dv EOL -character. If +character. +If .Dv ICANON is set, the .Dv ERASE @@ -519,13 +567,15 @@ discarded when processed. .It Dv KILL Special character on input and is recognized if the .Dv ICANON -flag is set. Deletes the entire line, as +flag is set. +Deletes the entire line, as delimited by a .Dv NL , .Dv EOF , or .Dv EOL -character. If +character. +If .Dv ICANON is set, the .Dv KILL @@ -533,17 +583,19 @@ character is discarded when processed. .It Dv EOF Special character on input and is recognized if the .Dv ICANON -flag is set. When received, all the bytes +flag is set. +When received, all the bytes waiting to be read are immediately passed to the process, without waiting for a newline, and the .Dv EOF -is discarded. Thus, if there are no bytes waiting (that -is, the +is discarded. +Thus, if there are no bytes waiting (that is, the .Dv EOF occurred at the beginning of a line), a byte count of zero is returned from the .Fn read , -representing an end-of-file indication. If +representing an end-of-file indication. +If .Dv ICANON is set, the @@ -552,13 +604,14 @@ character is discarded when processed. .It Dv NL Special character on input and is recognized if the .Dv ICANON -flag is set. It is the line delimiter +flag is set. +It is the line delimiter .Ql \&\en . .It Dv EOL Special character on input and is recognized if the .Dv ICANON -flag is set. Is an additional line delimiter, -like +flag is set. +Is an additional line delimiter, like .Dv NL . .It Dv SUSP If the @@ -580,8 +633,9 @@ recognized if the (output control) or .Dv IXOFF (input -control) flag is set. Can be used to temporarily -suspend output. It is useful with fast terminals to +control) flag is set. +Can be used to temporarily suspend output. +It is useful with fast terminals to prevent output from disappearing before it can be read. If .Dv IXON @@ -596,8 +650,8 @@ recognized if the (output control) or .Dv IXOFF (input -control) flag is set. Can be used to resume output that -has been suspended by a +control) flag is set. +Can be used to resume output that has been suspended by a .Dv STOP character. If .Dv IXON @@ -611,7 +665,8 @@ flag is set; it is the .Ql \&\er , as denoted in the .Tn \&C -Standard {2}. When +Standard {2}. +When .Dv ICANON and .Dv ICRNL @@ -638,12 +693,14 @@ character. Same function as .It Dv WERASE Special character on input and is recognized if the .Dv ICANON -flag is set. Erases the last word in the current -line according to one of two algorithms. If the +flag is set. +Erases the last word in the current line according to one of two algorithms. +If the .Dv ALTWERASE flag is not set, first any preceding whitespace is erased, and then the maximal sequence of non-whitespace -characters. If +characters. +If .Dv ALTWERASE is set, first any preceding whitespace is erased, and then the maximal sequence @@ -651,13 +708,13 @@ of alphabetic/underscores or non alphabetic/underscores. As a special case in this second algorithm, the first previous non-whitespace character is skipped in determining whether the preceding word is a sequence of -alphabetic/underscores. This sounds confusing but turns -out to be quite practical. +alphabetic/underscores. +This sounds confusing but turns out to be quite practical. .It Dv REPRINT Special character on input and is recognized if the .Dv ICANON -flag is set. Causes the current input edit line -to be retyped. +flag is set. +Causes the current input edit line to be retyped. .It Dv DSUSP Has similar actions to the .Dv SUSP @@ -672,20 +729,22 @@ controlling terminal. .It Dv LNEXT Special character on input and is recognized if the .Dv IEXTEN -flag is set. Receipt of this character causes the next -character to be taken literally. +flag is set. +Receipt of this character causes the next character to be taken literally. .It Dv DISCARD Special character on input and is recognized if the .Dv IEXTEN -flag is set. Receipt of this character toggles the flushing -of terminal output. +flag is set. +Receipt of this character toggles the flushing of terminal output. .It Dv STATUS Special character on input and is recognized if the .Dv ICANON -flag is set. Receipt of this character causes a +flag is set. +Receipt of this character causes a .Dv SIGINFO signal to be sent to the foreground process group of the -terminal. Also, if the +terminal. +Also, if the .Dv NOKERNINFO flag is not set, it causes the kernel to write a status message to the terminal @@ -724,12 +783,14 @@ field for the terminal, the .Dv SIGHUP signal is sent to the controlling -process associated with the terminal. Unless other arrangements have +process associated with the terminal. +Unless other arrangements have been made, this causes the controlling process to terminate. Any subsequent call to the .Fn read function returns the value zero, -indicating end of file. Thus, processes that read a terminal +indicating end of file. +Thus, processes that read a terminal file and test for end-of-file can terminate appropriately after a disconnect. .\" If the @@ -752,7 +813,8 @@ until the device is closed. .Sh General Terminal Interface .Ss Closing a Terminal Device File The last process to close a terminal device file causes any output -to be sent to the device and any input to be discarded. Then, if +to be sent to the device and any input to be discarded. +Then, if .Dv HUPCL is set in the control modes, and the communications port supports a disconnect function, the terminal device performs a disconnect. @@ -763,8 +825,8 @@ characteristics do so by using the termios structure as defined in the header .Aq Pa termios.h . This structure contains minimally four scalar elements of bit flags -and one array of special characters. The scalar flag elements are -named: +and one array of special characters. +The scalar flag elements are named: .Fa c_iflag , .Fa c_oflag , .Fa c_cflag , @@ -812,16 +874,19 @@ following masks: .Pp In the context of asynchronous serial data transmission, a break condition is defined as a sequence of zero-valued bits that continues for -more than the time to send one byte. The entire sequence of zero-valued +more than the time to send one byte. +The entire sequence of zero-valued bits is interpreted as a single break condition, even if it continues for -a time equivalent to more than one byte. In contexts other than +a time equivalent to more than one byte. +In contexts other than asynchronous serial data transmission the definition of a break condition is implementation defined. .Pp If .Dv IGNBRK is set, a break condition detected on input is ignored, that -is, not put on the input queue and therefore not read by any process. If +is, not put on the input queue and therefore not read by any process. +If .Dv IGNBRK is not set and .Dv BRKINT @@ -830,7 +895,8 @@ input and output queues and if the terminal is the controlling terminal of a foreground process group, the break condition generates a single .Dv SIGINT -signal to that foreground process group. If neither +signal to that foreground process group. +If neither .Dv IGNBRK nor .Dv BRKINT @@ -881,11 +947,13 @@ break) is given to the application as a single character .Pp If .Dv INPCK -is set, input parity checking is enabled. If +is set, input parity checking is enabled. +If .Dv INPCK is not set, input parity checking is disabled, allowing output parity generation -without input parity errors. Note that whether input parity checking is +without input parity errors. +Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or disabled (see .Sx "Control Modes" ) . @@ -923,7 +991,8 @@ character. .Pp If .Dv IXON -is set, start/stop output control is enabled. A received +is set, start/stop output control is enabled. +A received .Dv STOP character suspends output and a received .Dv START @@ -940,7 +1009,8 @@ is set, and .Dv STOP characters are not -read, but merely perform flow control functions. When +read, but merely perform flow control functions. +When .Dv IXON is not set, the @@ -951,8 +1021,8 @@ characters are read. .Pp If .Dv IXOFF -is set, start/stop input control is enabled. The system shall -transmit one or more +is set, start/stop input control is enabled. +The system shall transmit one or more .Dv STOP characters, which are intended to cause the terminal device to stop transmitting data, as needed to prevent the input @@ -963,7 +1033,8 @@ and shall transmit one or more characters, which are intended to cause the terminal device to resume transmitting data, as soon as the device can continue transmitting data without risk of -overflowing the input queue. The precise conditions under which +overflowing the input queue. +The precise conditions under which .Dv STOP and START @@ -1090,7 +1161,8 @@ flow control of output */ The .Dv CSIZE bits specify the byte size in bits for both transmission and -reception. The +reception. +The .Fa c_cflag is masked with .Dv CSIZE @@ -1101,17 +1173,18 @@ values .Dv CS7 , or .Dv CS8 . -This size does not include the parity bit, if any. If +This size does not include the parity bit, if any. +If .Dv CSTOPB -is set, two stop bits are used, otherwise one stop bit. For example, at -110 baud, two stop bits are normally used. +is set, two stop bits are used, otherwise one stop bit. +For example, at 110 baud, two stop bits are normally used. .Pp If .Dv CREAD -is set, the receiver is enabled. Otherwise, no character is -received. -Not all hardware supports this bit. In fact, this flag -is pretty silly and if it were not part of the +is set, the receiver is enabled. +Otherwise, no character is received. +Not all hardware supports this bit. +In fact, this flag is pretty silly and if it were not part of the .Nm specification it would be omitted. @@ -1119,7 +1192,8 @@ it would be omitted. If .Dv PARENB is set, parity generation and detection are enabled and a parity -bit is added to each character. If parity is enabled, +bit is added to each character. +If parity is enabled, .Dv PARODD specifies odd parity if set, otherwise even parity is used. @@ -1128,12 +1202,14 @@ If .Dv HUPCL is set, the modem control lines for the port are lowered when the last process with the port open closes the port or the process -terminates. The modem connection is broken. +terminates. +The modem connection is broken. .Pp If .Dv CLOCAL is set, a connection does not depend on the state of the modem -status lines. If +status lines. +If .Dv CLOCAL is clear, the modem status lines are monitored. @@ -1141,7 +1217,8 @@ monitored. Under normal circumstances, a call to the .Fn open function waits for -the modem connection to complete. However, if the +the modem connection to complete. +However, if the .Dv O_NONBLOCK flag is set or if @@ -1227,7 +1304,8 @@ and .Pp If .Dv ECHO -is set, input characters are echoed back to the terminal. If +is set, input characters are echoed back to the terminal. +If .Dv ECHO is not set, input characters are not echoed. .Pp @@ -1239,7 +1317,8 @@ are set, the .Dv ERASE character causes the terminal to erase the last character in the current line from the display, if -possible. If there is no character to erase, an implementation may echo +possible. +If there is no character to erase, an implementation may echo an indication that this was the case or do nothing. .Pp If @@ -1301,7 +1380,8 @@ is not set. .Pp If .Dv ICANON -is set, canonical processing is enabled. This enables the +is set, canonical processing is enabled. +This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by .Dv NL , @@ -1314,12 +1394,14 @@ as described in If .Dv ICANON is not set, read requests are satisfied directly from the input -queue. A read is not satisfied until at least +queue. +A read is not satisfied until at least .Dv MIN bytes have been received or the timeout value .Dv TIME -expired between bytes. The time value +expired between bytes. +The time value represents tenths of seconds. See .Sx "Noncanonical Mode Input Processing" for more details. @@ -1332,12 +1414,15 @@ control characters .Dv QUIT , and .Dv SUSP -(job control only). If an input +(job control only). +If an input character matches one of these control characters, the function -associated with that character is performed. If +associated with that character is performed. +If .Dv ISIG is not set, no -checking is done. Thus these special input functions are possible only +checking is done. +Thus these special input functions are possible only if .Dv ISIG is set. @@ -1345,7 +1430,8 @@ is set. If .Dv IEXTEN is set, implementation-defined functions are recognized -from the input data. How +from the input data. +How .Dv IEXTEN being set interacts with @@ -1383,9 +1469,11 @@ is set, the signal .Dv SIGTTOU is sent to the process group of a process that tries to write to its controlling terminal if it is not in the foreground process group for -that terminal. This signal, by default, stops the members of the process -group. Otherwise, the output generated by that process is output to the -current output stream. Processes that are blocking or ignoring +that terminal. +This signal, by default, stops the members of the process group. +Otherwise, the output generated by that process is output to the +current output stream. +Processes that are blocking or ignoring .Dv SIGTTOU signals are excepted and allowed to produce output and the .Dv SIGTTOU @@ -1403,7 +1491,8 @@ characters (see The special control characters values are defined by the array .Fa c_cc . This table lists the array index, the corresponding special character, -and the system default value. For an accurate list of +and the system default value. +For an accurate list of the system defaults, consult the header file .Aq Pa ttydefaults.h . .Pp diff --git a/share/man/man4/ti.4 b/share/man/man4/ti.4 index dc50eed..e07b517 100644 --- a/share/man/man4/ti.4 +++ b/share/man/man4/ti.4 @@ -114,7 +114,8 @@ such as file transfers and data streaming. Header splitting support for Tigon 2 boards (this option has no effect for the Tigon 1) can be turned on with the .Dv TI_JUMBO_HDRSPLIT -option. See +option. +See .Xr zero_copy 9 for more discussion on zero copy receive and header splitting. .Pp @@ -124,8 +125,8 @@ driver normally uses jumbo receive buffers allocated by the .Xr jumbo 9 buffer allocator, but can be configured to use its own private pool of jumbo buffers that are contiguous instead of buffers from the jumbo -allocator, which are made up of multiple page sized chunks. To turn on -private jumbos, use the +allocator, which are made up of multiple page sized chunks. +To turn on private jumbos, use the .Dv TI_PRIVATE_JUMBOS option. .Pp @@ -192,7 +193,8 @@ In addition to the standard calls implemented by most network drivers, the .Nm driver also includes a character device interface that can be used for -additional diagnostics, configuration and debugging. With this character +additional diagnostics, configuration and debugging. +With this character device interface, and a specially patched version of .Xr gdb 1 , the user can @@ -210,7 +212,8 @@ ioctl.) The argument is .Vt "struct ti_stats" . .It Dv TIIOCGETPARAMS Get various performance-related firmware parameters that largely affect how -interrupts are coalesced. The argument is +interrupts are coalesced. +The argument is .Vt "struct ti_params" . .It Dv TIIOCSETPARAMS Set various performance-related firmware parameters that largely affect how @@ -221,25 +224,30 @@ Tell the NIC to trace the requested types of information. The argument is .Vt ti_trace_type . .It Dv TIIOCGETTRACE -Dump the trace buffer from the card. The argument is +Dump the trace buffer from the card. +The argument is .Vt "struct ti_trace_buf" . .It Dv ALT_ATTACH -This ioctl is used for compatibility with Alteon's Solaris driver. They -apparently only have one character interface for debugging, so they have -to tell it which Tigon instance they want to debug. This ioctl is a noop -for +This ioctl is used for compatibility with Alteon's Solaris driver. +They apparently only have one character interface for debugging, so they have +to tell it which Tigon instance they want to debug. +This ioctl is a noop for .Fx . .It Dv ALT_READ_TG_MEM -Read the requested memory region from the Tigon board. The argument is +Read the requested memory region from the Tigon board. +The argument is .Vt "struct tg_mem" . .It Dv ALT_WRITE_TG_MEM -Write to the requested memory region on the Tigon board. The argument is +Write to the requested memory region on the Tigon board. +The argument is .Vt "struct tg_mem" . .It Dv ALT_READ_TG_REG -Read the requested register on the Tigon board. The argument is +Read the requested register on the Tigon board. +The argument is .Vt "struct tg_reg" . .It Dv ALT_WRITE_TG_REG -Write to the requested register on the Tigon board. The argument is +Write to the requested register on the Tigon board. +The argument is .Vt "struct tg_reg" . .El .Sh FILES diff --git a/share/man/man4/ttcp.4 b/share/man/man4/ttcp.4 index 8b624af..d4ceab5 100644 --- a/share/man/man4/ttcp.4 +++ b/share/man/man4/ttcp.4 @@ -54,7 +54,8 @@ which permit hosts to reliably exchange a small amount of data in a two-packet exchange, thus eliminating the extra round-trip delays inherent in a standard .Tn TCP -connection. The socket interface includes modifications to support +connection. +The socket interface includes modifications to support .Tn T/TCP , detailed here for the specific case, and in the .Xr socket 2 @@ -69,11 +70,13 @@ The extensions work by including certain options in all segments of a particular connection, which enable the implementation to avoid the three-way handshake for all but the first connection between a pair of -hosts. These same options also make it possible to more reliably +hosts. +These same options also make it possible to more reliably recognize old, duplicate packets, which in turn reduces the amount of time the .Tn TCP -protocol must maintain state after a connection closes. The +protocol must maintain state after a connection closes. +The .Dq Li net.inet.tcp.rfc1644 MIB variable can be used to disable .Tn T/TCP @@ -100,10 +103,11 @@ The server program accepts the request in the same manner as for regular .Tn TCP connections, interprets it, and generates a reply which may be small -enough to fit in a single segment. If it is, the reply is sent in a +enough to fit in a single segment. +If it is, the reply is sent in a single SYN PUSH FIN ACK segment with (different) options and data back -to the client. If not, then the connection degenerates into (almost) -the usual case for +to the client. +If not, then the connection degenerates into (almost) the usual case for .Tn TCP . The server then closes its socket. .It @@ -150,12 +154,12 @@ the socket is now in the same state as if the .Xr connect 2 and .Xr shutdown 2 -system calls had been used. That is to say, the only reasonable -operations to perform on this socket are +system calls had been used. +That is to say, the only reasonable operations to perform on this socket are .Xr read 2 and .Xr close 2 . -(Because the client's +(As the client's .Tn TCP sender is already shut down, it is not possible to .Xr connect 2 @@ -185,12 +189,13 @@ extensions; simply add a call to .Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One" (where .Va One -is an integer variable with a non-zero value). The server socket must +is an integer variable with a non-zero value). +The server socket must be closed before any data is sent (unless the socket buffers fill up). .Pp The second option is preferable for new servers, and is sometimes easy -enough to retrofit into older servers. In this case, where the reply -phase would ordinarily have included a call to +enough to retrofit into older servers. +In this case, where the reply phase would ordinarily have included a call to .Fn write , one substitutes: .Pp diff --git a/share/man/man4/tty.4 b/share/man/man4/tty.4 index 26eb366..43dc28a 100644 --- a/share/man/man4/tty.4 +++ b/share/man/man4/tty.4 @@ -61,11 +61,13 @@ system when logging in over a network (using .Xr rlogin 1 , or .Xr telnet 1 -for example). Even in these cases the details of how the terminal +for example). +Even in these cases the details of how the terminal file was opened and set up is already handled by special software in the system. Thus, users do not normally need to worry about the details of -how these lines are opened or used. Also, these lines are often used +how these lines are opened or used. +Also, these lines are often used for dialing out of a system (through an out-calling modem), but again the system provides programs that hide the details of accessing these terminal special files (see @@ -78,17 +80,19 @@ the particular details of which is described in .Xr stty 1 at the command level, and in .Xr termios 4 -at the programming level. A user may be concerned with changing +at the programming level. +A user may be concerned with changing settings associated with his particular login terminal and should refer -to the preceding man pages for the common cases. The remainder of -this man page is concerned +to the preceding man pages for the common cases. +The remainder of this man page is concerned with describing details of using and controlling terminal devices at a low level, such as that possibly required by a program wishing to provide features similar to those provided by the system. .Ss Line disciplines A terminal file is used like any other file in the system in that it can be opened, read, and written to using standard system -calls. For each existing terminal file, there is a software processing module +calls. +For each existing terminal file, there is a software processing module called a .Em "line discipline" is associated with it. The @@ -99,14 +103,16 @@ level generic interface routines (such as and .Xr write 2 ) , and is responsible for implementing the semantics associated -with the device. When a terminal file is first opened by a program, -the default +with the device. +When a terminal file is first opened by a program, the default .Em "line discipline" called the .Dv termios -line discipline is associated with the file. This is the primary +line discipline is associated with the file. +This is the primary line discipline that is used in most cases and provides the semantics -that users normally associate with a terminal. When the +that users normally associate with a terminal. +When the .Dv termios line discipline is in effect, the terminal file behaves and is operated according to the rules described in @@ -125,8 +131,8 @@ hardware (or lack thereof, as in the case of ptys). .Ss Terminal File Operations All of the following operations are invoked using the .Xr ioctl 2 -system call. Refer to that man page for a description of -the +system call. +Refer to that man page for a description of the .Em request and .Em argp @@ -140,8 +146,8 @@ specific to it (actually .Xr termios 4 defines them as function calls, not ioctl .Em requests . ) -The following section lists the available ioctl requests. The -name of the request, a description of its purpose, and the typed +The following section lists the available ioctl requests. +The name of the request, a description of its purpose, and the typed .Em argp parameter (if any) are listed. For example, the first entry says @@ -245,20 +251,22 @@ Place the current number of characters in the output queue in the integer pointed to by .Fa num . .It Dv TIOCSTI Fa char *cp -Simulate typed input. Pretend as if the terminal received the -character pointed to by +Simulate typed input. +Pretend as if the terminal received the character pointed to by .Fa cp . .It Dv TIOCNOTTY Fa void -This call is obsolete but left for compatibility. In the past, when -a process that didn't have a controlling terminal (see +This call is obsolete but left for compatibility. +In the past, when a process that didn't have a controlling terminal (see .Em The Controlling Terminal in .Xr termios 4 ) first opened a terminal device, it acquired that terminal as its -controlling terminal. For some programs this was a hazard as they +controlling terminal. +For some programs this was a hazard as they didn't want a controlling terminal in the first place, and this provided a mechanism to disassociate the controlling terminal from -the calling process. It +the calling process. +It .Em must be called by opening the file .Pa /dev/tty @@ -278,8 +286,8 @@ In addition, a program can and call the .Fn setsid system call which will place the process into its own session - which -has the effect of disassociating it from the controlling terminal. This -is the new and preferred method for programs to lose their controlling +has the effect of disassociating it from the controlling terminal. +This is the new and preferred method for programs to lose their controlling terminal. .It Dv TIOCSTOP Fa void Stop output on the terminal (like typing ^S at the keyboard). @@ -291,12 +299,14 @@ must not currently have a controlling terminal). .It Dv TIOCDRAIN Fa void Wait until all output is drained. .It Dv TIOCEXCL Fa void -Set exclusive use on the terminal. No further opens are permitted -except by root. Of course, this means that programs that are run by +Set exclusive use on the terminal. +No further opens are permitted except by root. +Of course, this means that programs that are run by root (or setuid) will not obey the exclusive setting - which limits the usefulness of this feature. .It Dv TIOCNXCL Fa void -Clear exclusive use of the terminal. Further opens are permitted. +Clear exclusive use of the terminal. +Further opens are permitted. .It Dv TIOCFLUSH Fa int *what If the value of the int pointed to by .Fa what @@ -304,11 +314,11 @@ contains the .Dv FREAD bit as defined in .Aq Pa sys/file.h , -then all characters in the input queue are cleared. If it contains -the +then all characters in the input queue are cleared. +If it contains the .Dv FWRITE -bit, then all characters in the output queue are cleared. If the -value of the integer is zero, then it behaves as if both the +bit, then all characters in the output queue are cleared. +If the value of the integer is zero, then it behaves as if both the .Dv FREAD and .Dv FWRITE @@ -319,9 +329,11 @@ Put the window size information associated with the terminal in the structure pointed to by .Fa ws . The window size structure contains the number of rows and columns (and pixels -if appropriate) of the devices attached to the terminal. It is set by user software +if appropriate) of the devices attached to the terminal. +It is set by user software and is the means by which most full\&-screen oriented programs determine the -screen size. The +screen size. +The .Va winsize structure is defined in .Aq Pa sys/ioctl.h . @@ -340,13 +352,14 @@ to this terminal. If .Fa on points to a zero integer, redirect kernel console output back to the normal -console. This is usually used on workstations to redirect kernel messages +console. +This is usually used on workstations to redirect kernel messages to a particular window. .It Dv TIOCMSET Fa int *state The integer pointed to by .Fa state -contains bits that correspond to modem state. Following is a list -of defined variables and the modem state they represent: +contains bits that correspond to modem state. +Following is a list of defined variables and the modem state they represent: .Pp .Bl -tag -width TIOCMXCTS -compact .It TIOCM_LE diff --git a/share/man/man4/udp.4 b/share/man/man4/udp.4 index 1504a47..0673ece 100644 --- a/share/man/man4/udp.4 +++ b/share/man/man4/udp.4 @@ -76,7 +76,8 @@ address formats are identical to those used by In particular .Tn UDP provides a port identifier in addition -to the normal Internet address format. Note that the +to the normal Internet address format. +Note that the .Tn UDP port space is separate from the @@ -88,7 +89,8 @@ may not be .Dq connected to a .Tn TCP -port). In addition broadcast +port). +In addition broadcast packets may be sent (assuming the underlying network supports this) by using a reserved .Dq broadcast address ; @@ -148,7 +150,8 @@ listening, log the connection attempt (disabled by default). .It udp.blackhole When a datagram is received on a port where there is no socket listening, do not return an ICMP port unreachable message. -(Disabled by default. See +(Disabled by default. +See .Xr blackhole 4 . ) .El .Sh SEE ALSO |
