diff options
Diffstat (limited to 'share/man')
32 files changed, 892 insertions, 442 deletions
diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3 index 851b7a67648d..8c716b31457d 100644 --- a/share/man/man3/intro.3 +++ b/share/man/man3/intro.3 @@ -131,7 +131,8 @@ flag. .\" .It Xr libresolv Pq Fl l Ns Ar resolv .\" Routines for network address resolution. .It Xr libtermcap Pq Fl l Ns Ar termcap -The terminal independent operation library package. (See +The terminal independent operation library package. +(See .Xr termcap 3 . ) .\" .It libvt0.a .It Xr liby Pq Fl l Ns Ar y diff --git a/share/man/man4/an.4 b/share/man/man4/an.4 index 2743c6706493..65d72b1f6dbd 100644 --- a/share/man/man4/an.4 +++ b/share/man/man4/an.4 @@ -62,8 +62,10 @@ kernel pccard driver support and the daemon. ISA cards can either be configured to use ISA Plug and Play or to use a particular I/O address and IRQ -by properly setting the DIP switches on the board. (The default -switch setting is for plug and play.) The +by properly setting the DIP switches on the board. +(The default +switch setting is for plug and play.) +The .Nm driver has Plug and Play support and will work in either configuration, however when using a hard-wired I/O address and IRQ, the driver @@ -86,7 +88,8 @@ selectable between 1Mbps, 2Mbps, 5.5Mbps, 11Mbps or By default, the .Nm driver configures the Aironet card for ad-hoc operation with an SSID -of "ANY." In this mode, +of "ANY." +In this mode, stations can communicate among each other without the aid of an access point. To join a service set, the driver must be set for BSS mode using diff --git a/share/man/man4/ccd.4 b/share/man/man4/ccd.4 index 27ffa2f147ca..d93871c21cdc 100644 --- a/share/man/man4/ccd.4 +++ b/share/man/man4/ccd.4 @@ -100,7 +100,8 @@ effect is achieved, which can increase sequential read/write performance. The interleave factor is expressed in units of DEV_BSIZE (usually 512 bytes). For large writes, the optimum interleave factor is typically the size of a track, while for large reads, it is about a -quarter of a track. (Note that this changes greatly depending on the +quarter of a track. +(Note that this changes greatly depending on the number and speed of disks.) For instance, with eight 7,200 RPM drives on two Fast-Wide SCSI buses, this translates to about 128 for writes and 32 for reads. A larger interleave tends to work better when the diff --git a/share/man/man4/ch.4 b/share/man/man4/ch.4 index d000c1474d82..dea964b3c72e 100644 --- a/share/man/man4/ch.4 +++ b/share/man/man4/ch.4 @@ -70,7 +70,8 @@ In configuring, if an optional .Ar count is given in the specification, that number of SCSI media changers are configured; Most storage for them is allocated only when found -so a large number of configured devices is cheap. (once the first +so a large number of configured devices is cheap. +(once the first has included the driver). .Pp diff --git a/share/man/man4/ed.4 b/share/man/man4/ed.4 index b0818e3e1f34..1138ccd022a3 100644 --- a/share/man/man4/ed.4 +++ b/share/man/man4/ed.4 @@ -67,24 +67,31 @@ are a bit field, and are summarized as follows: .Pp .Bl -hang -offset indent .It Em 0x01 -Disable tranceiver. On those cards which support it, this flag causes the tranceiver to +Disable tranceiver. +On those cards which support it, this flag causes the tranceiver to be disabled and the AUI connection to be used by default. .It Em 0x02 -Force 8bit mode. This flag forces the card to 8bit mode regardless of how the -card identifies itself. This may be needed for some clones which incorrectly +Force 8bit mode. +This flag forces the card to 8bit mode regardless of how the +card identifies itself. +This may be needed for some clones which incorrectly identify themselves as 16bit, even though they only have an 8bit interface. .It Em 0x04 -Force 16bit mode. This flag forces the card to 16bit mode regardless of how the -card identifies itself. This may be needed for some clones which incorrectly +Force 16bit mode. +This flag forces the card to 16bit mode regardless of how the +card identifies itself. +This may be needed for some clones which incorrectly identify themselves as 8bit, even though they have a 16bit ISA interface. .It Em 0x08 -Disable transmitter multi-buffering. This flag disables the use of multiple +Disable transmitter multi-buffering. +This flag disables the use of multiple transmit buffers and may be necessary in rare cases where packets are sent out faster than a machine on the other end can handle (as evidenced by severe packet lossage). Some .Pf ( No non- Ns Tn FreeBSD :-)) machines have terrible ethernet performance -and simply can't cope with 1100K+ data rates. Use of this flag also provides +and simply can't cope with 1100K+ data rates. +Use of this flag also provides one more packet worth of receiver buffering, and on 8bit cards, this may help reduce receiver lossage. .El @@ -102,61 +109,75 @@ into the kernel) differs from the irq that has been set on the interface card. .It "ed%d: failed to clear shared memory at %x - check configuration." When the card was probed at system boot time, the .Nm ed -driver found that it could not clear the card's shared memory. This is most commonly +driver found that it could not clear the card's shared memory. +This is most commonly caused by a BIOS extension ROM being configured in the same address space as the -ethernet card's shared memory. Either find the offending card and change its BIOS +ethernet card's shared memory. +Either find the offending card and change its BIOS ROM to be at an address that doesn't conflict, or change the .Em iomem option in the kernel config file so that the card's shared memory is mapped at a non-conflicting address. .It "ed%d: Invalid irq configuration (%d) must be 2-5 for 3c503." The irq number that was specified in the kernel config file is not valid for -the 3Com 3c503 card. The 3c503 can only be assigned to irqs 2 through 5. +the 3Com 3c503 card. +The 3c503 can only be assigned to irqs 2 through 5. .It "ed%d: Cannot find start of RAM." .It "ed%d: Cannot find any RAM, start : %d, x = %d." The probe of a Gateway card was unsuccessful in configuring the card's packet memory. This likely indicates that the card was improperly recognized as a Gateway or that the card is defective. .It "ed: packets buffered, but transmitter idle." -Indicates a logic problem in the driver. Should never happen. +Indicates a logic problem in the driver. +Should never happen. .It "ed%d: device timeout" -Indicates that an expected transmitter interrupt didn't occur. Usually caused by an +Indicates that an expected transmitter interrupt didn't occur. +Usually caused by an interrupt conflict with another card on the ISA bus. .It "ed%d: NIC memory corrupt - invalid packet length %d." Indicates that a packet was received with a packet length that was either larger than -the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. Usually +the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. +Usually caused by a conflict with another card on the ISA bus, but in some cases may also indicate faulty cabling. .It "ed%d: remote transmit DMA failed to complete." This indicates that a programmed I/O transfer to an NE1000 or NE2000 style card -has failed to properly complete. Usually caused by the ISA bus speed being set +has failed to properly complete. +Usually caused by the ISA bus speed being set too fast. .El .Sh CAVEATS -Early revision DS8390 chips have problems. They lock up whenever the receive -ring-buffer overflows. They occasionally switch the byte order +Early revision DS8390 chips have problems. +They lock up whenever the receive +ring-buffer overflows. +They occasionally switch the byte order of the length field in the packet ring header (several different causes of this related to an off-by-one byte alignment) - resulting in "NIC -memory corrupt - invalid packet length" messages. The card is reset +memory corrupt - invalid packet length" messages. +The card is reset whenever these problems occur, but otherwise there is no problem with recovering from these conditions. .Pp The NIC memory access to 3Com and Novell cards is much slower than it is on WD/SMC cards; it's less than 1MB/second on 8bit boards and less than 2MB/second -on the 16bit cards. This can lead to ring-buffer overruns resulting in +on the 16bit cards. +This can lead to ring-buffer overruns resulting in dropped packets during heavy network traffic. .Pp -16bit Compex cards identify themselves as being 8bit. While these cards will +16bit Compex cards identify themselves as being 8bit. +While these cards will work in 8bit mode, much higher performance can be achieved by specifying .Em "flags 0x04" -(force 16bit mode) in your kernel config file. In addition, you should also specify +(force 16bit mode) in your kernel config file. +In addition, you should also specify .Em "iosize 16384" to take advantage of the extra 8k of shared memory that 16bit mode provides. .Sh BUGS The .Nm ed driver is a bit too aggressive about resetting the card whenever any bad -packets are received. As a result, it may throw out some good packets which +packets are received. +As a result, it may throw out some good packets which have been received but not yet transfered from the card to main memory. .Sh SEE ALSO .Xr arp 4 , diff --git a/share/man/man4/en.4 b/share/man/man4/en.4 index 392506f4be75..1fef5526cbd9 100644 --- a/share/man/man4/en.4 +++ b/share/man/man4/en.4 @@ -48,7 +48,8 @@ To enable the link use the following commands: .It "en0: 7 32KB receive buffers, 8 32KB transmit buffers allocated" .El .Sh CAVEATS -The driver extensively uses DMA on PCI. The first +The driver extensively uses DMA on PCI. +The first generation PCI chipsets do not work or exhibit poor performance. .Sh SEE ALSO .Xr ifconfig 8 , diff --git a/share/man/man4/intpm.4 b/share/man/man4/intpm.4 index 68c04b6cbb9d..e46dfb8342f8 100644 --- a/share/man/man4/intpm.4 +++ b/share/man/man4/intpm.4 @@ -44,7 +44,8 @@ This driver provides access to .Tn Intel PIIX4 PCI Controller function 3 , Power management controller. Currently, only smbus controller -function is implemented. But it also have bus idle monitoring function. +function is implemented. +But it also have bus idle monitoring function. It will display mapped I/O address for bus monitoring function when attaching. diff --git a/share/man/man4/ipfirewall.4 b/share/man/man4/ipfirewall.4 index 970246577c07..f69e23efe01b 100644 --- a/share/man/man4/ipfirewall.4 +++ b/share/man/man4/ipfirewall.4 @@ -24,7 +24,8 @@ which point the corresponding action is taken. Rules are numbered from 1 to 65534; multiple rules may share the same number. .Pp -There is one rule that always exists, rule number 65535. This rule +There is one rule that always exists, rule number 65535. +This rule normally causes all packets to be dropped. Hence, any packet which does not match a lower numbered rule will be dropped. However, a kernel compile @@ -34,7 +35,8 @@ allows the administrator to change this fixed rule to permit everything. .Pp The value passed to .Fn setsockopt -is a struct ip_fw describing the rule (see below). In some cases +is a struct ip_fw describing the rule (see below). +In some cases (such as IP_FW_DEL), only the rule number is significant. .Sh COMMANDS The following socket options are used to manage the rule list: diff --git a/share/man/man4/isp.4 b/share/man/man4/isp.4 index c16c7329e7cc..92ddaff48656 100644 --- a/share/man/man4/isp.4 +++ b/share/man/man4/isp.4 @@ -198,7 +198,8 @@ as they should. Sometimes, when booting, the driver gets stuck waiting for the Fibre Channel f/w to tell it that the loop port database is ready. In this case you'll -see an announcement that the loop state has a value of 0x1. To unwedge +see an announcement that the loop state has a value of 0x1. +To unwedge the system, unplug and replug the fibre channel connection, or otherwise cause a LIP (Loop Initialization Primitive sequence)- this will kick the f/w into getting unstuck. diff --git a/share/man/man4/man4.i386/dgb.4 b/share/man/man4/man4.i386/dgb.4 index c1898aacd2ef..29003f0e3e98 100644 --- a/share/man/man4/man4.i386/dgb.4 +++ b/share/man/man4/man4.i386/dgb.4 @@ -49,14 +49,16 @@ All values are just examples. .Pp The \fBNDGBPORTS\fR option defines the total number of ports on all cards -installed in the system. When not defined the number is computed: +installed in the system. +When not defined the number is computed: .br default \fBNDGBPORTS\fR = number_of_described_DigiBoard_cards * 16 If it is less than the actual number of ports the system will be able to use only the -first \fBNDGBPORTS\fR ports. If it is greater then all ports will be usable +first \fBNDGBPORTS\fR ports. +If it is greater then all ports will be usable but some memory will be wasted. .Pp Meaning of \fBflags\fR: @@ -97,10 +99,12 @@ Input and output for each line may set to one of following baud rates; .Pp The driver doesn't use any interrupts, it is ``polling-based''. This means that it uses clock interrupts instead of interrupts generated by DigiBoard cards and -checks the state of cards 25 times per second. This is practical because the +checks the state of cards 25 times per second. +This is practical because the DigiBoard cards have large input and output buffers (more than 1Kbyte per port) and hardware that allows efficiently finding the port that needs -attention. The only problem seen with this policy is slower +attention. +The only problem seen with this policy is slower SLIP and PPP response. .Pp Each line in the kernel configuration file describes one card, not one port @@ -145,15 +149,18 @@ for all the DigiBoards installed (but not for any other card or real memory). DigiBoards with a large amount of memory (256K or 512K and perhaps even 128K) must be mapped -to memory addresses outside of the first megabyte. If the computer +to memory addresses outside of the first megabyte. +If the computer has more than 15 megabytes of memory then there is no free address space outside of the first megabyte where such DigiBoards can be mapped. In this case you may need to reduce the amount of memory in the computer. -But many machines provide a better solution. They have the ability to +But many machines provide a better solution. +They have the ability to ``turn off'' the memory in the 16th megabyte (addresses 0xF00000 - 0xFFFFFF) using the -BIOS setup. Then the DigiBoard's address space can be set to this ``hole''. +BIOS setup. +Then the DigiBoard's address space can be set to this ``hole''. .\" XXX the following should be true for all serial drivers and .\" should not be repeated in the man pages for all serial drivers. .\" It was copied from sio.4. The only changes were s/sio/dgb/g. @@ -267,12 +274,14 @@ the wrong \fBiomem\fR value is specified in the kernel config file. .El .Bl -diag .It dgb\fIX\fB: BIOS start failed -Problems with starting the on-board BIOS. Probably the memory addresses of the +Problems with starting the on-board BIOS. +Probably the memory addresses of the DigiBoard overlap with some other device or with RAM. .El .Bl -diag .It dgb\fIX\fB: BIOS download failed -Problems with the on-board BIOS. Probably the memory addresses of the +Problems with the on-board BIOS. +Probably the memory addresses of the DigiBoard overlap with some other device or with RAM. .El .Bl -diag @@ -319,12 +328,14 @@ unusable due to misconfiguration. .El .Bl -diag .It dgb\fIX\fB: port \fIY\fB: event \fIN\fB mstat \fIM\fB lstat \fIK\fB -The driver got a strange event from card. Probably this means that you have a +The driver got a strange event from card. +Probably this means that you have a newer card with an extended list of events or some other hardware problem. .El .Bl -diag .It dgb\fIX\fB: port \fIY\fB: overrun -Input buffer has filled up. Problems in polling logic of driver. +Input buffer has filled up. +Problems in polling logic of driver. .El .Bl -diag .It dgb\fIX\fB: port \fIY\fB: FEP command on disabled port @@ -357,6 +368,8 @@ There was a bug in implementation of .Xr select 2 . It is fixed now but not widely tested yet. .Pp -There is no ditty command. Most of its functions (alternate pinout, -speed up to 115200 baud, etc.) are implemented in the driver itself. Some +There is no ditty command. +Most of its functions (alternate pinout, +speed up to 115200 baud, etc.) are implemented in the driver itself. +Some other functions are missing. diff --git a/share/man/man4/man4.i386/ed.4 b/share/man/man4/man4.i386/ed.4 index b0818e3e1f34..1138ccd022a3 100644 --- a/share/man/man4/man4.i386/ed.4 +++ b/share/man/man4/man4.i386/ed.4 @@ -67,24 +67,31 @@ are a bit field, and are summarized as follows: .Pp .Bl -hang -offset indent .It Em 0x01 -Disable tranceiver. On those cards which support it, this flag causes the tranceiver to +Disable tranceiver. +On those cards which support it, this flag causes the tranceiver to be disabled and the AUI connection to be used by default. .It Em 0x02 -Force 8bit mode. This flag forces the card to 8bit mode regardless of how the -card identifies itself. This may be needed for some clones which incorrectly +Force 8bit mode. +This flag forces the card to 8bit mode regardless of how the +card identifies itself. +This may be needed for some clones which incorrectly identify themselves as 16bit, even though they only have an 8bit interface. .It Em 0x04 -Force 16bit mode. This flag forces the card to 16bit mode regardless of how the -card identifies itself. This may be needed for some clones which incorrectly +Force 16bit mode. +This flag forces the card to 16bit mode regardless of how the +card identifies itself. +This may be needed for some clones which incorrectly identify themselves as 8bit, even though they have a 16bit ISA interface. .It Em 0x08 -Disable transmitter multi-buffering. This flag disables the use of multiple +Disable transmitter multi-buffering. +This flag disables the use of multiple transmit buffers and may be necessary in rare cases where packets are sent out faster than a machine on the other end can handle (as evidenced by severe packet lossage). Some .Pf ( No non- Ns Tn FreeBSD :-)) machines have terrible ethernet performance -and simply can't cope with 1100K+ data rates. Use of this flag also provides +and simply can't cope with 1100K+ data rates. +Use of this flag also provides one more packet worth of receiver buffering, and on 8bit cards, this may help reduce receiver lossage. .El @@ -102,61 +109,75 @@ into the kernel) differs from the irq that has been set on the interface card. .It "ed%d: failed to clear shared memory at %x - check configuration." When the card was probed at system boot time, the .Nm ed -driver found that it could not clear the card's shared memory. This is most commonly +driver found that it could not clear the card's shared memory. +This is most commonly caused by a BIOS extension ROM being configured in the same address space as the -ethernet card's shared memory. Either find the offending card and change its BIOS +ethernet card's shared memory. +Either find the offending card and change its BIOS ROM to be at an address that doesn't conflict, or change the .Em iomem option in the kernel config file so that the card's shared memory is mapped at a non-conflicting address. .It "ed%d: Invalid irq configuration (%d) must be 2-5 for 3c503." The irq number that was specified in the kernel config file is not valid for -the 3Com 3c503 card. The 3c503 can only be assigned to irqs 2 through 5. +the 3Com 3c503 card. +The 3c503 can only be assigned to irqs 2 through 5. .It "ed%d: Cannot find start of RAM." .It "ed%d: Cannot find any RAM, start : %d, x = %d." The probe of a Gateway card was unsuccessful in configuring the card's packet memory. This likely indicates that the card was improperly recognized as a Gateway or that the card is defective. .It "ed: packets buffered, but transmitter idle." -Indicates a logic problem in the driver. Should never happen. +Indicates a logic problem in the driver. +Should never happen. .It "ed%d: device timeout" -Indicates that an expected transmitter interrupt didn't occur. Usually caused by an +Indicates that an expected transmitter interrupt didn't occur. +Usually caused by an interrupt conflict with another card on the ISA bus. .It "ed%d: NIC memory corrupt - invalid packet length %d." Indicates that a packet was received with a packet length that was either larger than -the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. Usually +the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. +Usually caused by a conflict with another card on the ISA bus, but in some cases may also indicate faulty cabling. .It "ed%d: remote transmit DMA failed to complete." This indicates that a programmed I/O transfer to an NE1000 or NE2000 style card -has failed to properly complete. Usually caused by the ISA bus speed being set +has failed to properly complete. +Usually caused by the ISA bus speed being set too fast. .El .Sh CAVEATS -Early revision DS8390 chips have problems. They lock up whenever the receive -ring-buffer overflows. They occasionally switch the byte order +Early revision DS8390 chips have problems. +They lock up whenever the receive +ring-buffer overflows. +They occasionally switch the byte order of the length field in the packet ring header (several different causes of this related to an off-by-one byte alignment) - resulting in "NIC -memory corrupt - invalid packet length" messages. The card is reset +memory corrupt - invalid packet length" messages. +The card is reset whenever these problems occur, but otherwise there is no problem with recovering from these conditions. .Pp The NIC memory access to 3Com and Novell cards is much slower than it is on WD/SMC cards; it's less than 1MB/second on 8bit boards and less than 2MB/second -on the 16bit cards. This can lead to ring-buffer overruns resulting in +on the 16bit cards. +This can lead to ring-buffer overruns resulting in dropped packets during heavy network traffic. .Pp -16bit Compex cards identify themselves as being 8bit. While these cards will +16bit Compex cards identify themselves as being 8bit. +While these cards will work in 8bit mode, much higher performance can be achieved by specifying .Em "flags 0x04" -(force 16bit mode) in your kernel config file. In addition, you should also specify +(force 16bit mode) in your kernel config file. +In addition, you should also specify .Em "iosize 16384" to take advantage of the extra 8k of shared memory that 16bit mode provides. .Sh BUGS The .Nm ed driver is a bit too aggressive about resetting the card whenever any bad -packets are received. As a result, it may throw out some good packets which +packets are received. +As a result, it may throw out some good packets which have been received but not yet transfered from the card to main memory. .Sh SEE ALSO .Xr arp 4 , diff --git a/share/man/man4/man4.i386/en.4 b/share/man/man4/man4.i386/en.4 index 392506f4be75..1fef5526cbd9 100644 --- a/share/man/man4/man4.i386/en.4 +++ b/share/man/man4/man4.i386/en.4 @@ -48,7 +48,8 @@ To enable the link use the following commands: .It "en0: 7 32KB receive buffers, 8 32KB transmit buffers allocated" .El .Sh CAVEATS -The driver extensively uses DMA on PCI. The first +The driver extensively uses DMA on PCI. +The first generation PCI chipsets do not work or exhibit poor performance. .Sh SEE ALSO .Xr ifconfig 8 , diff --git a/share/man/man4/man4.i386/ep.4 b/share/man/man4/man4.i386/ep.4 index cdfe7eeed3da..f4c57d6acf8c 100644 --- a/share/man/man4/man4.i386/ep.4 +++ b/share/man/man4/man4.i386/ep.4 @@ -55,7 +55,8 @@ UTP, also known as twisted pair .El .Pp The default port to use is the port that has been selected with the -setup utility. To override this, use the following media options with +setup utility. +To override this, use the following media options with .Xr ifconfig 8 or in your .Pa /etc/rc.conf @@ -107,4 +108,5 @@ Erase the pencil mark and reboot. .Xr ifconfig 8 , .Xr ng_ether 8 .Sh STANDARDS -are great. There's so many to choose from. +are great. +There's so many to choose from. diff --git a/share/man/man4/man4.i386/gsc.4 b/share/man/man4/man4.i386/gsc.4 index 6ae7e3590562..8c097b583010 100644 --- a/share/man/man4/man4.i386/gsc.4 +++ b/share/man/man4/man4.i386/gsc.4 @@ -65,16 +65,20 @@ output The .Nm gsc character device driver currently handles only the -Genius GS-4500 handy scanner. It operates in pure DMA modes, although -the hardware could be set up to work with irq. I had neither enough +Genius GS-4500 handy scanner. +It operates in pure DMA modes, although +the hardware could be set up to work with irq. +I had neither enough documentation nor experience in writing interrupt driven device drivers. .Pp The device can operate at four different .Em resolutions : 100, 200, -300 and 400dpi. It produces a simple bitmap with the most significant -bit at the left side. The driver can optionally output the famous and +300 and 400dpi. +It produces a simple bitmap with the most significant +bit at the left side. +The driver can optionally output the famous and likely simple portable bitmap file format .Xr pbm 5 by Jef Poskanzer. @@ -87,7 +91,8 @@ only to name some of them ...). In .Em raw mode a bit which is set means a black pixel because the scanner detects black -points on white paper. On the other hand, because pnm format describes +points on white paper. +On the other hand, because pnm format describes intensities of electron beams in video screens a set bit in .Em pbm mode means a white pixel. @@ -95,13 +100,15 @@ mode means a white pixel. The .Em width of the output bitmap is fixed as given by the -resolution value. However, the +resolution value. +However, the .Em height of the bitmap must be supplied in .Em pnm mode since the driver must know at what time the -'end-of-file' shall be reached. With this feature you are able to +'end-of-file' shall be reached. +With this feature you are able to directly copy the scanner output into a pbm file with .Xr cat . Of course you can obtain a similar effect by using @@ -114,7 +121,8 @@ The .Em graymap output mode is not yet implemented into the driver. It is even questionable if external programs would not do this job -better thereby not counting to the size of the kernel. Even though, I +better thereby not counting to the size of the kernel. +Even though, I do not know of tools which produce a graymap from a halftone bitmap. .Pp The ioctl requests that are served by @@ -126,22 +134,26 @@ requests from within shell. .It GSC_SRES int Set the .Em resolution -value. If this call is made after the first +value. +If this call is made after the first read access to the device there will be no effect unless the device is closed and opened again. .It GSC_GRES int Get current resolution in dots per inch (dpi). .It GSC_SRESSSW void -Set resolution value from selector switch. The driver must be in an +Set resolution value from selector switch. +The driver must be in an open though untouched state otherwise the request will fail and .Xr errno 2 is set to EBUSY. .It GSC_SWIDTH int Set the .Em width -of the bitmap. Actually, this is an alternative +of the bitmap. +Actually, this is an alternative way of setting the resolution, since any allowed resolution matches -exactly one width. Allowed are listed in the table below. +exactly one width. +Allowed are listed in the table below. .Bl -tag -width resolution -compact -offset indent .It resolution width @@ -167,10 +179,13 @@ call to fail with set to .Er EINVAL . .Pp -As you can see, there are width values > 1696. This does, however, not +As you can see, there are width values > 1696. +This does, however, not mean that you can obtain scanned lines longer than the width of your -scanner or by higher resolutions. Actually, the resolution is selected -by only by the hardware switch. Any line that is longer than what is +scanner or by higher resolutions. +Actually, the resolution is selected +by only by the hardware switch. +Any line that is longer than what is defined for the actual resolution will be undefined (usually white) on the right part that is exceeding the standard line. .It GSC_GWIDTH int @@ -180,35 +195,46 @@ Set the .Em height of the bitmap in .Em pnm -mode. This is actually +mode. +This is actually a limit on the amount of lines scannable after the first read -operation. When the limit is reached read will return 0. However, the +operation. +When the limit is reached read will return 0. However, the device is turned off only when a close is performed (either explicitly or implicitly on exit of the calling process). .It GSC_GHEIGHT int Get the current height of the bitmap. .It GSC_SBLEN int Set the length of the buffer used internally to do the DMA transfer. -The buffer length is supplied in lines of the bitmap. Since the buffer +The buffer length is supplied in lines of the bitmap. +Since the buffer size limit is (currently) 0x3000 bytes the maximum number of lines -allowed will vary with the width of each line. This upper limit is +allowed will vary with the width of each line. +This upper limit is checked before it overwrites the current value and pases an ENOMEM in the .Xr errno 2 -variable. However, since the bitmap width can change +variable. +However, since the bitmap width can change after a buffer length was selected a read request may fail with ENOMEM -if the buffer length turns out too high. It is generally wise to +if the buffer length turns out too high. +It is generally wise to choose long buffers rather than go save in order to obtain better output. .It GSC_GBLEN int Get the current buffer length in lines. .It GSC_SBTIME int -Set the timeout for the completion of reading one buffer. Since a +Set the timeout for the completion of reading one buffer. +Since a handy scanner is a human/computer interface timeout values are usually -higher than those of a flat scanner. Default is 15 seconds. After -timeout is reached the read operation will fail with EBUSY. Note that +higher than those of a flat scanner. +Default is 15 seconds. +After +timeout is reached the read operation will fail with EBUSY. +Note that the timeout timer starts anew for each buffer to be read and thus does -not cause you to scan faster for longer images. BLEN/BTIME is similar +not cause you to scan faster for longer images. +BLEN/BTIME is similar as MIN/TIME in termios(4). .It GSC_GBTIME int Get the current buffer timeout. @@ -216,19 +242,24 @@ Get the current buffer timeout. .Pp All ioctl requests that modify a parameter except GSC_SBTIME do not have an effect on an ongoing scan process, i.e. after the first read -request that follows open. You must close the device and open it again -for the new selections to take effect. Consequently, the selections +request that follows open. +You must close the device and open it again +for the new selections to take effect. +Consequently, the selections are not reset when you close or open the device. .Pp Similarly, requests that read a value do not report the value that is -used for the ongoing scan process. The values needed during the scan +used for the ongoing scan process. +The values needed during the scan process are saved when it starts and thus are not accessed by ioctl requests. .Pp The BTIME value does, however, have an immediate effect on the ongoing -scan. Thus the timeout can for example be set to long until the user +scan. +Thus the timeout can for example be set to long until the user starts scanning. It can then be set to a short amount to react -(nearly) immediately when the user stops. Note that the user should be +(nearly) immediately when the user stops. +Note that the user should be left time to at least fill one buffer without having to haste. .Pp Note that the @@ -236,7 +267,8 @@ Note that the versus .Em raw mode selection is done by the -minor number not by ioctl requests. In +minor number not by ioctl requests. +In .Em raw mode the selected height of the bitmap will have no effect. @@ -295,6 +327,7 @@ whose debug bit (i.e. bit 5 out of 7) is set. .Sh BUGS Even though the scanner device has a little switch by which you should be able to select one of the four resolution modes, I could not yet -determine how to read its status. Unless this is not fixed the driver +determine how to read its status. +Unless this is not fixed the driver depends on the value passed by means of ioctl(2) which need not match what is selected by the hardware. diff --git a/share/man/man4/man4.i386/mcd.4 b/share/man/man4/man4.i386/mcd.4 index 42f49539f829..fd65713de937 100644 --- a/share/man/man4/man4.i386/mcd.4 +++ b/share/man/man4/man4.i386/mcd.4 @@ -38,8 +38,10 @@ The .Nm mcd driver provides a data and audio interface to the Mitsumi-brand CD-ROM -player. The CD-ROM player must be interfaced to the ISA bus through -one of the Mitsumi proprietary controller boards. The controller +player. +The CD-ROM player must be interfaced to the ISA bus through +one of the Mitsumi proprietary controller boards. +The controller boards supported are the LU002S, LU005S, the FX001 and the quite common FX001D. .Pp @@ -62,7 +64,8 @@ The .Nm mcd driver also responds to special CD-ROM .Fn ioctl -commands. These commands +commands. +These commands control the CD-ROM player's audio features. The commands are: .Pp @@ -107,7 +110,8 @@ The .Fn ioctl commands defined above are the only ones that the .Nm mcd -driver supports. There are other CD-ROM related +driver supports. +There are other CD-ROM related .Fn ioctl commands (such as .Dv CDIOCSETVOL @@ -132,7 +136,8 @@ CD-ROM player as the performance on data is abysmal. .Pp The current version of the driver uses neither the DMA or IRQ features of the interface board, although it has an interrupt handler -for any IRQ requests that are generated. Until the DMA features are +for any IRQ requests that are generated. +Until the DMA features are supported, the only interrupts that the board generates are those that aren't supported by the driver anyway. .Sh SEE ALSO diff --git a/share/man/man4/man4.i386/mse.4 b/share/man/man4/man4.i386/mse.4 index d3b8638f63ee..369d15ca3732 100644 --- a/share/man/man4/man4.i386/mse.4 +++ b/share/man/man4/man4.i386/mse.4 @@ -35,19 +35,23 @@ and a D-sub 9-pin male connector or a round DIN 9-pin male connector. .Pp The primary port address of the bus and InPort mouse interface cards -is usually 0x23c. Some cards may also be set to use the secondary port -address at 0x238. The interface cards require a single IRQ, which may be +is usually 0x23c. +Some cards may also be set to use the secondary port +address at 0x238. +The interface cards require a single IRQ, which may be 2, 3, 4 or 5. Some cards may offer additional IRQs. The port number and the IRQ number are configured by jumpers on the cards or by software provided with the card. .Pp Frequency, or report rate, at which the device sends movement and button state reports to the host system, may also be configurable on -some interface cards. It may be 15, 30, 60 or 120Hz. +some interface cards. +It may be 15, 30, 60 or 120Hz. .Pp The difference between the two types of the mice is not in mouse devices (in fact they are exactly the same). But in the circuit on the interface -cards. This means that the device from a bus mouse package can be +cards. +This means that the device from a bus mouse package can be connected to the interface card from an InPort mouse package, or vice versa, provided that their connectors match. .Ss Operation Levels @@ -71,7 +75,8 @@ Always zero. .It bit 2 Left button status; cleared if pressed, otherwise set. .It bit 1 -Middle button status; cleared if pressed, otherwise set. Always one, +Middle button status; cleared if pressed, otherwise set. +Always one, if the device does not have the middle button. .It bit 0 Right button status; cleared if pressed, otherwise set. @@ -101,7 +106,8 @@ driver can somewhat `accelerate' the movement of the pointing device. The faster you move the device, the further the pointer travels on the screen. The driver has an internal variable which governs the effect of -the acceleration. Its value can be modified via the driver flag +the acceleration. +Its value can be modified via the driver flag or via an ioctl call. .Ss Device Number The minor device number of the @@ -124,7 +130,8 @@ for device node names. .Ss Driver Flags The .Nm -driver accepts the following driver flag. Set it in the +driver accepts the following driver flag. +Set it in the kernel configuration file .Pq see Xr config 8 or in the User Configuration Menu at @@ -136,7 +143,8 @@ the boot time This flag controls the amount of acceleration effect. The smaller the value of this flag is, more sensitive the movement becomes. The minimum value allowed, thus the value for the most sensitive setting, -is one. Setting this flag to zero will completely disables the +is one. +Setting this flag to zero will completely disables the acceleration effect. .El .Sh IOCTLS @@ -258,7 +266,8 @@ If it is zero, acceleration is disabled. .Pp The .Dv packetsize -field specifies the length of the data packet. It depends on the +field specifies the length of the data packet. +It depends on the operation level. .Pp .Bl -tag -width level_0__ -compact @@ -273,7 +282,8 @@ The array holds a bit mask and pattern to detect the first byte of the data packet. .Dv syncmask[0] -is the bit mask to be ANDed with a byte. If the result is equal to +is the bit mask to be ANDed with a byte. +If the result is equal to .Dv syncmask[1] , the byte is likely to be the first byte of the data packet. Note that this detection method is not 100% reliable, @@ -296,7 +306,8 @@ Only .Dv level and .Dv accelfactor -may be modifiable. Setting values in the other field does not generate +may be modifiable. +Setting values in the other field does not generate error and has no effect. .\" .Pp .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars diff --git a/share/man/man4/man4.i386/pnp.4 b/share/man/man4/man4.i386/pnp.4 index df9adec6a9c3..9970232d39a1 100644 --- a/share/man/man4/man4.i386/pnp.4 +++ b/share/man/man4/man4.i386/pnp.4 @@ -46,26 +46,31 @@ parameters in the card's configuration space. The manual override mechanism requires the kernel to be compiled with .Cd options USERCONFIG. In this case, the kernel keeps a table of fixed size (20 entries as a -default) where configuration data are held for PnP devices. Each +default) where configuration data are held for PnP devices. +Each PnP card can contain several independent devices (5 or 6 is not unusual). .Pp By booting the kernel with the .Dq Fl c flag, commands are available to -modify the configuration of PnP cards. Commands start with the +modify the configuration of PnP cards. +Commands start with the sequence: .Dl pnp CSN LDN where CSN and LDN are the Card Select Number and Logical Device Number -associated to the device. Following this sequence any combination of +associated to the device. +Following this sequence any combination of the following commands can be used: .Bl -tag -width "mmmmmmmmmm"" .It Dv irqN line -Sets the irq line for interrupt 0 or 1 on the card. Line=0 means the line +Sets the irq line for interrupt 0 or 1 on the card. +Line=0 means the line is unused. .It Dv drqN n -Sets the drq channel used for DMA 0 or 1 on the card. Channel=4 means +Sets the drq channel used for DMA 0 or 1 on the card. +Channel=4 means the channel is unused. .It Dv portN address Sets the base address for the N-th port's range (N=0..7). address=0 @@ -74,7 +79,8 @@ means that the port is not used. Sets the base address for the N-th memory's range (N=0..3). address=0 means that the memory range is not used. .It Dv bios -Makes the PnP device use the configuration set by the BIOS. This +Makes the PnP device use the configuration set by the BIOS. +This is the default, and is generally ok if your BIOS has PnP support. If BIOS is used, then other parameters are ignored except "flags". .It Dv os @@ -88,13 +94,15 @@ Frees the entry used for the device, so that it can be used for another device with a different CSN/LDN pair. .It Dv flags Sets the value of a 32-bit flags entry which is passed to the device -driver. This can be used to set special operation modes (e.g. SB vs. WSS +driver. +This can be used to set special operation modes (e.g. SB vs. WSS emulation on some sound cards, etc.). .El .Pp The current content of the table can be printed using the .Ic ls -command in userconfig. In addition to modifications done by the user, +command in userconfig. +In addition to modifications done by the user, the table contains an entry for all logical devices accessed by a PnP device driver. .Pp @@ -137,15 +145,18 @@ This data structure (defined in /sys/i386/isa/pnp.h) contains all informations related to a PnP logical device. .It Fn read_pnp_parms "struct pnp_cinfo *d" "int ldn" This function returns the configuration of the requested -logical device. It is not possible to specify a CSN since this function +logical device. +It is not possible to specify a CSN since this function is only meant to be used during probe and attach routines .It Fn write_pnp_parms "struct pnp_cinfo *d" "int ldn" -This function sets the parameters of the requested logical device. At +This function sets the parameters of the requested logical device. +At the same time, it updates the entry in the kernel override table. Device drivers in general should .Em not modify the configuration of a device, since either the BIOS or the user -(through userconfig) should know better what to do. In particular, +(through userconfig) should know better what to do. +In particular, device driver .Em should not enable a logical device which has diff --git a/share/man/man4/man4.i386/wi.4 b/share/man/man4/man4.i386/wi.4 index 7246daf1663b..9e40cdfd668b 100644 --- a/share/man/man4/man4.i386/wi.4 +++ b/share/man/man4/man4.i386/wi.4 @@ -45,27 +45,35 @@ The driver provides support for WaveLAN/IEEE PCCARD adapters (also known as WaveLAN II cards). Note that while Lucent sells both ISA and PCMCIA WaveLAN/IEEE devices, the ISA product is actually a PCMCIA card in an -ISA to PCMCIA bridge adapter. Consequently, the +ISA to PCMCIA bridge adapter. +Consequently, the .Nm -driver is required for both the ISA and PCMCIA NICs. Both the original +driver is required for both the ISA and PCMCIA NICs. +Both the original 2Mbps WaveLAN/IEEE cards and the newer 6Mbps WaveLAN/IEEE Turbo adapters are supported. .Pp -The core of the WaveLAN/IEEE is the Lucent Hermes controller. All -host/device interaction is via programmed I/O with the Hermes. The +The core of the WaveLAN/IEEE is the Lucent Hermes controller. +All +host/device interaction is via programmed I/O with the Hermes. +The Hermes supports 802.11 and 802.3 frames, power management, BSS, WDS -and ad-hoc operation modes. The +and ad-hoc operation modes. +The .Nm driver encapsulates all IP and ARP traffic as 802.11 frames, however -it can receive either 802.11 or 802.3 frames. Transmit speed is +it can receive either 802.11 or 802.3 frames. +Transmit speed is selectable between 1Mbps fixed, 2Mbps fixed or 2Mbps with auto fallback. For WaveLAN/IEEE Turbo adapters, speeds up to 6Mbps are available. .Pp By default, the .Nm -driver configures the WaveLAN card for ad-hoc operation. In this mode, +driver configures the WaveLAN card for ad-hoc operation. +In this mode, stations can communicate among each other without the aid of an access -point. To join a service set, the driver must be set for BSS mode using +point. +To join a service set, the driver must be set for BSS mode using the .Xr wicontrol 8 utility. diff --git a/share/man/man4/pcvt.4 b/share/man/man4/pcvt.4 index 89c5fc966f22..230a9e01ee04 100644 --- a/share/man/man4/pcvt.4 +++ b/share/man/man4/pcvt.4 @@ -234,7 +234,8 @@ If an option is given with no value, a value of 1 .Pq activated is substituted. If an option value is given as 0, this options is -deactivated. Any other value is substituted by 1, too. +deactivated. +Any other value is substituted by 1, too. If an option is omitted, a built-in default is assumed. @@ -303,7 +304,8 @@ Default: off .It Em PCVT_EMU_MOUSE Emulate a three-button mouse via the keypad. Useful for notebooks when -running XFree86. See +running XFree86. +See .Sx Mouse emulation below. .br @@ -524,7 +526,8 @@ were the mouse emulator device. The mouse emulation is turned on by pressing the .Aq Em NumLock -key. The pointer is moved by the numerical keypad keys, into the +key. +The pointer is moved by the numerical keypad keys, into the obvious directions. The pointer is initially moved in single steps, and is accelerated after an adjustable time @@ -729,7 +732,8 @@ sets the number of columns for the current screen, .El its parameter is a pointer to an integer containing either a value of 80, -or a value of 132. Note that setting the number of columns to 132 is +or a value of 132. +Note that setting the number of columns to 132 is only supported on VGA adaptors. Any unsupported numbers cause the ioctl to fail with diff --git a/share/man/man4/ppbus.4 b/share/man/man4/ppbus.4 index 3ca7453c06d9..1ee649cc9570 100644 --- a/share/man/man4/ppbus.4 +++ b/share/man/man4/ppbus.4 @@ -178,7 +178,8 @@ operate at close to the same performance levels as an equivalent ISA plug-in card. .Pp At software level, you may implement the protocol you wish, using data and -address cycles as you want. This is for the IEEE1284 compatible part. +address cycles as you want. +This is for the IEEE1284 compatible part. Then, peripheral vendors may implement protocol handshake with the following status lines: PError, nFault and Select. @@ -224,7 +225,8 @@ states. .Pp At any time, the slave may want to send data to the host. This is only -possible from forward idle states (nibble, byte, ecp...). So, the +possible from forward idle states (nibble, byte, ecp...). +So, the host must have previously negotiated to permit the peripheral to request transfer. Interrupt lines may be dedicated to the requesting signals diff --git a/share/man/man4/rl.4 b/share/man/man4/rl.4 index 40fa7e19d88b..9709841d5778 100644 --- a/share/man/man4/rl.4 +++ b/share/man/man4/rl.4 @@ -207,7 +207,8 @@ DMAing all of it. .Pp The driver can check for an incomplete frame by inspecting the frame length in the header preceeding the actual packet data: an incomplete -frame will have the magic length of 0xFFF0. When the driver encounters +frame will have the magic length of 0xFFF0. +When the driver encounters this value, it knows that it has finished processing all currently available packets. Neither this magic value nor its significance are diff --git a/share/man/man4/wi.4 b/share/man/man4/wi.4 index 7246daf1663b..9e40cdfd668b 100644 --- a/share/man/man4/wi.4 +++ b/share/man/man4/wi.4 @@ -45,27 +45,35 @@ The driver provides support for WaveLAN/IEEE PCCARD adapters (also known as WaveLAN II cards). Note that while Lucent sells both ISA and PCMCIA WaveLAN/IEEE devices, the ISA product is actually a PCMCIA card in an -ISA to PCMCIA bridge adapter. Consequently, the +ISA to PCMCIA bridge adapter. +Consequently, the .Nm -driver is required for both the ISA and PCMCIA NICs. Both the original +driver is required for both the ISA and PCMCIA NICs. +Both the original 2Mbps WaveLAN/IEEE cards and the newer 6Mbps WaveLAN/IEEE Turbo adapters are supported. .Pp -The core of the WaveLAN/IEEE is the Lucent Hermes controller. All -host/device interaction is via programmed I/O with the Hermes. The +The core of the WaveLAN/IEEE is the Lucent Hermes controller. +All +host/device interaction is via programmed I/O with the Hermes. +The Hermes supports 802.11 and 802.3 frames, power management, BSS, WDS -and ad-hoc operation modes. The +and ad-hoc operation modes. +The .Nm driver encapsulates all IP and ARP traffic as 802.11 frames, however -it can receive either 802.11 or 802.3 frames. Transmit speed is +it can receive either 802.11 or 802.3 frames. +Transmit speed is selectable between 1Mbps fixed, 2Mbps fixed or 2Mbps with auto fallback. For WaveLAN/IEEE Turbo adapters, speeds up to 6Mbps are available. .Pp By default, the .Nm -driver configures the WaveLAN card for ad-hoc operation. In this mode, +driver configures the WaveLAN card for ad-hoc operation. +In this mode, stations can communicate among each other without the aid of an access -point. To join a service set, the driver must be set for BSS mode using +point. +To join a service set, the driver must be set for BSS mode using the .Xr wicontrol 8 utility. diff --git a/share/man/man4/xl.4 b/share/man/man4/xl.4 index 3bd9edb9439f..86be2a97cfc4 100644 --- a/share/man/man4/xl.4 +++ b/share/man/man4/xl.4 @@ -45,7 +45,8 @@ The .Nm driver provides support for PCI ethernet adapters and embedded controllers based on the 3Com "boomerang" and "cyclone" bus-master -Etherlink XL chips. This includes the 3c900-TP, 3c900-COMBO, 3c905-TX, +Etherlink XL chips. +This includes the 3c900-TP, 3c900-COMBO, 3c905-TX, 3c905-T4, 3c905B-TP, 3c905B-T4 and 3c905B-TX, and embedded 3c905-TX and 3c905B-TX ethernet hardware in certain Dell Optiplex and Dell Precision desktop machines, and certain Dell Latitude laptop docking @@ -53,10 +54,12 @@ stations. .Pp The Etherlink XL chips support built-in 10baseT, 10base2 and 10base5 transceivers as well as an MII bus for externally attached PHY -transceivers. The 3c905 series typically uses a National Semiconductor +transceivers. +The 3c905 series typically uses a National Semiconductor NS 83840A 10/100 PHY for 10/100 Mbps support in full or half-duplex. The 3c905B adapters have built-in autonegotiation logic mapped onto -the MII for compatibility with previous drivers. Fast Etherlink XL +the MII for compatibility with previous drivers. +Fast Etherlink XL adapters such as the 3c905-TX and 3c905B-TX are capable of 10 or 100Mbps data rates in either full or half duplex and can be manually configured for any supported mode or automatically negotiate the highest @@ -68,22 +71,27 @@ driver supports the following media types: .Pp .Bl -tag -width xxxxxxxxxxxxxxxxxxxx .It autoselect -Enable autoselection of the media type and options. Note that this +Enable autoselection of the media type and options. +Note that this option is only available with the 3c905 and 3c905B adapters with -external PHYs or built-in autonegotiation logic. For 3c900 adapters, -the driver will choose the mode specified in the EEPROM. The user can +external PHYs or built-in autonegotiation logic. +For 3c900 adapters, +the driver will choose the mode specified in the EEPROM. +The user can change this by adding media options to the .Pa /etc/rc.conf file. .It 10baseT/UTP -Set 10Mbps operation. The +Set 10Mbps operation. +The .Ar mediaopt option can also be used to select either .Ar full-duplex or .Ar half-duplex modes. .It 100baseTX -Set 100Mbps (fast ethernet) operation. The +Set 100Mbps (fast ethernet) operation. +The .Ar mediaopt option can abso be used to select either .Ar full-duplex @@ -127,39 +135,50 @@ allocating a pad buffer or collapsing an mbuf chain into a cluster. .It "xl%d: command never completed!" Some commands issued to the 3c90x ASIC take time to complete: the driver is supposed to wait until the 'command in progress' bit in -the status register clears before continuing. In rare instances, this -bit may not clear. To avoid getting caught in an infinite wait loop, +the status register clears before continuing. +In rare instances, this +bit may not clear. +To avoid getting caught in an infinite wait loop, the driver only polls the bit for a finite number of times before -giving up, at which point it issues this message. This message may -be printed during driver initialization on slower machines. If you +giving up, at which point it issues this message. +This message may +be printed during driver initialization on slower machines. +If you see this message but the driver continues to function normally, the message can probably be ignored. .It "xl%d: chip is in D3 power state -- setting to D0" This message applies only to 3c905B adapters, which support power -management. Some operating systems place the 3c905B in low power +management. +Some operating systems place the 3c905B in low power mode when shutting down, and some PCI BIOSes fail to bring the chip -out of this state before configuring it. The 3c905B loses all of +out of this state before configuring it. +The 3c905B loses all of its PCI configuration in the D3 state, so if the BIOS does not set it back to full power mode in time, it won't be able to configure it -correctly. The driver tries to detect this condition and bring +correctly. +The driver tries to detect this condition and bring the adapter back to the D0 (full power) state, but this may not be -enough to return the driver to a fully operational condition. If +enough to return the driver to a fully operational condition. +If you see this message at boot time and the driver fails to attach the device as a network interface, you will have to perform second warm boot to have the device properly configured. .Pp Note that this condition only occurs when warm booting from another -operating system. If you power down your system prior to booting +operating system. +If you power down your system prior to booting .Fx , the card should be configured correctly. .It "xl%d: WARNING: no media options bits set in the media options register!" This warning may appear when using the driver on some Dell Latitude -docking stations with built-in 3c905-TX adapters. For whatever the +docking stations with built-in 3c905-TX adapters. +For whatever the reason, the 'MII available' bit in the media options register on this particular equipment is not set, even though it should be (the 3c905-TX always uses an external PHY transceiver). The driver will attempt to guess the proper media type based on the PCI device ID -word. The driver makes a lot of noise about this condition because +word. +The driver makes a lot of noise about this condition because the author considers it a manufacturing defect. .El .Sh SEE ALSO diff --git a/share/man/man4/yp.4 b/share/man/man4/yp.4 index bc268565d29e..dda8944bb79e 100644 --- a/share/man/man4/yp.4 +++ b/share/man/man4/yp.4 @@ -88,7 +88,8 @@ is an client/server system that allows a group of machines within an .Tn NIS -domain to share a common set of configuration files. This permits a system +domain to share a common set of configuration files. +This permits a system administrator to set up .Tn NIS client systems with only minimal configuration @@ -109,11 +110,13 @@ where .Pa [domainname] is the name of the .Tn NIS -domain being served. A single +domain being served. +A single .Tn NIS server can support several domains at once, therefore it is possible to have several -such directories, one for each supported domain. Each domain will have +such directories, one for each supported domain. +Each domain will have its own independent set of maps. .Pp In @@ -137,8 +140,10 @@ into and .Em .pag files which the ndbm code uses to hold separate parts of the hash -database. The Berkeley DB hash method instead uses a single file for -both pieces of information. This means that while you may have +database. +The Berkeley DB hash method instead uses a single file for +both pieces of information. +This means that while you may have .Pa passwd.byname.dir and .Pa passwd.byname.pag @@ -153,7 +158,8 @@ server, .Xr ypserv 8 , and related tools need to know the database format of the .Tn NIS -maps. Client +maps. +Client .Tn NIS systems receive all .Tn NIS @@ -200,20 +206,24 @@ command) and begins broadcasting requests on the local network. These requests specify the name of the domain for which .Xr ypbind 8 -is attempting to establish a binding. If a server that has been +is attempting to establish a binding. +If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to .Xr ypbind 8 , -which will record the server's address. If there are several servers +which will record the server's address. +If there are several servers available (a master and several slaves, for example), .Xr ypbind 8 -will use the address of the first one to respond. From that point +will use the address of the first one to respond. +From that point on, the client system will direct all of its .Tn NIS requests to that server. .Xr Ypbind 8 will occasionally ``ping'' the server to make sure it's still up -and running. If it fails to receive a reply to one of its pings +and running. +If it fails to receive a reply to one of its pings within a reasonable amount of time, .Xr ypbind 8 will mark the domain as unbound and begin broadcasting again in the @@ -231,7 +241,8 @@ is responsible for receiving incoming requests from clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database -back to the client. There is a specific set of requests that +back to the client. +There is a specific set of requests that .Xr ypserv 8 is designed to handle, most of which are implemented as functions within the standard C library: @@ -280,11 +291,13 @@ and are not meant to be used by standard utilities. .Pp On networks with a large number of hosts, it is often a good idea to use a master server and several slaves rather than just a single master -server. A slave server provides the exact same information as a master +server. +A slave server provides the exact same information as a master server: whenever the maps on the master server are updated, the new data should be propagated to the slave systems using the .Xr yppush 8 -command. The +command. +The .Tn NIS Makefile .Pf ( Pa /var/yp/Makefile ) @@ -305,8 +318,10 @@ master server using automatically from within .Xr ypserv 8 ; therefore it is not usually necessary for the administrator -to use it directly. It can be run manually if -desired, however.) Maintaining +to use it directly. +It can be run manually if +desired, however.) +Maintaining slave servers helps improve .Tn NIS performance on large @@ -328,11 +343,13 @@ domain to extend beyond a local network (the .Xr ypbind 8 daemon might not be able to locate a server automatically if it resides on -a network outside the reach of its broadcasts. It is possible to force +a network outside the reach of its broadcasts. +It is possible to force .Xr ypbind 8 to bind to a particular server with .Xr ypset 8 -but this is sometimes inconvenient. This problem can be avoided simply by +but this is sometimes inconvenient. +This problem can be avoided simply by placing a slave server on the local network.) .El .Pp @@ -345,7 +362,8 @@ other implementations) when used exclusively with .Bx Free client -systems. The +systems. +The .Bx Free password database system (which is derived directly from @@ -373,8 +391,10 @@ in a special way: the server will only provide access to these maps in response to requests that originate on privileged ports. Since only the super-user is allowed to bind to a privileged port, the server assumes that all such requests come from privileged -users. All other requests are denied: requests from non-privileged -ports will receive only an error code from the server. Additionally, +users. +All other requests are denied: requests from non-privileged +ports will receive only an error code from the server. +Additionally, .Bx Free Ns 's .Xr ypserv 8 includes support for Wietse Venema's tcp wrapper package; with tcp @@ -384,7 +404,8 @@ to respond only to selected client machines. .Pp While these enhancements provide better security than stock .Tn NIS Ns , -they are by no means 100% effective. It is still possible for +they are by no means 100% effective. +It is still possible for someone with access to your network to spoof the server into disclosing the shadow password maps. .Pp @@ -393,9 +414,11 @@ On the client side, .Fn getpwent 3 functions will automatically search for the .Pa master.passwd -maps and use them if they exist. If they do, they will be used, and +maps and use them if they exist. +If they do, they will be used, and all fields in these special maps (class, password age and account -expiration) will be decoded. If they aren't found, the standard +expiration) will be decoded. +If they aren't found, the standard .Pa passwd maps will be used instead. .Sh COMPATIBILITY @@ -405,7 +428,8 @@ to be running in order for their hostname resolution functions ( .Fn gethostbyname , .Fn gethostbyaddr , -etc) to work properly. On these systems, +etc) to work properly. +On these systems, .Xr ypserv 8 performs .Tn DNS @@ -425,12 +449,14 @@ if desired), therefore its server doesn't do .Tn DNS lookups -by default. However, +by default. +However, .Xr ypserv 8 can be made to perform .Tn DNS lookups if it is started with a special -flag. It can also be made to register itself as an +flag. +It can also be made to register itself as an .Tn NIS v1 server in order to placate certain systems that insist on the presence of @@ -463,7 +489,8 @@ client and server capabilities, it does not yet have support for .Xr ypupdated 8 or the .Fn yp_update -function. Both of these require secure +function. +Both of these require secure .Tn RPC Ns , which .Bx Free @@ -476,7 +503,8 @@ and .Xr getprotoent 3 functions do not yet have .Tn NIS -support. Fortunately, these files +support. +Fortunately, these files don't need to be updated that often. .Pp Many more manual pages should be written, especially @@ -492,7 +520,8 @@ The .Nm YP subsystem was written from the ground up by .An Theo de Raadt -to be compatible to Sun's implementation. Bug fixes, improvements +to be compatible to Sun's implementation. +Bug fixes, improvements and .Tn NIS server support were later added by @@ -501,5 +530,6 @@ The server-side code was originally written by .An Peter Eriksson and .An Tobias Reber -and is subject to the GNU Public License. No Sun code was +and is subject to the GNU Public License. +No Sun code was referenced. diff --git a/share/man/man5/elf.5 b/share/man/man5/elf.5 index 8b15b3f76986..72dc524fcc44 100644 --- a/share/man/man5/elf.5 +++ b/share/man/man5/elf.5 @@ -35,21 +35,25 @@ .Sh DESCRIPTION The header file .Aq Pa elf.h -defines the format of ELF executable binary files. Amongst these files are +defines the format of ELF executable binary files. +Amongst these files are normal executable files, relocatable object files, core files and shared libraries. .Pp An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. -The ELF header is always at offset zero of the file. The program header +The ELF header is always at offset zero of the file. +The program header table and the section header table's offset in the file are defined in the -ELF header. The two tables describe the rest of the particularities of +ELF header. +The two tables describe the rest of the particularities of the file. .Pp Applications which wish to process ELF binary files for their native architecture only should include .Pa sys/elf.h -in their source code. These applications should need to refer to +in their source code. +These applications should need to refer to all the types and structures by their generic names .Dq Elf_xxx and to the macros by @@ -105,7 +109,8 @@ Elf64_Quarter Unsigned quarterword field .Pp All data structures that the file format defines follow the .Dq natural -size and alignment guidelines for the relevant class. If necessary, +size and alignment guidelines for the relevant class. +If necessary, data structures contain explicit padding to ensure 4-byte alignment for 4-byte objects, to force structure sizes to a multiple of 4, etc. .Pp @@ -163,16 +168,20 @@ The following macros are defined: .Pp .Bl -tag -width "EI_VERSION" -compact .It Dv EI_MAG0 -The first byte of the magic number. It must be filled with +The first byte of the magic number. +It must be filled with .Sy ELFMAG0 . .It Dv EI_MAG1 -The second byte of the magic number. It must be filled with +The second byte of the magic number. +It must be filled with .Sy ELFMAG1 . .It Dv EI_MAG2 -The third byte of the magic number. It must be filled with +The third byte of the magic number. +It must be filled with .Sy ELFMAG2 . .It Dv EI_MAG3 -The fourth byte of the magic number. It must be filled with +The fourth byte of the magic number. +It must be filled with .Sy ELFMAG3 . .It Dv EI_CLASS The fifth byte identifies the architecture for this binary: @@ -181,14 +190,16 @@ The fifth byte identifies the architecture for this binary: .It Dv ELFCLASSNONE This class is invalid. .It Dv ELFCLASS32 -This defines the 32-bit architecture. It supports machines with files +This defines the 32-bit architecture. +It supports machines with files and virtual address spaces up to 4 Gigabytes. .It Dv ELFCLASS64 This defines the 64-bit architecture. .El .It Dv EI_DATA The sixth byte specifies the data encoding of the processor-specific -data in the file. Currently these encodings are supported: +data in the file. +Currently these encodings are supported: .Pp .Bl -tag -width "ELFDATA2LSB" -compact .It Dv ELFDATANONE @@ -208,8 +219,11 @@ Invalid version. Current version. .El .It Dv EI_PAD -Start of padding. These bytes are reserved and set to zero. Programs -which read them should ignore them. The value for EI_PAD will change in +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for EI_PAD will change in the future if currently unused bytes are given meanings. .It Dv EI_BRAND Start of architecture identification. @@ -278,16 +292,20 @@ Current version .El .It Dv e_entry This member gives the virtual address to which the system first transfers -control, thus starting the process. If the file has no associated entry +control, thus starting the process. +If the file has no associated entry point, this member holds zero. .It Dv e_phoff -This member holds the program header table's file offset in bytes. If +This member holds the program header table's file offset in bytes. +If the file has no program header table, this member holds zero. .It Dv e_shoff -This member holds the section header table's file offset in bytes. If the +This member holds the section header table's file offset in bytes. +If the file has no section header table this member holds zero. .It Dv e_flags -This member holds processor-specific flags associated with the file. Flag +This member holds processor-specific flags associated with the file. +Flag names take the form EF_`machine_flag'. Currently no flags have been defined. .It Dv e_ehsize This member holds the ELF header's size in bytes. @@ -296,37 +314,44 @@ This member holds the size in bytes of one entry in the file's program header table; all entries are the same size. .It Dv e_phnum This member holds the number of entries in the program header -table. Thus the product of +table. +Thus the product of .Sy e_phentsize and .Sy e_phnum gives the table's size -in bytes. If a file has no program header, +in bytes. +If a file has no program header, .Sy e_phnum holds the value zero. .It Dv e_shentsize -This member holds a sections header's size in bytes. A section header is one +This member holds a sections header's size in bytes. +A section header is one entry in the section header table; all entries are the same size. .It Dv e_shnum -This member holds the number of entries in the section header table. Thus +This member holds the number of entries in the section header table. +Thus the product of .Sy e_shentsize and .Sy e_shnum -gives the section header table's size in bytes. If a file has no section +gives the section header table's size in bytes. +If a file has no section header table, .Sy e_shnum holds the value of zero. .It Dv e_shstrndx This member holds the section header table index of the entry associated -with the section name string table. If the file has no section name string +with the section name string table. +If the file has no section name string table, this member holds the value .Sy SHN_UNDEF . .Pp .Bl -tag -width "SHN_LORESERVE" -compact .It Dv SHN_UNDEF This value marks an undefined, missing, irrelevant, or otherwise meaningless -section reference. For example, a symbol +section reference. +For example, a symbol .Dq defined relative to section number .Sy SHN_UNDEF @@ -342,7 +367,8 @@ This value down to and including .Sy SHN_LOPROC are reserved for processor-specific semantics. .It Dv SHN_ABS -This value specifies absolute values for the corresponding reference. For +This value specifies absolute values for the corresponding reference. +For example, symbols defined relative to section number .Sy SHN_ABS have absolute values and are not affected by relocation. @@ -356,7 +382,8 @@ indices between and .Sy SHN_HIRESERVE , inclusive; the values do -not reference the section header table. That is, the section header table +not reference the section header table. +That is, the section header table does .Em not contain entries for the reserved indices. @@ -365,7 +392,8 @@ contain entries for the reserved indices. .Pp An executable or shared object file's program header table is an array of structures, each describing a segment or other information the system needs -to prepare the program for execution. An object file +to prepare the program for execution. +An object file .Em segment contains one or more .Em sections . @@ -374,7 +402,8 @@ A file specifies its own program header size with the ELF header's .Sy e_phentsize and .Sy e_phnum -members. As with the Elf executable header, the program header +members. +As with the Elf executable header, the program header also has different versions depending on the architecture: .Pp .Bd -literal -offset indent @@ -423,7 +452,8 @@ The array element specifies a loadable segment, described by and .Sy p_memsz . The bytes from the file are mapped to the beginning of the memory -segment. If the segment's memory size ( +segment. +If the segment's memory size ( .Sy p_memsz ) is larger than the file size ( @@ -431,7 +461,8 @@ size ( ), the .Dq extra bytes are defined to hold the value 0 and to follow the segment's -initialized area. The file size may not be larger than the memory size. +initialized area. +The file size may not be larger than the memory size. Loadable segment entries in the program header table appear in ascending order, sorted on the .Sy p_vaddr @@ -440,21 +471,26 @@ member. The array element specifies dynamic linking information. .It Dv PT_INTERP The array element specifies the location and size of a null-terminated -path name to invoke as an interpreter. This segment type is meaningful +path name to invoke as an interpreter. +This segment type is meaningful only for executable files (though it may occur for shared objects). However -it may not occur more than once in a file. If it is present it must precede +it may not occur more than once in a file. +If it is present it must precede any loadable segment entry. .It Dv PT_NOTE The array element specifies the location and size for auxiliary information. .It Dv PT_SHLIB -This segment type is reserved but has unspecified semantics. Programs that +This segment type is reserved but has unspecified semantics. +Programs that contain an array element of this type do not conform to the ABI. .It Dv PT_PHDR The array element, if present, specifies the location and size of the program header table itself, both in the file and in the memory image of the program. -This segment type may not occur more than once in a file. Moreover, it may +This segment type may not occur more than once in a file. +Moreover, it may only occur if the program header table is part of the memory image of the -program. If it is present it must precede any loadable segment entry. +program. +If it is present it must precede any loadable segment entry. .It Dv PT_LOPROC This value up to and including .Sy PT_HIPROC @@ -473,7 +509,8 @@ This member holds the virtual address at which the first byte of the segment resides in memory. .It Dv p_paddr On systems for which physical addressing is relevant, this member is -reserved for the segment's physical address. Under BSD this member is +reserved for the segment's physical address. +Under BSD this member is not used and must be zero. .It Dv p_filesz This member holds the number of bytes in the file image of the segment. @@ -504,11 +541,13 @@ and .Sy PF_R . .It Dv p_align This member holds the value to which the segments are aligned in memory -and in the file. Loadable process segments must have congruent values for +and in the file. +Loadable process segments must have congruent values for .Sy p_vaddr and .Sy p_offset , -modulo the page size. Values of zero and one mean no alignment is required. +modulo the page size. +Values of zero and one mean no alignment is required. Otherwise, .Sy p_align should be a positive, integral power of two, and @@ -519,8 +558,10 @@ modulo .Sy p_align . .El .Pp -An file's section header table lets one locate all the file's sections. The -section header table is an array of Elf32_Shdr or Elf64_Shdr structures. The +An file's section header table lets one locate all the file's sections. +The +section header table is an array of Elf32_Shdr or Elf64_Shdr structures. +The ELF header's .Sy e_shoff member gives the byte offset from the beginning of the file to the section @@ -530,8 +571,10 @@ holds the number of entries the section header table contains. .Sy e_shentsize holds the size in bytes of each entry. .Pp -A section header table index is a subscript into this array. Some section -header table indices are reserved. An object file does not have sections for +A section header table index is a subscript into this array. +Some section +header table indices are reserved. +An object file does not have sections for these special indices: .Pp .Bl -tag -width "SHN_LORESERVE" -compact @@ -549,7 +592,8 @@ This value down to and including .Sy SHN_LOPROC are reserved for processor-specific semantics. .It Dv SHN_ABS -This value specifies absolute values for the corresponding reference. For +This value specifies absolute values for the corresponding reference. +For example, symbols defined relative to section number .Sy SHN_ABS have absolute values and are not affected by relocation. @@ -557,12 +601,14 @@ have absolute values and are not affected by relocation. Symbols defined relative to this section are common symbols, such as FORTRAN COMMON or unallocated C external variables. .It Dv SHN_HIRESERVE -This value specifies the upper bound of the range of reserved indices. The +This value specifies the upper bound of the range of reserved indices. +The system reserves indices between .Sy SHN_LORESERVE and .Sy SHN_HIRESERVE, -inclusive. The section header table does not contain entries for the +inclusive. +The section header table does not contain entries for the reserved indices. .El .Pp @@ -599,7 +645,8 @@ typedef struct { .Pp .Bl -tag -width "sh_addralign" -compact .It Dv sh_name -This member specifies the name of the section. Its value is an index +This member specifies the name of the section. +Its value is an index into the section header string table section, giving the location of a null-terminated string. .It Dv sh_type @@ -607,36 +654,46 @@ This member categorizes the section's contents and semantics. .Pp .Bl -tag -width "SHT_PROGBITS" -compact .It Dv SHT_NULL -This value marks the section header as inactive. It does not -have an associated section. Other members of the section header +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header have undefined values. .It Dv SHT_PROGBITS The section holds information defined by the program, whose format and meaning are determined solely by the program. .It Dv SHT_SYMTAB -This section holds a symbol table. Typically, +This section holds a symbol table. +Typically, .Sy SHT_SYMTAB provides symbols for link editing, though it may also be used -for dynamic linking. As a complete symbol table, it may contain -many symbols unnecessary for dynamic linking. An object file can +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can also contain a .Sy SHN_DYNSYM section. .It Dv SHT_STRTAB -This section holds a string table. An object file may have multiple +This section holds a string table. +An object file may have multiple string table sections. .It Dv SHT_RELA This section holds relocation entries with explicit addends, such as type .Sy Elf32_Rela -for the 32-bit class of object files. An object may have multiple +for the 32-bit class of object files. +An object may have multiple relocation sections. .It Dv SHT_HASH -This section holds a symbol hash table. All object participating in -dynamic linking must contain a symbol hash table. An object file may +This section holds a symbol hash table. +All object participating in +dynamic linking must contain a symbol hash table. +An object file may have only one hash table. .It Dv SHT_DYNAMIC -This section holds information for dynamic linking. An object file may +This section holds information for dynamic linking. +An object file may have only one dynamic section. .It Dv SHT_NOTE This section holds information that marks the file in some way. @@ -651,12 +708,14 @@ member contains the conceptual file offset. This section holds relocation offsets without explicit addends, such as type .Sy Elf32_Rel -for the 32-bit class of object files. An object file may have multiple +for the 32-bit class of object files. +An object file may have multiple relocation sections. .It Dv SHT_SHLIB This section is reserved but has unspecified semantics. .It Dv SHT_DYNSYM -This section holds a minimal set of dynamic linking symbols. An +This section holds a minimal set of dynamic linking symbols. +An object file can also contain a .Sy SHN_SYMTAB section. @@ -673,7 +732,8 @@ This value specifies the lower bound of the range of indices reserved for application programs. .It Dv SHT_HIUSER This value specifies the upper bound of the range of indices reserved for -application programs. Section types between +application programs. +Section types between .Sy SHT_LOUSER and .Sy SHT_HIUSER @@ -687,17 +747,21 @@ If a flag bit is set in .Sy sh_flags , the attribute is .Dq on -for the section. Otherwise, the attribute is +for the section. +Otherwise, the attribute is .Dq off -or does not apply. Undefined attributes are set to zero. +or does not apply. +Undefined attributes are set to zero. .Pp .Bl -tag -width "SHF_EXECINSTR" -compact .It Dv SHF_WRITE This section contains data that should be writable during process execution. .It Dv SHF_ALLOC -The section occupies memory during process execution. Some control -sections do not reside in the memory image of an object file. This +The section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This attribute is off for those sections. .It Dv SHF_EXECINSTR The section contains executable machine instructions. @@ -712,18 +776,21 @@ holds the address at which the section's first byte should reside. Otherwise, the member contains zero. .It Dv sh_offset This member's value holds the byte offset from the beginning of the file -to the first byte in the section. One section type, +to the first byte in the section. +One section type, .Sy SHT_NOBITS , occupies no space in the file, and its .Sy sh_offset member locates the conceptual placement in the file. .It Dv sh_size -This member holds the section's size in bytes. Unless the section type +This member holds the section's size in bytes. +Unless the section type is .Sy SHT_NOBITS , the section occupies .Sy sh_size -bytes in the file. A section of type +bytes in the file. +A section of type .Sy SHT_NOBITS may have a non-zero size, but it occupies no space in the file. .It Dv sh_link @@ -733,13 +800,16 @@ depends on the section type. This member holds extra information, whose interpretation depends on the section type. .It Dv sh_addralign -Some sections have address alignment constraints. If a section holds a +Some sections have address alignment constraints. +If a section holds a doubleword, the system must ensure doubleword alignment for the entire -section. That is, the value of +section. +That is, the value of .Sy sh_addr must be congruent to zero, modulo the value of .Sy sh_addralign . -Only zero and positive integral powers of two are allowed. Values of zero +Only zero and positive integral powers of two are allowed. +Values of zero or one mean the section has no alignment constraints. .It Dv sh_entsize Some sections hold a table of fixed-sized entries, such as a symbol table. @@ -752,20 +822,24 @@ Various sections hold program and control information: .Bl -tag -width ".shstrtab" -compact .It .bss This section holds uninitialized data that contributes to the program's -memory image. By definition, the system initializes the data with zeros -when the program begins to run. This section is of type +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type .Sy SHT_NOBITS . The attributes types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .comment -This section holds version control information. This section is of type +This section holds version control information. +This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .data This section holds initialized data that contribute to the program's -memory image. This section is of type +memory image. +This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC @@ -773,24 +847,30 @@ and .Sy SHF_WRITE . .It .data1 This section holds initialized data that contribute to the program's -memory image. This section is of type +memory image. +This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .debug -This section holds information for symbolic debugging. The contents -are unspecified. This section is of type +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .dynamic -This section holds dynamic linking information. The section's attributes +This section holds dynamic linking information. +The section's attributes will include the .Sy SHF_ALLOC -bit. Whether the +bit. +Whether the .Sy SHF_WRITE -bit is set is processor-specific. This section is of type +bit is set is processor-specific. +This section is of type .Sy SHT_DYNAMIC . See the attributes above. .It .dynstr @@ -801,31 +881,37 @@ This section is of type The attribute type used is .Sy SHF_ALLOC . .It .dynsym -This section holds the dynamic linking symbol table. This section is of type +This section holds the dynamic linking symbol table. +This section is of type .Sy SHT_DYNSYM . The attribute used is .Sy SHF_ALLOC . .It .fini This section holds executable instructions that contribute to the process -termination code. When a program exits normally the system arranges to -execute the code in this section. This section is of type +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .got -This section holds the global offset table. This section is of type +This section holds the global offset table. +This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .hash -This section holds a symbol hash table. This section is of type +This section holds a symbol hash table. +This section is of type .Sy SHT_HASH . The attribute used is .Sy SHF_ALLOC . .It .init This section holds executable instructions that contribute to the process -initialization code. When a program starts to run the system arranges to +initialization code. +When a program starts to run the system arranges to execute the code in this section before calling the main program entry point. This section is of type .Sy SHT_PROGBITS . @@ -834,36 +920,46 @@ The attributes used are and .Sy SHF_EXECINSTR . .It .interp -This section holds the pathname of a program interpreter. If the file has +This section holds the pathname of a program interpreter. +If the file has a loadable segment that includes the section, the section's attributes will include the .Sy SHF_ALLOC -bit. Otherwise, that bit will be off. This section is of type +bit. +Otherwise, that bit will be off. +This section is of type .Sy SHT_PROGBITS . .It .line This section holds line number information for symbolic debugging, which describes the correspondence between the program source and the machine code. -The contents are unspecified. This section is of type +The contents are unspecified. +This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .note This section holds information in the .Dq Note Section -format described below. This section is of type +format described below. +This section is of type .Sy SHT_NOTE . No attribute types are used. .It .plt -This section holds the procedure linkage table. This section is of type +This section holds the procedure linkage table. +This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .relNAME -This section holds relocation information as described below. If the file +This section holds relocation information as described below. +If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC -bit. Otherwise the bit will be off. By convention, +bit. +Otherwise the bit will be off. +By convention, .Dq NAME -is supplied by the section to which the relocations apply. Thus a relocation +is supplied by the section to which the relocations apply. +Thus a relocation section for .Sy .text normally would have the name @@ -871,13 +967,17 @@ normally would have the name This section is of type .Sy SHT_REL . .It .relaNAME -This section holds relocation information as described below. If the file +This section holds relocation information as described below. +If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC -bit. Otherwise the bit will be off. By convention, +bit. +Otherwise the bit will be off. +By convention, .Dq NAME -is supplied by the section to which the relocations apply. Thus a relocation +is supplied by the section to which the relocations apply. +Thus a relocation section for .Sy .text normally would have the name @@ -886,39 +986,49 @@ This section is of type .Sy SHT_RELA . .It .rodata This section holds read-only data that typically contributes to a -non-writable segment in the process image. This section is of type +non-writable segment in the process image. +This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .rodata1 This section hold read-only data that typically contributes to a -non-writable segment in the process image. This section is of type +non-writable segment in the process image. +This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .shstrtab -This section holds section names. This section is of type +This section holds section names. +This section is of type .Sy SHT_STRTAB . No attribute types are used. .It .strtab This section holds strings, most commonly the strings that represent the -names associated with symbol table entries. If the file has a loadable +names associated with symbol table entries. +If the file has a loadable segment that includes the symbol string table, the section's attributes will include the .Sy SHF_ALLOC -bit. Otherwise the bit will be off. This section is of type +bit. +Otherwise the bit will be off. +This section is of type .Sy SHT_STRTAB . .It .symtab -This section holds a symbol table. If the file has a loadable segment +This section holds a symbol table. +If the file has a loadable segment that includes the symbol table, the section's attributes will include the .Sy SHF_ALLOC -bit. Otherwise the bit will be off. This section is of type +bit. +Otherwise the bit will be off. +This section is of type .Sy SHT_SYMTAB . .It .text This section holds the .Dq text , -or executable instructions, of a program. This section is of type +or executable instructions, of a program. +This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC @@ -927,14 +1037,19 @@ and .El .Pp String table sections hold null-terminated character sequences, commonly -called strings. The object file uses these strings to represent symbol -and section names. One references a string as an index into the string -table section. The first byte, which is index zero, is defined to hold -a null character. Similarly, a string table's last byte is defined to +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null character. +Similarly, a string table's last byte is defined to hold a null character, ensuring null termination for all strings. .Pp An object file's symbol table holds information needed to locate and -relocate a program's symbolic definitions and references. A symbol table +relocate a program's symbolic definitions and references. +A symbol table index is a subscript into this array. .Pp .Bd -literal -offset indent @@ -962,13 +1077,16 @@ typedef struct { .Bl -tag -width "st_value" -compact .It Dv st_name This member holds an index into the object file's symbol string table, -which holds character representations of the symbol names. If the value +which holds character representations of the symbol names. +If the value is non-zero, it represents a string table index that gives the symbol -name. Otherwise, the symbol table has no name. +name. +Otherwise, the symbol table has no name. .It Dv st_value This member gives the value of the associated symbol. .It Dv st_size -Many symbols have associated sizes. This member holds zero if the symbol +Many symbols have associated sizes. +This member holds zero if the symbol has no size or an unknown size. .It Dv st_info This member specifies the symbol's type and binding attributes: @@ -981,13 +1099,15 @@ The symbol is associated with a data object. .It Dv STT_FUNC The symbol is associated with a function or other executable code. .It Dv STT_SECTION -The symbol is associated with a section. Symbol table entries of +The symbol is associated with a section. +Symbol table entries of this type exist primarily for relocation and normally have .Sy STB_LOCAL bindings. .It Dv STT_FILE By convention the symbol's name gives the name of the source file -associated with the object file. A file symbol has +associated with the object file. +A file symbol has .Sy STB_LOCAL bindings, its section index is .Sy SHN_ABS , @@ -1007,10 +1127,12 @@ are reserved for processor-specific semantics. .Bl -tag -width "STB_GLOBAL" -compact .It Dv STB_LOCAL Local symbols are not visible outside the object file containing their -definition. Local symbols of the same name may exist in multiple file +definition. +Local symbols of the same name may exist in multiple file without interfering with each other. .It Dv STB_GLOBAL -Global symbols are visible to all object files being combined. One file's +Global symbols are visible to all object files being combined. +One file's definition of a global symbol will satisfy another file's undefined reference to the same symbol. .It Dv STB_WEAK @@ -1047,15 +1169,18 @@ This member currently holds zero and has no defined meaning. .It Dv st_shndx Every symbol table entry is .Dq defined -in relation to some action. This member holds the relevant section +in relation to some action. +This member holds the relevant section header table index. .El .Pp Relocation is the process of connecting symbolic references with -symbolic definitions. Relocatable files must have information that +symbolic definitions. +Relocatable files must have information that describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process' -program image. Relocation entries are these data. +program image. +Relocation entries are these data. .Pp Relocation structures that do not need an addend: .Pp @@ -1093,13 +1218,16 @@ typedef struct { .It Dv r_offset This member gives the location at which to apply the relocation action. For a relocatable file, the value is the byte offset from the beginning -of the section to the storage unit affected by the relocation. For an +of the section to the storage unit affected by the relocation. +For an executable file or shared object, the value is the virtual address of the storage unit affected by the relocation. .It Dv r_info This member gives both the symbol table index with respect to which the -relocation must be made and the type of relocation to apply. Relocation -types are processor-specific. When the text refers to a relocation +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation entry's relocation type or symbol table index, it means the result of applying .Sy ELF_[32|64]_R_TYPE diff --git a/share/man/man5/fbtab.5 b/share/man/man5/fbtab.5 index 728e86b605ec..7abacb9d4bdb 100644 --- a/share/man/man5/fbtab.5 +++ b/share/man/man5/fbtab.5 @@ -20,7 +20,8 @@ All other lines consist of three fields delimited by whitespace: a login device (/dev/ttyv0), an octal permission number (0600), and a ":"-delimited list of devices (/dev/console). All device names are -absolute paths. A path that ends in "/*" refers to all +absolute paths. +A path that ends in "/*" refers to all directory entries except "." and "..". .Pp If the tty argument (relative path) matches a login device diff --git a/share/man/man5/link.5 b/share/man/man5/link.5 index 2991453a7570..d683aa02b1f0 100644 --- a/share/man/man5/link.5 +++ b/share/man/man5/link.5 @@ -44,12 +44,15 @@ The include file declares several structures that are present in dynamically linked programs and libraries. The structures define the interface between several components of the -link-editor and loader mechanism. The layout of a number of these +link-editor and loader mechanism. +The layout of a number of these structures within the binaries resembles the a.out format in many places as it serves such similar functions as symbol definitions (including the accompanying string table) and relocation records needed to resolve -references to external entities. It also records a number of data structures -unique to the dynamic loading and linking process. These include references +references to external entities. +It also records a number of data structures +unique to the dynamic loading and linking process. +These include references to other objects that are required to complete the link-editing process and indirection tables to facilitate .Em Position Independent Code @@ -63,36 +66,45 @@ format offers no room for it elsewhere. .Pp Several utilities cooperate to ensure that the task of getting a program ready to run can complete successfully in a way that optimizes the use -of system resources. The compiler emits PIC code from which shared libraries +of system resources. +The compiler emits PIC code from which shared libraries can be built by .Xr ld 1 . The compiler also includes size information of any initialized data items -through the .size assembler directive. PIC code differs from conventional code +through the .size assembler directive. +PIC code differs from conventional code in that it accesses data variables through an indirection table, the Global Offset Table, by convention accessible by the reserved name .Em _GLOBAL_OFFSET_TABLE_. The exact mechanism used for this is machine dependent, usually a machine -register is reserved for the purpose. The rational behind this construct -is to generate code that is independent of the actual load address. Only +register is reserved for the purpose. +The rational behind this construct +is to generate code that is independent of the actual load address. +Only the values contained in the Global Offset Table may need updating at run-time depending on the load addresses of the various shared objects in the address space. .Pp Likewise, procedure calls to globally defined functions are redirected through the Procedure Linkage Table (PLT) residing in the data segment of the core -image. Again, this is done to avoid run-time modifications to the text segment. +image. +Again, this is done to avoid run-time modifications to the text segment. .Pp The linker-editor allocates the Global Offset Table and Procedure Linkage Table when combining PIC object files into an image suitable for mapping into the -process address space. It also collects all symbols that may be needed by the +process address space. +It also collects all symbols that may be needed by the run-time link-editor and stores these along with the image's text and data bits. Another reserved symbol, .Em _DYNAMIC -is used to indicate the presence of the run-time linker structures. Whenever +is used to indicate the presence of the run-time linker structures. +Whenever _DYNAMIC is relocated to 0, there is no need to invoke the run-time -link-editor. If this symbol is non-zero, it points at a data structure from +link-editor. +If this symbol is non-zero, it points at a data structure from which the location of the necessary relocation- and symbol information can -be derived. This is most notably used by the start-up module, +be derived. +This is most notably used by the start-up module, .Em crt0. The _DYNAMIC structure is conventionally located at the start of the data segment of the image to which it pertains. @@ -120,7 +132,8 @@ struct _dynamic { .Bl -tag -width d_version .It Fa d_version This field provides for different versions of the dynamic linking -implementation. The current version numbers understood by +implementation. +The current version numbers understood by .Xr ld 1 and .Xr ld.so 1 @@ -300,12 +313,15 @@ structure. Hook for attaching private data maintained by the run-time link-editor. .El .Pp -Symbol description with size. This is simply an +Symbol description with size. +This is simply an .Fa nlist structure with one field .Pq Fa nz_size -added. Used to convey size information on items in the data segment -of shared objects. An array of these lives in the shared object's +added. +Used to convey size information on items in the data segment +of shared objects. +An array of these lives in the shared object's text segment and is addressed by the .Fa sdt_nzlist field of @@ -356,12 +372,14 @@ The index of the symbol in the shared object's symbol table (as given by the field). .It Fa rh_next In case of collisions, this field is the offset of the next entry in this -hash table bucket. It is zero for the last bucket element. +hash table bucket. +It is zero for the last bucket element. .El The .Fa rt_symbol structure is used to keep track of run-time allocated commons -and data items copied from shared objects. These items are kept on linked list +and data items copied from shared objects. +These items are kept on linked list and is exported through the .Fa dd_cc field in the @@ -383,7 +401,8 @@ The symbol description. .It Fa rt_next Virtual address of next rt_symbol. .It Fa rt_link -Next in hash bucket. Used by internally by +Next in hash bucket. +Used by internally by .Nm ld.so . .It Fa rt_srcaddr Location of the source of initialized data within a shared object. @@ -396,7 +415,8 @@ The .Fa so_debug structure is used by debuggers to gain knowledge of any shared objects that have been loaded in the process's address space as a result of run-time -link-editing. Since the run-time link-editor runs as a part of process +link-editing. +Since the run-time link-editor runs as a part of process initialization, a debugger that wishes to access symbols from shared objects can only do so after the link-editor has been called from crt0. A dynamically linked binary contains a @@ -426,7 +446,8 @@ run under control of a debugger. Set by the run-time linker whenever it adds symbols by loading shared objects. .It Fa dd_bpt_addr The address were a breakpoint will be set by the run-time linker to -divert control to the debugger. This address is determined by the start-up +divert control to the debugger. +This address is determined by the start-up module, .Em crt0.o, to be some convenient place before the call to _main. @@ -485,7 +506,8 @@ was loaded by crt0. .It Fa crt_dzfd On SunOS systems, this field contains an open file descriptor to .Dq Pa /dev/zero -used to get demand paged zeroed pages. On +used to get demand paged zeroed pages. +On .Tn FreeBSD systems it contains -1. .It Fa crt_ldfd diff --git a/share/man/man5/passwd.5 b/share/man/man5/passwd.5 index 890f021571b9..53f6b7bf5fd5 100644 --- a/share/man/man5/passwd.5 +++ b/share/man/man5/passwd.5 @@ -190,7 +190,8 @@ The system administrator can configure to use NIS/YP for its password information by adding special records to the .Pa /etc/master.passwd -file. These entries should be added with +file. +These entries should be added with .Xr vipw 8 so that the changes can be properly merged with the hashed password databases and the @@ -220,10 +221,12 @@ Note that the entry shown above is known as a .Em wildcard entry, because it matches all users (the `+' without any other information matches everybody) and allows all NIS password data to be retrieved -unaltered. However, by +unaltered. +However, by specifying a username or netgroup next to the `+' in the NIS entry, the administrator can affect what data are extracted from the -NIS passwd maps and how it is interpreted. Here are a few example +NIS passwd maps and how it is interpreted. +Here are a few example records that illustrate this feature (note that you can have several NIS entries in a single .Pa master.passwd @@ -240,8 +243,10 @@ file): Specific usernames are listed explicitly while netgroups are signified by a preceding `@'. In the above example, users in the ``staff'' and ``permitted-users'' netgroups will have their password information -read from NIS and used unaltered. In other words, they will be allowed -normal access to the machine. Users ``ken'' and ``dennis,'' who have +read from NIS and used unaltered. +In other words, they will be allowed +normal access to the machine. +Users ``ken'' and ``dennis,'' who have been named explicitly rather than through a netgroup, will also have their password data read from NIS, _except_ that user ``ken'' will have his shell remapped to @@ -250,7 +255,8 @@ This means that value for his shell specified in the NIS password map will be overridden by the value specified in the special NIS entry in the local .Pa master.passwd -file. User ``ken'' may have been assigned the csh shell because his +file. +User ``ken'' may have been assigned the csh shell because his NIS password entry specified a different shell that may not be installed on the client machine for political or technical reasons. Meanwhile, users in the ``rejected-users'' netgroup are prevented @@ -261,12 +267,14 @@ User ``mitnick'' will be be ignored entirely because his entry is specified with a `-' instead of a `+'. A minus entry can be used to block out certain NIS password entries completely; users who's password data has been excluded in this way are not recognized by -the system at all. (Any overrides specified with minus entries are +the system at all. +(Any overrides specified with minus entries are also ignored since there is no point in processing override information for a user that the system isn't going to recognize in the first place.) In general, a minus entry is used to specifically exclude a user who might otherwise be granted access because he happens to be a -member of an authorized netgroup. For example, if ``mitnick'' is +member of an authorized netgroup. +For example, if ``mitnick'' is a member of the ``permitted-users'' netgroup and must, for whatever the reason, be permitted to remain in that netgroup (possibly to retain access to other machines within the domain), the administrator @@ -276,12 +284,14 @@ allowed access rather than generate a possibly complicated list of users who are allowed access and omit the rest. .Pp Note that the plus and minus entries are evaluated in order from -first to last with the first match taking precedence. This means +first to last with the first match taking precedence. +This means the system will only use the first entry that matches a particular user. If, for instance, we have a user ``foo'' who is a member of both the ``staff'' netgroup and the ``rejected-users'' netgroup, he will be admitted to the system because the above example lists the entry for ``staff'' -before the entry for ``rejected-users.'' If we reversed the order, +before the entry for ``rejected-users.'' +If we reversed the order, user ``foo'' would be flagged as a ``rejected-user'' instead and denied access. .Pp @@ -294,11 +304,13 @@ entries). In our example shown above, we do not have a wildcard entry at the end of the list; therefore, the system will not recognize anyone except ``ken,'' ``dennis,'' the ``staff'' netgroup and the ``permitted-users'' -netgroup as authorized users. The ``rejected-users'' netgroup will +netgroup as authorized users. +The ``rejected-users'' netgroup will be recognized but all members will have their shells remapped and therefore be denied access. All other NIS password records -will be ignored. The administrator may add a wildcard entry to the +will be ignored. +The administrator may add a wildcard entry to the end of the list such as: .Bd -literal -offset indent +:::::::::/usr/local/bin/go_away @@ -309,7 +321,8 @@ any of the other entries. .Pa /usr/local/bin/go_away can be a short shell script or program that prints a message telling the user that he is not allowed access -to the system. This technique is sometimes useful when it is +to the system. +This technique is sometimes useful when it is desirable to have the system be able to recognize all users in a particular NIS domain without necessarily granting them login access. See the above text on the shell field regarding security concerns when using @@ -318,7 +331,8 @@ a shell script as the login shell. The primary use of this .Pa override feature is to permit the administrator -to enforce access restrictions on NIS client systems. Users can be +to enforce access restrictions on NIS client systems. +Users can be granted access to one group of machines and denied access to other machines simply by adding or removing them from a particular netgroup. Since the netgroup database can also be accessed via NIS, this allows @@ -334,10 +348,12 @@ are stored only in .Pa /etc/master.passwd and .Pa /etc/spwd.db , -which are readable and writable only by the superuser. This is done +which are readable and writable only by the superuser. +This is done to prevent users from running the encrypted passwords through password-guessing programs and gaining unauthorized access to -other users' accounts. NIS does not support a standard means of +other users' accounts. +NIS does not support a standard means of password shadowing, which implies that placing your password data into the NIS passwd maps totally defeats the security of .Tn FreeBSD Ns 's @@ -345,11 +361,13 @@ password shadowing system. .Pp .Tn FreeBSD provides a few special features to help get around this -problem. It is possible to implement password shadowing between +problem. +It is possible to implement password shadowing between .Tn FreeBSD NIS clients and .Tn FreeBSD -NIS servers. The +NIS servers. +The .Xr getpwent 3 routines will search for a .Pa master.passwd.byname @@ -357,7 +375,8 @@ and .Pa master.passwd.byuid maps which should contain the same data found in the .Pa /etc/master.passwd -file. If the maps exist, +file. +If the maps exist, .Tn FreeBSD will attempt to use them for user authentication instead of the standard @@ -368,12 +387,14 @@ maps. .Tn FreeBSD Ns 's .Xr ypserv 8 will also check client requests to make sure they originate on a -privileged port. Since only the superuser is allowed to bind to +privileged port. +Since only the superuser is allowed to bind to a privileged port, the server can tell if the requesting user is the superuser; all requests from non-privileged users to access the .Pa master.passwd -maps will be refused. Since all user authentication programs run +maps will be refused. +Since all user authentication programs run with superuser privilege, they should have the required access to users' encrypted password data while normal users will only be allowed access to the standard @@ -382,7 +403,8 @@ maps which contain no password information. .Pp Note that this feature cannot be used in an environment with .No non- Ns Tn FreeBSD -systems. Note also that a truly determined user with +systems. +Note also that a truly determined user with unrestricted access to your network could still compromise the .Pa master.passwd maps. @@ -407,7 +429,8 @@ This entry will cause all users in the `foo-users' netgroup to have .Pa all of their password information overridden, including UIDs, -GIDs and passwords. The result is that all `foo-users' will be +GIDs and passwords. +The result is that all `foo-users' will be locked out of the system, since their passwords will be remapped to invalid values. .Pp @@ -451,21 +474,25 @@ password .Pa /etc/passwd file is in plain .Tn ASCII -format. The +format. +The .Tn SunOS documentation claims that adding a '+' entry to the password file causes the contents of the NIS password database to be 'inserted' at the position in -the file where the '+' entry appears. If, for example, the +the file where the '+' entry appears. +If, for example, the administrator places the +:::::: entry in the middle of .Pa /etc/passwd, then the entire contents of the NIS password map would appear as though it had been copied into the middle of the password -file. If the administrator places the +:::::: entry at both the +file. +If the administrator places the +:::::: entry at both the middle and the end of .Pa /etc/passwd , then the NIS password map would appear twice: once in the middle -of the file and once at the end. (By using override entries +of the file and once at the end. +(By using override entries instead of simple wildcards, other combinations could be achieved.) .Pp By contrast, @@ -473,7 +500,8 @@ By contrast, does not have a single .Tn ASCII password file: it -has a hashed password database. This database does not have an +has a hashed password database. +This database does not have an easily-defined beginning, middle or end, which makes it very hard to design a scheme that is 100% compatible with .Tn SunOS . @@ -485,8 +513,10 @@ and functions in .Tn FreeBSD are designed to do direct queries to the -hash database rather than a linear search. This approach is faster -on systems where the password database is large. However, when +hash database rather than a linear search. +This approach is faster +on systems where the password database is large. +However, when using direct database queries, the system does not know or care about the order of the original password file, and therefore it cannot easily apply the same override logic used by @@ -495,7 +525,8 @@ it cannot easily apply the same override logic used by Instead, .Tn FreeBSD groups all the NIS override entries together -and constructs a filter out of them. Each NIS password entry +and constructs a filter out of them. +Each NIS password entry is compared against the override filter exactly once and treated accordingly: if the filter allows the entry through unaltered, it's treated unaltered; if the filter calls for remapping @@ -536,13 +567,15 @@ In %99 of all configurations, NIS client behavior will be indistinguishable from that of .Tn SunOS -or other similar systems. Even +or other similar systems. +Even so, users should be aware of these architectural differences. .Pp .Ss Using groups instead of netgroups for NIS overrides .Tn FreeBSD offers the capability to do override matching based on -user groups rather than netgroups. If, for example, an NIS entry +user groups rather than netgroups. +If, for example, an NIS entry is specified as: .Bd -literal -offset indent +@operator::::::::: @@ -567,7 +600,8 @@ was possible for .Fn getpwuid to return a login name that .Fn getpwnam -would not recognize. This has been fixed: overrides specified +would not recognize. +This has been fixed: overrides specified in .Pa /etc/master.passwd now apply to all @@ -580,7 +614,8 @@ netgroup overrides did not work at all, largely because .Tn FreeBSD did not have support for reading -netgroups through NIS. Again, this has been fixed, and +netgroups through NIS. +Again, this has been fixed, and netgroups can be specified just as in .Tn SunOS and similar NIS-capable diff --git a/share/man/man8/yp.8 b/share/man/man8/yp.8 index bc268565d29e..dda8944bb79e 100644 --- a/share/man/man8/yp.8 +++ b/share/man/man8/yp.8 @@ -88,7 +88,8 @@ is an client/server system that allows a group of machines within an .Tn NIS -domain to share a common set of configuration files. This permits a system +domain to share a common set of configuration files. +This permits a system administrator to set up .Tn NIS client systems with only minimal configuration @@ -109,11 +110,13 @@ where .Pa [domainname] is the name of the .Tn NIS -domain being served. A single +domain being served. +A single .Tn NIS server can support several domains at once, therefore it is possible to have several -such directories, one for each supported domain. Each domain will have +such directories, one for each supported domain. +Each domain will have its own independent set of maps. .Pp In @@ -137,8 +140,10 @@ into and .Em .pag files which the ndbm code uses to hold separate parts of the hash -database. The Berkeley DB hash method instead uses a single file for -both pieces of information. This means that while you may have +database. +The Berkeley DB hash method instead uses a single file for +both pieces of information. +This means that while you may have .Pa passwd.byname.dir and .Pa passwd.byname.pag @@ -153,7 +158,8 @@ server, .Xr ypserv 8 , and related tools need to know the database format of the .Tn NIS -maps. Client +maps. +Client .Tn NIS systems receive all .Tn NIS @@ -200,20 +206,24 @@ command) and begins broadcasting requests on the local network. These requests specify the name of the domain for which .Xr ypbind 8 -is attempting to establish a binding. If a server that has been +is attempting to establish a binding. +If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to .Xr ypbind 8 , -which will record the server's address. If there are several servers +which will record the server's address. +If there are several servers available (a master and several slaves, for example), .Xr ypbind 8 -will use the address of the first one to respond. From that point +will use the address of the first one to respond. +From that point on, the client system will direct all of its .Tn NIS requests to that server. .Xr Ypbind 8 will occasionally ``ping'' the server to make sure it's still up -and running. If it fails to receive a reply to one of its pings +and running. +If it fails to receive a reply to one of its pings within a reasonable amount of time, .Xr ypbind 8 will mark the domain as unbound and begin broadcasting again in the @@ -231,7 +241,8 @@ is responsible for receiving incoming requests from clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database -back to the client. There is a specific set of requests that +back to the client. +There is a specific set of requests that .Xr ypserv 8 is designed to handle, most of which are implemented as functions within the standard C library: @@ -280,11 +291,13 @@ and are not meant to be used by standard utilities. .Pp On networks with a large number of hosts, it is often a good idea to use a master server and several slaves rather than just a single master -server. A slave server provides the exact same information as a master +server. +A slave server provides the exact same information as a master server: whenever the maps on the master server are updated, the new data should be propagated to the slave systems using the .Xr yppush 8 -command. The +command. +The .Tn NIS Makefile .Pf ( Pa /var/yp/Makefile ) @@ -305,8 +318,10 @@ master server using automatically from within .Xr ypserv 8 ; therefore it is not usually necessary for the administrator -to use it directly. It can be run manually if -desired, however.) Maintaining +to use it directly. +It can be run manually if +desired, however.) +Maintaining slave servers helps improve .Tn NIS performance on large @@ -328,11 +343,13 @@ domain to extend beyond a local network (the .Xr ypbind 8 daemon might not be able to locate a server automatically if it resides on -a network outside the reach of its broadcasts. It is possible to force +a network outside the reach of its broadcasts. +It is possible to force .Xr ypbind 8 to bind to a particular server with .Xr ypset 8 -but this is sometimes inconvenient. This problem can be avoided simply by +but this is sometimes inconvenient. +This problem can be avoided simply by placing a slave server on the local network.) .El .Pp @@ -345,7 +362,8 @@ other implementations) when used exclusively with .Bx Free client -systems. The +systems. +The .Bx Free password database system (which is derived directly from @@ -373,8 +391,10 @@ in a special way: the server will only provide access to these maps in response to requests that originate on privileged ports. Since only the super-user is allowed to bind to a privileged port, the server assumes that all such requests come from privileged -users. All other requests are denied: requests from non-privileged -ports will receive only an error code from the server. Additionally, +users. +All other requests are denied: requests from non-privileged +ports will receive only an error code from the server. +Additionally, .Bx Free Ns 's .Xr ypserv 8 includes support for Wietse Venema's tcp wrapper package; with tcp @@ -384,7 +404,8 @@ to respond only to selected client machines. .Pp While these enhancements provide better security than stock .Tn NIS Ns , -they are by no means 100% effective. It is still possible for +they are by no means 100% effective. +It is still possible for someone with access to your network to spoof the server into disclosing the shadow password maps. .Pp @@ -393,9 +414,11 @@ On the client side, .Fn getpwent 3 functions will automatically search for the .Pa master.passwd -maps and use them if they exist. If they do, they will be used, and +maps and use them if they exist. +If they do, they will be used, and all fields in these special maps (class, password age and account -expiration) will be decoded. If they aren't found, the standard +expiration) will be decoded. +If they aren't found, the standard .Pa passwd maps will be used instead. .Sh COMPATIBILITY @@ -405,7 +428,8 @@ to be running in order for their hostname resolution functions ( .Fn gethostbyname , .Fn gethostbyaddr , -etc) to work properly. On these systems, +etc) to work properly. +On these systems, .Xr ypserv 8 performs .Tn DNS @@ -425,12 +449,14 @@ if desired), therefore its server doesn't do .Tn DNS lookups -by default. However, +by default. +However, .Xr ypserv 8 can be made to perform .Tn DNS lookups if it is started with a special -flag. It can also be made to register itself as an +flag. +It can also be made to register itself as an .Tn NIS v1 server in order to placate certain systems that insist on the presence of @@ -463,7 +489,8 @@ client and server capabilities, it does not yet have support for .Xr ypupdated 8 or the .Fn yp_update -function. Both of these require secure +function. +Both of these require secure .Tn RPC Ns , which .Bx Free @@ -476,7 +503,8 @@ and .Xr getprotoent 3 functions do not yet have .Tn NIS -support. Fortunately, these files +support. +Fortunately, these files don't need to be updated that often. .Pp Many more manual pages should be written, especially @@ -492,7 +520,8 @@ The .Nm YP subsystem was written from the ground up by .An Theo de Raadt -to be compatible to Sun's implementation. Bug fixes, improvements +to be compatible to Sun's implementation. +Bug fixes, improvements and .Tn NIS server support were later added by @@ -501,5 +530,6 @@ The server-side code was originally written by .An Peter Eriksson and .An Tobias Reber -and is subject to the GNU Public License. No Sun code was +and is subject to the GNU Public License. +No Sun code was referenced. diff --git a/share/man/man9/DEVICE_PROBE.9 b/share/man/man9/DEVICE_PROBE.9 index 8de3c499f946..f643d397b594 100644 --- a/share/man/man9/DEVICE_PROBE.9 +++ b/share/man/man9/DEVICE_PROBE.9 @@ -44,8 +44,10 @@ .Pp This device method should probe to see if the device is present. It should return 0 if the device exists, ENXIO if it cannot be -found. If some other error happens during the probe (such as a memory -allocation failure), an appropriate error code should be returned. For +found. +If some other error happens during the probe (such as a memory +allocation failure), an appropriate error code should be returned. +For cases where more than one driver matches a device, a priority value can be returned. In this case, success codes are values less than or equal to zero with the highest value representing the best match. Failure @@ -54,15 +56,18 @@ codes should be used for the purpose. .Pp If a driver returns a success code which is less than zero, it must not assume that it will be the same driver which is attached to the -device. In particular, it must not assume that any values stored in +device. +In particular, it must not assume that any values stored in the softc structure will be available for its attach method and any resources allocated during probe must be released and re-allocated -if the attach method is called. If a success code of zero is +if the attach method is called. +If a success code of zero is returned, the driver can assume that it will be the one attached. .Pp Devices which implement busses should use this method to probe for the existence of devices attached to the bus and add them as -children. If this is combined with the use of +children. +If this is combined with the use of .Xr bus_generic_attach 9 the child devices will be automatically probed and attached. .Sh RETURN VALUES diff --git a/share/man/man9/MD5.9 b/share/man/man9/MD5.9 index 6535f52bd6e5..37a5dedb095b 100644 --- a/share/man/man9/MD5.9 +++ b/share/man/man9/MD5.9 @@ -55,7 +55,8 @@ module implements the RSA Data Security, Inc. MD5 Message-Digest Algorithm .It Pa MD5Init must be called just before .Fn MD5Transform -will be used to produce a digest. The +will be used to produce a digest. +The .Fa buf argument is the storage for the digest being produced on subsequent calls to the diff --git a/share/man/man9/microseq.9 b/share/man/man9/microseq.9 index 01fef87f374c..0a7f93e95fd9 100644 --- a/share/man/man9/microseq.9 +++ b/share/man/man9/microseq.9 @@ -57,7 +57,8 @@ microsequencer implementation and an example of how using it in .Ss Background The parallel port model chosen for ppbus is the PC parallel port model. Thus, any register described later has the same semantic than its counterpart -in a PC parallel port. For more info about ISA/ECP programming, get the +in a PC parallel port. +For more info about ISA/ECP programming, get the Microsoft standard referenced as "Extended Capabilities Port Protocol and ISA interface Standard". Registers described later are standard parallel port registers. @@ -66,8 +67,10 @@ Mask macros are defined in the standard ppbus include files for each valid bit of parallel port registers. .Ss Data register In compatible or nibble mode, writing to this register will drive data to the -parallel port data lines. In any other mode, drivers may be tri-stated by -setting the direction bit (PCD) in the control register. Reads to this register +parallel port data lines. +In any other mode, drivers may be tri-stated by +setting the direction bit (PCD) in the control register. +Reads to this register return the value on the data lines. .Ss Device status register This read-only register reflects the inputs on the parallel port interface. @@ -99,7 +102,8 @@ some functions. .Ss Description .Em Microinstructions are either parallel port accesses, program iterations, submicrosequence or -C calls. The parallel port must be considered as the logical model described in +C calls. +The parallel port must be considered as the logical model described in .Xr ppbus 4 . .Pp Available microinstructions are: @@ -217,7 +221,8 @@ is positive. Parameter: .Bl -enum -offset ident .It -integer offset in the current executed (sub)microsequence. Offset is added to +integer offset in the current executed (sub)microsequence. +Offset is added to the index of the next microinstruction to execute. .El .Pp @@ -231,7 +236,8 @@ Parameter: .It bits of the status register .It -integer offset in the current executed (sub)microsequence. Offset is added to +integer offset in the current executed (sub)microsequence. +Offset is added to the index of the next microinstruction to execute. .El .Pp @@ -245,13 +251,16 @@ Parameter: .It bits of the status register .It -integer offset in the current executed (sub)microsequence. Offset is added to +integer offset in the current executed (sub)microsequence. +Offset is added to the index of the next microinstruction to execute. .El .Pp Predefined macro: MS_BRCLEAR(mask,offset) .Ss MS_OP_RET - RETurn -is used to return from a microsequence. This instruction is mandatory. This +is used to return from a microsequence. +This instruction is mandatory. +This is the only way for the microsequencer to detect the end of the microsequence. The return code is returned in the integer pointed by the (int *) parameter of the ppb_MS_microseq(). @@ -264,7 +273,8 @@ integer return code .Pp Predefined macro: MS_RET(code) .Ss MS_OP_C_CALL - C function CALL -is used to call C functions from microsequence execution. This may be useful +is used to call C functions from microsequence execution. +This may be useful when a non-standard i/o is performed to retrieve a data character from the parallel port. .Pp @@ -294,7 +304,8 @@ Note that this pointer is automatically incremented during xxx_P() calls .Pp Predefined macro: MS_PTR(ptr) .Ss MS_OP_ADELAY - do an Asynchronous DELAY -is used to make a tsleep() during microsequence execution. The tsleep is +is used to make a tsleep() during microsequence execution. +The tsleep is executed at PPBPRI level. .Pp Parameter: @@ -310,27 +321,33 @@ is used to branch on status register state condition. Parameter: .Bl -enum -offset ident .It -mask of asserted bits. Bits that shall be asserted in the status register +mask of asserted bits. +Bits that shall be asserted in the status register are set in the mask .It -mask of cleared bits. Bits that shall be cleared in the status register +mask of cleared bits. +Bits that shall be cleared in the status register are set in the mask .It -integer offset in the current executed (sub)microsequence. Offset is added +integer offset in the current executed (sub)microsequence. +Offset is added to the index of the next microinstruction to execute. .El .Pp Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset) .Ss MS_OP_SUBRET - SUBmicrosequence RETurn -is used to return from the submicrosequence call. This action is mandatory -before a RET call. Some microinstructions (PUT, GET) may not be callable +is used to return from the submicrosequence call. +This action is mandatory +before a RET call. +Some microinstructions (PUT, GET) may not be callable within a submicrosequence. .Pp No parameter. .Pp Predefined macro: MS_SUBRET() .Ss MS_OP_CALL - submicrosequence CALL -is used to call a submicrosequence. A submicrosequence is a microsequence with +is used to call a submicrosequence. +A submicrosequence is a microsequence with a SUBRET call. Parameter: .Bl -enum -offset ident @@ -352,7 +369,8 @@ register .Pp Predefined macro: MS_RASSERT_P(iter,reg) .Ss MS_OP_RFETCH_P - Register FETCH to internal PTR -is used to fetch data from a register. Data is stored in the buffer currently +is used to fetch data from a register. +Data is stored in the buffer currently pointed by the internal PTR pointer. Parameter: .Bl -enum -offset ident @@ -366,9 +384,12 @@ mask applied to fetched data .Pp Predefined macro: MS_RFETCH_P(iter,reg,mask) .Ss MS_OP_TRIG - TRIG register -is used to trigger the parallel port. This microinstruction is intended to -provide a very efficient control of the parallel port. Triggering a register -is writing data, wait a while, write data, wait a while... This allows to +is used to trigger the parallel port. +This microinstruction is intended to +provide a very efficient control of the parallel port. +Triggering a register +is writing data, wait a while, write data, wait a while... +This allows to write magic sequences to the port. Parameter: .Bl -enum -offset ident @@ -379,8 +400,10 @@ register .It size of the array .It -array of unsigned chars. Each couple of u_chars define the data to write to -the register and the delay in us to wait. The delay is limited to 255 us to +array of unsigned chars. +Each couple of u_chars define the data to write to +the register and the delay in us to wait. +The delay is limited to 255 us to simplify and reduce the size of the array. .El .Pp @@ -402,9 +425,11 @@ struct ppb_microseq { .Ed .Ss Using microsequences To instantiate a microsequence, just declare an array of ppb_microseq -structures and initialize it as needed. You may either use predefined macros +structures and initialize it as needed. +You may either use predefined macros or code directly your microinstructions according to the ppb_microseq -definition. For example, +definition. +For example, .Bd -literal struct ppb_microseq select_microseq[] = { @@ -430,7 +455,8 @@ definition. For example, .Ed .Pp Here, some parameters are undefined and must be filled before executing -the microsequence. In order to initialize each microsequence, one +the microsequence. +In order to initialize each microsequence, one should use the ppb_MS_init_msq() function like this: .Bd -literal ppb_MS_init_msq(select_microseq, 2, @@ -443,7 +469,8 @@ and then execute the microsequence. The microsequencer is executed either at ppbus or adapter level (see .Xr ppbus 4 for info about ppbus system layers). Most of the microsequencer is executed -at ppc level to avoid ppbus to adapter function call overhead. But some +at ppc level to avoid ppbus to adapter function call overhead. +But some actions like deciding whereas the transfer is IEEE1284-1994 compliant are executed at ppbus layer. .Sh BUGS |