1213

Part VII:

Miscellaneous

		Part VII: Miscellaneous
	1214

intro

intro—Introduction to miscellany section.

DESCRIPTION

This chapter describes miscellaneous things such as nroff macro packages, tables, C header files, the file hierarchy, general concepts, and other things that don’t fit anywhere else.

AUTHORS

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page to page!

Linux, 23 April 1993

ascii

ascii—The ASCII character set encoded in octal, decimal, and hexadecimal

DESCRIPTION

The following table contains the 128 ASCII characters.

C program ‘\X’ escapes are noted.

Oct	Dec	Hex	Char	Oct	Dec	Hex	Char
000	0	00	NUL ‘\0’	100	64	40	@
001	1	01	SOH	101	65	41	A
002	2	02	STX	102	66	42	B
003	3	03	ETX	103	67	43	C
004	4	04	EOT	104	68	44	D
005	5	05	ENQ	105	69	45	E
006	6	06	ACK	106	70	46	F
007	7	07	BEL ‘\a’	107	71	47	G
010	8	08	BS ‘\b’	110	72	48	H
011	9	09	HT ‘\t’	111	73	49	I
012	10	0A	LF ‘\n’	112	74	4A	J
013	11	0B	VT ‘\v’	113	75	4B	K
014	12	0C	FF ‘\f ’	114	76	4C	L
015	13	0D	CR ‘\r’	115	77	4D	M
016	14	0E	SO	116	78	4E	N
017	15	0F	SI	117	79	4F	O
020	16	10	DLE	120	80	50	P
021	17	11	DC1	121	81	51	Q
022	18	12	DC2	122	82	52	R
023	19	13	DC3	123	83	53	S
024	20	14	DC4	124	84	54	T
025	21	15	NAK	125	85	55	U
026	22	16	SYN	126	86	56	V

							ascii
									1215
Oct	Dec	Hex	Char	Oct	Dec	Hex		Char
027	23	17	ETB	127	87	57		W
030	24	18	CAN	130	88	58		X
031	25	19	EM	131	89	59		Y
032	26	1A	SUB	132	90	5A		Z
033	27	1B	ESC	133	91	5B		[
034	28	1C	FS	134	92	5C		\’\\’
035	29	1D	GS	135	93	5D		]
036	30	1E	RS	136	94	5E		ˆ
037	31	1F	US	137	95	5F		_
040	32	20	SPACE	140	96	60		‘
041	33	21	!	141	97	61		a
042	34	22	“	142	98	62		b
043	35	23	#	143	99	63		c
044	36	24	$	144	100	64		d
045	37	25	%	145	101	65		e
046	38	26	&	146	102	66		f
047	39	27	‘	147	103	67		g
050	40	28	(	150	104	68		h
051	41	29	)	151	105	69		i
052	42	2A	*	152	106	6A		j
053	43	2B	+	153	107	6B		k
054	44	2C	,	154	108	6C		l
055	45	2D	–	155	109	6D		m
056	46	2E	.	156	110	6E		n
057	47	2F	/	157	111	6F		o
060	48	30	0	160	112	70		p
061	49	31	1	161	113	71		q
062	50	32	2	162	114	72		r
063	51	33	3	163	115	73		s
064	52	34	4	164	116	74		t
065	53	35	5	165	117	75		u
066	54	36	6	166	118	76		v
067	55	37	7	167	119	77		w
070	56	38	8	170	120	78		x
071	57	39	9	171	121	79		y
072	58	3A	:	172	122	7A		z
073	59	3B	;	173	123	7B		{
074	60	3C	<	174	124	7C		|
075	61	3D	=	175	125	7D		}
076	62	3E	>	176	126	7E		˜
077	63	3F	?	177	127	7F		DEL

		Part VII: Miscellaneous
	1216

HISTORY

An ascii manual page appeared in version 7 AT&T UNIX.

SEE ALSO

iso_8859_1(7)

Linux

bootparam

bootparam—Introduction to boot-time parameters of the Linux kernel.

DESCRIPTION

The Linux kernel accepts certain command-line options or boot-time parameters at the moment it is started. In general, this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid or override the values that the kernel would otherwise detect.

When the kernel is booted directly by the BIOS (say, from a floppy to which you copied a kernel using cp zImage /dev/fd0), you have no opportunity to specify any parameters. To take advantage of this possibility, you have to use software that is able to pass parameters, such as LILO or loadlin. For a few parameters, one can also modify the kernel image itself, using rdev; see rdev(8) for further details.

The LILO program (LInux LOader) written by Werner Almesberger is the most commonly used. It has the ability to boot various kernels and stores the configuration information in a plain text file. (See lilo(8) and lilo.conf(5).) LILO can boot DOS, OS/2, Linux, FreeBSD, and so on and is quite flexible.

The other commonly used Linux loader is loadlin, which is a DOS program that has the capability to launch a Linux kernel from the DOS prompt (with boot args) assuming that certain resources are available. This is good for people who want to launch Linux from DOS.

It is also very useful if you have certain hardware that relies on the supplied DOS driver to put the hardware into a known state. A common example is SoundBlaster-compatible sound cards that require the DOS driver to twiddle a few mystical registers to put the card into a SB-compatible mode. Booting DOS with the supplied driver and then loading Linux from the DOS prompt with loadlin avoids the reset of the card that happens if one reboots instead.

THE ARGUMENT LIST

Most of the boot args take the form of

name[=value_1][,value_2]...[,value_11]

name is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Multiple boot args are just a space-separated list of the preceding format. Note the limit of 11 is real because the present code handles only 11 comma-separated parameters per keyword. (However, you can reuse the same keyword with up to an additional 11 parameters in unusually complicated situations, assuming the setup function supports it.)

Most of the sorting occurs in linux/init/main.c. First, the kernel checks to see if the argument is any of the special arguments root=, ro, rw, or debug. The meaning of these special arguments is described later in the document.

Then, it walks a list of setup functions (contained in the bootsetups array) to see if the specified argument string (such as foo) is associated with a setup function (foo_setup()) for a particular device or part of the kernel. If you passed the kernel the line foo=3,4,5,6, then the kernel searches the bootsetups array to see if foo is registered. If it is, it calls the setup function associated with foo (foo_setup()) and hands it the arguments 3, 4, 5, and 6 as given on the kernel command line.

Anything of the form foo=bar variable to be set. A (useless?)

that is not accepted as a setup function as described is then interpreted as an environment example is to use TERM=vt100 as a boot argument.

bootparam 1217

Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto process one, which is usually the init program. The most common argument that is passed to the init process is the word single, which instructs init to boot the computer in single-user mode and not launch all the usual daemons. Check the manual page for the version of init installed on your system to see what arguments it accepts.

GENERAL NON-DEVICE-SPECIFIC BOOT ARGS

no387

Some i387 coprocessor chips have bugs that show up when used in 32-bit protected mode.

For example, some of the early ULSI-387 chips cause solid lockups while performing floating-point calculations. Using the ‘no387’ boot arg causes Linux to ignore the maths coprocessor even if you have one. Of course, you must then have your kernel compiled with math emulation support!

no-hlt

Some of the early i486DX-100 chips have a problem with the hlt instruction in that they can’t reliably return to operating mode after this instruction is used. Using the ‘no-hlt’ instruction tells Linux to just run an infinite loop when there is nothing else to do and to not halt the CPU. This allows people with these broken chips to use Linux.

root=...

This argument tells the kernel what device is to be used as the root filesystem while booting. The default of this setting is determined at compile time and usually is the value of the root device of the system that the kernel was built on. To override this value and select the second floppy drive as the root device, one uses ‘root=/dev/fd1’. (The root device can also be set using rdev(8).)

The root device can be specified symbolically or numerically. A symbolic specification has the form /dev/XXYN, where XX designates the device type (hd for ST-506-compatible hard disk with Y in a-h; sd for SCSI-compatible disk with Y in a-e; xd for XT-compatible disk with Y either a or b; fd for floppy disk with Y the floppy drive number—fd0 is the DOS A: drive and fd1 is B:), Y is the driver letter or number, and N is the number of the partition on this device (absent in the case of floppies).

Note that this has nothing to do with the designation of these devices on your filesystem. The /dev/ part is purely conventional.

The more awkward and less portable numeric specification of the previous possible root devices in major/minor format is also accepted. (For example, /dev/sda3 is major 8, minor 3, so you can use root=0x803 as an alternative.)

ro and rw

The ro option tells the kernel to mount the root filesystem as readonly so that filesystem consistency check programs (fsck) can do their work on a quiescent file system. No processes can write to files on the filesystem in question until it is remounted as read/write capable, such as by mount -w -n -o remount /. (See also mount(8).)

The rw option tells the kernel to mount the root filesystem read/write. This is the default.

The choice between read-only and read/write can also be set usingrdev(8).

debug

Kernel messages are handed off to the kernel log daemon klogd so that they can be logged to disk. Messages with a priority above console_loglevel are also printed on the console. (For these levels, see <linux/kernel.h>.) By default, this variable is set to log anything more important than debug messages. This boot argument causes the kernel to also print the messages of DEBUG priority. The console log level can also be set at runtime via an option to klogd. See klogd(8).

reserve=...

This is used to protect I/O port regions from probes. The form of the command is

reserve=iobase,extent[,iobase,extent]...

		Part VII: Miscellaneous
	1218

In some machines, it might be necessary to prevent device drivers from checking for devices (auto-probing) in a specific region. This may be because of hardware that reacts badly to the probing, hardware that would be mistakenly identified, or hardware you don’t want the kernel to initialize.

The reserve boot-time argument specifies an I/O port region that shouldn’t be probed. A device driver does not probe a reserved region unless another boot argument explicitly specifies that it do so.

For example, the boot line

reserve=0x300,32 blah=0x300

keeps all device drivers except the driver for blah from probing 0x300-0x31f.

ramdisk=...

This option is obsolete since Linux 1.3.48 or so. It specifies the size in kilobytes of the optional RAM disk device. For example, if one wants to have a root filesystem on a 1.44MB floppy loaded into the RAM disk device, they use

ramdisk=1440

This option is set at compile time (default is no RAM disk), and can be modified using rdev(8).

mem=...

The BIOS call defined in the PC specification that returns the amount of installed memory was only designed to be able to report up to 64MB. Linux uses this BIOS call at boot to determine how much memory is installed. If you have more than 64MB of RAM installed, you can use this boot arg to tell Linux how much memory you have. The value is in decimal or hexadecimal (prefix 0x), and the suffixes K (times 1024) or M (times 1048576) can be used. The following quote from Linus describes the use of the mem= parameter:

“The kernel will accept any mem=xx parameter you give it, and if it turns out that you lied to it, it will crash horribly sooner or later. The parameter indicates the highest addressable RAM address, so ‘mem=0x1000000’ means you have 16MB of memory, for example. For a 96MB machine this would be mem=0x6000000.

NOTE: Some machines might use the top of memory for BIOS caching or whatever, so you might not actually have up to the full 96MB addressable. The reverse is also true: Some chipsets will map the physical memory that is covered by the BIOS area into the area just past the top of memory, so the top-of-mem might actually be 96MB + 384KB, for example. If you tell Linux that it has more memory than it actually does have, bad things will happen: maybe not at once, but surely eventually.”

reboot=warm

Since 2.0.22, a reboot is by default a cold reboot. This command-line option changes back to the old default, a warm reboot.

BOOT ARGUMENTS FOR SCSI DEVICES

General notation for this section:

iobase—the first I/O port that the SCSI host occupies. These are specified in hexadecimal notation and usually lie in the range from 0x200 to 0x3ff.

irq—the hardware interrupt that the card is configured to use. Valid values are dependent on the card in question but are usually 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripherals such as IDE hard disks, floppies, serial ports, and so on.

scsi-id—the ID that the host adapter uses to identify itself on the SCSI bus. Only some host adapters allow you to change this value because most have it permanently specified internally. The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6.

parity—whether the SCSI host adapter expects the attached devices to supply a parity value with all information exchanges. Specifying a 1 indicates parity checking is enabled, and a 0 disables parity checking. Again, not all adapters support selection of parity behavior as a boot argument.

bootparam 1219

max_scsi_luns=...

A SCSI device can have a number of subdevices contained within itself. The most common example is one of the new SCSI CD-ROMs that handle more than one disk at a time. Each CD is addressed as a Logical Unit Number (LUN) of that particular device. Most devices, such as hard disks and tape drives, are only one device and are assigned to LUN 0.

Some poorly designed SCSI devices cannot handle being probed for LUNs not equal to 0. Therefore, if the compile-time flag CONFIG SCSI MULTI LUN is not set, newer kernels by default only probe LUN 0.

To specify the number of probed LUNs at boot, one enters max scsi luns=n as a boot arg, where n is a number between 1 and 8. To avoid problems as described, one uses n=1 to avoid upsetting such broken devices.

SCSI TAPE CONFIGURATION

Some boot-time configuration of the SCSI tape driver can be achieved with the following:

st=buf_size[,write_threshold[,max_bufs]]

The first two numbers are specified in units of kilobytes. The default buf_size is 32KB, and the maximum size that can be specified is a ridiculous 16384KB. The write_threshold is the value at which the buffer is committed to tape with a default value of 30KB. The maximum number of buffers varies with the number of drives detected and has a default of two. A sample usage is

st=32,30,2

Full details can be found in the README.st file that is in the scsi directory of the kernel source tree.

ADAPTEC AHA151X, AHA152X, AIC6260, AIC6360, SB16-SCSI CONFIGURATION

The aha numbers refer to cards and the aic numbers refer to the actual SCSI chip on these types of cards, including the SoundBlaster-16 SCSI.

The probe code for these SCSI hosts looks for an installed BIOS, and if none is present, the probe will not find your card. Then you must use a boot arg of the form:

aha152x=iobase[,irq[,scsi-id[,reconnect[,parity]]]]

If the driver was compiled with debugging enabled, a sixth value can be specified to set the debug level.

All the parameters are as described at the top of this section, and the reconnect value allows device disconnect/reconnect if a nonzero value is used. A sample usage is as follows:

aha152x=0x340,11,7,1

Note that the parameters must be specified in order, meaning that if you want to specify a parity setting, then you must specify an iobase, irq, scsi-id, and reconnect value as well.

ADAPTEC AHA154X CONFIGURATION

The aha1542 series cards have an i82077 floppy controller on board, whereas the aha1540 series cards do not. These are busmastering cards and have parameters to set the “fairness” that is used to share the bus with other devices. The boot arg looks like the following:

aha1542=iobase[,buson,busoff[,dmaspeed]]

Valid iobase values are usually one of 0x130, 0x134, 0x230, 0x234, 0x330, or 0x334. Clone cards may permit other values.

The buson and busoff values refer to the number of microseconds that the card dominates the ISA bus. The defaults are 11us on and 4us off so that other cards (such as an ISA LANCE Ethernet card) have a chance to get access to the ISA bus.

The dmaspeed value refers to the rate (in MB/s) at which the DMA (Direct Memory Access) transfers proceed. The default is 5MB/s. Newer revision cards allow you to select this value as part of the soft-configuration; older cards use jumpers. You can use values up to 10MB/s, assuming that your motherboard is capable of handling it. Experiment with caution if using values over 5MB/s.

		Part VII: Miscellaneous
	1220

ADAPTEC AHA274X, AHA284X, AIC7XXX CONFIGURATION

These boards can accept an argument of the form:

aic7xxx=extended,no_reset

The extended value, if nonzero, indicates that extended translation for large disks is enabled. The no_reset value, if nonzero, tells the driver not to reset the SCSI bus when setting up the host adapter at boot.

BUSLOGIC SCSI HOSTS CONFIGURATION (buslogic=)

At present, the buslogic driver accepts only one parameter, the I/O base. It expects that to be one of the following valid values: 0x130, 0x134, 0x230, 0x234, 0x330, or 0x334.

FUTURE DOMAIN TMC-8XX, TMC-950 CONFIGURATION

If your card is not detected at boot time, you must use a boot arg of the form

tmc8xx=mem_base,irq

The mem_base value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, or 0xde000.

PRO AUDIO SPECTRUM CONFIGURATION

The PAS16 uses an NC5380 SCSI chip, and newer models support jumperless configuration. The boot arg is of the form

pas16=iobase,irq

The only difference is that you can specify an IRQ value of 255, which tells the driver to work without using interrupts, albeit at a performance loss. The iobase is usually 0x388.

SEAGATE ST-0X CONFIGURATION

If your card is not detected at boot time, you must use a boot arg of the form

st0x=mem_base,irq

The mem_base value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, or 0xde000.

TRANTOR T128 CONFIGURATION

These cards are also based on the NCR5380 chip and accept the following options:

t128=mem_base,irq

The valid values for mem_base are as follows: 0xcc000, 0xc8000, 0xdc000, and 0xd8000.

CARDS THAT DON’T ACCEPT BOOT ARGS

At present, the following SCSI cards do not make use of any boot-time parameters. In some cases, you can hard-wire values by directly editing the driver itself, if required.

Always IN2000, Adaptec aha1740, EATA-DMA, EATA-PIO, Future Domain 16xx, NCR5380 (generic), NCR53c7xx to NCR53c8xx, Qlogic, Ultrastor (including u?4f), and Western Digital wd7000.

HARD DISKS

IDE DISK/CD-ROM DRIVER PARAMETERS

The IDE driver accepts a number of parameters, which range from disk geometry specifications to support for broken controller chips. Drive specific options are specified by using hdX= with X in a-h.

Non-drive–specific options are specified with the prefix hd=. Note that using a drive-specific prefix for a non-drive–specific option will still work, and the option will just be applied as expected.

bootparam 1221

Also note that hd= can be used to refer to the next unspecified drive in the (a, …, h) sequence. For the following discussions, the hd= option will be cited for brevity. See the file README.ide in linux/drivers/block for more details.

THE hd=cyls,heads,sects[,wpcom[,irq]] OPTIONS

These options are used to specify the physical geometry of the disk. Only the first three values are required. The cylinder, head, and sectors values are those used by fdisk. The write precompensation value is ignored for IDE disks. The IRQ value specified is the IRQ used for the interface that the drive resides on and is not really a drive-specific parameter.

THE hd=serialize OPTION

The dual IDE interface CMD-640 chip is broken as designed such that when drives on the secondary interface are used at the same time as drives on the primary interface, it will corrupt your data. Using this option tells the driver to make sure that both interfaces are never used at the same time.

THE hd=dtc2278 OPTION

This option tells the driver that you have a DTC-2278D IDE interface. The driver then tries to do DTC-specific operations to enable the second interface and to enable faster transfer modes.

THE hd=noprobe OPTION

Do not probe for this drive. The following line

hdb=noprobe hdb=1166,7,17

disables the probe but still specifies the drive geometry so that it is registered as a valid block device and hence usable.

THE hd=nowerr OPTION

Some drives apparently have the WRERR STAT bit stuck on permanently. This enables a work-around for these broken devices.

THE hd=cdrom OPTION

This tells the IDE driver that there is an ATAPI compatible CD-ROM attached in place of a normal IDE hard disk. In most cases, the CD-ROM is identified automatically, but if it isn’t, then this might help.

STANDARD ST-506 DISK DRIVER OPTIONS (hd=)

The standard disk driver can accept geometry arguments for the disks similar to the IDE driver. Note however that it only expects three values (C/H/S); any more or any less and it will silently ignore you. Also, it only accepts hd= as an argument; hda= and so on are not valid here. The format is as follows:

hd=cyls,heads,sects

If there are two disks installed, the preceding line is repeated with the geometry parameters of the second disk.

XT DISK DRIVER OPTIONS (xd=)

If you are unfortunate enough to be using one of these old 8-bit cards that move data at a whopping 125KB/s, then here is the scoop. If the card is not recognized, you must use a boot arg of the form

xd=type,irq,iobase,dma_chan

The type value specifies the particular manufacturer of the card, and you use one of the following: 0=generic, 1=DTC, 2, 3, 4=Western Digital, 5, 6, 7=Seagate, or 8=OMTI. The only difference between multiple types from the same manufacturer is the BIOS string used for detection, which is not used if the type is specified.

The xd_setup() function does no checking on the values and assumes that you entered all four values. Don’t disappoint it. Here is a sample usage for a WD1002 controller with the BIOS disabled or removed, using the default XT controller parameters:

xd=2,5,0x320,3

		Part VII: Miscellaneous
	1222

CD-ROMS (NON-SCSI/ATAPI/IDE)

THE AZTECH INTERFACE

The syntax for this type of card is

aztcd=iobase[,magic_number]

If you set the magic_number to 0x79, the driver will run anyway in the event of an unknown firmware version. All other values are ignored.

THE CDU-31A AND CDU-33A SONY INTERFACE

This CD-ROM interface is found on some of the Pro Audio Spectrum sound cards and other Sony supplied interface cards. The syntax is as follows:

cdu31a=iobase,[irq[,is_pas_card]]

Specifying an IRQ value of 0 tells the driver that hardware interrupts aren’t supported (as on some PAS cards). If your card supports interrupts, you should use them because they cut down on the CPU usage of the driver.

The is_pas_card should be entered as PAS if using a Pro Audio Spectrum card; otherwise, it should not be specified at all.

THE CDU-535 SONY INTERFACE

The syntax for this CD-ROM interface is

sonycd535=iobase[,irq]

A 0 can be used for the I/O base as a placeholder if you want to specify an IRQ value.

THE GOLDSTAR INTERFACE

The syntax for this CD-ROM interface is

gscd=iobase

THE MITSUMI STANDARD INTERFACE

The syntax for this CD-ROM interface is

mcd=iobase,[irq[,wait_value]]

The wait_value is used as an internal time-out value for people who are having problems with their drive and may or may not be implemented depending on a compile-time #define. The Mitsumi FX400 is an IDE/ATAPI CD-ROM player and does not use the mcd driver.

THE MITSUMI XA/MULTISESSION INTERFACE (mcdx=)

At present, this experimental driver has a setup function, but no parameters are implemented (as of 1.3.15). This is for the same hardware as previously described, but the driver has extended features.

THE OPTICS STORAGE INTERFACE

The syntax for this type of card is

optcd=iobase

THE PHILLIPS CM206 INTERFACE

The syntax for this type of card is

cm206=[iobase][,irq]

The driver assumes numbers between 3 and 11 are IRQ values and numbers between 0x300 and 0x370 are I/O ports, so you can specify one, or both numbers, in any order. It also accepts cm206=auto to enable autoprobing.

param_n

bootparam 1223

THE SANYO INTERFACE

The syntax for this type of card is

sjcd=iobase[,irq[,dma_channel]]

THE SOUNDBLASTER PRO INTERFACE

The syntax for this type of card is

sbpcd=iobase,type

type is one of the following (case-sensitive) strings: SoundBlaster, LaserMate, or SPEA. The I/O base is that of the CD-ROM interface and not that of the sound portion of the card.

ETHERNET DEVICES

Different drivers use different parameters, but they all at least share having an IRQ, an I/O port base value, and a name. In its most generic form, it looks something like this:

ether=irq,iobase[,param_1[,param_2,...param_8]],name

The first non-numeric argument is taken as the name. The param_n values (if applicable) usually have different meanings for each different card or driver. Typical param_n values are used to specify things such as shared memory address, interface selection, DMA channel, and the like.

The most common use of this parameter is to force probing for a second ethercard because the default is to only probe for one. This can be accomplished with a simple

ether=0,0,eth1

Note that the values of 0 for the IRQ and I/O base in the example tell the drivers to autoprobe.

The Ethernet How To has extensive documentation on using multiple cards and on the card-specific or driver-specific implementation of the values where used. Interested readers should refer to the section in that document on their particular card.

THE FLOPPY DISK DRIVER

There are many floppy driver options, and they are all listed in README.fd in linux/drivers/block. This information is taken directly from that file.

floppy=mask,allowed_drive_mask

Sets the bitmask of allowed drives to mask. By default, only units 0 and 1 of each floppy controller are allowed. This is done because certain non-standard hardware (ASUS PCI motherboards) mess up the keyboard when accessing units 2 or 3. This option is somewhat obsolete because of the cmos option.

floppy=all drives

Sets the bitmask of allowed drives to all drives. Use this if you have more than two drives connected to a floppy controller.

floppy=asus_pci

Sets the bitmask to allow only units 0 and 1 (the default).

floppy=daring

Tells the floppy driver that you have a well-behaved floppy controller. This allows more efficient and smoother operation but may fail on certain controllers. This can speed up certain operations.

floppy=0,daring

Tells the floppy driver that your floppy controller should be used with caution.

		Part VII: Miscellaneous
	1224

floppy=one_fdc

Tells the floppy driver that you have only one floppy controller (default).

floppy=two_fdc OR floppy=address,two_fdc

Tells the floppy driver that you have two floppy controllers. The second floppy controller is assumed to be at address. If address is not given, 0x370 is assumed.

floppy=thinkpad

Tells the floppy driver that you have a Thinkpad. Thinkpads use an inverted convention for the disk change line.

floppy=0,thinkpad

Tells the floppy driver that you don’t have a Thinkpad.

floppy=drive,type,cmos

Sets the cmos type of drive to type. Additionally, this drive is allowed in the bitmask. This is useful if you have more than two floppy drives (only two can be described in the physical cmos), or if your BIOS uses non-standard cmos types. Setting the cmos to 0 for the first two drives (default) makes the floppy driver read the physical cmos for those drives.

floppy=unexpected_interrupts

Print a warning message when an unexpected interrupt is received (default behavior)

floppy=no unexpected_interrupts OR floppy=L40SX

Don’t print a message when an unexpected interrupt is received. This is needed on IBM L40SX laptops in certain video modes. (There seems to be an interaction between video and floppy. The unexpected interrupts only affect performance and can safely be ignored.)

THE SOUND DRIVER

The sound driver can also accept boot args to override the compiled in values. This is not recommended because it is rather complex. It is described in the Readme.Linux file in linux/drivers/sound. It accepts a boot arg of the form

sound=device1[,device2[,device3...[,device11]]]

Each deviceN value is of the format 0xTaaaId and the bytes are used as follows:

T—device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, and 7=SB16-MPU401

aaa—I/O address in hex

I—interrupt line in hex (10=a, 11=b, …)

d—DMA channel

As you can see, it gets pretty messy, and you are better off to compile in your own personal values as recommended. Using a boot arg of sound=0 disables the sound driver entirely.

THE BUS MOUSE DRIVER (bmouse=)

The busmouse driver only accepts one parameter, the hardware IRQ value to be used.

AUTHORS

Linus Torvalds (and many others)

SEE ALSO

klogd(8), lilo.conf(5), lilo(8), mount(8), rdev(8)

This man page was derived from the Boot Parameter HOWTO (version 1.0.1) written by Paul Gortmaker. More information can be found in this (or a more recent) HOWTO.

Linux 1.3.19, 15 August 1995

groff_me 1225

groff_me

groff_me—troff macros for formatting papers.

SYNOPSIS

groff_me [ options ] file ...

troff_me [ options ] file ...

DESCRIPTION

This manual page describes the GNU version of the _me macros, which is part of the groff document formatting system. This version can be used with both GNU troff and UNIX troff. This package of troff macro definitions provides a canned formatting facility for technical papers in various formats.

The macro requests are defined as follows. Many troff requests are unsafe in conjunction with this package; however, these requests can be used with impunity after the first .pp:

.bp	Begin new page
.br	Break output line here
.sp n	Insert n spacing lines
.ls n	Line spacing; n=1 single, n=2 double space
.na	No alignment of right margin
.ce n	Center next n lines
.ul n	Underline next n lines

Output of the pic, eqn, refer, and tbl preprocessors is acceptable as input.

FILES

/usr/lib/groff/tmac/tmac.e

SEE ALSO

groff(1), gtroff(1), _me Reference Manual, Eric P. Allman, Writing Papers with Groff Using _me

REQUESTS

This list is incomplete; see the _me Reference Manual for interesting details.

Request	Initial Value	Cause Break	Explanation
.(c	-	Yes	Begin centered block.
.(d	-	No	Begin delayed text.
.(f	-	No	Begin footnote.
.(l	-	Yes	Begin list.
.(q	-	Yes	Begin major quote.
.(x x	-	No	Begin indexed item in index x.
.(z	-	No	Begin floating keep.
.)c	-	Yes	End centered block.
.)d	-	Yes	End delayed text.
.)f	-	Yes	End footnote.
.)l	-	Yes	End list.
.)q	-	Yes	End major quote.

continues

		Part VII: Miscellaneous
	1226

Request	Initial Value	Cause Break	Explanation
.)x	-	Yes	End index item.
.)z	-	Yes	End floating keep.
.++ m H	-	No	Define paper section.
			m defines the part of the paper and can be C
			(chapter), A (appendix), P (preliminary, such as
			abstract, table of contents, and so on), B (bibliogra-
			phy), RC (chapters renumbered from page one each
			chapter), or RA (appendix renumbered from page
			one).
.+c T	-	Yes	Begin chapter (or appendix and so on as set by .++).
			T is the chapter title.
.1c	1	Yes	One column format on a new page.
.2c	1	Yes	Two column format. Equation number is y.
.EN	-	Yes	Space after equation produced by eqn or neqn.
.EQ x y	-	Yes	Precede equation; break out and add space.
			The optional argument x may be I to indent
			equation (default), L to left-adjust the equation, or C
			to center the equation.
.GE	-	Yes	End gremlin picture.
.GS	-	Yes	Begin gremlin picture.
.PE	-	Yes	End pic picture.
.PS	-	Yes	Begin pic picture.
.TE	-	Yes	End table.
.TH	-	Yes	End heading section of table.
.TS x	-	Yes	Begin table; if x is H, table has repeated heading.
.b x	No	No	Print x in boldface; if no argument switch to
			boldface.
.ba +n	0	Yes	Augments the base indent by n.
			This indent is used to set the indent on regular text
			(like paragraphs).
.bc	No	Yes	Begin new column.
.bi x	No	No	Print x in bold italics (no fill only).
.bu	-	Yes	Begin bulleted paragraph.
.bx x	No	No	Print x in a box (no fill only).
.ef ‘x’y’z’	“”	No	Set even footer to x y z.
.eh ‘x’y’z’	“”	No	Set even header to x y z.
.fo ‘x’y’z’	“”	No	Set footer to x y z.
.hx	-	No	Suppress headers and footers on next page.
.he ‘x’y’z’	“”	No	Set header to x y z.
.hl	-	Yes	Draw a horizontal line.
.i x	No	No	Italicize x; if x is missing, italic text follows.
.ip x y	No	Yes	Start indented paragraph with hanging tag x.
			Indentation is y ens (default is 5).

			groff_mm
					1227
Request	Initial Value	Cause Break	Explanation
.lp	Yes	Yes	Start left-blocked paragraph.
.np	1	Yes	Start numbered paragraph.
.of ‘x’y’z’	“”	No	Set odd footer to x y z.
.oh ‘x’y’z’	“”	No	Set odd header to x y z.
.pd	-	Yes	Print delayed text.
.pp	No	Yes	Begin paragraph. First line indented.
.r	Yes	No	Roman text follows.
.re	-	No	Reset tabs to default values.
.sh n x	-	Yes	Section head follows; font is automatically bold. n is
			level of section. x is title of section.
.sk	No	No	Leave the next page blank. Only one page is
			remembered ahead.
.sm x	-	No	Set x in a smaller point size.
.sz +n	10p	No	Augment the point size by n points.
.tp	No	Yes	Begin title page.
.u x	-	No	Underline argument (even in troff) (nofill only).
.uh	-	Yes	Like .sh but unnumbered.
.xp x	-	No	Print index x.

Groff Version 1.09, 6 August 1992

groff_mm

groff_mm—groff mm macros.

SYNOPSIS

groff_mgm [ options... ] [files... ]

DESCRIPTION

The groff mm macros are intended to be compatible with the DWB mm macros with the following limitations:

No letter macros are implemented (yet).

No Bell Labs localisms are implemented.

The macros OK and PM are not implemented.

groff mm does not support cut marks.

mgm is intended to be international. Therefore, it is possible to write short national macro-files that change all English text to the preferred language. Use mgmse as an example.

groff mm has several extensions:
1C [1]	Begin one column processing. A 1 as argument disables the page break.
APP name text	Begin an appendix with the name name. Automatic naming occurs if name is “”. The
	appendixes starts with A if auto is used. A new page is ejected, and a header is also
	produced if the number variable Aph is non-zero. This is the default. The appendix
	always appear in the list of contents with the correct page number. The name
	APPENDIX can be changed by setting the string App to the desired text.

		Part VII: Miscellaneous
	1228

APPSK name pages text	Same as .APP, but the page number is incremented with pages. This is used
	when diagrams or other non-formatted documents are included as appen-
	dixes.
B1	Begin box (as the ms macro) Draws a box around the text.
B2	End box. Finish the box.
BVL	Start of broken variable-item list. Like VL but text begins always at the next
	line.
COVER [arg]	COVER begins a coversheet definition. It is important that .COVER appears
	before any normal text. .COVER uses arg to build the filename /usr/lib/groff/
	tmac/mm/arg.cov. Therefore, it is possible to create unlimited types of
	coversheets. ms.cov is supposed to look like the ms coversheet. .COVER requires
	a .COVEND at the end of the cover definition. Always use this order of the cover
	macros:
	.COVER
	.TL
	.AF
	.AU
	.AT
	.AS
	.AE
	.COVEND
	However, only .TL and .AU are required.
COVEND	This finishes the cover description and prints the cover page. It is defined in
	the cover file.
GETHN refname [varname]	Includes the header number where the corresponding SETR refname was
	placed. Will be X.X.X. in pass 1. See INITR. If varname is used, GETHN sets the
	string variable varname to the header number.
GETPN refname [varname]	Includes the page number where the corresponding SETR refname was placed.
	Will be 9999 in pass 1. See INITR. If varname is used, GETPN sets the string
	variable varname to the page number.
GETR refname	Combines GETHN and GETPN with the text ‘chapter’ and ‘, page’. The string
	Qrf contains the text for reference: .ds Qrf See chapter \\*[Qrfh], page
	\\*[Qrfp]. Qrf may be changed to support other languages. Strings Qrfh and
	Qrfp are set by GETR and contain the page and header number.
GETST refname [varname]	Includes the string saved with the second argument to .SETR. Will be dummy
	string in pass 1. If varname is used, GETST sets the string variable varname to the
	saved string. See INITR.
INITR filename	Initialize the reference macros. References will be written to filename. tmp
	and filename.qrf. Requires two passes with groff. The first looks for
	references and the second includes them. INITR can be used several times, but
	it is only the first occurrence of INITR that is active. See also SETR, GETPN, and
	GETHN.
MC column-size [column-separation]	Begin multiple columns. Return to normal with 1C.
MT [arg [addressee]]	Memorandum type. The arg is part of a filename in /usr/lib/groff/tmac/mm/
	*.MT. Memorandum type 0 through 5 are supported, including string.
	addressee just sets a variable, used in the AT&T macros.
MOVE y-pos [x-pos[line-length]]	Move to a position, page offset set to x-pos. If line-length is not given, the
	difference between the current and new page offset is used. Use PGFORM
	without arguments to return to normal.

MULB cw1 space1[cw2 space2 [cw3 ...]]

MULN

MULE

PGFORM [linelength[pagelength[pageoffset [1]]]] linelength, pagelength and/or pageoffset.

PGNH

SETR refname [string]

TAB

VERBON [flag [pointsize[font]]]

VERBOFF

New variables in mgm:

App

Aph

groff_mm 1229

Begin a special multi-column mode. Every column’s width must be specified. Also, the space between the columns must be specified. The last column does not need any space definition. MULB starts a diversion and MULE ends the diversion and prints the columns. The unit for width and space is n, but MULB accepts all normal unit specifications such as c and i. MULB operates in a separate environment.

Begin the next column. This is the only way to switch columns. End the multi-column mode and print the columns.

This macro can be used for special formatting, such as PGFORM letterheads. Sets can be used without arguments to reset everything after a MOVE. A line break is done unless the fourth argument is given. This can be used to avoid the page number on the first page while setting new width and length.

No header is printed on the next page. Used to get rid of the header in letters or other special texts. This macro must be used before any text to inhibit the page header on the first page.

Remember the current header and page number as refname. Saves string if string is defined. string is retrieved with .GETST. See

INITR.

Reset tabs to every 5n. Usually used to reset any previous tab positions.

Begin verbatim output using Courier font. Usually for printing programs. All characters have equal width. The point size can be changed with the second argument. By specifying the font argument, it is possible to use another font instead of Courier. flag controls several special features. It contains the sum of all wanted features:

Value Description

1Disable the escape-character (n). This is usually turned on during verbose output.

2Add an empty line before the verbose text.

4	Add an empty line after the verbose text.

8Print the verbose text with numbered lines. This adds four digit-sized spaces in the beginning of each line. Finer control is available with the string-variable Verbnm. It contains all arguments to the troff-command .nm, usually 1.

16Indent the verbose text with five ns. This is controlled by the number-variable Verbin (in units).

End verbatim output.

A string containing the word APPENDIX.

Print an appendix page for every new appendix if this number variable is nonzero. No output will occur if Aph is zero, but there

		Part VII: Miscellaneous
	1230

	will always be an appendix entry in the list of contents.
Hps	Number variable with the heading pre-space level. If the heading
	level is less than or equal to Hps, then two lines precede the section
	heading instead of one. Default is first level only. The real amount
	of lines is controlled by the variables Hps1 and Hps2.
Hps1	This is the number of lines preceding .H when the heading level is
	greater than Hps. Value is in units, usually 0.5v.
Hps2	This is the number of lines preceding .H when the heading level is
	less than or equal to Hps. Value is in units, usually 1v.
Lifg	String containing figure.
Litb	String containing table.
Liex	String containing exhibit.
Liec	String containing equation.
Licon	String containing contents.
Lsp	The size of an empty line. Usually 0.5v, but it is 1v if n is set
	(.nroff).
MO1 - MO12	Strings containing January to December.
Qrf	String containing “See chapter \\*[Qrfh], page \\n[Qrfp].”.
Pgps	Controls whether header and footer point size should follow the
	current setting or just change when the header and footer is
	defined.
	Value	Description
	0	Point size will only change to the current setting
		when .PH, .PF, .OH, .EH, .OF, or .OE is executed.
	1	Point size will change after every .S. This is the
		default.
Sectf	Flag controlling section figures. A nonzero value enables this. See
	also register N.
Sectp	Flag controlling section page numbers. A nonzero value enables
	this. See also register N.
.mgm	Always 1.

A file called locale or lang_locale is read after the initiation of the global variables. It is therefore possible to localize the macros with a company name and so on.

The following standard macros are implemented:
2C	Begin two column processing.
AE	Abstract end.
AF [name of firm]	Author’s firm.
AL [type[text-indent [1]]]]	Start autoincrement list.
AS [arg [indent]]	Abstract start. Indent is specified in ens, but scaling is allowed.
AST [title]	Abstract title. Default is ‘ABSTRACT’.
AT title1 [title2 ...]	Author’s title.
AU name [initials [loc [dept
	[ext [room [arg [arg
	[arg]]]]]]]] Author information.
B [bold-text[prev-font-text [...]]]	Begin boldface. No limit on the number of arguments.

		groff_mm
				1231
BE	End bottom block.
BI[bold-text [italic-text [bold-text [...]]]	Bold italic. No limit on the number of arguments.
BL [text-indent [1]]	Start bullet list.
BR [bold-text [roman-text[bold-text [...]]]	Bold roman. No limit on the number of arguments.
BS	Bottom block start.
DE	Display end.
DF[format [fill [rindent]]]	Begin floating display (no nesting allowed).
DL [text-indent [1]]	Dash list start.
DS [format[fill [rindent]]]	Static display start. Can now have unlimited nesting. Also, right-
	adjusted text and block may be used (R or RB as format).
EC [title [override[flag [refname]]]]	Equation title. If refname is used, then the equation number is
	saved with .SETR and can be retrieved with .GETST refname.
EF [arg]	Even page footer.
EH [arg]	Even page header.
EN	Equation end.
EQ [label]	Equation start.
EX [title [override[flag [refname]]]]	Exhibit title. If refname is used, then the exhibit number is saved
	with .SETR and can be retrieved with .GETST refname.
FD [arg [1]]	Footnote default format.
FE	Footnote end.
FG [title [override[flag [refname]]]]	Figure title. If refname is used, then the figure number is saved
	with .SETR and can be retrieved with .GETST refname.
FS	Footnote start. Footnotes in displays is now possible.
H level [heading-text[heading-suffix]]	Numbered heading.
HC [hyphenation-character]	Set hyphenation character.
HM [arg1 [arg2[... [arg7]]]]	Heading mark style.
HU heading-text	Unnumbered header.
HX dlevel rlevel heading-text	User-defined heading exit. Called just before printing the header.
HY dlevel rlevel heading-text	User-defined heading exit. Called just before printing the header.
HZ dlevel rlevel heading-text	User-defined heading exit. Called just after printing the header.
I [italic-text.
	[prev-font-text
	[italic-text [...]]]	Italic.
IB [italic-text
	[bold-text
	[italic-text [...]]]	Italic bold.
IR [italic-text
	[roman-text
	[italic-text [...]]]	Italic roman.
LB text-indentmark-indent
	pad type[mark
	[LI-space [LB-space]]]	List begin macro.
LC [list level]	List status clear.
LE	List end.
LI [mark [1]]	List item.
ML mark [text-indent]	Marked list start.
MT [arg [addressee]]	Memorandum type. See above note about MT.

		Part VII: Miscellaneous
	1232

ND new-date	New date.
OF [arg]	Odd page footer.
OH [arg]	Odd page header.
OP	Skip to odd page.
P [type]	Begin new paragraph.
PE	Picture end.
PF [arg]	Page footer.
PH [arg]	Page header.
PS	Picture start (from pic).
PX	Page header user-defined exit.
R	Roman.
RB [roman-text [bold-text
	[roman-text [...]]]	Roman-bold.
RD [prompt[diversion [string]]]	Read to diversion and/or string.
RF	Reference end.
RI [roman-text
	[italic-text
	[roman-text [...]]]	Roman italic.
RL [text-indent [1]]	Reference list start.
RP [arg [arg]]	Produce reference page.
RS [string-name]	Reference start.
S [size [spacing]]	Set point size and vertical spacing. If any argument equals P, then the
	previous value is used. A C means current value, and D means default
	value. If + or – is used before the value, an increment or decrement of
	the current value is done.
SA [arg]	Set adjustment.
SK [pages]	Skip pages.
SM string1[string2 [string3]]	Make a string smaller.
SP [lines]	Space vertically. lines can have any scaling factor, such as 3i or 8v.
TB [title [override[flag [refname]]]]	Table title. If refname is used, then the table number is saved with
	.SETR and can be retrieved with .GETST refname.
TC [slevel [spacing
	[tlevel [tab [h1 [h2
	[h3 [h4 [h5]]]]]]]]]
	Table of contents. All texts can be redefined. new string variables
	Lifg, Litb, Liex, Liec, and Licon contain “Figure”, “TABLE”, “Exhibit”,
	“Equation”, and “CONTENTS”. These can be redefined to other
	languages.
TE	Table end.
TH [N]	Table header.
TL	Begin title of memorandum.
TM [num1 [num2 [...]]]	Technical memorandum numbers used in .MT. Unlimited number of
	arguments may be given.
TP	Top of page user-defined macro. Note that header and footer is
	printed in a separate environment. Line length is preserved.
TS [H]	Table start.
TX	User-defined table of contents exit.
TY	User-defined table of contents exit (no “CONTENTS”).

VL [text-indent [mark-indent [1]]]

VM [top [bottom]]

WC [format]

Strings used in mgm:

EM

HF

HP

Lf

Lt

Lx

Le

Rp

Tm

Number variables used in mgm:

Cl=2

Cp=0

D=0

De=0

Df=5

Ds=1

Ej=0

Eq=0

Fs=1

H1 - H7

Hb=2

Hc=0

Hi=1

Hs=2

Ht=0

Hu=2

Hy=1

Lf=1, Lt=1, Lx=1, Le=0

Li=6

Ls=99

N=0

groff_mm 1233

Variable-item list start.

Vertical margin.

Footnote and display width control.

Em dash string.

Font list for headings, usually “2 2 2 2 2 2 2”. Nonnumeric font names may also be used.

Point size list for headings. Usually “0 0 0 0 0 0 0”, which is the same as “10 10 10 10 10 10 10”.

Contains “LIST OF FIGURES”.

Contains “LIST OF TABLES”.

Contains “LIST OF EXHIBITS”.

Contains “LIST OF EQUATIONS”.

Contains “REFERENCES”.

Contains \(tm, trademark.

Contents level [0:7]; contents saved if heading level <=Cl. Eject page between LIST OF XXXX if Cp == 0.

Debug flag, values greater than 0 produce varying degree of debug. A value of 1 gives information about the progress of formatting.

Eject after floating display is output [0:1]. Floating keep output [0:5].

Space before and after display if == 1 [0:1]. Eject page.

Equation label adjust 0=left, 1=right. Footnote spacing.

Heading counters. Heading break level [0:7].

Heading centering level [0:7].

Heading temporary indent [0:2]. 0 is no indent, left margin. 1 is indent to right, like .P 1. 2 is indent to line up with text part of preceding heading.

Heading space level [0:7]

Heading numbering type 0 is multiple (1.1.1 …). 1 is single. Unnumbered heading level.

Hyphenation in body. 0 is no hyphenation. 1 is hyphenation 14 on.

Enables (1) or disables (0) the printing of a list of figures, list of tables, list of exhibits, and list of equations.

List indent, used by .AL.

List space, if current list level is greater than Ls, then no spacing occurs around lists.

Numbering style [0:5]:

0 == (Default) Normal header for all pages.

1 == Header replaces footer on first page; header is empty. 2 == Page header is removed on the first page.

	Part VII: Miscellaneous
1234
		== Section page numbering enabled.
	3
	4	== Page header is removed on the first page.
	5	== Section page and section figure numbering enabled. See also the
	number register Sectf and Sectp.

Np=0	Numbered paragraphs. 0 is not numbered. 1 is numbered in first-level
	headings.
Of=0	Format of figure, table, exhibit, and equation titles. 0 is “. “. 1 is “-”.
P	Current page number, usually the same as % unless section-page
	numbering is enabled.
Pi=5	Paragraph indent.
Ps=1	Paragraph spacing.
Pt=0	Paragraph type. 0 is left-justified. 1 is indented .P. 2 is indented .P
	except after .H, .DE, or .LE.
Si=5	Display indent.

AUTHOR

Jorgen Hagg, Lund Institute of Technology, Sweden ([e-mail]).

FILES

/usr/lib/groff/tmac/tmac.gm /usr/lib/groff/tmac/mm/*.cov /usr/lib/groff/tmac/mm/*.MT /usr/lib/groff/tmac/mm/locale

SEE ALSO

groff(1), gtroff(1), gtbl(1), gpic(1), geqn(1), mm(7), mgmse(7)

Groff Version 1.09, 14 February 1994

groff_ms

groff_ms—groff ms macros.

SYNOPSIS

groff_mgs [ options... ] [files... ]

DESCRIPTION

This manual page describes the GNU version of the ms macros, which is part of the groff document formatting system. The groff ms macros are intended to be compatible with the documented behavior of the 4.3 BSD UNIX ms macros, subject to the following limitations:

The internals of groff ms are not similar to the internals of UNIX ms, so documents that depend upon implementation details of UNIX ms might not work with groff ms.

There is no support for typewriter-like devices.

Berkeley localisms, in particular the TM and CT macros, are not implemented.

groff ms does not provide cut marks.

Multiple line spacing is not allowed. (Use a larger vertical spacing instead.)

groff ms does not work in compatibility mode (such as with the -C option).

groff_ms 1235

The error-handling policy of groff ms is to detect and report errors, rather than silently ignore them.

The groff ms macros use many features of GNU troff and therefore cannot be used with any other troff.

Bell Labs localisms are not implemented in either the BSD ms macros or in the groff ms macros.

Some UNIX ms documentation says that the CW and GW number registers can be used to control the column width and gutter width. This is not the case. These number registers are not used in groff ms.

Macros that cause a reset set the indent. Macros that change the indent do not increment or decrement the indent, but rather set it absolutely. This can cause problems for documents that define additional macros of their own. The solution is to not use the in request but instead to use the RS and RE macros.

The number register GS is set to 1 by the groff ms macros but is not used by the UNIX ms macros. It is intended that documents that need to determine whether they are being formatted with UNIX ms or groff ms use this number register.

Footnotes are implemented so that they can safely be used within keeps and displays. Automatically numbered footnotes within floating keeps are not recommended. It is safe to have another \** between a \** and the corresponding .FS; it is required only that each .FS occur after the corresponding \** and that the occurrences of .FS are in the same order as the corresponding occurrences of \**.

The strings \*{ and \*} can be used to begin and end a superscript.

Some UNIX V10 ms features are implemented. The B, I, and BI macros can have an optional third argument that is printed in the current font before the first argument. There is a macro CW like B that changes to a constant-width font.

The following strings can be redefined to adapt the groff ms macros to languages other than English:

String	Default Value
REFERENCES	References
ABSTRACT	ABSTRACT
TOC	Table of Contents
MONTH1	January
MONTH2	February
MONTH3	March
MONTH4	April
MONTH5	May
MONTH6	June
MONTH7	July
MONTH8	August
MONTH9	September
MONTH10	October
MONTH11	November
MONTH12	December

The font family is reset from the string FAM; at initialization if this string is undefined, it is set to the current font family. The point size, vertical spacing, and inter-paragraph spacing for footnotes are taken from the number registers FPS, FVS, and FPD; at initialization, these are set to \n(PS-2, \n[FPS]+2, and \n(PD/2; however, if any of these registers was defined before initialization, it is not set. The hyphenation flags (as set by the .hy request) are set from the HY register; if this was not defined at initialization, it is set to 14.

Right-aligned displays are available with .DS R and .RD.

The following conventions are used for names of macros, strings, and number registers. External names available to documents that use the groff ms macros contain only uppercase letters and digits. Internally, the macros are divided into

		Part VII: Miscellaneous
	1236

modules. Names used only within one module are of the form module*name. Names used outside the module in which they are defined are of the form module@name. Names associated with a particular environment are of the form environment:name; these are used only within the par module, and name does not have a module prefix. Constructed names used to implement arrays are of the form array!index. Thus, the groff ms macros reserve the following names:

Names containing *

Names containing @

Names containing :

Names containing only uppercase letters and digits

FILES

/usr/lib/groff/tmac/tmac.gs

SEE ALSO

groff(1), gtroff(1), gtbl(1), gpic(1), geqn(1), ms(7)

Groff Version 1.09, 9 January 1994

hier

hier—Description of the filesystem hierarchy.

DESCRIPTION

A typical Linux system has, among others, the following directories:

/	This is the root directory. This is where the whole tree starts.
/bin	This directory contains executable programs that are needed in single-user mode and to
	bring the system up or repair it.
/boot	Contains static files for the boot loader. This directory only holds the files that are
	needed during the boot process. The map installer and configuration files should go to /
	sbin and /etc.
/dev	Special or device files that refer to physical devices. See mknod(1).
/dos	If both MS–DOS and Linux are run on one computer, this is a typical place to mount a
	DOS filesystem.
/etc	Contains configuration files that are local to the machine. Some larger software
	packages, such as X11, can have their own subdirectories below /etc. Site-wide
	configuration files may be placed here or in /usr/etc. Nevertheless, programs should
	always look for these files in /etc and you may have links for these files to /usr/etc.
/etc/skel	When a new user account is created, files from this directory are usually copied into the
	user’s home directory.
/etc/X11	Configuration files for the X11 window system.
/home	On machines with home directories for users, these are usually beneath this directory,
	directly or not. The structure of this directory depends on local administration
	decisions.
/lib	This directory should hold those shared libraries that are necessary to boot the system
	and to run the commands in the root filesystem.
/mnt	This is a mount point for temporarily mounted filesystems.
/proc	This is a mount point for the proc filesystem, which provides information about
	running processes and the kernel. This pseudo-filesystem is described in more detail in
	proc(5).

	hier
		1237
/sbin	Like /bin, this directory holds commands needed to boot the system but usually not
	executed by normal users.
/tmp	This directory contains temporary files that may be deleted with no notice, such as by a
	regular job or at system bootup.
/usr	This directory is usually mounted from a separate partition. It should hold only
	sharable, read-only data so that it can be mounted by various machines running Linux.
/usr/X11R6	The X window system, version 11, release 6.
/usr/X11R6/bin	Binaries that belong to the X window system; often, there is a symbolic link from the
	more traditional /usr/bin/X11 to here.
/usr/X11R6/lib	Data files associated with the X window system.
/usr/X11R6/lib/X11	These contain miscellaneous files needed to run X; Often, there is a symbolic link from
	/usr/lib/X11 to this directory.
/usr/X11R6/include/X11	Contains include files needed for compiling programs using the X11 window system.
	Often, there is a symbolic link from /usr/include/X11 to this directory.
/usr/bin	This is the primary directory for executable programs. Most programs executed by
	normal users that are not needed for booting or for repairing the system and that are not
	installed locally should be placed in this directory.
/usr/bin/X11	This is the traditional place to look for X11 executables; on Linux, it usually is a
	symbolic link to /usr/X11R6/bin.
/usr/dict	This directory holds files containing word lists for spell-checkers.
/usr/etc	Site-wide configuration files to be shared between several machines may be stored in this
	directory. However, commands should always reference those files using the /etc
	directory. Links from files in /etc should point to the appropriate files in /usr/etc.
/usr/include	Include files for the C compiler.
/usr/include/X11	Include files for the C compiler and the X window system. This is usually a symbolic
	link to /usr/X11R6/include/X11.
/usr/include/asm	Include files that declare some assembler functions. This should be a symbolic link to /
	usr/src/linux/include/asm.
/usr/include/linux	This contains information that may change from system release to system release and
	should be a symbolic link to /usr/src/linux/include/linux to get at operating-system–
	specific information.
/usr/include/g++	Include files to use with the GNU C++ compiler.
/usr/lib	Object libraries, including dynamic libraries, plus some executables that usually are not
	invoked directly. More complicated programs may have whole subdirectories there.
/usr/lib/X11	The usual place for data files associated with X programs and configuration files for the
	X system itself. On Linux, it usually is a symbolic link to /usr/X11R6/lib/X11.
/usr/lib/gcc-lib	Contains executables and include files for the GNU C compiler, gcc(1).
/usr/lib/groff	Files for the GNU groff document formatting system.
/usr/lib/uucp	Files for uucp(1).
/usr/lib/zoneinfo	Files for time zone information.
/usr/local	This is where programs that are local to the site typically go.
/usr/local/bin	Binaries for programs local to the site go there.
/usr/local/doc	Local documentation.
/usr/local/etc	Configuration files associated with locally installed programs go there.
/usr/local/lib	Files associated with locally installed programs go there.
/usr/local/info	Info pages associated with locally installed programs go there.
/usr/local/man	Man pages associated with locally installed programs go there.
/usr/local/sbin	Locally installed programs for system administration.

		Part VII: Miscellaneous
	1238

/usr/local/src	Source code for locally installed software.
/usr/man	Man pages go in there into their subdirectories.
/usr/man/cat[1-9]	These directories contain preformatted manual pages according to their man page
	section.
/usr/man/locale/man[1-9]	These directories contain manual pages that are in source code form. Systems that use a
	unique language and code set for all manual pages may omit the locale substring.
/usr/sbin	This directory contains program binaries for system administration that are not essential
	for the boot process, for mounting /usr, or for system repair.
/usr/src	Source files for different parts of the system.
/usr/src/linux	This contains the sources for the kernel of the operating system itself.
/usr/tmp	An alternative place to store temporary files; This should be a link to /var/tmp.
/var	This directory contains files that may change in size, such as spool and log files.
/var/adm	This directory is superseded by /var/log and should be a symbolic link to /var/log.
/var/lock	Lock files are placed in this directory. The naming convention for device lock files is
	LCK..device where device is the device’s name in the filesystem. The format used is that
	of HDU UUCP lock files—that is, lock files contain a PID as a 10-byte ASCII decimal
	number, followed by a newline character.
/var/log	Miscellaneous log files.
/var/preserve	This is where vi(1) saves edit sessions so they can be restored later.
/var/run	Runtime variable files, such as files holding process identifiers (PIDs) and logged user
	information (utmp). Files in this directory are usually cleared when the system boots.
/var/spool	Spooled (or queued) files for various programs.
/var/spool/at	Spooled jobs for at(1).
/var/spool/cron	Spooled jobs for cron(1).
/var/spool/lpd	Spooled files for printing.
/var/spool/mail	Users’ mailboxes.
/var/spool/smail	Spooled files for the smail(1) mail delivery program.
/var/spool/news	Spool directory for the news subsystem.
/var/spool/uucp	Spooled files for uucp(1).
/var/tmp	Like /tmp, this directory holds temporary files stored for an unspecified duration.

CONFORMS TO

The Linux filesystem standard, release 1.2.

BUGS

This list is not exhaustive; different systems may be configured differently.

SEE ALSO

find(1), ln(1), mount(1), proc(5), The Linux Filesystem Standard

Linux, 10 February 1996

hostname

hostname—Hostname resolution description.

hostname 1239

DESCRIPTION

Hostnames are domains. A domain is a hierarchical, dot-separated list of subdomains. For example, the machine monet in the Berkeley subdomain of the EDU subdomain of the Internet Domain Name System is represented as monet.Berkeley.EDU (with no trailing dot).

Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is usually performed by the library routine gethostbyname(3).) The default method for resolving hostnames by the Internet name resolver is to follow RFC 1535’s security recommendations. Actions can be taken by the administrator to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 resolvers.

The default method (using RFC 1535 guidelines) follows.

If the name consists of a single component (that is, contains no dot) and if the environment variable HOSTALIASES is set to the name of a file, that file is searched for a string matching the input hostname. The file should consist of lines made up of two strings separated by whitespace, the first of which is the hostname alias and the second of which is the complete hostname to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing.

If there is at least one dot in the name, then the name is first tried as is. The number of dots to cause this action is configurable by setting the threshold using the ndots option in /etc/resolv.conf (default is 1). If the name ends with a dot, the trailing dot is removed, and the remaining name is looked up (regardless of the setting of the ndots option) and no further processing is done.

If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. If neither the search option in the /etc/resolv.conf file or the LOCALDOMAIN environment variable is used, then the search list of domains contains only the full domain specified by the domain option (in /etc/resolv.conf) or the domain used in the local hostname (see hostname(1) and resolver(5)). For example, if the domain option is set to CS.Berkeley.EDU, then only CS.Berkeley.EDU is in the search list and is the only domain appended to the partial hostname. For example, a setting of lithium makes lithium.CS.Berkeley.EDU the only name to be tried using the search list.

If the search option is used in /etc/resolv.conf or the environment variable, LOCALDOMAIN is set by the user, then the search list includes what is set by these methods. For example, if the search option contained CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU, then the partial hostname (such as lithium) is tried with each domain name appended (in the same order specified). The resulting hostnames that are tried include

lithium.CS.Berkeley.EDU

lithium.CChem.Berkeley.EDU

lithium.Berkeley.EDU

The environment variable LOCALDOMAIN overrides the search and domain options, and if both search and domain options are present in the resolver configuration file, then only the last one listed is used (see resolver(5)).

If the name was not previously tried “as is” (that is, it fell below the ndots threshold or did not contain a dot), then the name as originally provided is attempted.

SEE ALSO

gethostbyname(3), resolver(5), mailaddr(7), named(8)

16 February 1994

iso_8859_1

iso_8859_1—The ISO 8859-1 character set encoded in octal, decimal, and hexadecimal.

DESCRIPTION

The ISO 8859 standard includes several 8-bit extensions to the ASCII character set (also known as ISO 646-IRV). Especially important is ISO 8859-1, the Latin Alphabet No. 1, which has become widely implemented and may already be seen as the

		Part VII: Miscellaneous
	1240

de facto standard ASCII replacement. ISO 8859-1 supports the following languages: Afrikaans, Basque, Catalan, Danish, Dutch, English, Faeroes, Finnish, French, Galician, German, Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, Spanish, and Swedish. Note that the ISO 8859-1 characters are also the first 256 characters of ISO 10646 (Unicode).

ISO 8859 ALPHABETS

The full set of ISO 8859 alphabets includes ISO 8859-1

ISO 8859-2

ISO 8859-3

ISO 8859-4

ISO 8859-5

ISO 8859-6

ISO 8859-7

ISO 8859-8

ISO 8859-9

ISO 8859-10

West European languages (Latin-1) East European languages (Latin-2)

Southeast European and miscellaneous languages (Latin-3) Scandinavian/Baltic languages (Latin-4)

Latin/Cyrillic

Latin/Arabic

Latin/Greek

Latin/Hebrew

Latin-1 modification for Turkish (Latin-5) Lappish/Nordic/Eskimo languages (Latin-6)

ISO 8859-1 CHARACTERS

The following table displays the characters in ISO 8859 Latin-1, which are printable and unlisted in the ascii(7) manual page.

Oct	Dec	Hex	Char	Description
240	160	A0		No-break space
241	161	A1	¡	Inverted exclamation mark
242	162	A2	¢	Cent sign
243	163	A3	£	Pound sign
244	164	A4	$	Currency sign
245	165	A5	¥	Yen sign
246	166	A6	|	Broken bar
247	167	A7	§	Section sign
250	168	A8	¨	Diaeresis
251	169	A9	Ó	Copyright sign
252	170	AA	_	Feminine ordinal indicator
			ª
253	171	AB	<<	Left-pointing double angle quotation
				mark
254	172	AC	¬	Not sign
255	173	AD	-	Soft hyphen
256	174	AE	â	Registered sign
257	175	AF	¯	Macron
260	176	B0	°	Degree sign
261	177	B1	±	Plus-minus sign
262	178	B2	2	Superscript two
263	179	B3	3	Superscript three

				iso_8859_1
						1241
Oct	Dec	Hex	Char	Description
264	180	B4	´	Acute accent
265	181	B5		Micro sign
266	182	B6	¶	Pilcrow sign
267	183	B7	.	Middle dot
270	184	B8	ç	Cedilla
271	185	B9	1	Superscript one
			_
272	186	BA		Masculine ordinal indicator
			º
273	187	BB	>>	Right-pointing double angle
				quotation mark
274	188	BC	1/4	Vulgar fraction one quarter
275	189	BD	1/2	Vulgar fraction one half
276	190	BE	3/4	Vulgar fraction three quarters
277	191	BF	¿	Inverted question mark
300	192	C0	À	Latin capital letter A with grave
301	193	C1	Á	Latin capital letter A with acute
302	194	C2	Â	Latin capital letter A with circumflex
303	195	C3	Ã	Latin capital letter A with tilde
304	196	C4	Ä	Latin capital letter A with diaeresis
305	197	C5	Å	Latin capital letter A with ring above
306	198	C6	Æ	Latin capital ligature AE
307	199	C7	Ç	Latin capital letter C with cedilla
310	200	C8	È	Latin capital letter E with grave
311	201	C9	É	Latin capital letter E with acute
312	202	CA	^	Latin capital letter E with circumflex
			E
313	203	CB	¨	Latin capital letter E with diaeresis
			E
314	204	CC	Ì	Latin capital letter I with grave
315	205	CD	Í	Latin capital letter I with acute
316	206	CE	Î	Latin capital letter I with circumflex
317	207	CF	Ï	Latin capital letter I with diaeresis
320	208	D0	D	Latin capital letter eth
321	209	D1	Ñ	Latin capital letter N with tilde
322	210	D2	O	Latin capital letter O with grave
323	211	D3	Ó	Latin capital letter O with acute
324	212	D4	Ô	Latin capital letter O with circumflex
325	213	D5	Õ	Latin capital letter O with tilde
326	214	D6	Ö	Latin capital letter O with diaeresis
327	215	D7	×	Multiplication sign
330	216	D8	Ø	Latin capital letter O with stroke
331	217	D9	Ù	Latin capital letter U with grave
332	218	DA	Ú	Latin capital letter U with acute
333	219	DB	^	Latin capital letter U with circumflex
			U

continues

		Part VII: Miscellaneous
	1242

Oct	Dec	Hex	Char	Description
334	220	DC	Ü	Latin capital letter U with diaeresis
335	221	DD	´	Latin capital letter Y with acute
			Y
336	222	DE		Latin capital letter thorn
337	223	DF	ß	Latin small letter sharp s
340	224	E0	à	Latin small letter a with grave
341	225	E1	á	Latin small letter a with acute
342	226	E2	â	Latin small letter a with circumflex
343	227	E3	ã	Latin small letter a with tilde
344	228	E4	ä	Latin small letter a with diaeresis
345	229	E5	å	Latin small letter a with ring above
346	230	E6	æ	Latin small ligature ae
347	231	E7	ç	Latin small letter c with cedilla
350	232	E8	è	Latin small letter e with grave
351	233	E9	é	Latin small letter e with acute
352	234	EA	ê	Latin small letter e with circumflex
353	235	EB	ë	Latin small letter e with diaeresis
354	236	EC	ì	Latin small letter i with grave
355	237	ED	í	Latin small letter i with acute
356	238	EE	î	Latin small letter i with circumflex
357	239	EF	ï	Latin small letter i with diaeresis
360	240	F0	∂	Latin small letter eth
361	241	F1	ñ	Latin small letter n with tilde
362	242	F2	ò	Latin small letter o with grave
363	243	F3	ó	Latin small letter o with acute
364	244	F4	ô	Latin small letter o with circumflex
365	245	F5	õ	Latin small letter o with tilde
366	246	F6	ö	Latin small letter o with diaeresis
367	247	F7	÷	Division sign
370	248	F8	ø	Latin small letter o with stroke
371	249	F9	ù	Latin small letter u with grave
372	250	FA	ú	Latin small letter u with acute
373	251	FB	û	Latin small letter u with circumflex
374	252	FC	ü	Latin small letter u with diaeresis
375	253	FD	y´	Latin small letter y with acute
376	254	FE		Latin small letter thorn
377	255	FF	ÿ	Latin small letter y with diaeresis

SEE ALSO

ascii(7)

11 July 1995

locale 1243

locale

Locale—Description of multi-language support.

SYNOPSIS

#include <locale.h>

DESCRIPTION

A locale is a set of language and cultural rules. These cover aspects such as language for messages, different character sets, lexigraphic conventions, and so on. A program needs to be able to determine its locale and act accordingly to be portable to different cultures.

The header <locale.h> declares data types, functions and macros that are useful in this task.

The functions it declares are setlocale() to set the current locale and localeconv() to get information about number formatting.

There are different categories for local information a program might need; they are declared as macros. Using them as the first argument to the setlocale() function, it is possible to set one of these to the desired locale:

LC_COLLATE	This is used to change the behavior of the functions strcoll() and strxfrm(), which
	are used to compare strings in the local alphabet. For example, the German sharp s is
	sorted as “ss.”
LC_TYPE	This changes the behavior of the character handling and classification functions,
	such as isupper() and toupper() and the multi–byte character functions such as
	mblen() or wctomb().
LC_MONETARY	Changes the behavior of the information returned by localeconv(), which describes
	the way numbers are usually printed, with details such as decimal point versus
	decimal comma.
LC_MESSAGES	Changes the language messages are displayed in.
LC_TIME	Changes the behavior of the strftime() function to display the current time in a
	locally acceptable form; for example, most of Europe uses a 24–hour clock versus the
	U.S. 12–hour clock.
LC_ALL	All of the above.

If the second argument to setlocale() is empty string for the default locale, it is determined using the following steps:

1.If there is a non-null environment variable LC_ALL, the value of LC_ALL is used.

2.If an environment variable with the same name as one of the preceding categories exists and is non-null, its value is used for that category.

3.If there is a non-null environment variable LANG, the value of LANG is used.

Values about local numeric formatting are made available in a struct lconv returned by the localeconv() function, which has the following declaration:

struct lconv

{

/* Numeric (non-monetary) information. */

char *decimal_point; /* Decimal point character. */ char *thousands_sep; /* Thousands separator. */

/* Each element is the number of digits in each group; elements with higher indices are farther left.

An element with value CHAR_MAX means that no further grouping is done. An element with value 0 means that the previous element is used for all groups farther left. */

char *grouping;

/* Monetary information. */

KOI-8

		Part VII: Miscellaneous
	1244

/* First three chars are a currency symbol from ISO 4217. Fourth char is the separator. Fifth char is ‘ ‘. */

char *int_curr_symbol;

char *currency_symbol; /* Local currency symbol. */ char *mon_decimal_point; /* Decimal point character. */ char *mon_thousands_sep; /* Thousands separator. */

char *mon_grouping; /* Like ‘grouping’ element (above). */ char *positive_sign; /* Sign for positive values. */

char *negative_sign; /* Sign for negative values. */ char int_frac_digits; /* Int’l fractional digits. */ char frac_digits; /* Local fractional digits. */

/* 1 if currency_symbol precedes a positive value, 0 if succeeds. */ char_p_cs_precedes;

/* 1 if a space separates currency_symbol from a positive value. */ char_p_sep_by_space;

/* 1 if currency_symbol precedes a negative value, 0 if succeeds. */ char_n_cs_precedes;

/* 1 if a space separates currency_symbol from a negative value. */ char_n_sep_by_space;

/* Positive and negative sign positions:

0Parentheses surround the quantity and currency_symbol.

1The sign string precedes the quantity and currency_symbol.

2The sign string succeeds the quantity and currency_symbol.

3The sign string immediately precedes the currency_symbol.

4The sign string immediately succeeds the currency_symbol. */ char_p_sign_posn;

char_n_sign_posn; };

CONFORMS TO

POSIX.1

At the moment, the only (European Latin-1), and

locales supported by Linux are the portable C, POSIX (identical to the C locale), ISO-8859-1 (Russian) locales.

SEE ALSO

setlocale(3), localeconf(3), locale(1), localedef(1)

Linux, 24 April 1993

mailaddr

mailaddr—Mail addressing description.

DESCRIPTION

Mail addresses are based on the ARPANET protocol listed at the end of this manual page. These addresses are in the general format

user@domain

A domain is a hierarchical dot separated list of subdomains. For example, the address

[e-mail]

is usually interpreted from right to left. The message should go to the ARPA name tables (which do not correspond exactly to the physical ARPANET) and then to the Berkeley gateway, after which it should go to the local host monet. When the message reaches monet, it is delivered to the user eric.

mailaddr 1245

Unlike some other forms of addressing, this does not imply any routing. Thus, although this address is specified as an ARPA address, it might travel by an alternate route if that were more convenient or efficient. For example, at Berkeley, the associated message would probably go directly to monet over the Ethernet rather than go via the Berkeley ARPANET gateway.

ABBREVIATION

Under certain circumstances, it might not be necessary to type the entire domain name. In general, anything following the first dot may be omitted if it is the same as the domain from which you are sending the message. For example, a user on calder.berkeley.edu could send to eric@monet without adding the berkeley.edu because it is the same on both sending and receiving hosts.

Certain other abbreviations may be permitted as special cases. For example, at Berkeley, ARPANET hosts may be referenced without adding the berkeley.edu as long as their names do not conflict with a local host name.

COMPATIBILITY

Certain old address formats are converted to the new format to provide compatibility with the previous mail system. In particular,

[e-mail]

is allowed and

host:user

is converted to

user@host

to be consistent with the rcp(1) command.

Also, the syntax

host!user

is converted to

[e-mail]

This is usually converted back to the host!user form before being sent on for compatibility with older UUCP hosts.

The current implementation is not able to route messages automatically through the UUCP network. Until that time, you must explicitly tell the mail system which hosts to send your message through to get to your final destination.

CASE DISTINCTIONS

Domain names (anything after the @ sign) may be given in any mixture of uppercase and lowercase with the exception of UUCP hostnames. Most hosts accept any combination of case in usernames, with the notable exception of MULTICS sites.

ROUTE-ADDRS

Under some circumstances, it might be necessary to route a message through several hosts to get it to the final destination. Usually, this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses that show these relays are termed “route-addrs.” These use the syntax

<@hosta,@hostb:user@hostc>

This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. This path is forced even if there is a more efficient path to hostc.

Route-addrs occur frequently on return addresses because these are generally augmented by the software at each host. It is generally possible to ignore all but the user@domain part of the address to determine the actual sender.

		Part VII: Miscellaneous
	1246

POSTMASTER

Every site is required to have a user or user alias designated “postmaster” to which problems with the mail system may be addressed.

OTHER NETWORKS

Some other networks can be reached by giving the name of the network as the last component of the domain. This is not a standard feature and might not be supported at all sites. For example, messages to CSNET or BITNET sites can often be sent to [e-mail] or [e-mail].

BUGS

The RFC 822 group syntax (group:user1,user2,user3;) is not supported except in the special case of group:; because of a conflict with old berknet-style addresses.

Route-Address syntax is grotty.

UUCPand ARPANET-style addresses do not coexist politely.

SEE ALSO

mail(1), sendmail(8); Crocker, D. H., Standard for the Format of Arpa Internet Text Messages, RFC822.

14 February 1989

man

man—Macros to format man pages.

SYNOPSIS

groff –Tascii –man file ...

groff –Tps –man file ...

man [section] title

DESCRIPTION

This manual page explains the groff tmac.an macro package. This macro package should be used by developers when writing or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package).

Note that NET-2 BSD man pages can be used with groff simply by specifying the -mdoc option instead of the -man option. Using the -mandoc option is, however, recommended because this automatically detects which macro package is in use.

PREAMBLE

The first command in a man page should be

.TH title section date source manual,

title	The title of the man page (such as MAN).
section	The section number the man page should be placed in (such as 7).
date	The date of the last revision; remember to change this every time a change is made
	to the man page because this is the most general way of doing version control.
source	The source of the command.
	For binaries, use something such as GNU, NET-2, SLS Distribution, MCC
	Distribution.
	For system calls, use the version of the kernel that you are currently looking at:

	man
		1247
	Linux 0.99.11.
	For library calls, use the source of the function: GNU, BSD 4.3, Linux DLL 4.4.1.
manual	The title of the manual (such as Linux Programmer’s Manual).

The manual sections are traditionally defined as follows:

1	Commands	Those commands that can be executed by the user from within a shell.
2	System calls	Those functions that must be performed by the kernel.
3	Library calls	Most of the libc functions, such as sort(3).
4	Special files	Files found in /dev.
5	File formats and conventions	The format for /etc/passwd and other human-readable files.
6 Games
7	Macro packages and conventions	A description of the standard file system layout, this man page, and other things.
8	System management commands	Commands such as mount(8), which only root can execute.
9	Kernel routines	This is a non-standard manual section and is included because the source code to
		the Linux kernel is freely available under the GNU Public License and many
		people are working on changes to the kernel.

FONTS

Although there are many arbitrary conventions for man pages in the UNIX world, the existence of several hundred Linuxspecific man pages defines the standards:

For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:

int myfunction(int argc, char **argv);

Filenames are always in italics (such as /usr/include/stdio.h), except in the SYNOPSIS section, where included files are in bold (such as #include <stdio.h>).

Special macros, which are usually in uppercase, are in bold (such as MAXINT).

When enumerating a list of error codes, the codes are in bold (this list usually uses the .TP macro).

Any reference to another man page (or to the subject of the current man page) is in bold. If the manual section number is given, it is given in roman, without any spaces (such as man(7)).

The commands to select the typeface are given below:

.B	Bold
.BI	Bold alternating with italics
.BR	Bold alternating with Roman
.I	Italics
.IB	Italics alternating with bold
.IR	Italics alternating with Roman
.RB	Roman alternating with bold
.RI	Roman alternating with italics
.SB	Small alternating with bold
.SM	Small

Traditionally, each command can have up to six arguments, but the GNU version seems to remove this limitation. Arguments are delimited by spaces. Double quotes can be used to specify an argument that contains spaces. All the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman.

		Part VII: Miscellaneous
	1248

SECTIONS

Sections are started with .SH followed by the heading name. If the name contains spaces and appears on the same line as .SH, then place the heading in double quotes. Traditional headings include NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, DIAGNOSTICS, BUGS, and AUTHOR. The only required heading is NAME, which should be followed on the next line by a one line description of the program:

.SH NAME

chess \- the game of chess

It is extremely important that this format is followed and that there is a backslash before the single dash that follows the command name. This syntax is used by the makewhatis(8) program to create a database of short command descriptions for the whatis(1) and apropos(1) commands.

OTHER MACROS

Other macros include the following:

.DT	Default tabs.
.HP	Begin hanging indent.
.IP	Begin paragraph with hanging tag. This is the same as .TP, except the tag is given on the
	same line, not on the following line.
.LP	Same as .PP.
.PD	Set interparagraph distance to argument.
.PP	Begin a new paragraph.
.RE	End relative indent (indented paragraph).
.RS	Start relative indent (indented paragraph).
.SS	Subheading (like .SH but used for a subsection).
.TP	Begin paragraph with hanging tag. The tag is given on the next line. This command is
	similar to .IP.

FILES

/usr/local/lib/groff/tmac/tmac.an

/usr/man/whatis

SEE ALSO

groff(1), man(1), whatis(1), apropos(1), makewhatis(8)

Linux, 25 July 1993

signal

signal—List of available signals.

DESCRIPTION

Linux supports the signals listed in this section. Several signal numbers are architecture dependent. First are the signals described in POSIX.1:

abort(3) alarm(1) Next various other signals.

(Here, – denotes that a signal is absent; there, where three values are given, the first one is usually valid for alpha and sparc, the middle one for i386 and ppc, the last one for mips. Signal 29 is SIGINFO/SIGPWR on an alpha but SIGLOST on a sparc.)

suffixes 1249

The letters in the Action column have the following meanings:

A	Default action is to terminate the process.
B	Default action is to ignore the signal.
C	Default action is to dump core.
D	Default action is to stop the process.
E	Signal cannot be caught.
F	Signal cannot be ignored.
G	Not a POSIX.1 conformant signal.

CONFORMING TO

POSIX.1

BUGS

SIGIO and SIGLOST have the same value. The latter is commented out in the kernel source, but the build process of some software still thinks that Signal 29 is SIGLOST.

SEE ALSO

kill(1), kill(2), setitimer(2)

Linux 1.3.88, 14 April 1996

suffixes

suffixes—List of file suffixes.

DESCRIPTION

It is customary to indicate the contents of a file with the file suffix, which consists of a period followed by one or more letters. Many standard utilities, such as compilers, use this to recognize the type of file they are dealing with. The make(1) utility is driven by rules based on file suffixes.

Following is a list of suffixes that are likely to be found on a Linux system:

Suffix	File Type
,v	Files for RCS (Revision Control System)
-	Backup file
.C	C++ source code
.F	FORTRAN source with cpp(1) directives
.S	Assembler source with cpp(1) directives
.Z	File compressed using compress(1)
.[0-9]+pk	TeX font files
.[1-9]	Manual page for the corresponding section
.[1-9][a-z]	Manual page for section plus subsection
.a	Static object code library
.afm	PostScript font metrics
.arc	ARC archive
.arj	ARJ archive
.asc	PGP ASCII-armored data

continues

		Part VII: Miscellaneous
	1250

Suffix	File Type
.awk	AWK language program
.bak	Backup file
.bm	Bitmap source
.c	C source
.cat	Message catalog files
.cc	C++ source
.cf	Configuration file
.conf	Configuration file
.config	Configuration file
.cweb	Donald Knuth’s WEB for C
.dat	Data file
.def	Modula-2 source for definition modules
.def	Other definition files
.diff	ASCII File differences
.doc	Documentation file
.dvi	TeX device independent output
.el	EMACS lisp source
.elc	Compiled EMACS lisp
.eps	Encapsulated PostScript
.f	FORTRAN source
.fas	Precompiled common lisp
.fi	FORTRAN include files
.gif	Graphics Interchange Format
.gsf	Ghostscript fonts
.gz	File compressed using gzip(1)
.h	C or C++ header files
.hlp	Help file
.htm	HTML file imported without renaming from a brain-damaged OS
.html	HTML document used with the World Wide Web
.i	C source after preprocessing
.idx	Reference or datum-index file for hypertext or database system
.icon	Bitmap source
.image	Bitmap source
.in	Configuration template, especially for GNU autoconf
.info	Files for the EMACS info browser
.java	A Java source file
.jpg	JPEG compressed picture format
.l	lex(1) or flex(1) files
.lib	Common lisp library
.ln	Files for use with lint(1)
.lsp	Common lisp source
.m4	M4(1) source
.mac	Macro files for various programs

suffixes 1251

Suffix	File Type
.man	Manual page (usually source rather than formatted)
.me	nroff source using the me macro package
.mf	Metafont (font generator for TeX) source
.mm	Sources for groff(1) in mm format
.mod	Modula-2 source for implementation modules
.o	Object file
.old	Old or backup file
.orig	Backup (original) version of a file from patch(1)
.out	Output file, often an executable program (a.out)
.p	Pascal source
.patch	File differences from patch(1)
.pcf	X11 font files
.pfa	PostScript font definition files, ASCII format
.pfb	PostScript font definition files, binary format
.pgp	PGP binary data
.pid	File to store daemon PID (such as crond.pid)
.png	Portable Network Graphics file
.pl	Perl script
.pr	Bitmap source
.ps	PostScript file
.r	RATFOR source (obsolete)
.rej	Patches that patch(1) couldn’t apply
.rules	Rules for something
.s	Assembler source
.sa	Stub libraries for a.out shared libraries
.sc	sc(1) spreadsheet commands
.sh	sh(1) scripts
.shar	Archive created by the shar(1) utility
.so	DLL dynamic library
.sqml	SQML schema or query program
.sty	LaTeX style files
.sym	Modula-2 compiled definition modules
.tar	Archive created by the tar(1) utility
.tar.Z	tar archive compressed with compress(1)
.tar.gz	tar archive compressed with gzip(1)
.taz	tar archive compressed with compress(1)
.tex	TeX or LaTeX source
.texi	Equivalent to .texinfo
.texinfo	TeXinfo documentation source
.tfm	TeX font metrics
.tgz	tar archive compressed with gzip(1)
.tmpl	Template files

continues

		Part VII: Miscellaneous
	1252

Suffix	File Type
.txt	Text file
.uue	Binary file encoded with uuencode(1)
.web	Donald Knuth’s WEB
.y	yacc(1) or bison(1) (parser generator) files
.z	File compressed using pack(1) (or an old gzip(1))
.zoo	ZOO archive
˜	EMACS or patch backup file
rc	Startup (run control) file, such as .newsrc

CONFORMS TO

General UNIX conventions.

BUGS

This list is not exhaustive.

SEE ALSO

file(1), make(1)

Linux, 4 April 1996

tr2tex

tr2tex—Convert a document from troff to LaTeX

SYNOPSIS

tr2tex [ -m ] filename

DESCRIPTION

tr2tex converts a document typeset in troff to a LaTeX format. It is intended to do the first pass of the conversion. The user should then finish up the rest of the conversion and customize the converted manuscript to his or her liking. It can also serve as a tutor for those who want to convert from troff to LaTeX.

Most of the converted document will be in LaTeX, but some of it may be in plain TeX. It will also use some macros in troffms.sty or troffman.sty, which are included in the package and must be available to the document when processed with LaTeX.

If there is more than one input file, they will all be converted into one LaTeX document.

tr2tex understands most of the -ms and -man macros and eqn preprocessor symbols. It also understands several plain troff commands. Few tbl preprocessor commands are understood to help convert very simple tables.

When converting manuals, use the -m flag.

If a troff command cannot be converted, the line that contain that command will be commented out.

Note that if you have eqn symbols, you must have the inline mathematics delimiter defined by delim in the file you are converting. If it is defined in another setup file, that setup file must be concatenated with the file to be converted; otherwise, tr2tex regards the inline math as ordinary text.

Unicode 1253

BUGS

Many of these bugs are harmless. Most of them cause local errors that can be fixed in the converted manuscript.

■Some macros and macro arguments are not recognized.

■Commands that are not separated from their argument by a space are not properly parsed (such as .sp3i).

■When some operators (notably over, sub, and sup) are renamed (via define) and then they are encountered in the text, tr2tex treats them as ordinary macros and does not apply their rules.

■rpile, lpile, and cpile are treated the same as cpile.

■rcol and lcol are treated the same as ccol.

■Math-mode size, gsize, fat, and gfont are ignored.

■lineup and mark are ignored. The rules are so different.

■Some troff commands are translated to commands that require delimiters that have to be explicitly put. Because they are sometimes not put in troff, they can create problems. Example: .nf is not closed by .fi.

■When local motions are converted to nraise or nlower, an nhbox is needed, which must be put manually after the conversion.

■a sub i sub j is converted to a_i_j, which TeX parses as a_i{}_j} with a complaint that it is vague. a sub {i subj} is parsed correctly and converted to a_{i_j}.

■Line spacing is not changed within a paragraph in TeX (which is a bad practice anyway). TeX uses the last line spacing in effect in that paragraph.

TO DO

Access registers via the .nr command.

SEE ALSO

texmatch(9), trmatch(9)

AUTHOR

Kamal Al-Yahya, Stanford University

1 January 1987

Unicode

Unicode—The unified 16-bit super character set.

DESCRIPTION

The international standard ISO 10646 defines the Universal Character Set (UCS). UCS contains all the characters of all other character-set standards. It also guarantees round-trip compatibility; conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back.

UCS contains the characters required to represent almost all known languages. This includes apart from the many languages that use extensions of the Latin script also the following scripts and languages: Greek, Cyrillic, Hebrew, Arabic, Armenian, Gregorian, Japanese, Chinese, Hiragana, Katakana, Korean, Hangul, Devangari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayam, Thai, Lao, Bopomofo, and a number of others. Work is going on to include further scripts such as Tibetan, Khmer, Runic, Ethiopian, Hieroglyphics, various Indo-European languages, and many others. For most of these latter scripts, it was not yet clear how they can be encoded best when the standard was published in 1993. In addition to the characters required by these scripts, also a large number of graphical, typographical, mathematical, and scientific symbols such as those provided by TeX, PostScript, MS-DOS, Macintosh, Videotext, OCR, and many word processing systems have been included, as well as special codes that guarantee round-trip compatibility to all other existing character-set standards.

wchar_t

		Part VII: Miscellaneous
	1254

The UCS standard (ISO 10646) describes a 31-bit character-set architecture; however, today only the first 65534 code positions (0x0000 to 0xfffd), which are called the Basic Multilingual Plane (BMP), have been assigned characters, and it is expected that only very exotic characters (such as Hieroglyphics) for special scientific purposes will ever get a place outside this 16-bit BMP.

The UCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCII character set and the characters in the range 0x0000 to 0x00ff are identical to those in the ISO 8859-1 Latin-1 character set.

COMBINING CHARACTERS

Some code points in UCS have been assigned to combining characters. These are similar to the non-spacing accent keys on a typewriter. A combining character just adds an accent to the previous character. The most important accented characters have codes of their own in UCS; however, the combining character mechanism allows you to add accents and other diacritical marks to any character. The combining characters always follow the character that they modify. For example, the German character Umlaut-A (“Latin capital letter A with diaeresis”) can either be represented by the precomposed UCS code 0x00c4 or alternately as the combination of a normal “Latin capital letter A” followed by a “combining diaeresis”: 0x0041 0x0308.

IMPLEMENTATION LEVELS

As not all systems are expected to support advanced mechanisms such as combining characters, ISO 10646 specifies the following three implementation levels of UCS:

Level 1	Combining characters and Hangul Jamo characters (a special, more complicated encoding
	of the Korean script, where Hangul syllables are coded as two or three subcharacters) are not
	supported.
Level 2	Like level 1, except in some scripts, some combining characters are now allowed (such as
	Hebrew, Arabic, Devangari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugo, Kannada,
	Malayalam, Thai, and Lao).
Level 3	All UCS characters are supported.

The Unicode 1.1 standard published by the Unicode Consortium contains exactly the UCS Basic Multilingual Plane at implementation Level 3, as described in ISO 10646. Unicode 1.1 also adds some semantical definitions for some characters to the definitions of ISO 10646.

UNICODE UNDER LINUX

Under Linux, only the BMP at implementation Level 1 should be used at the moment to keep the implementation complexity of combining characters low. The higher implementation levels are more suitable for special word processing formats but not as a generic system character set. The C type is on Linux an unsigned 16-bit integer type and its values are interpreted as UCS Level 1 BMP codes.

The locale setting specifies whether the system character encoding is UTF-8 or such as wctomb, mbtowc, or wprintf can be used to transform the internal wchar_t character encoding and back.

ISO 8859-1, for example. Library functions characters and strings into the system

PRIVATE AREA

In the BMP, the range 0xe000 to 0xf8ff will never be assigned any characters by the standard and is reserved for private usage. For the Linux community, this private area is subdivided further into the range 0xe000 to 0xefff, which can be used individually by any end user and the Linux zone in the range 0xf000 to 0xf8ff where extensions are coordinated among all Linux users. The registry of the characters assigned to the Linux zone is currently maintained by H. Peter Anvin ([e-mail]), Yggdrasil Computing, Inc. It contains some DEC VT100 graphics characters missing in Unicode, gives direct access to the characters in the console font buffer, and contains the characters used by a few advanced scripts such as Klingon.

UTF-8 1255

LITERATURE

Information technology—Universal Multiple-Octet Coded Character Set (UCS). Part 1: Architecture and Basic Multilingual Plane. International Standard ISO 10646-1, International Organization for Standardization, Geneva, 1993.

This is the official specification of UCS. Pretty official, pretty thick, and pretty expensive. For ordering information, check www.iso.ch.

The Unicode Standard—Worldwide Character Encoding Version 1.0. The Unicode Consortium, Addison-Wesley, Reading, MA, 1991.

There is already Unicode 1.1.4 available. The changes to the 1.0 book are available from ftp.unicode.org. Unicode 2.0 will be published again as a book in 1996.

S. Harbison, G. Steele. C, A Reference Manual. Fourth edition, Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3.

A good reference book about the C programming language. The fourth edition now covers also the 1994 Amendment 1 to the ISO C standard (ISO/IEC 9899:1990), which adds a large number of new C library functions for handling wide character sets.

BUGS

At the time when this man page was written, the Linux libc support for UCS was far from complete.

AUTHOR

Markus Kuhn ([e-mail])

SEE ALSO

utf-8(7)

Linux, 27 December 1995

UTF-8

UTF-8—An ASCII-compatible multibyte Unicode encoding.

DESCRIPTION

The Unicode character set occupies a 16-bit code space. The most obvious Unicode encoding (known as UCS-2) consists of a sequence of 16-bit words. Such strings can contain as parts of many 16-bit characters bytes such as \0 or /, which have a special meaning in filenames and other C library function parameters. In addition, the majority of UNIX tools expects ASCII files and can’t read 16-bit words as characters without major modifications. For these reasons, UCS-2 is not a suitable external encoding of Unicode in filenames, text files, environment variables, and so on. The ISO 10646 Universal Character Set (UCS), a superset of Unicode, occupies even a 31-bit code space, and the obvious UCS-4 encoding for it (a sequence of 32-bit words) has the same problems.

The UTF-8 encoding of Unicode and UCS does not have these problems and is the way to go for using the Unicode character set under UNIX-style operating systems.

PROPERTIES

The UTF-8 encoding has the following nice properties:

UCS characters 0x00000000 to 0x0000007f (the classical U.S. ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII compatibility). This means that files and strings that contain only 7-bit ASCII characters have the same encoding under both ASCII and UTF-8.

All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can appear as part of another character and there are no problems with \0 or /.

		Part VII: Miscellaneous
	1256

The lexicographic sorting order of UCS-4 strings is preserved. All possible 2ˆ31 UCS codes can be encoded using UTF-8. The bytes 0xfe and 0xff are never used in the UTF-8 encoding.

The first byte of a multibyte sequence that represents a single non-ASCII UCS character is always in the range 0xc0 to 0xfd and indicates how long this multibyte sequence is. All further bytes in a multibyte sequence are in the range 0x80 to 0xbf. This allows easy resynchronization and makes the encoding stateless and robust against missing bytes.

UTF-8–encoded UCS characters may be up to six bytes long; however, Unicode characters can only be up to three bytes long. Because Linux uses only the 16-bit Unicode subset of UCS, under Linux, UTF-8 multibyte sequences can only be one, two, or three bytes long.

ENCODING

The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number of the character:

0x00000000 - 0x0000007F: 0xxxxxxx

0x00000080 - 0x000007FF: 110xxxxx 10xxxxxx

0x00000800 - 0x0000FFFF: 1110xxxx 10xxxxxx 10xxxxxx 0x00010000 - 0x001FFFFF: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

0x00200000 - 0x03FFFFFF: 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 0x04000000 - 0x7FFFFFFF: 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

10xxxxxx

The xxx-bit positions are filled with the bits of the character code number in binary representation. Only the shortest possible multibyte sequence that can represent the code number of the character can be used.

EXAMPLES

The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in UTF-8 as

11000010 10101001 = 0xc2 0xa9

and character 0x2260 = 0010 0010 0110 0000 (the “not equal” symbol) is encoded as

11100010 10001001 10100000 = 0xe2 0x89 0xa0

STANDARDS

ISO 10646, Unicode 1.1, XPG4, Plan 9.

AUTHOR

Markus Kuhn ([e-mail])

SEE ALSO

unicode(7)

1257

Part VIII:

Administration

and Privileged

Commands

		Part VIII: Administration and Privileged Commands
	1258

intro

intro—Introduction to administration and privileged commands.

DESCRIPTION

This chapter describes commands that either can be or are only used by the superuser, such as daemons and machine or hardware-related commands.

AUTHORS

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page to page.

Linux, 24 July 1993

adduser, addgroup

adduser, addgroup—Add a user or group to the system.

SYNOPSIS

adduser [--		system [--	home directory] [		--group]] [--quiet]
[	--force-badname] [--		help] [--	version] [--debug] username
adduser [--		quiet] [--	force-badname] [--		help] [--	version]
[--debug] username group
adduser [--		group] [--	quiet] [--	force-badname] [--		help]
[--	version] [--debug] group

DESCRIPTION

adduser and addgroup add users and groups to the system according to information provided in the configuration file /etc/ adduser.conf. adduser and addgroup automatically determine the UID or GID and place the entity in the password or group file as appropriate.

If necessary, adduser creates a home directory for the new user, copies “skeletal” user files to it from /etc/skel, and allows the system administrator to set an initial password and finger information for the user.

Because it needs to be able to write to such files as /etc/passwd, adduser can only be run as root.

Generally, there are two types of users and groups on a system: those users that log into the system and those “non-user” accounts and groups that exist for various system tasks and projects. Henceforth, user will refer to the login type and system user or group will refer to the type used for system maintenance and projects.

By default, each user in Debian GNU/Linux is given a corresponding group with the same name and ID, allowing people easily to give access to their home directories to others. This option can be turned off in the configuration file, in which case each user is, by default, added to a group called users.

Under Debian GNU/Linux, IDs less than or equal to 100 are allocated by the base system maintainer for various purposes. IDs from 101 to the value specified in the configuration file (1000, by default) are used for system users and groups. IDs greater than 1000 are reserved for users and their corresponding groups.

When invoked with a single name, adduser creates a user with that name. When given two names, adduser assumes that the first name represents an existing user and that the second name represents an existing group. In this case, the user is added to the group.

	agetty
		1259
OPTIONS
--system	Create a system user. This user will be assigned the shell /bin/false and have an
	asterisk in the password field. Unless otherwise specified, the user will be placed
	in the group nogroup. Skeletal configuration files will not be copied into the
	user’s home directory.
--home directory	When used with --system, this uses directory as the user’s home directory,
	rather than the default specified in the configuration file. If the directory does
	not exist, it is created.
--group	When combined with —system, a group with the same name and ID as the
	system user is created. If not combined with --system, a group with the given
	name is created. This is the default action if the program is invoked as addgroup.
--quiet	Suppress progress messages.
--force-badname	By default, user and group names are required to consist of a lowercase letter
	followed by one or more lowercase letters or numbers. This option forces
	adduser or addgroup to be more lenient.

--help --version --debug

Display brief instructions.

Display version and copyright information. Display a large quantity of debugging information.

SEE ALSO

adduser.conf(5)

COPYRIGHT

Copyright(c) 1995, Ted Hajek, with a great deal borrowed from the original Debian adduser, copyright(c) 1994, Ian Murdock. adduser is free software; see the GNU General Public License version two or later for copying conditions. There is no warranty.

Debian GNU/Linux version 1.94

agetty

agetty—Alternative Linux getty.

SYNOPSIS

agetty [-ihL] [-l login_program] [-m] [-t timeout] port baud_rate,... [term] agetty [-ihL] [-l login_program] [-m] [-t timeout] baud_rate,... port [term]

DESCRIPTION

agetty opens a tty port, prompts for a login name, and invokes the /bin/login command. It is usually invoked by init(8).

agetty has several non-standard features that are useful for hard-wired and for dial-in lines:

Adapts the tty settings to parity bits and to erase, kill, end-of-line, and uppercase characters when it reads a login name. The program can handle 7-bit characters with even, odd, none, or space parity and 8-bit characters with no parity. The following special characters are recognized: @ and Control+U (kill); #, Del and Backspace (erase); carriage return and line feed (end of line).

Optionally deduces the baud rate from the CONNECT messages produced by Hayes-compatible modems.

Optionally does not hang up when it is given an already opened line (useful for call-back applications).

Optionally does not display the contents of the /etc/issue file (System V only).

		Part VIII: Administration and Privileged Commands
	1260

Optionally invokes a non-standard login program instead of /bin/login.

Optionally turns on hardware flow control.

Optionally forces the line to be local with no need for carrier detect.

This program does not use the /etc/gettydefs (System V) or /etc/gettytab (SunOS 4) files.

ARGUMENTS

port	A path name relative to the /dev directory. If a – is specified, agetty
	assumes that its standard input is already connected to a tty port and that
	a connection to a remote user has already been established. Under System
	V, a – port argument should be preceded by a –.
baud rate,...	A comma-separated list of one or more baud rates. Each time agetty
	receives a break character, it advances through the list, which is treated as
	if it were circular. Baud rates should be specified in descending order, so
	that the null character (Ctrl+@) can also be used for baud rate switching.
term	The value to be used for the TERM environment variable. This overrides
	whatever init(8) may have set and is inherited by login and the shell.

OPTIONS

-h	Enable hardware (RTS/CTS) flow control. It is left up to the application
	to disable software (XON/XOFF) flow protocol where appropriate.
-i	Do not display the contents of /etc/issue before writing the login
	prompt. Terminals or communications hardware might become confused
	when receiving lots of text at the wrong baud rate; dial-up scripts might
	fail if the login prompt is preceded by too much text.
-l login_program	Invoke the specified login program instead of /bin/login. This allows
	the use of a non-standard login program (for example, one that asks for a
	dial-up password or that uses a different password file).
-m	Try to extract the baud rate the connect status message produced by some
	Hayes-compatible modems. These status messages are of the form:
	“<junk><speed><junk>”. agetty assumes that the modem emits its
	status message at the same speed as specified with (the first) baud rate
	value on the command line.
	Because the -m feature might fail on heavily loaded systems, you still
	should enable break processing by enumerating all expected baud rates on
	the command line.
-t timeout	Terminate if no username could be read within timeout seconds. This
	option should probably not be used with hard-wired lines.
-L	Force the line to be a local line with no need for carrier detect. This can
	be useful when you have a locally attached terminal where the serial line
	does not set the carrier detect signal.

EXAMPLES

This section shows sample entries for the /etc/inittab file.

For a hard-wired line:

tty1:con80x60:/sbin/agetty 9600 tty1

For a dial-in line with a 9600/2400/1200 baud modem:

ttyS1:dumb:/sbin/agetty -mt60 ttyS1 9600,2400,1200

agetty 1261

These examples assume you use the simpleinit(8) init program for Linux. If you use a SysV-like init (does /etc/inittab mention “respawn”?), refer to the appropriate manual page.

ISSUE ESCAPES

The /etc/issue file might contain certain escape codes to display the system name, date and time, and so on. All escape codes consist of a backslash (\) immediately followed by one of the following letters:

b	Insert the baudrate of the current line.
d	Insert the current date.
s	Insert the system name, the name of the operating system.
l	Insert the name of the current tty line.
m	Insert the architecture identifier of the machine, such as i486.
n	Insert the nodename of the machine, also known as the hostname.
o	Insert the domain name of the machine.
r	Insert the release number of the OS, such as 1.1.9.
t	Insert the current time.
u	Insert the number of current users logged in.
U	Insert the string 1 user or n users where n is the number of current users logged in.
v	Insert the version of the OS, such as the build date and so on.

For example, on my system, the following /etc/issue file

This is \n.\o (\s\m\r) \t

displays as

This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30

FILES

/var/run/utmp, the system status file

/etc/issue, printed before the login prompt (System V only)

/dev/console, problem reports (if syslog(3) is not used)

/etc/inittab (Linux simpleinit(8) configuration file)

BUGS

The baud-rate detection feature (the -m option) requires that agetty be scheduled soon call (within 30ms with modems that talk at 2400 baud). For robustness, always use the multiple baud rate command-line argument so that break processing is enabled.

enough after completion of a dial-in -m option in combination with a

The text in the /etc/issue file and the login prompt are always output with 7-bit characters and space parity.

The baud-rate detection feature (the -m option) requires that the modem emits its status message after raising the DCD line.

DIAGNOSTICS

Depending on how the program was configured, all diagnostics are written to the console device or reported via the syslog(3) facility. Error messages are produced if the port argument does not specify a terminal device, if there is no utmp entry for the current process (System V only), and so on.

AUTHORS

W.Z. Venema ([e-mail]) Eindhoven University of Technology, Department of Mathematics and Computer Science, Den Dolech 2, P.O. Box 513, 5600 MB Eindhoven, The Netherlands.

Peter Orbaek ([e-mail]), Linux port.

		Part VIII: Administration and Privileged Commands
	1262

CREATION DATE

Sat Nov 25 22:51:05 MET 1989

LAST MODIFICATION

91/09/01 23:22:00

VERSION/RELEASE

1.29

archive

archive—Usenet article archiver.

SYNOPSIS

archive [ -a archive ][-f ][-i index ][-m ][-r ][input ]

DESCRIPTION

archive makes copies of files specified on its standard input. It is usually run either as a channel feed under innd(8) or by a script before expire(8) is run.

archive reads the named input file or standard input if no file is given. The input is taken as a set of lines. Blank lines and lines starting with a number sign (#) are ignored. All other lines should specify the name of a file to archive. If a filename is not an absolute pathname, it is taken to be relative to /news/spool.

Files are copied to a directory within the archive directory, /news/spool/news.archive. The default is to create a hierarchy that mimics the input files; intermediate directories are created as needed. For example, the input file comp/sources/unix/ 2211 (article 2211 in the newsgroup comp.sources.unix) is copied to /news/spool/news.archive/comp/sources/unix/ 2211. If the –f flag is used, then all directory names are flattened out, replacing the slashes with periods. In this case, the file is copied to /news/spool/news.archive/comp.sources.unix/2211.

If the –i flag is used, then archive appends one line to the specified index file for each article that it copies. This line contains the destination name and the Message-ID and Subject headers.

For example, a typical newsfeeds(5) entry to archive most source newsgroups is as follows:

source-archive\ :!*,*sources*,!*wanted*,!*.d\ :Tc,Wn\

:/archive –f –i \ /usr/spool/news/news.archive/INDEX

Files are copied by making a link. If that fails, a new file is created. If the –m flag is used, then the file is copied to the destination, and the input file is replaced with a symbolic link pointing to the new file. The –m flag is ignored.

By default, archive sets its standard error to /var/log/news/errlog. To suppress this redirection, use the –r flag.

If the input is exhausted, archive exits with a zero status. If an I/O error occurs, it tries to spool its input, copying it to a file. If there was no input filename, the standard input is copied to /news/spool/out.going/archive and the program exits. If an input filename was given, a temporary file named input.bch (if input is an absolute pathname) or /news/spool/ out.going/input.bch (if the filename does not begin with a slash) is created. Once the input is copied, archive tries to rename this temporary file to be the name of the input file and then exits.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

arp 1263

SEE ALSO

newsfeeds(5)

arp

arp—Manipulate the system ARP cache.

SYNOPSIS

arp [-v] [-t type] -a [hostname] arp [-v] -d hostname ...

arp [-v] [-t type] -s hostname hw_addr arp [-v] -f filename

DESCRIPTION

arp manipulates the kernel’s ARP cache in various ways. The primary options are clearing an address mapping entry and manually setting up one. For debugging purposes, the arp program also allows a complete dump of the ARP cache.

OPTIONS

-v	Tell the user what is going on by being verbose.
-t type	When setting or reading the ARP cache, this optional parameter tells arp which class
	of entries it should check for. The default value of this parameter is ether (hardware
	code 0x01 for IEEE 802.3 10Mbps Ethernet). Other values might include network
	technologies such as ARCnet (arcnet), PROnet (pronet), and AX.25 (ax25).
-a [hostname]	Shows the entries of the specified hosts. If the hostname parameter is not used, all
	entries are displayed.

-d hostname

Remove the entries of the specified host. This can be used if the indicated host is brought down, for example.

-s hostname hw_addr	Manually create an ARP address mapping entry for host hostname with hardware
	address set to hw_addr. The format of the hardware address is dependent on the
	hardware class, but for most classes, you can assume that the usual presentation can
	be used. For the Ethernet class, this is six bytes in hexadecimal, separated by colons.
-f filename	Similar to the -s option, only this time the address info is taken from file filename.
	This can be used if ARP entries for a lot of hosts have to be set up. The name of the
	data file is often /etc/ethers, but this is not official.
	The format of the file is simple; it only contains ASCII text lines with a hostname
	and a hardware address separated by whitespace.

In all places where a hostname is expected, you can also enter an IP address in dotted-decimal notation.

FILES

/proc/net/arp

/etc/ethers

AUTHOR

Fred N. van Kempen ([e-mail])

09 June 1994

		Part VIII: Administration and Privileged Commands
	1264

badblocks

badblocks—Search a device for bad blocks.

SYNOPSIS

badblocks [ -b block-size ] [ -o output_file ] [ -v ][-w ] device blocks-count

DESCRIPTION

badblocks is used to search for bad blocks on a device (usually a disk partition). device is the special file corresponding to the device (such as /dev/hdXX). blocks-count is the number of blocks on the device.

OPTIONS

-b block-size	Specify the size of blocks in bytes.
-o output_file	Write the list of bad blocks to the specified file. Without this option, badblocks
	displays the list on its standard output.
-v	Verbose mode.
-w	Use write-mode test. With this option, badblocks scans for bad blocks by writing
	some patterns (0xaa, 0x55, 0xff, and 0x00) on every block of the device, reading
	every block and comparing the contents.

WARNING

Never use the -w option on a device containing an existing filesystem. This option erases data!

AUTHOR

badblocks was written by Remy Card ([e-mail]), the developer and maintainer of the ext2 fs.

BUGS

I had no chance to make real tests of this program because I use IDE drives, which remap bad blocks. I only made some tests on floppies.

AVAILABILITY

badblocks is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs.

SEE ALSO

e2fsck(8), mke2fs(8)

Version 0.5b, November 1994

buffchan

buffchan—Buffered file-writing back end for InterNetNews.

SYNOPSIS

buffchan [ -b ][-c lines ][-C seconds ][-d directory ] [-f fields ][-m map ][-p pidfile ][-l lines ][-L seconds ] [-r ][-s file_format ][-u ]

DESCRIPTION

buffchan reads lines from standard input and copies certain fields in each line into files named by other fields within the line. buffchan is intended to be called by innd(8) as an exploder feed.

cfdisk 1265

buffchan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace. The default number of initial fields is one; the –f flag may be used to specify a different number of fields. See filechan(8) for an example.

After the initial fields, each remaining field names a file to write. The -s flag may be used to specify a format string that maps the field to a filename. This is a sprintf(3) format string, which should have a single %s parameter that is given the field. The default value is /news/spool/out.going/%s. See the description of this flag in filechan(8). The –d flag may be used to specify a directory the program should change to before starting. If this flag is used, then the default for the –s flag is changed to be a simple %s.

Once buffchan opens a file, it keeps it open. The input must therefore never specify more files than the number of available descriptors can keep open. If the –b flag is used, the program will allocate a buffer and attach it to the file using setbuf(3). If the –u flag is used, the program will request unbuffered output.

If the –l flag is used with a number n, then buffchan will call fflush(3) after every n lines are written to a file. If the –c flag is used with a number n, then buffchan will close, and reopen, a file after every n lines are written to a file.

If the –L flag is used with a number n, then all files will be flushed every n seconds. Similarly, the –C flag may be used to specify that all files should be closed and reopened every n seconds.

By default, the program sets its standard error to /var/log/news/errlog. To suppress this redirection, use the –r flag.

If the –p flag is used, the program will write a line containing its process ID (in text) to the specified file.

buffchan can be invoked as an exploder feed (see newsfeeds(5)). As such, if a line starts with an exclamation point, it is treated as a command. There are three commands:

flush	The flush command closes and reopens all open files; flush xxx flushes only the
	specified site. These are analogous to the ctlinnd(8) flush command and can be
	achieved by doing a send flush xxx command. Applications can tell that the flush
	has completed by renaming the file before issuing the command; buffchan has
	completed the command when the original filename reappears.
	buffchan also changes the access permissions of the file from read-only for everyone
	to read-write for owner and group as it flushes or closes each output file. It changes
	the modes back to read-only if it reopens the same file.
drop	The drop command is similar to the flush command except that any files are not
	reopened. If given an argument, then the specified site is dropped; otherwise, all sites
	are dropped. (Note that the site will be restarted if the input stream mentions the
	site.) When a ctlinnd “drop site” command is sent, innd will automatically forward
	the command to buffchan if the site is a funnel that feeds into this exploder. To
	drop all sites, use the ctlinnd send buffchan-site drop command.
readmap	The map file (specified with the –m flag) is reloaded.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

ctlinnd(8), filechan(8), innd(8), newsfeeds(5).

cfdisk

cfdisk—Curses-based disk partition table manipulator for Linux.

SYNOPSIS

cfdisk [ -avz ] [ -c cylinders ][-h heads ][-s sectors-per-track ][-P opt ] [device ]

		Part VIII: Administration and Privileged Commands
	1266

DESCRIPTION

cfdisk is a curses-based program for partitioning a hard disk drive. The device can be any one of the following:

/dev/hda [default] /dev/hdb

/dev/sda

/dev/sdb

/dev/sdc

/dev/sdd

cfdisk first tries to read the geometry of the hard disk. If it fails, an error message is displayed and cfdisk exits. This should only happen when partitioning a SCSI drive on an adapter without a BIOS. To correct this problem, you can set the cylinders, heads, and sectors-per-track on the command line. Next, cfdisk tries to read the current partition table from the disk drive. If it is unable to figure out the partition table, an error is displayed and the program exits. This might also be caused by incorrect geometry information and can be overridden on the command line. Another way around this problem is with the -z option. This will ignore the partition table on the disk.

The main display is composed of four sections, from top to bottom: the header, the partitions, the command line, and a warning line. The header contains the program name and version number followed by the disk drive and its geometry. The partitions section always displays the current partition table. The command line is the place where commands and text are entered. The available commands are usually displayed in brackets. The warning line is usually empty except when there is important information to be displayed. The current partition is highlighted with reverse video (or an arrow if the -a option is given). All partition-specific commands apply to the current partition.

The format of the partition table in the partition’s section is, from left to right: Name, Flags, Partition Type, Filesystem Type, and Size. The name is the partition device name. The flags can be Boot, which designates a bootable partition or NC, which stands for “Not Compatible with DOS or OS/2.” DOS, OS/2, and possibly other operating systems require the first sector of the first partition on the disk and all logical partitions to begin on the second head. This wastes the second through the last sector of the first track of the first head (the first sector is taken by the partition table itself). cfdisk allows you to recover these “lost” sectors with the maximize command (m). Note that fdisk(8) and some early versions of DOS create all partitions with the number of sectors already maximized. For more information, see the maximize command later in this chapter. The partition type can be Primary or Logical. For unallocated space on the drive, the partition type can also be Pri/Log or empty (if the space is unusable). The filesystem type section displays the name of the filesystem used on the partition, if known. If it is unknown, then Unknown and the hex value of the filesystem type are displayed. A special case occurs when there are sections of the disk drive that cannot be used (because all the primary partitions are used). When this is detected, the filesystem type is displayed as Unusable. The size field displays the size of the partition in megabytes (by default). It can also display the size in sectors and cylinders (see the change units command later in this chapter). If an asterisks (*) appears after the size, this means that the partition is not aligned on cylinder boundaries.

DOS 6.X WARNING

The DOS 6.x FORMAT command looks for some information in the first sector of the data area of the partition and treats this information as more reliable than the information in the partition table. DOS FORMAT expects DOS FDISK to clear the first 512 bytes of the data area of a partition whenever a size change occurs. DOS FORMAT looks at this extra information even if the /U flag is given; we consider this a bug in DOS FORMAT and DOS FDISK.

The bottom line is that if you use cfdisk or fdisk to change the size of a DOS partition table entry and then you must also use dd to zero the first 512 bytes of that partition before using DOS FORMAT to format the partition. For example, if you were using cfdisk to make a DOS partition table entry for /dev/hda1, then (after exiting fdisk or cfdisk and rebooting Linux so that the partition table information is valid), you use the command dd if=/dev/zero of=/dev/hda1 bs=512 count=1 to zero the first 512 bytes of the partition.

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless.

For best results, you should always use an OS-specific partition table program. For example, you should make DOS partitions with the DOS FDISK program and Linux partitions with the Linux fdisk or Linux cfdisk program.

cfdisk 1267

COMMANDS

cfdisk commands can be entered by pressing the desired key (pressing Enter after the command is not necessary). Here is a list of the available commands:

b	Toggle bootable flag of the current partition. This allows you to select which primary partition is
	bootable on the drive.
d	Delete the current partition. This will convert the current partition into free space and merge it
	with any free space immediately surrounding the current partition. A partition already marked as
	free space or marked as unusable cannot be deleted.
g	Change the disk geometry (cylinders, heads, or sectors-per-track). Warning: This option should
	only be used by people who know what they are doing. A command-line option is also available to
	change the disk geometry. While at the change disk geometry command line, you can choose to
	change cylinders (d), heads (h), and sectors per track (s). The default value will be printed at the
	prompt, which you can accept by simply pressing the Enter key or you can exit without changes by
	pressing the Esc key. If you want to change the default value, simply enter the desired value and
	press Enter. The altered disk parameter values do not take effect until you return to the main menu
	(by pressing Enter or Esc at the change disk geometry command line. If you change the geometry
	such that the disk appears larger, the extra sectors are added at the end of the disk as free space. If
	the disk appears smaller, the partitions that are beyond the new last sector are deleted and the last
	partition on the drive (or the free space at the end of the drive) is made to end at the new last
	sector.
h	Print the help screen.
m	Maximize disk usage of the current partition. This command will recover the the unused space
	between the partition table and the beginning of the partition, at the cost of making the partition
	incompatible with DOS, OS/2, and possibly other operating systems. This option will toggle
	between maximal disk usage and DOS, OS/2, and so on compatible disk usage. The default when
	creating a partition is to create DOS, OS/2, and so on compatible partitions.
n	Create new partitions from free space. If the partition type is Primary or Logical, a partition of
	that type will be created, but if the partition type is Pri/Log, you will be prompted for the type you
	want to create. Be aware that there are only four slots available for primary partitions and because
	there can be only one extended partition that contains all of the logical drives, all of the logical
	drives must be contiguous (with no intervening primary partition). cfdisk next prompts you for
	the size of the partition you want to create. The default size, equal to the entire free space of the
	current partition, is displayed in megabytes. You can either press the Enter key to accept the default
	size or enter a different size at the prompt. cfdisk accepts size entries in megabytes (M) (default),
	kilobytes (K), cylinders (d), and sectors (S) when you enter the number immediately followed by M,
	K, C, or S. If the partition fills the free space available, the partition is created and you are returned
	to the main command line. Otherwise, the partition can be created at the beginning or the end of
	the free space, and cfdisk will ask you to choose where to place the partition. After the partition is
	created, cfdisk automatically adjusts the other partition’s partition types if all of the primary
	partitions are used.
p	Print the partition table to the screen or to a file. There are several different formats for the
	partition that you can choose from:
r	Raw data format (exactly what would be written to disk).
s	Partition table in sector order format.
t	Partition table in raw format. The raw data format will print the sectors that would be written to
	disk if a write command is selected. First, the primary partition table is printed, followed by the
	partition tables associated with each logical partition. The data is printed in hex byte-by-byte with
	16 bytes per line. The partition table in sector order format will print the partition table ordered by
	sector number. The fields, from left to right, are the number of the partition, the partition type, the
	first sector, the last sector, the offset from the first sector of the partition to the start of the data, the

		Part VIII: Administration and Privileged Commands
	1268
		length of the partition, the filesystem type (with the hex value in parentheses), and the flags (with
		the hex value in parentheses). In addition to the primary and logical partitions, free and unusable
		space is printed and the extended partition is printed before the first logical partition.
		If a partition does not start or end on a cylinder boundary or if the partition length is not divisible
		by the cylinder size, an asterisk (*) is printed after the non-aligned sector number/count. This
		usually indicates that a partition was created by an operating system that either does not align
		partitions to cylinder boundaries or that used different disk geometry information. If you know the
		disk geometry of the other operating system, you can enter the geometry information with the
		change geometry command (g).
		For the first partition on the disk and for all logical partitions, if the offset from the beginning of
		the partition is not equal to the number of sectors per track (that is, the data does not start on the
		first head), a number sign (#) is printed after the offset. For the remaining partitions, if the offset is
		not zero, a number sign is printed after the offset. This corresponds to the NC flag in the partitions
		section of the main display.
		The partition table in raw format will print the partition table ordered by partition number. It will
		leave out all free and unusable space. The fields, from left to right, are the number of the partition,
		the flags (in hex), the starting head, sector, and cylinder, the filesystem ID (in hex), the ending
		head, sector, and cylinder, the starting sector in the partition, and the number of sectors in the
		partition. The information in this table can be directly translated to the raw data format. The
		partition table entries only have 10 bits available to represent the starting and ending cylinders.
		Thus, when the absolute starting (ending) sector number is on a cylinder greater than 1023, the
		maximal values for starting (ending) head, sector, and cylinder are printed. This is the method used
		by OS/2, and it fixes the problems associated with OS/2’s fdisk rewriting the partition table when
		it is not in this format. Because Linux and OS/2 use absolute sector counts, the values in the
		starting and ending head, sector, and cylinder are not used.

q	Quit program. This will exit the program without writing any data to disk.
t	Change the filesystem type. By default, new partitions are created as Linux partitions, but because
	cfdisk can create partitions for other operating systems, changing the partition type allows you to
	enter the hex value of the filesystem you desire. A list of the known filesystem types is displayed.
	You can type the filesystem type at the prompt or accept the default filesystem type (Linux).
u	Change units of the partition size display. It will rotate through megabytes, sectors, and cylinders.
W	Write partition table to disk (you must enter an uppercase W). Because this might destroy data on
	the disk, you must either confirm or deny the write by entering yes or no. If you enter yes, cfdisk
	will write the partition table to disk and the tell the kernel to re-read the partition table from the
	disk. The re-reading of the partition table works in most cases, but I have seen it fail. Don’t panic.
	It will be correct after you reboot the system. In all cases, I still recommend rebooting the system
	just to be safe.
Up arrow, Down arrow	Move cursor to the previous or next partition. If there are more partitions than can be displayed on
	a screen, you can display the next (previous) set of partitions by moving down (up) at the last (first)
	partition displayed on the screen.
Ctrl+L	Redraws the screen. In case something goes wrong and you cannot read anything, you can refresh
	the screen from the main command line.
?	Print the help screen.

All the commands can be entered with either uppercase or lowercase letters (except for writes). When in a submenu or at a prompt to enter a filename, you can hit the Esc key to return to the main command line.

OPTIONS

-a	Use an arrow cursor instead of reverse video for highlighting the current partition.
-v	Print the version number and copyright.

	chat
		1269
-z	Start with zeroed partition table. This option is useful when you want to repartition
	your entire disk. Note that this option does not zero the partition table on the disk;
	rather, it simply starts the program without reading the existing partition table.

-c cylinders

-h heads

-s sectors-per-track

Override the number of cylinders, heads, and sectors-per-track read from the BIOS. If your BIOS or adapter does not supply this information or if it supplies incorrect information, use these options to set the disk geometry values.

-P opt	Prints the partition table in specified formats. opt can be one or more of r, s, or t. See
	the print command for more information on the print formats.

SEE ALSO

fdisk(8)

BUGS

The current version does not support multiple disks (future addition).

AUTHOR

Kevin E. Martin ([e-mail])

The BOGUS Linux Release, 3 June 1995

chat

chat—Automated conversational script with a modem.

SYNOPSIS

chat [ options ] script

DESCRIPTION

The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point protocol daemon (pppd) and the remote’s pppd process.

OPTIONS

-f <chat file>

Read the chat script from the chat file. The use of this option is mutually exclusive with the chat script parameters. The user must have read access to the file. Multiple lines are permitted in the file. Space or horizontal tab characters should be used to separate the strings.

-t <timeout>

Set the time-out for the expected string to be received. If the string is not received within the time limit, then the reply string is not sent. An alternate reply may be sent or the script will fail if there is no alternate reply string. A failed script will cause the chat program to terminate with a nonzero error code.

-r <report file>	Set the file for output of the report strings. If you use the keyword REPORT, the resulting
	strings are written to this file. If this option is not used and you still use REPORT
	keywords, the stderr file is used for the report strings.
-v	Request that the chat script be executed in a verbose mode. The chat program will then
	log all text received from the modem and the output strings that it sends to the SYSLOG.

1270

-V

Part VIII: Administration and Privileged Commands

Request that the chat script be executed in a stderr verbose mode. The chat program will then log all text received from the modem and the output strings that it sends to the stderr device. This device is usually the local console at the station running the chat or pppd program. This option does not work properly if the stderr is redirected to the / dev/null location because in that case pppd should run in the detached mode. In that case, use the -v option to record the session on the SYSLOG device.

script	If the script is not specified in a file with the -f option, then the script is included as
	parameters to the chat program.

CHAT SCRIPT

The chat script defines the communications.

A script consists of one or more “expect-send” pairs of strings, separated by spaces, with an optional “subexpect-subsend” string pair, separated by a dash as in the following example:

ogin:-BREAK-ogin: ppp ssword: hello2u2

This line indicates that the chat program should expect the string ogin:. If it fails to receive a login prompt within the time interval allotted, it is to send a break sequence to the remote and then expect the string ogin:. If the first ogin: is received, then the break sequence is not generated.

Once it receives the login prompt, the chat program will send the string ppp and then expect the prompt ssword:. When it receives the prompt for the password, it will send the password hello2u2.

A carriage return is usually sent following the reply string. It is not expected in the “expect” string unless it is specifically requested by using the nr character sequence.

The expect sequence should contain only what is needed to identify the string. Because it is usually stored on a disk file, it should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, or other variable pieces of data such as an expect string.

To help correct for characters that may be corrupted during the initial sequence, look for the string ogin: rather than login:. It is possible that the leading l character might be received in error and you might never find the string even though it was sent by the system. For this reason, scripts look for ogin: rather than login: and ssword: rather than password:.

A very simple script might look like this:

ogin: ppp ssword: hello2u2

In other words, expect ....

ogin:, send ppp, expect

...ssword:, send hello2u2.

In actual practice, simple scripts are rare. At the vary least, you should include subexpect sequences in case the original string is not received. For example, consider the following script:

ogin:–ogin: ppp ssword: hello2u2

This is a better script than the simple one used earlier. This looks for the same login: prompt; however, if one was not received, a single return sequence is sent and then it will look for login: again. Should line noise obscure the first login prompt then sending the empty line will usually generate a login prompt again.

ABORT STRINGS

Many modems will report the status of the call as a string. These strings may be CONNECTED or NO CARRIER or BUSY. It is often desirable to terminate the script if the modem fails to connect to the remote. The difficulty is that a script does not know exactly which modem string it might receive. On one attempt, it might receive BUSY, but the next time, it might receive NO CARRIER.

These “abort” strings can be specified in the script using the ABORT sequence. It is written in the script as in the following example:

ABORT BUSY ABORT ‘NO CARRIER’ “ ATZ OK ATDT5551212 CONNECT

chat 1271

This sequence will expect nothing and then send the string ATZ. The expected response to this is the string OK. When it receives OK, the string ATDT5551212 dials the telephone. The expected string is CONNECT. If the string CONNECT is received, the remainder of the script is executed. However, if the modem finds a busy telephone, it sends the string BUSY. This causes the string to match the abort character sequence. The script then fails because it found a match to the abort string. If it received the string NO CARRIER, it aborts for the same reason. Either string may be received. Either string will terminate the chat script.

REPORT STRINGS

A report string is similar to the ABORT string. The difference is that the strings and all characters to the next control character such as a carriage return, are written to the report file.

The report strings may be used to isolate the transmission rate of the modem’s connect string and return the value to the chat user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the expect string. The use of the same string for a report and abort sequence is probably not very useful; however, it is possible.

The report strings do not change the completion code of the program.

These “report” strings may be specified in the script using the REPORT sequence. It is written in the script as in the following example:

REPORT CONNECT ABORT BUSY “ ATDT5551212 CONNECT “ ogin: account

This sequence expects nothing and then sends the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received, the remainder of the script is executed. In addition, the program writes to the expect-file the string CONNECT plus any characters that follow it such as the connection rate.

TIME-OUT

The initial time-out value is 45 seconds. This may be changed using the -t parameter.

To change the time-out value for the next expect string, the following example may be used:

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:–ogin: TIMEOUT 5 password:: hello2u2

This changes the time-out to 10 seconds when it expects the login: prompt. The time-out is then changed to 5 seconds when it looks for the password prompt.

The time-out, once changed, remains in effect until it is changed again.

SENDING EOT

The special reply string of EOT indicates that the chat program should send an EOT character to the remote. This is usually the End-of-file character sequence. A return character is not sent following the EOT. The EOT sequence may be embedded into the send string using the sequence ^D.

GENERATING BREAK

The special reply string of BREAK causes a break condition to be sent. The break is a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. It may be used to cycle through the available transmission rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded into the send string using the \K sequence.

ESCAPE SEQUENCES

The expect and reply strings may contain escape sequences. All the sequences are legal in the reply string. Many are legal in the expect. Those that are not valid in the expect sequence are so indicated.

‘’	Expects or sends a null string. If you send a null string, it will still send the return
	character. This sequence may either be a pair of apostrophe or quote characters.
\\b	Represents a backspace character.

		Part VIII: Administration and Privileged Commands
	1272

\\c	Suppresses the newline at the end of the reply string. This is the only method to send a
	string without a trailing return character. It must be at the end of the send string. For
	example, the sequence hello\c will simply send the characters h, e, l, l, o. (Not valid in
	expect.)
\\d	Delay for one second. The program uses sleep(1), which will delay to a maximum of
	one second. (Not valid in expect.)
\\K	Insert a BREAK. (Not valid in expect.)
\\n	Send a newline or linefeed character.
\\N	Send a null character. The same sequence may be represented by \0. (Not valid in
	expect.)
\\p	Pause for a fraction of a second. The delay is one tenth of a second. (Not valid in
	expect.)
\\q	Suppress writing the string to the SYSLOG file. The string ?????? is written to the log in
	its place. (Not valid in expect.)
\\r	Send or expect a carriage return.
\\s	Represents a space character in the string. This may be used when it is not desirable to
	quote the strings that contains spaces. The sequence HI TIM and HI\sTIM are the same.
\\t	Send or expect a tab character.
\\\\	Send or expect a backslash character.
\\ddd	Collapse the octal digits (ddd) into a single ASCII character and send that character.
	(Some characters are not valid in expect.)
^C	Substitute the sequence with the control character represented by C. For example, the
	character DC1 (17) is shown as ˆQ. (Some characters are not valid in expect.)
TERMINATION CODES

The chat program will terminate with the following completion codes:

0	The normal termination of the program. This indicates that the script was executed
	without error to the normal conclusion.
1	One or more of the parameters are invalid or an expect string was too large for the
	internal buffers. This indicates that the program as not properly executed.
2	An error occurred during the execution of the program. This may be due to a read or
	write operation failing for some reason or chat receiving a signal such as SIGINT.
3	A time-out event occurred when there was an expect string without having a -subsend
	string. This may mean that you did not program the script correctly for the condition or
	that some unexpected event occurred and the expected string could not be found.
4	The first string marked as an ABORT condition occurred.
5	The second string marked as an ABORT condition occurred.
6	The third string marked as an ABORT condition occurred.
7	The fourth string marked as an ABORT condition occurred.
...	The other termination codes are also strings marked as an ABORT condition.

Using the termination code, it is possible to determine which event terminated the script. It is possible to decide if the string BUSY was received from the modem as opposed to NO DIAL TONE. Although the first event may be retried, the second will probably have little chance of succeeding during a retry.

SEE ALSO

Additional information about chat scripts may be found with UUCP documentation. The chat script was taken from the ideas proposed by the scripts used by the uucico program.

uucico(1), uucp(1)

clock 1273

COPYRIGHT

The chat program is in public domain. This is not the GNU public license. If it breaks, then you get to keep both pieces.

Chat Version 1.9, 5 May 1995

chroot

chroot—Change root directory and execute a program there.

SYNOPSIS

chroot directory program [ arg ... ]

DESCRIPTION

chroot changes the root directory for a process to a new directory executes a program there.

SEE ALSO

chroot(2)

AUTHOR

Rick Sladkey ([e-mail])

Linux 0.99, 20 November 1993

clock

clock—Manipulate the CMOS clock.

SYNOPSIS

/sbin/clock [ -u ] -r /sbin/clock [ -u ] -w /sbin/clock [ -u ] -s /sbin/clock [ -u ] -a

DESCRIPTION

clock manipulates the CMOS clock in various ways, allowing it to be read or written and allowing synchronization between the CMOS clock and the kernel’s version of the system time.

OPTIONS

-u	Indicates that the CMOS clock is set to Universal Time.
-r	Read CMOS clock and print the result to stdout.
-w	Write the system time into the CMOS clock.
-s	Set the system time from the CMOS clock.
-a	Set the system time from the CMOS clock, adjusting the time to correct for systematic
	error and writing it back into the CMOS clock. This option uses the file /etc/adjtime
	to determine how the clock changes. It contains three numbers.
	The first number is the correction in seconds per day. (For example, if your clock runs 5
	seconds fast each day, the first number should read -5.0.)
	The second number tells when clock was last used in seconds since 1/1/1970.
	The third number is the remaining part of a second that was leftover after the last
	adjustment.

		Part VIII: Administration and Privileged Commands
	1274

The following instructions are from the source code:

1.Create a file /etc/adjtime containing as the first and only line 0.0 0 0.0.

2.Run clock -au or clock -a, depending on whether your CMOS is in Universal or Local Time. This updates the second number.

3.Set your system time using the date command.

4.Update your CMOS time using clock -wu or clock -w.

5.Replace the first number in /etc/adjtime by your correction.

6.Put the command clock -au or clock -a in your /etc/rc.local or let cron(8) start it regularly.

FILES

/etc/adjtime

/etc/rc.local

AUTHORS

V1.0	Charles Hedrick ([e-mail]) Apr 1992
V1.1	Modified for clock adjustments, Rob Hooft ([e-mail]) Nov 1992
V1.2	Patches by Harald Koenig ([e-mail]) applied by
	Rob Hooft ([e-mail]) Oct 1993

Linux 0.99, 24 December 1992

comsat

comsat—Biff server

SYNOPSIS

comsat

DESCRIPTION

comsat is the server process that receives reports of incoming mail and notifies users if they requested this service. comsat receives messages on a datagram port associated with the biff service specification (see services(5) and inetd(8)). The oneline messages are of the form

user@mailbox-offset

If the user specified is logged in to the system and the associated terminal has the owner execute bit turned on (by a biff y), the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or 560 characters of the message are printed on the user’s terminal. Lines that appear to be part of the message header other than the From, To, Date, or Subject lines are not included in the displayed message.

FILES

/var/run/utmp to find out who’s logged on and on what terminals

SEE ALSO

biff(1), inetd(8)

BUGS

The message header filtering is prone to error. The density of the information presented is near the theoretical minimum.

Users should be notified of mail that arrives on other machines than the one to which they are currently logged in.

The notification should appear in a separate window so it does not mess up the screen.

crond 1275

HISTORY

The command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

crond

crond—cron daemon (Dillon’s Cron).

SYNOPSIS

crond [-l#] [-d[#]] [-f] [-b] [-c directory]

OPTIONS

crond is a background daemon that parses individual crontab files and executes commands on behalf of the users in question.

-lloglevel	Set logging level; default is 8.
-d[debuglevel]	Set debugging level; default is 0. If no level is specified with the -d option, the default is
	1. This option also sets the logging level to 0 and causes crond to run in the foreground.
-f	Run crond in the foreground.
-b	Run crond in the background (the default unless -d is specified).
-c directory	Specify directory containing crontab files.

DESCRIPTION

crond is responsible for scanning the crontab files and running their commands at the appropriate time. The crontab program communicates with crond through the cron.update file, which resides in the crontabs directory, usually /var/ spool/cron/crontabs. This is accomplished by appending the filename of the modified or deleted crontab file to cron.update, which crond then picks up to resynchronize or remove its internal representation of the file.

crond has a number of built-in limitations to reduce the chance of it being ill-used. Potentially infinite loops during parsing are dealt with via a failsafe counter, and user crontabs are generally limited to 256 crontab entries. crontab lines may not be longer than 1024 characters, including the newline.

Whenever crond must run a job, it first creates a daemon-owned temporary file O_EXCL and O_APPEND to store any output, and then it fork()s and changes its user and group permissions to match that of the user the job is being run for. Then, it executes /bin/sh -c to run the job. The temporary file remains under the ownership of the daemon to prevent the user from tampering with it. Upon job completion, crond verifies the secureness of the mail file and, if it has been appended to, mails to the file to user. The sendmail program is run under the user’s UID to prevent mail-related security holes. Unlike crontab, the crond program does not leave an open descriptor to the file for the duration of the job’s execution because this might cause crond to run out of descriptors. When the crontab program allows a user to edit his crontab, it copies the crontab to a user-owned file before running the user’s preferred editor. The suid crontab program keeps an open descriptor to the file, which it later uses to copy the file back, thereby ensuring the user has not tampered with the file type.

crond always synchronizes to the top of the minute, checking the current time against the list of possible jobs. The list is stored such that the scan goes very quickly, and crond can deal with several thousand entries without taking any noticeable amount of CPU.

AUTHOR

Matthew Dillon ([e-mail])

1 May 1994

		Part VIII: Administration and Privileged Commands
	1276

ctlinnd

ctlinnd—Control the InterNetNews daemon.

SYNOPSIS

ctlinnd [ -h ][-s ][-t timeout ] command [ argument... ]

DESCRIPTION

ctlinnd sends a message to the control channel of innd(8), the InterNetNews server.

In the normal mode of behavior, the message is sent to the server, which then performs the requested action and sends back a reply with a text message and the exit code for ctlinnd. If the server successfully performed the command, ctlinnd will exit with a status of zero and print the reply on standard output. If the server could not perform the command (for example, it was told to remove a newsgroup that does not exist), it will direct ctlinnd to exit with a status of one. The shutdown, xabort, and xexec commands do not generate a reply; ctlinnd will always exit silently with a status of zero. If the –s flag is used, then no message will be printed if the command was successful.

The –t flag can be used to specify how long to wait for the reply from the server. The timeout value specifies the number of seconds to wait. A value of zero waits forever, and a value less than zero indicates that no reply is needed. When waiting for a reply, ctlinnd will try every two minutes to see if the server is still running, so it is unlikely that –t0 will hang. The default is –t0.

To see a command summary, use the –h flag. If a command is included when ctlinnd is invoked with the –h flag, then only the usage for that command will be given.

If a large number of groups are going to be created or deleted at once, it may be more efficient to pause or throttle the server and edit the active file directly.

The complete list of commands follows. Note that all commands have a fixed number of arguments. If a parameter can be an empty string, then it is necessary to specify it as two adjacent quotes (“”).

addhistMessage-IDarr exp post paths	Add an entry to the history database. This directs the server to create a
	history line for Message-ID. The angle brackets are optional. arr, exp, and
	post specify when the article arrived, what its expiration date is, and when it
	was posted. All three values are a number indicating the number of seconds
	since the epoch. If the article does not have an Expires header, then exp
	should be zero. paths is the pathname within the newsspool directory where
	the article is filed. If the article is cross-posted, then the names should be
	separated by whitespace and the paths argument should be inside double
	quotes. If the server is paused or throttled, this command causes it to briefly
	open the history database.
allow reason	Remote connections are allowed. The reason must be the same text given
	with an earlier reject command or an empty string.
begin site	Begin feeding site. This will cause the server to rescan the newsfeeds(5) file
	to find the specified site and set up a newsfeed for it. If the site already exists,
	a “drop” is done first. This command is forwarded; see below.

cancel <Message-ID>

Remove the article with the specified Message-ID from the local system. This does not generate a cancel message. The angle brackets are optional. If the server is paused or throttled, this command causes it to briefly open the history database.

changegroup group rest

The newsgroup group is changed so that its fourth field in the active file becomes the value specified by the rest parameter. This may be used to make an existing group moderated or unmoderated, for example.

checkfile	Check the syntax of the newsfeeds file, and display a message if any errors are
	found. The details of the errors are reported to syslog(3).

		ctlinnd
				1277
drop site		Flush and drop site from the server’s list of active feeds. This command is
		forwarded; see below.
flush site		Flush the buffer for the specified site. The actions taken depend on the type
		of feed the site receives; see newsfeeds(5). This is useful when the site is fed
		by a file and batching is going to start. If site is an empty string, then all sites
		are flushed and the active file and history databases are also written out. This
		command is forwarded; see below.
flushlogs		Close the log and error log files and rename them to have a .old extension.
		The history database and active file are also written out.
go reason		Reopen the history database and start accepting articles after a pause or
		throttle command. The reason must either be an empty string or match the
		text that was given in the earlier pause or throttle command. If a reject
		command was done, this will also do an allow command if the reason
		matches the text that was given in the reject. If a reserve command was done,
		this will also clear the reservation if the reason matches the text that was given
		in the reserve. Note that if only the history database has changed while the
		server is paused or throttled, it is not necessary to send it a reload command
		before sending it a go command. If the server throttled itself because it
		accumulated too many I/O errors, this command will reset the error count. If
		the server was not started with the –ny flag, then this command also does a
		readers command with yes as the flag and reason as the text.
hangup channel		Close the socket on the specified incoming channel. This is useful when an
		incoming connection appears to be hung.
help [command]		Print a command summary for all commands, or just command if specified.
mode		Print the server’s operating mode as a multiline summary of the parameters
		and operating state.
name nnn		Print the name of channel number nnn or of all channels if it is an empty
		string.
newgroup group rest creator		Create the specified newsgroup. The rest parameter should be the fourth
		field as described in active(5); if it is not an equal sign, only the first letter is
		used. The creator should be the name of the person creating the group. If the
		newsgroup already exists, this is equivalent to the changegroup command.
		This is the only command that has defaults. The creator can be omitted and
		will default to the empty string, and the rest parameter can be omitted and
		will default to y. This command can be done while the server is paused or
		throttled; it will update its internal state when a go command is sent. This
		command updates the active.times (see active(5)) file.
param letter	value	Change the command-line parameters of the server. The combination of
		defaults makes it possible to use the text of the Control header directly.
		letter is the innd command-line option to set, and value is the new value.
		For example, i 5 directs the server to allow only five incoming connections.
		To enable or disable the action of the –n flag, use the letter y or n for the
		value.
pause reason		Pause the server so that no incoming articles are accepted. No existing
		connections are closed, but the history database is closed. This command
		should be used for short-term locks, such as when replacing the history files.
		If the server was not started with the –ny flag, then this command also does a
		readers command with no as the flag and reason as the text.
readers flag	text	Allow or disallow newsreaders. If flag starts with the letter n, then
		newsreading is disallowed by causing the server to pass the text as the value of
		the nnrpd(8) –r flag. If flag starts with the letter y and text is either an empty

		Part VIII: Administration and Privileged Commands
	1278
		string, or the same string that was used when newsreading was disallowed,
		then newsreading will be allowed.

reject reason	Remote connections (those that would not be handed off to nnrpd) are
	rejected, with reason given as the explanation.
reload what reason	The server updates its in-memory copies of various configuration files. what
	identifies what should be reloaded. If it is an empty string or the word all,
	then everything is reloaded; if it is the word history, then the history
	database is closed and opened; if it is the word hosts.nntp, then the
	hosts.nntp(5) file is reloaded; if it is the word active or newsfeeds, then
	both the active and newsfeeds files are reloaded; if it is the word
	overview.fmt, then the overview.fmt(5) file is reloaded. The reason is
	reported to syslog. There is no way to reload the data inn.conf(5) file; the
	server currently only uses the pathhost parameter, so this restriction should
	not be a problem.

renumber group

Scan the spool directory for the specified newsgroup and update the lowwater mark in the active file. If group is an empty string, then all newsgroups are scanned.

reserve reason	The next pause or throttle command must use reason as its text. This
	reservation is cleared by giving an empty string for the reason. This
	command is used by programs such as expire(8) that want to avoid running
	into other instances of each other.
rmgroup group	Remove the specified newsgroup. This is done by editing the active file. The
	spool directory is not touched, and any articles in the group will be expired
	using the default expiration parameters. Unlike the newgroup command, this
	command does not update the active.times file.
send feed text...	The specified text is sent as a control line to the exploder feed.
shutdown reason	The server is shut down, with the specified reason recorded in the log and
	sent to all open connections. It is a good idea to send a throttle command
	first.
signal sig site	Signal sig is sent to the specified site, which must be a channel or exploder
	feed. sig can be a numeric signal number or the word hup, int, or term; case
	is not significant.
throttle reason	Input is throttled so that all existing connections are closed and new
	connections are rejected. The history database is closed. This should be used
	for long-term locks, such as when expire is being run. If the server was not
	started with the –ny flag, then this command also does a readers command
	with no as the flag and reason as the text.
trace item flag	Tracing is turned on or off for the specified item. flag should start with the
	letter y or n to turn tracing on or off. If item starts as a number, then tracing
	is set for the specified innd channel, which must be for an incoming NNTP
	feed. If it starts with the letter I, then general innd tracing is turned on or off.
	If it starts with the letter n, then future nnrpd’s will or will not have the –t
	flag enabled, as appropriate.
xabort reason	The server logs the specified reason and then invokes the abort(3) routine.
xexec path	The server gets ready to shut itself down, but instead of exiting, it executes
	the specified path with all of its original arguments. If path is innd, then /
	news/bin/innd is invoked; if it is inndstart, then /news/bin/inndstart is
	invoked; if it is an empty string, it will invoke the appropriate program
	depending on whether it was started with the –p flag; any other value is an
	error.

cvsbug 1279

In addition to being acted upon within the server, certain commands can be forwarded to the appropriate child process. If the site receiving the command is an exploder (such as buffchan(8)) or it is a funnel that feeds into an exploder, then the command can be forwarded. In this case, the server will send a command line to the exploder that consists of the ctlinnd command name. If the site funnels into an exploder that has an asterisk (*) in its W flag (see newsfeed(5)), then the site name is appended to the command; otherwise, no argument is appended.

BUGS

ctlinnd uses the inndcomm(3) library and is therefore limited to server replies no larger than 4KB.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

active(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsfeeds(5), overview.fmt(5)

ctrlaltdel

ctrlaltdel—Set the function of the Ctrl+Alt+Del combination.

SYNOPSIS

ctrlaltdel hard|soft

DESCRIPTION

Based on examination of the linux/kernel/sys.c code, it is clear that there are two supported functions that the Ctrl+Alt+Del sequence can perform: a hard reset, which immediately reboots the computer without calling sync(2) and without any other preparation, and a soft reset, which sends the SIGINT (interrupt) signal to the init process (this is always the process with PID 1). If this option is used, the init(8) program must support this feature. Because there are now several init(8) programs in the Linux community, consult the documentation for the version that you are currently using.

ctrlaltdel is usually used in the /etc/rc.local file.

FILES

/etc/rc.local

SEE ALSO

simpleinit(8), init(8)

AUTHOR

Peter Orbaek ([e-mail])

Linux 0.99, 25 October 1993

cvsbug

cvsbug—Send problem report (PR) about CVS to a central support site.

SYNOPSIS

cvsbug [ site ][-f problem-report ][-t mail-address ][-P ][-L ] [--request-id ][-v ]

		Part VIII: Administration and Privileged Commands
	1280

DESCRIPTION

cvsbug is a tool used to submit problem reports (PRs) to a central support site. In most cases, the correct site will be the default. This argument indicates the support site that is responsible for the category of problem involved. Some sites may use a local address as a default. Site values are defined by using the aliases(5).

cvsbug invokes an editor on a problem report template (after trying to fill in some fields with reasonable default values). When you exit the editor, cvsbug sends the completed form to the Problem Report Management System (GNATS) at a central support site. At the support site, the PR is assigned a unique number and is stored in the GNATS database according to its category and submitter ID. GNATS automatically replies with an acknowledgment, citing the category and the PR number.

To ensure that a PR is handled promptly, it should contain your (unique) submitter ID and one of the available categories to identify the problem area. (Use cvsbug -L to see a list of categories.)

The cvsbug template at your site should already be customized with your submitter ID (running install-sid submitter-id to accomplish this is part of the installation procedures for cvsbug). If this hasn’t been done, see your system administrator for your submitter ID, or request one from your support site by invoking cvsbug —-request–id. If your site does not distinguish between different user sites, or if you are not affiliated with the support site, use net for this field.

The more precise your problem description and the more complete your information, the faster your support team can solve your problems.

OPTIONS

-f problem-report	Specify a file (problem-report) that already contains a complete problem report. cvsbug
	sends the contents of the file without invoking the editor. If the value for problem-report
	is –, then cvsbug reads from standard input.
-t mail-address	Change mail address at the support site for problem reports. The default mail-address is
	the address used for the default site. Use the site argument rather than this option in
	nearly all cases.
-P	Print the form specified by the environment variable PR FORM on standard output. If PR
	FORM is not set, print the standard blank PR template. No mail is sent.
-L	Print the list of available categories. No mail is sent.
--request-id	Sends mail to the default support site, or site if specified, with a request for your
	submitter ID. If you are not affiliated with site, use a submitter ID of net.
-v	Display the cvsbug version number.

Note: Use cvsbug to submit problem reports rather than mail them directly. Using both the template and cvsbug itself will help ensure all necessary information will reach the support site.

ENVIRONMENT

The environment variable EDITOR specifies the editor to invoke on the template. The default is vi.

If the environment variable PR FORM is set, then its value is used as the filename of the template for your problem-report editing session. You can use this to start with a partially completed form (for example, a form with the identification fields already completed).

HOW TO FILL OUT A PROBLEM REPORT

Problem reports have to be in a particular form so that a program can easily manage them. Please remember the following guidelines:

Describe only one problem with each problem report.

For follow-up mail, use the same subject line as the one in the automatic acknowledgment. It consists of category, PR number, and the original synopsis line. This allows the support site to relate several mail messages to a particular PR and to record them automatically.

cvtbatch 1281

Please try to be as accurate as possible in the subject or synopsis line.

The subject and the synopsis line are not confidential. This is because open-bugs lists are compiled from them. Avoid putting confidential information there.

See the GNU Info file cvsbug.info or the document Reporting Problems With cvsbug for detailed information on reporting problems

HOW TO SUBMIT TEST CASES, CODE, AND SO ON

Submit small code samples with the PR. Contact the support site for instructions on submitting larger test cases and problematic source code.

FILES

/tmp/p$$ copy of PR used in editing session

/tmp/pf$$ copy of empty PR form, for testing purposes

/tmp/pbad$$ file for rejected PRs

EMACS USER INTERFACE

An EMACS user interface for cvsbug with completion of field values is part of the cvsbug distribution (invoked with M-x cvsbug). See the file cvsbug.info or the ASCII file INSTALL in the top-level directory of the distribution for configuration and installation information. The EMACS LISP template file is cvsbug-el.in and is installed as cvsbug.el.

INSTALLATION AND CONFIGURATION

See cvsbug.info or INSTALL for installation instructions.

SEE ALSO

Reporting Problems Using cvsbug (also installed as the GNU Info file cvsbug.info). gnats(l), query-pr(1), edit-pr(1), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8)

AUTHORS

Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus Support).

COPYING

Copyright(c) 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

xVERSIONx, February 1993

cvtbatch

cvtbatch—Convert Usenet batch file to INN format.

SYNOPSIS

cvtbatch [ -w items ]

		Part VIII: Administration and Privileged Commands
	1282

DESCRIPTION

cvtbatch reads standard input as a series of lines, converts each line, and writes it to standard output. It is used to convert simple batchfiles that contain just the article name to INN batchfiles that contain additional information about each article.

Each line is taken as the pathname to a Usenet article. If it is not an absolute pathname, it is taken relative to the spool directory, /news/spool. (Only the first word of each line is parsed; anything following whitespace is ignored.)

The –w flag specifies how each output line should be written. The items for this flag should be chosen from the W flag items as specified in newsfeeds(5). They may be chosen from the following set:

b	Size of article in bytes
f	Full pathname of article
m	Article Message-ID
n	Relative pathname of article

If the input file consists of a series of Message-IDs, then use grephistory(1) with the –s flag piped into cvtbatch.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

grephistory(1) newsfeeds(5)

cytune

cytune—Tune Cyclades driver parameters.

SYNOPSIS

cytune [-q [-i interval]] ([-s value]|[-S value]) [-g|G] ([-t timeout]|[-T timeout]) tty [tty ...]

DESCRIPTION

cytune queries and modifies the interruption threshold for the Cyclades driver. Each serial line on a Cyclades card has a 12byte FIFO for input (and another 12-byte FIFO for output). The “threshold” specifies how many input characters must be present in the FIFO before an interruption is raised. When a Cyclades tty is opened, this threshold is set to a default value based on baud rate:

Baud	Threshold
50-4800	10
9600	8
19200	4
38400	2
57600-150000	1

If the threshold is set too low, the large number of interruptions can load the machine and decrease overall system throughput. If the threshold is set too high, the FIFO buffer can overflow, and characters will be lost. Slower machines, however, may not be able to deal with the interrupt load and will require that the threshold be adjusted upwards.

If the Cyclades driver was compiled with ENABLE MONITORING defined, the cytune command can be used with the -q option to report interrupts over the monitoring interval and characters transferred over the monitoring interval. It will also report

cytune 1283

the state of the FIFO. The maximum number of characters in the FIFO when an interrupt occurred, the instantaneous count of characters in the FIFO, and how many characters are now in the FIFO are reported. This output might look like this:

/dev/cubC0: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now 166.259866 interrupts/second, 1828.858521 characters/second

This output indicates that for this monitoring period, the interrupts were always being handled within one character time because max never rose above threshold. This is good, and you can probably run this way, provided that a large number of samples come out this way. You will lose characters if you overrun the FIFO because the Cyclades hardware does not seem to support the RTS RS-232 signal line for hardware flow control from the DCE to the DTE.

cytune will in query mode produce a summary report when ended with a SIGINT or when the threshold or time-out is changed.

There may be a responsiveness versus throughput tradeoff. The Cyclades card, at the higher speeds, is capable of putting a very high interrupt load on the system. This will reduce the amount of CPU time available for other tasks on your system. However, the time it takes to respond to a single character may be increased if you increase the threshold. This might be noticed by monitoring ping(8) times on a SLIP link controlled by a Cyclades card. If your SLIP link is generally used for interactive work such as telnet(1), you might want to leave the threshold low so that characters are responded to as quickly as possible. If your SLIP link is generally used for file transfer, WWW, and the like, setting the FIFO to a high value is likely to reduce the load on your system while not significantly affecting throughput. Alternatively, see the -t or -T options to adjust the time that the Cyclades waits before flushing its buffer. Units are 5ms.

If you are running a mouse on a Cyclades port, it is likely that you want to maintain the threshold and time-out at a low value.

OPTIONS

-s value	Set the current threshold to value characters. Note that if the tty is not being held open
	by another process, the threshold will be reset on the next open. Only values between 1
	and 12, inclusive, are permitted.
-t value	Set the current flush time-out to value units. Note that if the tty is not being held open
	by another process, the threshold will be reset on the next open. Only values between 0
	and 255, inclusive, are permitted. Setting value to 0 forces the default, currently 0x20
	(160ms) but soon to be 0x02 (10ms). Units are 5ms.
-g	Get the current threshold and time-out.
-T value	Set the default flush time-out to value units. When the tty is next opened, this value is
	used instead of the default. If value is 0, then the value defaults to 0x20 (160ms), soon to
	be 0x02 (10ms).
-G	Get the default threshold and flush time-out values.
-q	Gather statistics about the tty. The results are only valid if the Cyclades driver has been
	compiled with ENABLE MONITORING defined. This is probably not the default.
-i interval	Statistics will be gathered every interval seconds.

BUGS

If you run two copies of cytune at the same time to report statistics about the same port, the ints, chars, and max values will be reset and not reported correctly. cytune(8) should prevent this but does not.

AUTHOR

Nick Simicich ([e-mail]), with modifications by Rik Faith ([e-mail])

		Part VIII: Administration and Privileged Commands
	1284

FILES

/dev/ttyC[0-8]

/dev/cubC[0-8]

SEE ALSO

setserial(8)

4 March 1995

debugfs

debugfs—ext2 filesystem debugger.

SYNOPSIS

debugfs [[-w ]device]

DESCRIPTION

debugfs is a filesystem debugger. It can be used to examine and change the state of an ext2 filesystem. device is the special file corresponding to the device containing the ext2 filesystem (such as /dev/hdXX).

OPTIONS

-w	Specify that the filesystem should be open in read-write mode. Without this option,
	the filesystem is open in read-only mode.

COMMANDS

debugfs is an interactive debugger. It understands a number of commands:

cd file
chroot file
close	Close the currently open filesystem.
clri file	Clear the contents of the inode corresponding to file.
expand_dir, file	Expand a directory.
find_free_block [goal]	Find the first free block, starting from goal, and allocate it.
find_free_inode [dir [mode]]	Find a free inode and allocate it.
freeb block	Mark the block as not allocated.
freei file	Free the inode corresponding to file.
help
iname inode	Print the filename corresponding to inode (currently not implemented).
initialize device blocksize	Create an ext2 file system on device.
kill_file file	Remove a file and deallocate its blocks.
ln source_file dest_file	Create a link.
ls [pathname]	Emulate the ls(1) command.
Modify_inode file	Modify the contents of the inode corresponding to file.
mkdir file	Make a directory.
open [-w] device	Open a filesystem.
pwd
quit	Quit debugfs.

dip 1285

rm file	Remove a file.
rmdir file	Remove a directory.
setb block	Mark the block as allocated.
seti file	Mark in use the inode corresponding to file
show_super_stats	List the contents of the super block.
stat file	Dump the contents of the inode corresponding to file.
testb block	Test if the block is marked as allocated.
testi file	Test if the inode corresponding to file is marked as allocated.
unlink file	Remove a link.

AUTHOR

debugfs was written by Theodore T’so ([e-mail]).

SEE ALSO

dumpe2fs(8), e2fsck(8), mke2fs(8)

Version 0.5b, November 1994

dip

dip—Dialup IP connection handler.

SYNOPSIS

dip [-t]

dip [-ktv] [-m mtu] scriptfile dip [-iv] [user_name]

DESCRIPTION

dip handles the connections needed for dialup IP links, such as SLIP or PPP. It can handle both incoming and outgoing connections, using password security for incoming connections. The outgoing connections use the system’s dial(3) library if available.

COMMAND MODE

The first possible use of dip is as a stand-alone program to set up an outgoing IP connection. This can be done by invoking dip with the -t option, which means enter TEST mode and, more precisely, dump you in the COMMAND-MODE of the dip program. You are reminded of this by the DIP> prompt, or, if you also specified the -v debugging flag, the DIP [NNNN]> prompt. The latter prompt also displays the current value of the global errlvl variable, which is used mostly when dip runs in script mode. For the interactive mode, it can be used to determine if the result of the previous command was okay.

The following is a sample taken from a live session:

$dip-t

DIP: Dialup IP Protocol Driver version 3.3.7 (12/13/93) Written by Fred N. van Kempen, MicroWalt Corporation.

DIP>_

The most helpful command in this mode is, of course, the help command, which should produce an output similar to this:

DIP> help

DIP knows about the following commands:

		Part VIII: Administration and Privileged Commands
	1286

databits default dial echo flush get goto help if init

mode modem parity print port reset send sleep speed stopbits term wait

DIP>_

All commands display how they should be used when invoking them with no or invalid arguments. Just experiment a little to get the feel of it, and have a look at the sample script files, which also use this command language.

DIALIN MODE

The second possible way of using dip is as a login shell for incoming IP connections, as in dialup SLIP and PPP connections. To make integration into the existing UNIX system as easy as possible, dip can be installed as simply as using it as a login shell in the system’s password file. A sample entry looks like

suunet:ij/SMxiTlGVCo:1004:10:UUNET:/tmp:/usr/bin/dip -i

When user suunet logs in, the login(1) program sets the home directory to /tmp and execute the dip program with the -i option, which means that dip must run in input mode. dip then tries to locate the name of the logged-in user (the name corresponding to its current user ID, as returned by the getuid(2) system call) in its database file. An optional single argument to the dip program in this mode can be the username that must be used in this lookup, regardless of the current user ID.

dip now scans the /etc/net/diphosts file for an entry for the given username. This file contains lines of text (much like the standard password file). The format looks like

#

#diphosts This file describes a number of name to

#address mappings for the DIP program. It

#is used to determine which IP address to

#use for in incoming call of some user.

#

#Version: @(#)diphosts 1.00 12/10/92 FvK

#Author: Fred N. van Kempen,

#<[e-mail]>

#

suunet::uunet.uu.net:UUNET SLIP:SLIP,296

# End of diphosts.

The first field of a line identifies the username, which you must match. The second field can contain an encrypted password. If this field is non-null, the dip program asks for an external security password, which must match the password in this field. The third field contains the name (or raw IP address) of the host that is connecting to the system with this link. If a hostname is given, the usual address resolving process is started, using either a nameserver or a local hosts file.

The fourth field can contain any text; it is not (yet) used by the dip program. In future releases, this info may be used in the system log files. Finally, the fifth field of a line contains a mixture of comma-separated flags. Possible flags are

SLIP to indicate you must use the SLIP protocol.

PPP to indicate you must use the PPP protocol.

number, which gives the MTU parameter of this connection.

After finding the correct line, dip puts the terminal line into RAW mode and asks the system networking layer to allocate a channel of the desired protocol. Finally, if the channel is activated, it adds an entry to the system’s routing table to make the connection work.

dip 1287

dip now goes into an endless loop of sleeping, which continues until the connection is physically aborted (the line is dropped). At that time, dip removes the entry it made in the system’s routing table and releases the protocol channel for reuse. It then exits, making room for another session.

DIALOUT MODE

The last way of using dip is as a program that initiates outgoing connections. To make life easier for the people who have to manage links of this type, dip uses a chat script to set up a link to a remote system. This gives the user an enormous amount of flexibility when making the connection, which otherwise could require many command-line options. The pathname of the script to be run is then given as the single argument to dip; the program will automatically check if the file has a filename ending in a .dip part. This is not mandatory—just a tool to group scripts together in a single directory. A script should look something like this:

#

#sample.dip Dialup IP connection support program.

#This file (should show) shows how to use the DIP

#scripting commands to establish a link to a host.

#This host runs the 386bsd operating system, and

#thus can only be used for the “static” addresses.

#NOTE: We also need an examnple of a script used to

#connect to a “dynamic” SLIP server, like an Annex

#terminal server...

#

#Version: @(#)sample.dip 1.30 07/05/93

#Author: Fred N. van Kempen, <[e-mail]>

main:

#First of all, set up our name for this connection.

#I am called “uwalt.hacktic.nl” (== 193.78.33.238)

get $local uwalt.hacktic.nl

#Next, set up the other side’s name and address.

#My dialin machine is called ‘xs4all.hacktic.nl’ (== 193.78.33.42) get $remote xs4all.hacktic.nl

#Set the desired serial port and speed.

port cua0 speed 38400

#Reset the modem and terminal line.

#This seems to cause trouble for some people! reset

#Prepare for dialing.

send ATQ0V1E1X1 wait OK 2

if $errlvl != 0 goto error dial 555-1234567

if $errlvl != 0 goto error wait CONNECT 60

if $errlvl != 0 goto error

# We are connected. Login to the system. login:

sleep 3

send \r\n\r\n wait ogin: 10

if $errlvl != 0 goto error send NO-WAY\n

wait ord: 5

if $errlvl != 0 goto error send HA-HA\n

		Part VIII: Administration and Privileged Commands
	1288

wait $ 30

if $errlvl != 0 goto error loggedin:

#We are now logged in. Start the ‘sliplogin’ program,

#as this is not automatically done for me.

send sliplogin\n wait SOME-STRING 15

#Set up the SLIP operating parameters. get $mtu 1500

#Set Destination net/address as type ‘default’ (vice an address).

#This is used by the ‘route’ command to set the kernel routing table.

#Some machines seem to require this be done for SLIP to work properly. default

#Say hello and fire up!

done:

print CONNECTED to $remote with address $rmtip mode SLIP

goto exit error:

print SLIP to $remote failed. exit:

This script causes dip to dial up a host, log in, and get a SLIP interface channel going (in the same manner as with incoming connections). When all is set up, it simply goes into the background and waits for a hangup (or just a lethal signal), at which it hangs up and exits.

FILES

/etc/passwd

/etc/diphosts

AUTHORS

Fred N. van Kempen ([e-mail]), Paul Mossip ([e-mail]), Jeff Uphoff ([e-mail]), Jim Seagrave ([e-mail]), Olaf Kirch ([e-mail]).

Version 3.3.7, 13 December 1993

dmesg

dmesg—Print or control the kernel ring buffer.

SYNOPSIS

dmesg [ -c ] [ -n level ]

DESCRIPTION

dmesg is used to examine or control the kernel ring buffer.

The program helps users to print their bootup messages. Instead of copying the messages by hand, the user need only

dmesg > boot.messages

and mail the boot.messages file to whoever can debug their problem.

	e2fsck
		1289
OPTIONS
-c	Clear the ring buffer contents after printing.
-n level	Set the level at which logging of messages is done to the console. For example, -n 1
	prevents all messages, except panic messages, from appearing on the console. All
	levels of messages are still written to /proc/kmsg, so syslogd(8) can still be used to
	control exactly where kernel messages appear. When the -n option is used, dmesg
	will not print or clear the kernel ring buffer.

When both options are used, only the last option on the command line will have an effect.

SEE ALSO

syslogd(8)

AUTHOR

Theodore Ts’o ([e-mail])

Linux 0.99, 28 October 1993

dumpe2fs

dumpe2fs—Dump filesystem information.

SYNOPSIS

dumpe2fs device

DESCRIPTION

dumpe2fs prints the super block and blocks group information for the filesystem present on device.

dumpe2fs is similar to Berkeley’s dumpfs program for the BSD Fast File System.

BUGS

You need to know the physical filesystem structure to understand the output.

AUTHOR

dumpe2fs was written by Remy Card ([e-mail]), the developer and maintainer of the ext2 fs.

AVAILABILITY

dumpe2fs is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs.

SEE ALSO

e2fsck(8), mke2fs(8), tune2fs(8)

Version 0.5b, November 1994

e2fsck

e2fsck—Check a Linux second extended filesystem.

SYNOPSIS

e2fsck [ -panyrdfvtFV ][-b superblock ][-B blocksize ] [-l|-L bad_blocks_file ] device

		Part VIII: Administration and Privileged Commands
	1290

DESCRIPTION

e2fsck is used to check a Linux second extended file system.

device The special file corresponding to the device (such as /dev/hdXX).

OPTIONS

-a	This option does the same thing as the -p option. It is provided for backwards
	compatibility only; it is suggested that people use -p option whenever possible.
-b superblock	Instead of using the normal superblock, use the alternative superblock specified by
	superblock.
-B blocksize	Usually, e2fsck will search for the superblock at various different block sizes in an
	attempt to find the appropriate block size. This search can be fooled in some cases.
	This option forces e2fsck to only try locating the superblock at a particular
	blocksize. If the superblock is not found, e2fsck will terminate with a fatal error.
-d	Print debugging output (useless unless you are debugging e2fsck ).
-f	Force checking even if the filesystem seems clean.
-F	Flush the filesystem device’s buffer caches before beginning. Only really useful for
	doing e2fsck time trials.
-l filename	Add the blocks listed in the file specified by filename to the list of bad blocks.
-L filename	Set the bad blocks list to be the list of blocks specified by filename. (This option is
	the same as the -l option except the bad blocks list is cleared before the blocks listed
	in the file are added to the bad blocks list.)
-n	Open the filesystem read-only, and assume an answer of “no” to all questions.
	Allows e2fsck to be used non-interactively. (Note: if the -l or -L options are
	specified in addition to the -n option, then the filesystem will be opened read-write
	to permit the bad-blocks list to be updated. However, no other changes will be made
	to the filesystem.)
-p	Automatically repair (“preen”) the filesystem without any questions.
-r	This option does nothing at all; it is provided only for backwards compatibility.
-t	Print timing statistics for e2fsck. If this option is used twice, additional timing
	statistics are printed on a pass-by-pass basis.
-v	Verbose mode.
-V	Print version information and exit.
-y	Assume an answer of “yes” to all questions; allows e2fsck to be used non-
	interactively.

EXIT CODE

The exit code returned by e2fsck is the sum of the following conditions:

0	No errors
1	Filesystem errors corrected
2	Filesystem errors corrected; system should be rebooted if filesystem was mounted
4	Filesystem errors left uncorrected
8	Operational error
16	Usage or syntax error
128	Shared library error

edquota 1291

BUGS

Almost any piece of software will have bugs. If you manage to find a filesystem that causes e2fsck to crash, or that e2fsck is unable to repair, please report it to the author.

Please include as much information as possible in your bug report. Ideally, include a complete transcript of the e2fsck run, so I can see exactly what error messages are displayed. If you have a writeable filesystem where the transcript can be stored, the script(1) program is a handy way to save the output of e2fsck to a file.

It is also useful to send the output of dumpe2fs(8). If a specific inode or inodes seems to be giving e2fsck trouble, try running the debugfs(8) command and send the output of the stat command run on the relevant inodes. If the inode is a directory, the debugfs dump command will allow you to extract the contents of the directory inode, which can sent to me after being first run through uuencode(1).

Always include the full version string that e2fsck displays when it is run so I know which version you are running.

AUTHOR

This version of e2fsck is written by Theodore Ts’o ([e-mail]).

SEE ALSO

mke2fs(8), tune2fs(8), dumpe2fs(8), debugfs(8)

Version 0.5b, November 1994

edquota

edquota—Edit user quotas.

SYNOPSIS

/usr/etc/edquota [ -p proto-user ][-ug ] name...

/usr/etc/edquota [ -ug ] -t

DESCRIPTION

edquota is a quota editor. One or more users or groups may be specified on the command line. For each user or group, a temporary file is created with an ASCII representation of the current disk quotas for that user or group and an editor is then invoked on the file. The quotas may then be modified, new quotas added, and so on. Upon leaving the editor, edquota reads the temporary file and modifies the binary quota files to reflect the changes made.

The editor invoked is vi(1) unless the environment variable specifies otherwise.

Only the superuser may edit quotas. (For quotas to be established on a filesystem, the root directory of the filesystem must contain a file, owned by root, called quota.user or quota.group. See quotaon(8) for details.)

OPTIONS

-u	Edit the userquota. This is the default.
-g	Edit the groupquota.
-p	Duplicate the quotas of the prototypical user specified for each user specified. This is
	the normal mechanism used to initialize quotas for groups of users.
-t	Edit the soft time limits for each filesystem. If the time limits are zero, the default
	time limits in <linux/quota.h> are used. Time units of sec(onds), min(utes),
	hour(s), day(s), week(s), and month(s) are understood. Time limits are printed in the
	greatest possible time unit such that the value is greater than or equal to one.

		Part VIII: Administration and Privileged Commands
1292
FILES

quota.user or quota.group	Quota file at the filesystem root
/etc/mtab	Mounted filesystems

SEE ALSO

quota(1), vi(1), quotactl(2), quotacheck(8), quotaon(8), repquota(8)

BUGS

The format of the temporary file is inscrutable.

8 June 1993

expire

expire—Usenet article and history expiration program.

SYNOPSIS

expire [ -d dir ][-f file ][-g file ][-h file ] [-i ][-l ][-n ][-p ][-q ][-r reason ][-s ][-t ] [-v level ][-w number ][-x ][-z file ][expire.ctl]

DESCRIPTION

expire scans the history(5) text file /news/lib/history and uses the information recorded in it to purge old news articles. To specify an alternate history file, use the –f flag. To specify an alternate input text history file, use the –h flag. expire uses the old dbz(3z) database to determine the size of the new one. To ignore the old database, use the –i flag.

expire usually just unlinks each file if it should be expired. If the –l flag is used, then all articles after the first one are treated as if they could be symbolic links to the first one. In this case, the first article will not be removed as long as any other crossposts of the article remain.

expire usually sends a pause command to the local innd(8) daemon when it needs exclusive access to the history file, using the string Expiring as the reason. To give a different reason, use the –r flag. The process ID will be appended to the reason. When expire is finished and the new history file is ready, it sends a go command. If innd is not running, use the –n flag and expire will not send the pause or go commands. (For more details on the commands, see ctlinnd(8).) Note that expire only needs exclusive access for a very short time—long enough to see if any new articles arrived since it first hit the end of the file and to rename the new files to the working files.

If the –s flag is used, then expire will print a summary when it exits, showing the approximate number of kilobytes used by all deleted articles.

If the –t flag is used, then expire will generate a list of the files that should be removed on its standard output, and the new history file will be left in history.n, history.n.dir, and history.n.pag. This flag is useful for debugging when used with the –n and –s flags. Note that if the –f flag is used, then the name specified with that flag will be used instead of history.

If the –x flag is used, then expire will not create any new history files. This is most useful when combined with the –n, –s, and –t flags to see how different expiration policies would change the amount of disk space used.

If the –z flag is used, then articles are not removed, but their names are written to the specified file. See the description of expirerm in news.daily(8).

expire makes its decisions on the time the article arrived, as found in the history file. This means articles are often kept a little longer than with other expiration programs that base their decisions on the article’s posting date. To use the article’s posting date, use the –p flag. Use the –w flag to “warp” time so that expire thinks it is running at some time other then the current time. The value should be a signed floating-point number of the number of days to use as the offset.

expireover 1293

If the –d flag is used, then the new history file and database is created in the specified directory, dir. This is useful when the filesystem does not have sufficient space to hold both the old and new history files. When this flag is used, expire leaves the server paused and creates a zero-length file named after the new history file, with an extension of .done to indicate that it has successfully completed the expiration. The calling script should install the new history file and unpause the server. The –r flag should be used with this flag.

If a filename is specified, it is taken as the control file and parsed according to the rules in expire.ctl(5). A single dash (–) may be used to read the file from standard input. If no file is specified, the file /news/lib/expire.ctl is read.

expire usually complains about articles that are posted to newsgroups not mentioned in the active file. To suppress this action, use the –q flag.

The –v flag is used to increase the verbosity of the program, generating messages to standard output. The level should be a number, where higher numbers result in more output. Level one will print totals of the various actions done (not valid if a new history file is not written), level two will print report on each individual file, and level five results in more than one line of output for every line processed. If the –g flag is given, then a one-line summary equivalent to the output of –v1 and preceded by the current time will be appended to the specified file.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

ctlinnd(8), dbz(3z), expire.ctl(5), history(5), innd(8), inndcomm(3)

expireover

expireover—Expire entries from the news overview database.

SYNOPSIS

expireover [ -a ][-D overviewdir ][-f file ][-n ] [-O overview.fmt ][-s ][-v ][-z ][file... ]

DESCRIPTION

expireover expires entries from the news overview database. It reads a list of pathnames (relative to the spool directory, / news/spool) from the specified files or standard input if none are specified. (A filename of – may be used to specify the standard input.) It then removes any mention of those articles from the appropriate overview database. If the –z flag is used, then the input is assumed to be sorted such that all entries for a newsgroup appear together so that it can be purged at once. This flag can be useful when used with the sorted output of expire(8)’s –z flag.

If the –s flag is used, then expireover will read the spool directory for all groups mentioned in the active(5) file and remove the overview entries for any articles that do not appear. To specify an alternate file, use the –f flag; a name of – is taken to mean the standard input.

The –a flag reads the spool directory and adds any missing overview entries. It will create files if necessary. This can be used to initialize a database or to sync up a overview database that may be lacking articles due to a crash. overchan should be running, to ensure that any incoming articles get included. Using this flag implies the –s flag; the –f flag may be used to add only a subset of the newsgroups.

To see a list of the entries that would be added or deleted, use the –v flag. To perform no real updates, use the –n flag.

The –D flag can be used to specify where the databases are stored. The default directory is /news/spool.

The –O flag may be used to specify an alternate location for the overview.fmt(5) file; this is usually only useful for debugging.

		Part VIII: Administration and Privileged Commands
	1294

HISTORY

Written by Rob Robertson ([e-mail]) and Rich $alz ([e-mail]) with help from Dave Laurence ([e-mail]) for InterNetNews.

SEE ALSO

expire(8), overview.fmt(5)

fastrm

fastrm—Quickly remove a set of files.

SYNOPSIS

fastrm [ -d ][-e ][-uN ][-sM ][-cI ] base_directory

DESCRIPTION

fastrm reads a list of files, one per line, from its standard input and removes them. If a file is not an absolute pathname, it is taken relative to the directory specified on the command line. The base directory parameter must be a simple absolute pathname—that is, it must not contain any /./ or /../ references.

fastrm is designed to be faster than the typical | xargs rm pipeline. For example, fastrm will usually chdir(2) into a directory before removing files from it. If the input is sorted, this means that most files to be removed will be simple names.

fastrm assumes that its input is valid and that it is safe to just do an unlink(2) call for each item to be removed. As a safety measure, if fastrm is run by root, it will first stat(2) the item to make sure that it is not a directory before unlinking it.

If the –d flag is used, then no files are removed. Instead, a list of the files to be removed, in debug form, is printed on the standard output. Each line contains either the current directory of fastrm at the time it would do the unlink and then the pathname it would pass to unlink(2) as two fields separated by white space and a / or the absolute pathname (a single field) of files it would unlink using the absolute pathname.

If the –e flag is used, fastrm will treat an empty input file (stdin) as an error. This is most useful when fastrm is last in a pipeline after a preceding sort(1) because if the sort fails, there will usually be no output to become input of fastrm.

If the –u flag is used, then fastrm makes further assumptions about its work environment—in particular, that there are no symbolic links in the target tree. This flag also suggests that it is probably faster to reference the path ../../../ rather than start from the root and come down (note that this probably isn’t true on systems that have a namei cache, which usually holds everything except ..). The optional N is an integer that specifies the maximum number of .. segments to use—paths that would use more than this use the absolute pathname (from the root) instead. If the –u flag is given without a value, –u1 is assumed.

If the –s flag is used, then fastrm will perform the unlinks from one directory—that is, when a group of files in one directory appear in the input consecutively—in the order that the files appear in the directory from which they are to be removed. The intent of this flag is that on systems that have a per-process directory cache, finding files in the directory should be faster. It can have smaller benefits on other systems. The optional M is an integer that specifies the number of files that must be going to be removed from one directory before the files will be ordered. If the –s flag is given without a value, –s5 is assumed. When the directory reordering is in use, fastrm will avoid attempting to unlink files that it can’t see in the directory, which can speed it appreciably when many of the filenames have already been removed.

The –c flag may be given to instruct fastrm when it should chdir(2). If the number of files to be unlinked from a directory is at least I, then fastrm will chdir and unlink the files from in the directory. Otherwise, it will build a path relative to its current directory. If –c is given without the optional integer I, then –c1 is assumed, which will cause fastrm to always use chdir. If –c is not used at all, then –c3 is assumed. Use –c0 to prevent fastrm from ever using chdir(2).

fdformat 1295

There are also –a and –r options, which do nothing at all except allow you to say fastrm –usa, fastrm –ussr, or fastrm –user. These happen to often be convenient sets of options to use.

fastrm exits with a status of 0 if there were no problems or 1 if something went wrong. Attempting to remove a file that does not exist is not considered a problem. If the program exits with a nonzero status, it is probably a good idea to feed the list of files into an xargs rm pipeline.

fdformat

fdformat—Low-level formats a floppy disk.

SYNOPSIS

fdformat [ -n ] device

DESCRIPTION

fdformat does a low-level format on a floppy disk. device is usually one of the following (for floppy devices, the major is 2, and the minor is shown for informational purposes only):

/dev/fd0d360 (minor = 4)

/dev/fd0h1200 (minor = 8)

/dev/fd0D360 (minor = 12)

/dev/fd0H360 (minor = 12)

/dev/fd0D720 (minor = 16)

/dev/fd0H720 (minor = 16)

/dev/fd0h360 (minor = 20)

/dev/fd0h720 (minor = 24)

/dev/fd0H1440 (minor = 28)

/dev/fd1d360 (minor = 5)

/dev/fd1h1200 (minor = 9)

/dev/fd1D360 (minor = 13)

/dev/fd1H360 (minor = 13)

/dev/fd1D720 (minor = 17)

/dev/fd1H720 (minor = 17)

/dev/fd1h360 (minor = 21)

/dev/fd1h720 (minor = 25)

/dev/fd1H1440 (minor = 29)

The generic floppy devices, /dev/fd0 and /dev/fd1, will fail to work with fdformat when a non-standard format is being used or if the format has not been autodetected earlier. In this case, use setfdprm(8) to load the disk parameters.

OPTIONS

-n	No verify. This option will disable the verification that is performed after the format.

SEE ALSO

fd(4), setfdprm(8), mkfs(8), emkfs(8)

		Part VIII: Administration and Privileged Commands
	1296

AUTHOR

Werner Almesberger ([e-mail])

Linux 0.99, 1 February 1993

fdisk

fdisk—Partition table manipulator for Linux.

SYNOPSIS

fdisk [ -l ] [ -v ] [ -s partition] [ device ]

DESCRIPTION

fdisk is a menu-driven program for manipulation of the hard disk partition table. The device is usually one of the following:

/dev/hda

/dev/hdb

/dev/sda

/dev/sdb

The partition is a device name followed by a partition number. For example, /dev/hda1 is the first partition on the first hard disk in the system.

If possible, fdisk will obtain the disk geometry automatically. This is not necessarily the physical disk geometry but is the disk geometry that MS-DOS uses for the partition table. If fdisk warns you that you need to set the disk geometry, please believe this statement and set the geometry. This should only be necessary with certain SCSI host adapters (the drivers for which are rapidly being modified to provide geometry information automatically).

Whenever a partition table is printed, a consistency check is performed on the partition table entries. This check verifies that the physical and logical start and end points are identical and that the partition starts and ends on a cylinder boundary (except for the first partition).

Old versions of fdisk (all versions prior to 1.1r including 0.93) incorrectly mapped the cylinder/head/sector specification onto absolute sectors. This might result in the first partition on a drive failing the consistency check. If you use LILO to boot, this situation can be ignored. However, there are reports that the OS/2 boot manager will not boot a partition with inconsistent data.

Some versions of MS-DOS create a first partition that does not begin on a cylinder boundary but on sector 2 of the first cylinder. Partitions beginning in cylinder 1 cannot begin on a cylinder boundary, but this is unlikely to cause difficulty unless you have OS/2 on your machine.

In version 1.1r, a BLKRRPART ioctl() is performed before exiting when the partition table is updated. This is primarily to ensure that removable SCSI disks have their partition table information updated. If the kernel does not update its partition table information, fdisk warns you to reboot. If you do not reboot your system after receiving such a warning, you might lose or corrupt the data on the disk. Sometimes BLKRRPART fails silently; when installing Linux, you should always reboot after editing the partition table.

DOS 6.X WARNING

The DOS 6.x FORMAT command looks for some information in the first sector of the data area of the partition and treats this information as more reliable than the information in the partition table. DOS FORMAT expects DOS FDISK to clear the first 512 bytes of the data area of a partition whenever a size change occurs. DOS FORMAT will look at this extra information even if the /U flag is given

filechan 1297

We consider this a bug in DOS FORMAT and DOS FDISK.

The bottom line is that if you use cfdisk or fdisk to change the size of a DOS partition table entry, then you must also use dd to zero the first 512 bytes of that partition before using DOS FORMAT to format the partition. For example, if you were using cfdisk to make a DOS partition table entry for /dev/hda1, then (after exiting fdisk or cfdisk and rebooting Linux so that the partition table information is valid) you would use the command dd if=/dev/zero of=/dev/hda1 bs=512 count=1 to zero the first 512 bytes of the partition.

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless.

For best results, you should always use an OS-specific partition table program. For example, you should make DOS partitions with the DOS FDISK program and Linux partitions with the Linux fdisk or Linux cfdisk program.

OPTIONS

-v	Prints version number of fdisk program.
-l	Lists the partition tables for /dev/hda, /dev/hdb, /dev/sda, /dev/sdb, /dev/sdc, /
	dev/sdd, /dev/sde, /dev/sdf, /dev/sdg, and /dev/sdh and then exits.
-s partition	If the partition is not a DOS partition (the partition ID is greater than 10), then the
	size of that partition is printed on the standard output. This value is usually used as
	an argument to the mkfs(8) program to specify the size of the partition that will be
	formatted.

BUGS

Although this man page (written by [e-mail]) is poor, there is excellent documentation in the README.fdisk file (written by [e-mail]) that should always be with the fdisk distribution. If you cannot find this file in the util- linux-* directory or with the fdisk.c source file, then you should write to the distributor of your version of fdisk and complain that you do not have all of the available documentation.

AUTHOR

A.V. LeBlanc ([e-mail]). v1.0r: SCSI and extfs support added by Rik Faith ([e-mail]). v1.1r: Bug fixes and enhancements by Rik Faith ([e-mail]), with special thanks to Michael Bischoff ([e-mail] or [e-mail]). v1.3: Latest enhancements and bug fixes by A.V. LeBlanc, including the addition of the -s option. v2.0: Disks larger than 2GB are now fully supported, thanks to Remy Card’s llseek support.

Linux 1.0, 3 June 1995

filechan

filechan—File-writing back end for InterNetNews.

SYNOPSIS

filechan [ -d directory ][-f fields ][-m mapfile ][-p pidfile ]

DESCRIPTION

filechan reads lines from standard input and copies certain fields in each line into files named by other fields within the line. filechan is intended to be called by innd(8) as a channel feed. (It is not a full exploder and does not accept commands; see newsfeeds(5) for a description of the difference and buffchan(8) for an exploder program.)

filechan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace. The default number of initial fields is one; the –f flag may be used to specify a different number of fields.

		Part VIII: Administration and Privileged Commands
	1298

For each line of input, filechan writes the initial fields, separated by whitespace and followed by a newline, to each of the files named in the filename fields. When writing to a file, filechan opens it in append mode and tries to lock it and change the ownership to the user and group who owns the directory where the file is being written.

By default, filechan writes its arguments into the directory /news/spool/out.going. The –d flag may be used to specify a directory the program should change to before starting.

If the –p flag is used, the program will write a line containing its process ID (in text) to the specified file.

If filechan is invoked with –f 2 and given the following input:

news/software/b/132 <[e-mail]>foo uunet news/software/b/133 <[e-mail]> uunet munnari comp/sources/unix/2002 <[e-mail]>foo uunet munnari

Then the file foo will have these lines:

news/software/b/132 <[e-mail]> comp/sources/unix/2002 <[e-mail]>

The file munnari will have these lines:

news/software/b/133 <[e-mail]> comp/sources/unix/2002 <[e-mail]>

The file uunet will have these lines:

news/software/b/132 <[e-mail]> news/software/b/133 <[e-mail]> comp/sources/unix/2002 <[e-mail]>

Because the time window in which a file is open is very small, complicated flushing and locking protocols are not needed; a mv(1) followed by a sleep(1) for a couple of seconds is sufficient.

A map file may be specified by using the –m flag. Blank lines and lines starting with a number sign (#) are ignored. All other lines should have two hostnames separated by a colon. The first field is the name that may appear in the input stream; the second field names the file to be used when the name in the first field appears. For example, the following map file may be used to map the short names to the full domain names:

# This is a comment uunet:news.uu.net foo:foo.com munnari:munnari.oz.au

HISTORY

Written by Robert Elz ([e-mail]); flags added by Rich $alz ([e-mail]).

SEE ALSO

buffchan(8), innd(8), newsfeeds(5)

fsck

fsck—Check and repair a Linux filesystem.

SYNOPSIS

fsck [ -AVRTN ][-s ][-t fstype ][fs-options ] filesys [ ...

]

fsck 1299

DESCRIPTION

fsck is used to check and optionally repair a Linux filesystem. filesys is either the device name (such as /dev/hda1 or /dev/ sdb2) or the mount point (such as /, /usr, or /home) for the filesystem. If this fsck has several filesystems on different physical disk drives to check, this fsck will try to run them in parallel. This reduces the total amount time it takes to check all of the filesystems because fsck takes advantage of the parallelism of multiple disk spindles.

The exit code returned by fsck is the sum of the following conditions:

0	No errors
1	Filesystem errors corrected
2	System should be rebooted
4	Filesystem errors left uncorrected
8	Operational error
16	Usage or syntax error
128	Shared library error

The exit code returned when all filesystems are checked using the -A option is the bitwise OR of the exit codes for each file system that is checked.

In actuality, fsck is simply a front end for the various filesystem checkers (fsck.fstype) available under Linux. The filesystem-specific checker is searched for in /sbin first, then in /etc/fs and /etc, and finally in the directories listed in the PATH environment variable. Please see the filesystem-specific checker manual pages for further details.

OPTIONS

-A	Walk through the /etc/fstab file and try to check all filesystems in one run. This
	option is typically used from the /etc/rc system initialization file, instead of
	multiple commands for checking a single file system.
-R	When checking all filesystems with the -A flag, skip the root file system (in case it’s
	already mounted read-write).
-T	Don’t show the title on startup.
-N	Don’t execute; just show what would be done.
-s	Serialize fsck operations. This is a good idea if you checking multiple filesystems in
	and the checkers are in an interactive mode. (Note: e2fsck runs in an interactive
	mode by default. To make e2fsck run in a non-interactive mode, you must either
	specify the -p or -a option, if you want errors to be corrected automatically, or the -
	n option if you do not.)
-V	Produce verbose output, including all filesystem-specific commands that are
	executed.
-tfstype	Specifies the type of filesystem to be checked. When the -A flag is specified, only
	filesystems that match fstype are checked. If fstype is prefixed with no, only
	filesystems whose filesystem do not match fstype are checked.
	Usually, the filesystem type is deduced by searching for filesys in the /etc/fstab
	file and using the corresponding entry. If the type can not be deduced, fsck will use
	the type specified by the -t option if it specifies a unique filesystem type. If this type
	is not available, the the default filesystem type (currently ext2) is used.
fs-options	Any options that are not understood by fsck, or that follow the - option are treated
	as filesystem-specific options to be passed to the filesystem-specific checker.

		Part VIII: Administration and Privileged Commands
	1300

Currently, standardized filesystem-specific options are somewhat in flux. Although not guaranteed, the following options are supported by most filesystem checkers:

-a	Automatically repair
	that e2fsck supports
	option, which is safe

the filesystem without any questions. (Use this option with caution.) Note -a for backwards compatibility only. This option is mapped to e2fsck’s -p to use, unlike the -a option that most filesystem checkers support.

-r	Interactively repair the filesystem (ask for confirmations). Note: It is generally a bad idea to use
	this option if multiple fsck’s are run in parallel. Also note that this is e2fsck default behavior; it
	supports this option for backwards compatibility reasons only.

AUTHOR

Theodore Ts’o ([e-mail])

The manual page was shamelessly adapted from David Engel and Fred van Kempen’s generic fsck front-end program, which in turn was shamelessly adapted from Remy Card’s version for the ext2 filesystem.

FILES

/etc/fstab

SEE ALSO

fstab(5), mkfs(8), fsck.minix(8), fsck.ext2(8) or e2fsck(8), fsck.xiafs(8)

Version 0.5b, November 1994

fsck.minix

fsck.minix—A filesystem consistency checker for Linux.

SYNOPSIS

fsck.minix [ -larvsmf ] device

DESCRIPTION

fsck.minix performs a consistency check for the Linux MINIX filesystem. The current version supports the 14 character and 30 character filename options.

The program assumes the filesystem is quiescent. fsck.minix should not be used on a mounted device unless you can be sure nobody is writing to it (and remember that the kernel can write to it when it searches for files).

The device will usually have the following form:

/dev/hda[1-8] /dev/hdb[1-8] /dev/sda[1-8] /dev/sdb[1-8]

If the filesystem was changed (that is, repaired), then fsck.minix will print File system has changed and will sync(2) three times before exiting. Because Linux does not currently have raw devices, there is no need to reboot at this time (versus a system that does have raw devices).

WARNING

fsck.minix should not be used on a mounted filesystem. Using fsck.minix on a mounted filesystem is very dangerous due to the possibility that deleted files are still in use and can seriously damage a perfectly good filesystem! If you absolutely have to run fsck.minix on a mounted filesystem (that is, the root filesystem), make sure nothing is writing to the disk and that no files are “zombies” waiting for deletion.

	ftpd
		1301
OPTIONS
-l	Lists all filenames.
-r	Performs interactive repairs.
-a	Performs automatic repairs (this option implies -r) and serves to answer all of the questions asked with the
	default. Note that this can be extremely dangerous in the case of extensive filesystem damage.
-v	Verbose.
-s	Outputs super-block information.
-m	Activates MINIX-like “mode not cleared” warnings.
-f	Force filesystem check even if the filesystem was marked as valid. (This marking is done by the kernel
	when the filesystem is unmounted.)

SEE ALSO

fsck(8), fsck.ext(8), fsck.ext2(8), fsck.xiafs(8), mkfs(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8), reboot(8)

DIAGNOSTICS

There are numerous diagnostic messages. The ones mentioned here are the most commonly seen in normal usage.

If the device does not exist, fsck.minix will print Unable to read super block. If the device exists but is not a MINIX filesystem, fsck.minix will print Bad magic number in super-block.

EXIT CODES

The exit code returned by fsck.minix is the sum of the following:

0	No errors.

3Filesystem errors corrected; system should be rebooted if filesystem was mounted.

4Filesystem errors left uncorrected.

8	Operational error.
16	Usage or syntax error.

In point of fact, only 0, 3, 4, 7, 8, and 16 can ever be returned.

AUTHOR

Linus Torvalds ([e-mail]). Error code values by Rik Faith ([e-mail]). Added support for filesystem valid flag: Dr. Wettstein ([e-mail]). Check to prevent fsck of mounted filesystem added by Daniel Quinlan ([e-mail]).

Linux 0.99, 10 January 1994

ftpd

ftpd—DARPA Internet File Transfer Protocol server.

SYNOPSIS

ftpd [-d] [-l] [-t timeout] [-T maxtimeout]

DESCRIPTION

ftpd is the DARPA Internet File Transfer Protocol server process. The server uses the TCP protocol and listens at the port specified in the FTP service specification; see services(5).

		Part VIII: Administration and Privileged Commands
1302
	Available options:

-d	Debugging information is written to the syslog.
-l	Each FTP 1 session is logged in the syslog.
-t	The inactivity timeout period is set to timeout seconds. (The default is 15 minutes.)
-T	A client can also request a different timeout period; the maximum period allowed can be set to timeout
	seconds with the -T option. The default limit is 2 hours.

The FTP server currently supports the following FTP requests; case is not distinguished.

Request	Description
ABOR	Abort previous command
ACCT	Specify account (ignored)
ALLO	Allocate storage (vacuously)
APPE	Append to a file
CDUP	Change to parent of current working directory
CWD	Change working directory
DELE	Delete a file
HELP	Give help information
LIST	Give list files in a directory (‘’ ls -lgA ‘’)
MKD	Make a directory
MDTM	Show last modification time of file
MODE	Specify data transfer mode
NLST	Give name list of files in directory
NOOP	Do nothing
PASS	Specify password
PASV	Prepare for server-to-server transfer
PORT	Specify data connection port
PWD	Print the current working directory
QUIT	Terminate session
REST	Restart incomplete transfer
RETR	Retrieve a file
RMD	Remove a directory
RNFR	Specify rename-from filename
RNTO	Specify rename-to filename
SITE	Nonstandard commands (see next section)
SIZE	Return size of file
STAT	Return status of server
STOR	Store a file
STOU	Store a file with a unique name
STRU	Specify data transfer structure
SYST	show operating system type of server system
TYPE	specify data transfer type
USER	specify username
XCUP	change to parent of current working directory (deprecated)

ftpd 1303

Request	Description
XCWD	change working directory (deprecated)
XMKD	make a directory (deprecated)
XPWD	print the current working directory (deprecated)
XRMD	remove a directory (deprecated)

The following non-standard or UNIX-specific commands are supported by the SITE request:

Request

Description

Example

UMASK	Change umask
IDLE	Set idle timer
CHMOD	Change mode of a file
HELP	Give help information

SITE UMASK 002 SITE IDLE 60 SITE CHMOD 755 SITE HELP

The remaining FTP requests specified in Internet RFC 959 are recognized but not implemented. MDTM and SIZE are not specified in RFC 959 but will appear in the next updated FTP RFC.

The FTP server will abort an active file transfer only when the ABOR command is preceded by a Telnet “Interrupt Process” (IP) signal and a Telnet “Synch” signal in the command Telnet stream, as described in Internet RFC 959. If a STAT command is received during a data transfer, preceded by a Telnet IP and Synch, transfer status will be returned.

ftpd interprets filenames according to the globbing conventions used by csh(1). This allows users to utilize the metacharacters Li &*?[].

ftpd authenticates users according to four rules:

The username must be in the password database and not have a null password. In this case, a password must be provided by the client before any file operations may be performed.

The username must not appear in the file (see ftpusers(5)).

The user must have a standard shell returned by getusershell(3).

If the username is anonymous or FTP, an anonymous FTP account must be present in the password file (user FTP). In this case, the user is allowed to log in by specifying any password. (By convention, this is given as the client host’s name.)

In the last case, ftpd takes special measures to restrict the client’s access privileges. The server performs a chroot(2) command to the home directory of the FTP user. So that system security is not breached, it is recommended that the FTP subtree be constructed with care; the following rules are recommended:

~ftp	Make the home directory owned by root and unwritable by anyone.
~ftp/bin	Make this directory owned by root and unwritable by anyone. The program ls(1) must be present to
	support the list command. This program should have mode 111.
~ftp/etc	Make this directory owned by root and unwritable by anyone. The files passwd(5) and group(5) must be
	present for the ls command to be able to produce owner names rather than numbers. The password field
	in passwd is not used and should not contain real encrypted passwords. These files should be mode 444 and
	owned by root. Don’t use the system’s /etc/passwd file as the password file or the system’s /etc/group file
	as the group file in the ~ftp/etc directory.
Pa ~ftp/pub	Make this directory mode 755 and owned by root. Create a subdirectory in ~ftp/pub with the appropriate
	mode (777 or 733) if you want to allow normal users to upload files.

SEE ALSO

ftp(1), getusershell(3), ftpusers(5), syslogd(8)

BUGS

The anonymous account is inherently dangerous and should avoided when possible.

		Part VIII: Administration and Privileged Commands
	1304

The server must run as the super-user to create sockets with privileged port numbers. It maintains an effective user ID of the logged-in user, reverting to the super-user only when binding addresses to sockets. The possible security holes have been extensively scrutinized but are possibly incomplete.

HISTORY

The command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

ifconfig

ifconfig—Configure a network interface.

SYNOPSIS

ifconfig [interface]

ifconfig interface [aftype] options | address ...

DESCRIPTION

ifconfig is used to set up (and maintain thereafter) the kernel-resident network interfaces. It is used at boot time to configure most of them to a running state. After that, it is usually only needed when debugging or when system tuning is needed.

If no arguments are given, ifconfig just displays the status of the currently defined interfaces. If the single interface argument is given, it displays the status of the given interface only. Otherwise, it assumes that things have to be set up.

ADDRESS FAMILIES

If the first argument after the interface name is recognized as the name of a supported address family, that address family is used for decoding and displaying all protocol addresses. Currently supported address families include inet (TCP/IP, default) and ax25 (AMPR Packet Radio.)

OPTIONS

interface	The name of the NET interface. This usually is a name such as wd0, sl3, or something like that:
	a device driver name followed by a unit number.
up	This flag causes the interface to be activated. It is implicitly specified if the interface is given a
	new address (see below).
down	This flag causes the driver for this interface to be shut down and is useful when things start
	going wrong.
[-]arp	Enable or disable the use of the ARP protocol on this interface. If the minus (–) sign is present,
	the flag is turned OFF.
[-]trailers	Enable or disable the use of trailers on Ethernet frames. This is not used in the current
	implementation of NET.
[-]allmulti	Enable or disable the promiscuous mode of the interface. This means that all incoming frames
	get sent to the network layer of the system kernel, allowing for networking monitoring.
metric N	This parameter sets the interface metric. It is not used at present, but we implement it for the
	future.
mtu N	This parameter sets the Maximum Transfer Unit (MTU) of an interface. For Ethernet, this is a
	number in the range of 1000-2000 (default is 1500). For SLIP, use something between 200 and
	4096. Note that the current implementation does not handle IP fragmentation yet, so you’d
	better make the MTU large enough!
dstaddr addr	Set the “other end’s” IP address in case of a point-to-point link, such as PPP. This keyword is
	obsoleted by the new pointopoint keyword.

inetd 1305

netmask addr

Set the IP network mask for this interface. This value defaults to the usual class A, B, or C network mask (as deducted from the interface IP address), but it can be set to any value for the use of subnetting.

[-]broadcast [addr]	If the address argument is also given, set the protocol broadcast address for this interface.
	Otherwise, it only sets the IFF_BROADCAST flag of the interface. If the keyword was preceded by a
	minus (-) sign, then the flag is cleared instead.
[-]pointopoint [addr]	This keyword enables the point-to-point mode of an interface, meaning that it is a direct link
	between two machines with nobody else listening on it. (At least we hope that this is the case,
	grin :-).)
	If the address argument is also given, set the protocol address of the other side of the link, just
	like the obsolete dstaddr keyword does. Otherwise, it only sets the IFF_POINTOPOINT flag of the
	interface. If the keyword was preceded by a minus (-) sign, then the flag is cleared instead.
hw	Set the hardware address of this interface if the device driver supports this operation. The
	keyword must be followed by the name of the hardware class and the printable ASCII
	equivalent of the hardware address. Hardware classes currently supported include ether
	(Ethernet), ax25 (AMPR AX.25), and ppp, although the latter is not really supported yet.
address	The hostname or IP address (a hostname will be resolved into an IP address) of that interface.
	This parameter is required, although the syntax doesn’t currently require it.

FILES

/dev/net/socket

BUGS

None so far, although the syntax checking could be better.

AUTHOR

Fred N. van Kempen ([e-mail])

6 October 1993

inetd

inetd—Internet superserver.

SYNOPSIS

inetd [-d] [configuration file]

DESCRIPTION

inetd should be run at boot time by /etc/rc.local (see rc(8)). It then listens for connections on certain Internet sockets. When a connection is found on one of its sockets, it decides what service the socket corresponds to and invokes a program to service the request. After the program is finished, it continues to listen on the socket (except in some cases, which are described later). Essentially, inetd allows running one daemon to invoke several others, reducing load on the system.

The option available for inetd:

-d	Turns on debugging.

Upon execution, inetd reads its configuration information from a configuration file, which, by default, is /etc/inetd.conf. There must be an entry for each field of the configuration file, with entries for each field separated by a tab or a space. Comments are denoted by a # at the beginning of a line. There must be an entry for each field. The fields of the configuration file are as follows:

		Part VIII: Administration and Privileged Commands
	1306

service name

socket type

protocol

wait/nowait[.max]

user[.group]

server program

server program arguments

To specify an Sun-RPC based service, the entry would contain these fields:

service name/version

socket type

rpc/protocol

wait/nowait[.max]

user[.group]

server program

server program arguments

The service-name entry is the name of a valid service in the file /etc/services . For internal services, the service name must be the official name of the service (that is, the first entry in /etc/services). When used to specify a Sun-RPC based service, this field is a valid RPC service name in the file /etc/rpc. The part on the right of the / is the RPC version number. This can simply be a single numeric argument or a range of versions. A range is bounded by the low version to the high version

- rusers/1-3.

The socket type should be one of stream, dgram, raw, rdm, or seqpacket, depending on whether the socket is a stream, datagram, raw, reliably delivered message, or sequenced packet socket.

The protocol must be a valid protocol as given in /etc/protocols. Examples might be tcp or udp. Rpc-based services are specified with the rpc/tcp or rpc/udp service type.

The wait/nowait entry is applicable to datagram sockets only. (Other sockets should have a nowait entry in this space.) If a datagram server connects to its peer, freeing the socket so inetd can receive further messages on the socket, it is said to be a multithreaded server and should use the nowait entry. For datagram servers that process all incoming datagrams on a socket and eventually time out, the server is said to be single-threaded and should use a wait entry. Comsat(8), biff(1), and talkd(8) are examples of the latter type of datagram server. Tftpd(8) is an exception; it is a datagram server that establishes pseudoconnections.

It must be listed as wait in order to avoid a race; the server reads the first packet, creates a new socket, and then forks and exits to allow inetd to check for new service requests to spawn new servers. The optional max suffix (separated from wait or nowait by a dot) specifies the maximum number of server instances that may be spawned from inetd within an interval of 60 seconds. When omitted, max defaults to 40.

The user entry should contain the username of the user as whom the server should run. This allows for servers to be given less permission than root. An optional group name can be specified by appending a dot to the username followed by the group name. This allows for servers to run with a different (primary) group ID than specified in the password file. If a group is specified and the user is not root, the supplementary groups associated with that user will still be set.

The server-program entry should contain the pathname of the program that is to be executed by inetd when a request is found on its socket. If inetd provides this service internally, this entry should be internal.

The server program arguments should appear just as arguments normally do, starting with argv[0], which is the name of the program. If the service is provided internally, the word internal should take the place of this entry.

inetd provides several trivial services internally by use of routines within itself. These services are echo, discard, chargen (character generator), daytime (human readable time), and time (machine readable time in the form of the number of seconds since midnight, January 1, 1900). All of these services are TCP based. For details of these services, consult the appropriate RFC from the Network Information Center.

init, telinit	1307

inetd rereads its configuration file when it receives a hangup signal, SIGHUP. Services may be added, deleted, or modified when the configuration file is reread. inetd creates a file /etc/inetd.pid that contains its process identifier.

SEE ALSO

comsat(8), fingerd(8), ftpd(8), rexecd(8), rlogind(8), rshd(8), telnetd(8), tftpd(8)

HISTORY

The command appeared in BSD 4.3. Support for Sun-RPC based services is modeled after that provided by Sun-OS 4.1.

BSD 4.3, 16 March 1991

init, telinit

init, telinit—Process control initialization.

SYNOPSIS

/sbin/init [ -t sec ][0123456SsQq ] /sbin/telinit [ -t sec ][0123456sSQqabc ]

DESCRIPTION

init

init is the father of all processes. Its primary role is to create processes from a script stored in the file /etc/inittab (see inittab(5)). This file usually has entries that cause init to spawn gettys on each line that users can log in. It also controls autonomous processes required by any particular system.

A run level is a software configuration of the system that allows only a selected group of processes to exist. The processes spawned by init for each of these run levels are defined in the /etc/inittab file. init can be in one of eight run levels, 06 and S or s. The run level is changed by having a privileged user run /sbin/telinit, which sends appropriate signals to init, telling it which run level to change to.

After init is invoked as the last step of the kernel booting, it looks for the file /etc/inittab to see if there is an entry of the type initdefault (see inittab(5)). initdefault determines the initial run level of the system. If there is no such entry or no /etc/inittab at all, a run level must be entered at the system console.

Run level S or s brings the system to single-user mode and does not require an /etc/initttab file. In single-user mode,

/bin/sh is invoked on /dev/console.

/dev/console need not necessarily be the physical system console. When init is told to enter single-user mode or run level 1 (either directly, by init S, or by telling shutdown to enter maintenance mode), it will link the terminal line the command was executed from to /dev/console. The device /dev/systty is called the physical system console and the device /dev/console is called the logical system console. If the logical system console is not the physical system console, pressing the combination Ctrl+Alt+Del on the physical system console will force a relink of /dev/console to /dev/systty. A terminal line can only become the logical console if it’s listed in the file /etc/securetty. All this is in preparation of the day that the Linux kernel will support serial consoles.

Beware: If you want to run X or anything else that is aware of Virtual Consoles, the logical system console (/dev/console) needs to be the same as the physical system console (/dev/systty).

When entering single-user mode, init reads the console’s ioctl(2) states from /etc/ioctl.save. If this file does not exist, init initializes the line at 9600 baud and with CLOCAL settings. When init leaves single-user mode, it stores the console’s ioctl settings in this file so it can re-use them for the next single-user session. If the logical system console is changed to another terminal line, the settings of the line from which the init or telinit command was given are stored in /etc/ioctl.save too, so that the terminal line will be initialized correctly in single-user mode.

		Part VIII: Administration and Privileged Commands
	1308

When entering a multi-user mode the first time, init performs the boot and bootwait entries to allow filesystems to be mounted before users can log in. Then all entries matching the run level are processed.

Each time a child terminates, init records the fact and the reason it died in /etc/utmp and /var/adm/wtmp if these files exist.

After it has spawned all the processes specified, init waits for one of its descendant processes to die, a powerfail signal, or a signal by /sbin/telinit to change the system’s run level. When one of these three conditions occurs, it re-examines the /etc/inittab file. New entries can be added to this file at any time. However, init still waits for one of the three conditions to occur. To provide for an instantaneous response, the Q or q command can wake up init to re-examine the /etc/inittab file.

If init is not in single-user mode and receives a powerfail signal, special powerfail entries are invoked.

When init is requested to change the run level, it sends the warning signal SIGTERM to all processes that are undefined in the new run level. It then waits 20 seconds before forcibly terminating these processes via the kill signal SIGKILL.

Note that init assumes that all these processes (and their descendants) remain in the same process group that init originally created for them. If any process changes its process group affiliation, it will not receive these signals. Such processes need to be terminated separately.

telinit

/sbin/telinit is linked to /sbin/init. It takes a one-character argument and signals init to perform the appropriate action. The following arguments serve as directives to /sbin/telinit:

0, 1, 2, 3, 4, 5, or 6	Tell /sbin/init to switch to the specified run level.
a, b, c	Tell /sbin/init to process only those /etc/inittab file entries having run level a, b, or c.
Q or q	Tell /sbin/init to re-examine the /etc/inittab file.
S or s	Tell /sbin/init to switch to single-user mode.

/sbin/telinit can also tell init how much time it should wait between sending processes the TERM and the KILL signal; the default is 20 seconds, but it can be changed by the -t sec option.

/sbin/telinit can be invoked only by users with appropriate privileges.

RUN LEVELS

Run levels 0, 1, and 6 are reserved. Run level 0 is used to halt the system, run level 6 is used to reboot the system, and run level 1 is used to get the system down into single-user mode. Run level S is not really meant to be used directly but should be used by scripts that are executed when entering run level 1. For more information on this, see the man pages for shutdown(1) and inittab(5).

FILES

/etc/inittab

/dev/console

/dev/systty

/etc/ioctl.save

/etc/utmp

/var/adm/wtmp

CONFORMING TO

init is compatible with the System V init. The scripts that are used with it, however, are mostly modeled after the BSD startup scripts. There are startup scripts available that let Linux boot more like a System V system, but most people find them too complex.

WARNINGS

init assumes that processes and descendants of processes remain in the same process group that was originally created for them. If the processes change their group, init can’t kill them and you might end up with two processes reading from one terminal line.

innd, inndstart	1309

DIAGNOSTICS

If /sbin/init finds that it is continuously respawning an entry more than ten times in two minutes, it will assume that there is an error in the command string, generate an error message on the system console, and refuse to respawn this entry until either five minutes has elapsed or it receives a signal. This prevents it from eating up system resources when someone makes a typographical error in the /etc/inittab file or the program for the entry is removed.

AUTHOR

Miquel van Smoorenburg ([e-mail]); initial manual page by Michael Haardt ([e-mail]).

SEE ALSO

getty(1), login(1), sh(1), who(1), shutdown(1), kill(2), inittab(5), utmp(5)

19 January 1994

innd, inndstart

innd, inndstart—InterNetNews daemon.

SYNOPSIS

innd [ -a ][-c days ][-d ][-f ][-i count ][-o count ][-l size ]

[-m mode ][-n flag ] [ -p port ][-r ][-s ][-S host ][-t timeout ][-u ][-x ] inndstart [ flags ]

DESCRIPTION

innd, the InterNetNews daemon, handles all incoming NNTP feeds. It reads the active(5), newsfeeds(5), and hosts.nntp(5) files into memory. It then opens the NNTP port to receive articles from remote sites, a UNIX-domain stream socket to receive articles from local processes such as nnrpd(8) and rnews(1), and a UNIX-domain datagram socket for use by ctlinnd(8) to direct the server to perform certain actions. It also opens the history(5) database and two log files to replace its standard output and standard error. If the –p flag is used, then the NNTP port is assumed to be open on the specified descriptor. (If this flag is used, then innd assumes it is running with the proper permissions and it does not call chown(2) on any files or directories it creates.)

Once the files and sockets have been opened, innd waits for connections and data to be ready on its ports by using select(2) and non-blocking I/O. If no data is available, then it flushes its in-core data structures. The default number of seconds to time out before flushing is 300. This timeout may be changed by using the –t flag.

To limit the number of incoming NNTP connections, use the –i flag. A value of 0 suppresses this check.

To limit the number of files that are kept open for outgoing file feeds, use the –o flag. The default is the number of available descriptors minus some reserved for internal use.

To limit the size of an article, use the –l flag. If this flag is used, then any article bigger than size bytes is rejected. The default is no checking, which can also be obtained by using a value of 0.

innd rejects articles that are too old. Although this behavior can be controlled by the history database, occasionally a site dumps a batch of very old news back onto the network. Use the –c flag to specify a cutoff. For example, –c21 rejects any articles that were posted more than 21 days ago. A value of 0 suppresses this check.

innd usually puts itself into the background, sets its standard output and error to log files, and disassociates itself from the terminal. Using the –d flag instructs the server to not do this, whereas using the –f flag just leaves the server running the foreground. The logs are usually buffered; use the –u flag to have them unbuffered.

To start the server in a paused or throttled state (see ctlinnd(8)) use the –m flag to set the initial running mode. The argument should start with a single letter g, p, or t to emulate the go, pause, or throttle commands.

		Part VIII: Administration and Privileged Commands
	1310

If the –r flag is used, the server renumbers the active file as if a renumber command were sent.

If the –s flag is used, then innd does not do any work but instead just checks the syntax of the news-feeds file. It exits with an error status if there are any errors; the actual errors are reported in syslog(3).

If innd gets an NOSPC error (see intro(2)) while trying to write the active file, an article file, or the history database, it sends itself a throttle command. This also happens if it gets too many I/O errors while writing to any files.

Any subprocesses spawned by the server get a nice(2) value of 10.

The –n flag specifies whether pausing or throttling the server should also disable future news-reading processes. A value of y makes news readers act as the server, a value of n allows news reading even when the server is not running.

If the –S flag is used, then innd runs in slave mode. When running as a slave, the server only accepts articles from the specified host, which must use the xreplic protocol extension. Note that either the host must appear in the hosts.nntp file or the server must be started with the –a flag.

By default, if a host is not mentioned in the hosts.nntp file, then the connection is handed off to nnrpd. If the –a flag is used, then any host can connect and transfer articles.

If the –x flag is used, then a Xref header is added to all articles even if they are not cross-posted.

inndstart is a small front-end program that opens the NNTP port, sets its user ID and group ID to the news maintainer, and then executes innd with the –p flag and a minimal secure environment. This is a small, easily understood front-end program that can be used if a site does not want to run innd with root privileges.

CONTROL MESSAGES

Arriving articles that have a Control header or have a Subject header that starts with the five characters cmsg are called control messages. Except for the cancel message, these messages are implemented by external programs in the /news/bin/control directory. (Cancel messages update the history database, so they must be handled internally; the cost of synching, locking, and then unlocking is too high, given the number of cancel messages that are received.)

When a control message arrives, the first word of the text is converted to lowercase and used as the name of the program to execute; if the named program does not exist, then a program named default is executed.

All control programs are invoked with four parameters. The first is the address of the person who posted the message; this is taken from the Sender header. If that header is empty, then it is taken from the From header. The second parameter is the address to send replies to; this is taken from the Reply-To header. If that header is empty, then the poster’s address is used. The third parameter is a name under which the article is filed, relative to the news spool directory. The fourth parameter is the host that sent the article, as specified on the Path line.

The distribution of control message is also different from those of standard articles.

Control messages are usually filed in the newsgroup named control. They can be filed in subgroups, however, based on the control message command. For example, a newgroup message is filed in control.newgroup if that group exists, otherwise it will be filed in control.

Sites may explicitly have the “control” newsgroup in their subscription list, although it is usually best to exclude it. If a control message is posted to a group whose name ends with the four characters .ctl, then the suffix is stripped off and what is left is used as the group name. For example, a cancel message posted to news.admin.ctl will be sent to all sites that subscribe to control or news.admin. newgroup and rmgroup messages receive additional special treatment. If the message is approved and posted to the name of the group being created or removed, then the message is sent to all sites whose subscription patterns would cause them to receive articles posted in that group.

If an article is posted to a newsgroup that starts with the three letters to., it gets special treatment if the newsgroup does not exist in the active file. The article is filed into the newsgroup to and it is sent to the first site named after the prefix. For example, a posting to to.uunet is filed in to and sent to the site uunet.

PROTOCOL DIFFERENCES

innd implements the NNTP commands defined in RFC 977 with the following differences:

site...

innd, inndstart	1311

■The list may be followed by an optional active, active.times, or newsgroups argument. This common extension is not fully supported; see nnrpd(8).

■The authinfo user and authinfo pass commands are implemented. These are based on the reference UNIX implementation; no other documentation is available.

■A new command, mode reader, is provided. This command causes the server to pass the connection on to nnrpd. The command mode query is intended for future use and is currently treated the same way.

■A new command, xreplic news.group:art[,news.group:art], is provided. This is similar to the ihave command (the same reply codes are used) except for the data that follows the command word. The data consists of entries separated by a single comma. Each entry consists of a newsgroup name, a colon, and an article number. Once processed, the article is filed in the newsgroup and article numbers specified in the command.

■A new command, xpath messageid, is provided. The server responds with a 223 response and a space-separated list of filenames where the article was filed.

■The only other commands implemented are head, help, ihave, quit, and stat.

HEADER MODIFICATIONS

innd modifies as few article headers as possible, although it could be better in this area.

The following headers, if present, are removed:

Date-Received

Posted

Posting-Version

Received

Relay-Version

Empty headers and headers that consist of nothing but whitespace are also dropped.

The local site’s name and an exclamation point are prepended to the Path header.

The Xref header is removed. If the article is cross-posted, a new header is generated.

The Lines header is added if it is missing.

innd does not rewrite incorrect headers. For example, it does not replace an incorrect Lines header but rejects the article.

LOGGING

innd reports all incoming articles in its log file. This is a text file with a variable number of space-separated fields in one of the following formats:

mon dd hh:mm:ss.mmm + feed <Message-ID>site...

mon dd hh:mm:ss.mmm j feed <Message-ID> site...

mon dd hh:mm:ss.mmm c feed <Message-ID> site...

mon dd hh:mm:ss.mmm - feed <Message-ID> reason...

The first three fields are the date and time to millisecond resolution. The fifth field is the site that sent the article (based on the Path header), and the sixth field is the article’s Message-ID; they will contain a question mark if the information is not available.

The fourth field indicates whether the article was accepted. If it is a plus sign, the article was accepted. If it is the letter j, the article was accepted, but all of newsgroups have a j in their active field, so the article was filed into the “junk” newsgroup. If the fourth field is the letter c, a cancel message was accepted before the original article arrived. In all three cases, the article has been accepted and the field contains the space-separated list of sites to which the article is sent.

If the fourth field is a minus sign, the article was rejected. The reasons for rejection include

%s header too long

%s wants to cancel <%s> by %s

Article exceeds local limit of %s bytes

Article posted in the future—%s

		Part VIII: Administration and Privileged Commands
	1312

Bad %s header

Can’t write history

Duplicate

Duplicate %s header

EOF in headers

Linecount %s != %s +- %s

Missing %s header

No body

No colon-space in %s header

No space

Space before colon in %s header

Too old—%s

Unapproved for %s

Unwanted newsgroup %s

Unwanted distribution %s

Whitespace in “Newsgroups” header—%s

Where %s, above, is replaced by more specific information.

Note that if an article is accepted and none of the newsgroups are valid, it is logged with both two lines, a j line and a minus sign line.

innd also makes extensive reports through syslog. The first word of the log message is the name of the site if the entry is sitespecific (such as a connected message). The first word is ME if the message relates to the server itself, such as when a read error occurs.

If the second word is the four letters cant, an error is being reported. In this case, the next two words generally name the system call or library routine that failed and the object upon which the action was performed. The rest of the line might contain other information.

In other cases, the second word attempts to summarize what change has been made, and the rest of the line gives more specific information. The word internal generally indicates an internal logic error.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

active(5), ctlinnd(8), dbz(3z), history(5), hosts.nntp(5), inn.conf(5), newsfeeds(5), nnrpd(8), rnews(1), syslog(8)

innxmit

innxmit—Send Usenet articles to a remote NNTP server.

SYNOPSIS

innxmit [ -A alt_spool ][-a ][-d ][-M ][-r ][-t timeout ] [-T timeout ][-p ][-S ] host file

DESCRIPTION

innxmit connects to the NNTP server at the specified host and sends it the articles specified in the batchfile named file. It is usually invoked by a script run out of cron(8) that uses shlock(1) to lock the hostname, followed by actlinnd(8) command to flush the batchfile.

Message-Id

ipcrm 1313

innxmit usually blocks until the connection is made. To specify a timeout on how long to try to make the connection, use the –t flag. To specify the total amount of time that should be allowed for article transfers, use the –T flag. The default is to wait until an I/O error occurs or all the articles have been transferred. If the –T flag is used, the time is checked just before an article is started; it does not abort a transfer that is in progress. Both values are measured in seconds.

If the file is not an absolute pathname, it is taken relative to the /news/spool/out.going directory. It is usually written by specifying the Wnm flags in the newsfeeds(5) file. Each line in the batchfile should be in one of the following formats:

filename Message-ID

filename

The filename field names the article to be sent. If it is not an absolute pathname, it is taken relative to the news spool directory, /news/spool. If the Message-ID field is not specified, it is obtained by scanning the article. The filename and

fields are separated by a space.

If a communication error such as a write(2) failure occurs, innxmit stops sending and rewrites the batchfile to contain the current article and any other unsent articles.

If the remote server sends an unexpected reply code, innxmit requeues the article and proceeds. Use the –r flag if the article should not be requeued.

Upon exit, innxmit reports transfer and CPU usage statistics via syslog(3). If the –v flag is used, they are also printed on the standard output. If all articles were sent successfully, innxmit removes the batchfile; otherwise, it rewrites it to contain the list of unsent articles. If no articles were sent or rejected, the file is left untouched. This can cause the batchfile to grow excessively large if many articles have been expired and there are communication problems. To always rewrite the batchfile, use the –a flag. If the –p flag is given, then no connection is made and the batchfile is purged of entries that refer to files that no longer exist. This implies the –a flag.

If the –S flag is given, then innxmit offers articles to the specified host using the xreplic protocol extension described in innd(8). To use this flag, the input file must contain the history data (commas are transliterated to spaces by the server). For this flag to be used, the input must contain the necessary history entries. This is usually done by setting up a WnR entry in the newsfeeds file.

Use the –d flag to print debugging information on standard error. This shows the protocol transactions between innxmit and the NNTP server on the remote host.

If the –M flag is used, innxmit scans an article’s headers before sending it. If the article appears to be a MIME article that is not in seven-bit format, the article is sent in “quoted-printable” form.

The –A flag may be used to specify an alternate spool directory to use if the article is not found; this is usually an NFSmounted spool directory of a master server with longer expiration times.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

ctlinnd(8), innd(8), newsfeeds(5), shlock(1)

ipcrm

ipcrm—Remove ipc facilities.

SYNOPSIS

ipcrm [ shm | msg | sem ] id

DESCRIPTION

ipcrm removes the resource specified by id.

		Part VIII: Administration and Privileged Commands
	1314

SEE ALSO

ipcs(8)

AUTHOR

Krishna Balasubramanian ([e-mail])

Linux 0.99, 9 October 1993

ipcs

ipcs—Provide information on ipc facilities.

SYNOPSIS

ipcs [ –asmq ] [ –tclup ] ipcs [ -smq ] -i id

ipcs –h

DESCRIPTION

ipcs provides information on the ipc facilities for which the calling process has read access.

The -i option allows a specific resource id to be specified. Only information on this id is printed.

Resources may be specified as follows:

-m	Shared memory segments
-q	Message queues
-s	Semaphore arrays
-a	All (this is the default)

The output format may be specified as follows:

-t	Time
-p	PID
-c	Creator
-l	Limits
-u	Summary

SEE ALSO

ipcrm(8)

AUTHOR

Krishna Balasubramanian ([e-mail])

Linux 0.99, 9 October 1993

kbdrate

kbdrate—Reset the keyboard repeat rate and delay time.

SYNOPSIS

kbdrate [ -s ] [ -r rate ][-d delay ]

klogd 1315

DESCRIPTION

kbdrate is used to change the IBM keyboard repeat rate and delay time. The delay is the amount of time that a key must be pressed before it starts to repeat. Using kbdrate without any options resets the rate to 10.9 characters per second (cps) and the delay to 250 milliseconds (ms). These are the IBM defaults.

OPTIONS

-s	Silent. No messages are printed.
-r rate	Change the keyboard repeat rate to rate cps. The allowable range is from 2.0 to 30.0 cps. Only certain
	specific values are possible, and the program selects the nearest possible value to the one specified. The
	possible values are given, in characters per second, as follows: 2.0, 2.1, 2.3, 2.5, 2.7, 3.0, 3.3, 3.7, 4.0, 4.3,
	4.6, 5.0, 5.5, 6.0, 6.7, 7.5, 8.0, 8.6, 9.2, 10.0, 10.9, 12.0, 13.3, 15.0, 16.0, 17.1, 18.5, 20.0, 21.8, 24.0,
	26.7, 30.0.
-d delay	Change the delay to delay milliseconds. The allowable range is from 250 to 1000 ms, but the only possible
	values (based on hardware restrictions) are 250 ms, 500 ms, 750 ms, and 1000 ms.

BUGS

Not all keyboards support all rates.

Not all keyboards have the rates mapped in the same way.

Setting the repeat rate on the Gateway AnyKey keyboard does not work. If someone with a Gateway figures out how to program the keyboard, please send mail to [e-mail].

FILES

/etc/rc.local

/dev/port

AUTHOR

Rik Faith ([e-mail])

Linux 1.1.19, 22 June 1994

klogd

klogd—Kernel log daemon.

SYNOPSIS

klogd –c [n] –d –f [fname] –os

DESCRIPTION

klogd is a system daemon that intercepts and logs Linux kernel messages.

OPTIONS

-c	Sets the default log level of console messages to [n].
-d	Enables debugging mode. This will generate a lot of output to stderr.
-f	Logs messages to the specified filename rather than to the syslog facility.
-o	Execute in one–shot mode. This causes klogd to read and log all the messages that are found in the kernel
	message buffers. After a single read and log cycle, the daemon exits.
-s	Force klogd to use the system call interface to the kernel message buffers.

		Part VIII: Administration and Privileged Commands
	1316

OVERVIEW

The functionality of klogd has been typically incorporated into other versions of syslogd, but this seems to be a poor place for it. In the modern Linux kernel, a number of kernel messaging issues such as sourcing and prioritization must be addressed. Incorporating kernel logging into a separate process appears to offer a cleaner separation of services.

In Linux, there are two potential sources of kernel log information: the /proc filesystem and the syscall (sys_syslog) interface, although ultimately they are one and the same. klogd is designed to choose whichever source of information is the most appropriate. It does this by first checking for the presence of a mounted /proc filesystem. If this is found, the /proc/kmsg file is used as the source of kernel log information. If the proc filesystem is not mounted, klogd uses a system call to obtain kernel messages. The command-line switch (–s) can be used to force klogd to use the system call interface as its messaging source.

If kernel messages are directed through the syslogd daemon, the klogd daemon, as of version 1.1, has the ability to properly prioritize kernel messages. Prioritization of the kernel messages was added at approximately the pl13 level of the kernel. The raw kernel messages are of the form:

<[0–7]>Something said by the kernel.

The priority of the kernel message is encoded as a single numeric digit enclosed inside the <> pair. The definitions of these values is given in the kernel include file kernel.h. When a message is received from the kernel, the klogd daemon reads this priority level and assigns the appropriate priority level to the syslog message. If file output (–f) is used, the prioritization sequence is left prepended to the kernel message.

The klogd daemon also allows the ability to alter the presentation of kernel messages to the system console. Consequent with the prioritization of kernel messages was the inclusion of default messaging levels for the kernel. In a stock kernel, the default console log level is set to 7. Any messages with a priority level numerically lower than 7 (higher priority) appear on the console.

Messages of priority level 7 are considered to be debug messages and do not appear on the console. Many administrators, particularly in a multi–user environment, prefer that all kernel messages be handled by klogd and either directed to a file or to the syslogd daemon. This prevents nuisance messages such as line printer out of paper or disk change detected from cluttering the console.

By default, the klogd daemon executes a system call to inhibit all kernel messages (except for panics) from being displayed on the console. The –c switch can be used to alter this behavior. The argument given to the –c switch specifies the priority level of messages that are directed to the console. Note that messages of a priority value lower than the indicated number are directed to the console.

For example, to have the kernel display all messages with a priority level of 3 (KERN ERR) or more severe, the following command is executed:

klogd –c 4

The definitions of the numeric values for kernel messages are given in the file kernel.h, which can be found in the /usr/include/linux directory if the kernel sources are installed. These values parallel the syslog priority values, which are defined in the file syslog.h, found in the /usr/include/sys subdirectory.

The klogd daemon can also be used in a one–shot mode for reading the kernel message buffers. One-shot mode is selected by specifying the –o switch on the command line. Output is directed to either the syslogd daemon or to an alternate file specified by the -f switch.

For example, to read all the kernel messages after a system boot and record them in a file called krnl.msg, the following command is given:

klogd -o -f ./krnl.msg

SIGNAL HANDLING

The klogd daemon responds to six signals: SIGHUP, SIGINT, SIGKILL, SIGTERM, SIGTSTP, and SIGCONT. The SIGINT, SIGKILL,

SIGTERM, and SIGHUP signals cause the daemon to close its kernel log sources and terminate gracefully.

lpc 1317

The SIGTSTP and SIGCONT signals are used to start and stop kernel logging. Upon receipt of a SIGTSTP signal, the daemon closes its log sources and spins in an idle loop. Subsequent receipt of a SIGCONT signal causes the daemon to go through its initialization sequence and rechoose an input source. Using SIGSTOP and SIGCONT in combination, the kernel log input can be rechosen without stopping and restarting the daemon. For example, if the /proc filesystem is to be unmounted, the following command sequence should be used:

#kill -TSTP pid

#umount /proc

#kill -CONT pid

Notations will be made in the system logs with LOG INFO priority documenting the start/stop of logging.

FILES

/proc/kmsg

BUGS

Probably numerous. Well-formed context diffs appreciated.

AUTHOR

Dr. Greg Wettstein ([e-mail]), Enjellic Systems Development, Oncology Research Division Computing Facility, Roger Maris Cancer Center, Fargo, ND 58122.

Version 1.1, 28 January 1994

lpc

lpc—Line printer control program.

SYNOPSIS

lpc [command [argument ...]]

DESCRIPTION

lpc is used by the system administrator to control the operation of the line printer system. For each line printer configured in

/etc/printcap, lpc may be used to

■Disable or enable a printer

■Disable or enable a printer’s spooling queue

■Rearrange the order of jobs in a spooling queue

■Find the status of printers and their associated spooling queues and printer daemons

Without any arguments, lpc prompts for commands from the standard input. If arguments are supplied, lpc interprets the first argument as a command and the remaining arguments as parameters to the command. The standard input may be redirected, causing lpc to read commands from file. Commands may be abbreviated; the following is the list of recognized commands:

? [ command ... ]help [ command ... ]

Print a short description of each command specified in the argument list or, if no arguments are given, a list of the recognized commands.

Ic abort No all - printer	Terminate an active spooling daemon on the local host immediately
	and then disable printing (preventing new daemons from being
	started by lpr) for the specified printers.

clean No all - printer

Remove any temporary files, data files, and control files that cannot be printed (that is, they do not form a complete printer job) from the specified printer queues on the local machine.

disable No all - printer	Turn the specified printer queues off. This prevents new printer jobs
	from being entered into the queue by lpr.

		Part VIII: Administration and Privileged Commands
	1318

Ic down No all - printer message ...	Turn the specified printer queue off, disable printing, and put message
	in the printer status file. The message doesn’t need to be quoted; the
	remaining arguments are treated like echo(1). This is usually used to
	take a printer down and let others know why lpq(1) indicates the
	printer is down and print the status message.
enable No all -- printer	Enable spooling on the local queue for the listed printers. This allows
	lpr(1) to put new jobs in the spool queue.
exit, quit	Exit from lpc.
restart all - printer	Attempt to start a new printer daemon. This is useful when some
	abnormal condition causes the daemon to die unexpectedly leaving
	jobs in the queue. lpq reports that there is no daemon present when
	this condition occurs. If the user is the super-user, try to abort the
	current daemon first (that is, kill and restart a stuck daemon).

start all - printer status No all - printer stop all - printer

Enable printing and start a spooling daemon for the listed printers. Display the status of daemons and queues on the local machine.

Stop a spooling daemon after the current job completes and disable printing.

topq printer [ jobnum ... ] [ user ... ] up all - printer

Place the jobs in the order listed at the top of the printer queue.

Enable everything and start a new printer daemon. Undoes the effects of down.

FILES

/etc/printcap	printer description file
/var/spool/*	spool directories
/var/spool/*/lock	lock file for queue control

SEE ALSO

lpd(8), lpr(1), lpq(1), lprm(1), printcap(5)

DIAGNOSTICS

?Ambiguous command

?Invalid command

?Privileged command

Abbreviation matches more than one command. No match was found.

Command can be executed by root only.

HISTORY

The lpc command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

lpd

lpd—Line printer spooler daemon.

SYNOPSIS

lpd [-l] [port#]

DESCRIPTION

lpd is the line printer daemon (spool area handler) and is usually invoked at boot time from the rc(8) file. It makes a single pass through the printcap(5) file to find out about the existing printers and prints any files left after a crash. It then uses the system calls listen(2) and accept(2) to receive requests to print files in the queue, transfer files to the spooling area, display

lpd 1319

the queue, or remove jobs from the queue. In each case, it forks a child to handle the request so the parent can continue to listen for more requests.

Available options:
-l	The -l flag causes lpd to log valid requests received from the network. This can be useful for
	debugging purposes.
port#	The Internet port number used to rendezvous with other processes is usually obtained with
	getservbyname(3) but can be changed with the port# argument.

Access control is provided by two means. First, all requests must come from one of the machines listed in the file /etc/ hosts.equiv or /etc/hosts.lpd. Second, if the rs capability is specified in the printcap entry for the printer being accessed, lpr requests are only honored for those users with accounts on the machine with the printer.

The file minfree in each spool directory contains the number of disk blocks to leave free so that the line printer queue won’t completely fill the disk. The minfree file can be edited with your favorite text editor.

The daemon begins processing files after it has successfully set the lock for exclusive access (described later) and scans the spool directory for files beginning with cf. Lines in each cf file specify files to be printed or non-printing actions to be performed. Each such line begins with a key character to specify what to do with the remainder of the line:

J	Job name. String to be used for the job name on the burst page.
C	Classification. String to be used for the classification line on the burst page.
L	Literal. The line contains identification info from the password file and causes the banner page
	to be printed.
T	Title. String to be used as the title for pr(1).
H	Host name. Name of the machine where lpr was invoked.
P	Person. Login name of the person who invoked lpr. This is used to verify ownership by lprm.
M	Send mail to the specified user when the current print job completes.
f	Formatted file. Name of a file to print which is already formatted.
l	Like f but passes control characters and does not make page breaks.
p	Name of a file to print using pr(1) as a filter.
t	Troff file. The file contains troff(1) output (cat phototypesetter commands).
n	Ditroff file. The file contains device independent troff output.
r	DVI file. The file contains Tex l output DVI format from Standford.
g	Graph file. The file contains data produced by plot(3).
c	Cifplot file. The file contains data produced by cifplot.
v	The file contains a raster image.
r	The file contains text data with FORTRAN carriage control characters.
1	Troff font R. Name of the font file to use instead of the default.
2	Troff font I. Name of the font file to use instead of the default.
3	Troff font B. Name of the font file to use instead of the default.
4	Troff font S. Name of the font file to use instead of the default.
W	Width. Changes the page width (in characters) used by pr(1) and the text filters.
I	Indent. The number of characters to indent the output by (in ASCII).
U	Unlink. Name of file to remove upon completion of printing.
N	Filename. The name of the file that is being printed or a blank for the standard input (when lpr
	is invoked in a pipeline).

If a file cannot be opened, a message is logged via syslog(3) using the LOG LPR facility. lpd tries up to 20 times to reopen a file it expects to be there, after which it skips the file to be printed.

		Part VIII: Administration and Privileged Commands
	1320

lpd uses flock(2) to provide exclusive access to the lock file and to prevent multiple daemons from becoming active simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be removed. The lock file is kept in a readable ASCII form and contains two lines. The first is the process ID of the daemon and the second is the control filename of the current job being printed. The second line is updated to reflect the current status of lpd for the programs lpq(1) and lprm(1).

FILES

/etc/printcap	Printer description file
/var/spool/*	Spool directories
/var/spool/*/minfree	Minimum free space to leave
/dev/lp*	Line printer devices
/dev/printer	Socket for local requests
/etc/hosts.equiv	Lists machine names allowed printer access
/etc/hosts.lpd	Lists machine names allowed printer access but not under same administrative control

SEE ALSO

lpc(8), pac(1), lpr(1), lpq(1), lprm(1), syslog(3), printcap(5)

4.2 BSD Line Printer Spooler Manual

HISTORY

An lpd daemon appeared in Version 6, AT&T UNIX.

BSD 4.2, 16 March 1991

MAKEDEV

MAKEDEV—Creates and maintains filesystem device entries.

SYNOPSIS

MAKEDEV [ -vcdnhV ] device or device-group names

DESCRIPTION

MAKEDEV is used to maintain the special filesystem entries found in /dev. It creates, or optionally removes, one or more device entries. The names and device numbers are defined in the devinfo file (q.v.); site-specific configuration is found in the file MAKEDEV.cfg. MAKEDEV itself has no knowledge of device information.

OPTIONS

-v	Verbose mode; print out exactly what’s being done.
-c	Create; create the specified devices (default).
-d	Delete; remove the specified devices instead of creating them.
-n	Do nothing; only print what would be done. Implies -v as well.
-h	Print a usage message.
-V	Print the version string.
The following targets are special:
update	Run MAKEDEV in update mode. This reads the list of devices currently available from
	/proc/devices and updates all entries in /dev to match the device numbers found there.

$cdrom

ENODEV: No such device

		MAKEDEV
				1321
local	Run MAKEDEV to create local devices. This option is obsolete and just prints a warning message.
	Use devinfo.local and makedev.cfg to achieve the same results.
FILES
/etc/devinfo		Device information
/usr/local/etc/devinfo.local		Local device information
/etc/devinfo.local		Alternate location for local device information
/etc/makedev.cfg		Configuration file
MAKEDEV.cache		Cached data for update
/proc/devices		The kernel’s list of current devices

AUTHOR

David A. Holland ([e-mail]). Based on the older MAKEDEV shell script written by Nick Holloway. Additional ideas were contributed by Rik Faith.

NOTES

The LALR(1) parser generator used to build makedev.c from makedev.syn is a commercial product. You won’t be able to do a complete rebuild unless you have it.

SEE ALSO

devinfo(5), makedev.cfg(5)

Version 1.5, March 1995

MAKEDEV

MAKEDEV—Creates devices.

SYNOPSIS

cd dev; ./MAKEDEV -V

cd dev; ./MAKEDEV [ -n ] [ -v ] update

cd dev; ./MAKEDEV [ -n ] [ -v ] [ -d ] device ...

DESCRIPTION

MAKEDEV is a script that creates the devices in /dev used to interface with drivers in the kernel.

Note that programs giving the error ENOENT: No such file or directory usually means that the device file is missing, whereas usually means the kernel does not have the driver configured or loaded.

OPTIONS

-V	Print out version (actually RCS version information) and exit.
-n	Do not actually update the devices; just print the actions that would be performed.
-d	Delete the devices. The main use for this flag is by MAKEDEV itself.
-v	Be verbose. Print out the actions as they are performed. This is the same output as produced by -n.

CUSTOMIZATION

Because there is currently no standardization in what names are used for system users and groups, it is possible that you might need to modify MAKEDEV to reflect your site’s settings. Near the top of the file is a mapping from device type to user, group, and permissions. (For example, all CD-ROM devices are set from the variable.) If you want to change the defaults, this is the section to edit.

		Part VIII: Administration and Privileged Commands
1322
DEVICES

General Options

update	This only works on kernels that have /proc/interrupts (introduced during 1.1.x). This file is
	scanned to see what devices are currently configured into the kernel, and this is compared with
	the previous settings stored in the file called DEVICES. Devices that are new since then or have a
	different major number are created, and those that are no longer configured are deleted.
generic	Create a generic subset of devices. This is the standard devices, plus floppy drives, various hard
	drives, pseudo-terminals, console devices, basic serial devices, busmice, and printer ports.
%std	Standard devices. These are mem, access to physical memory; kmem, access to kernel virtual
	memory; null, null device (infinite sink); port, access to I/O ports; zero, null byte source
	(infinite source); core, symlink to /proc/kcore (for kernel debugging); full, always returns
	ENOSPACE on write; ram, ramdisk; tty, to access the controlling tty of a process.
local	This simply runs MAKEDEV.local. This is a script that can create any local devices.
Virtual Terminals
console	This creates the devices associated with the console. This is the virtual terminals ttyx, where x
	can be from 0 though 63. The device tty0 is the currently active vt and is also known as console.
	For each vt, there are two devices, vcsx and vcsax, which are used to generate screen-dumps of
	the vt (the vcsx is just the text and vcsax includes the attributes).
Serial Devices
ttyS{0..63}	Serial ports and corresponding dial-out device. For device ttySx, there is also the device cuax,
	which is used to dial out with. This can avoid the need for cooperative locks in simple
	situations.
cyclades	Dial-in and dial-out devices for the cyclades intelligent I/O serial card. The dial in device is
	ttyCx and the corresponding dial-out device is cubx. By default, devices for 7 lines are created,
	but this can be changed to 15 by removing the comment.
Pseudo Terminals
pty[p-s]	Each possible argument will create a bank of 16 master and slave pairs. The current kernel (1.2)
	is limited to 64 such pairs. The master pseudo-terminals are pty[p-s][0-9a-f] and the slaves are
	tty[p-s][0-9a-f].
Parallel Ports
lp	Standard parallel ports. The devices are created lp0, lp1, and lp2. These correspond to ports at
	0x3bc, 0x378, and 0x278. Hence, on some machines, the first printer port may actually be lp1.
par	Alternative to lp. Ports are named parx instead of lpx.
Bus Mice
busmice	The various bus mice devices. This creates the following devices: logimouse (Logitech bus
	mouse), psmouse (PS/2-style mouse), msmouse (Microsoft Inport bus mouse), atimouse (ATI XL
	bus mouse) and jmouse (J-mouse).
Joystick Devices
js	Joystick. Creates js0 and js1.
Disk Devices
fd[0-7]	Floppy disk devices. The device fdx is the device that autodetects the format, and the additional
	devices are fixed format (whose size is indicated in the name). The other devices are named as

	MAKEDEV
			1323
	fdxLn. The single letter L identifies the type of floppy disk (d = 5.25" DD, h = 5.25" HD,
	D =3.5" DD, H = 3.5" HD, E = 3.5" ED). The number n represents the capacity of that format
	in KB. Thus the standard formats are fdxd360, fdxh1200, fdxD720, fdxH1440, and fdxE2880.
	For more information, see Alain Knaff’s fdutils pack-age.
	Devices fd0* through fd3* are floppy disks on the first controller, and devices fd4* through fd7*
	are floppy disks on the second controller.
hd[a-d]	AT hard disks. The device hdx provides access to the whole disk, with the partitions being
	hdx[0-20]. The four primary partitions are hdx1 through hdx4, with the logical partitions being
	numbered from hdx5 though hdx20. (A primary partition can be made into an extended
	partition, which can hold four logical partitions). By default, only the devices for four logical
	partitions are made. The others can be made by uncommenting them.
	Drives hda and hdb are the two on the first controller. If using the new IDE driver (rather than
	the old HD driver), then hdc and hdd are the two drives on the secondary controller. These
	devices can also be used to access IDE CD-ROMs if using the new IDE driver.
xd[a-d]	XT hard disks. Partitions are the same as IDE disks.
sd[a-h]	SCSI hard disks. The partitions are similar to the IDE disks, but there is a limit of 11 logical
	partitions (sdx5 through sdx15). This is to allow 8 SCSI disks.
loop	Loopback disk devices. These allow you to use a regular file as a block device. This means that
	images of filesystems can be mounted and used as normal. This creates 8 devices loop0 through
	loop7.
Tape Devices
st[0-7]	SCSI tapes. This creates the rewinding tape device stx and the non-rewinding tape device nstx.
qic	QIC-80 tapes. The devices created are rmt8, rmt16, tape-d, and tape-reset.
ftape	Floppy driver tapes (QIC-117). There are four methods of access depending on the floppy tape
	drive. For each of the access methods 0, 1, 2, and 3, the devices rftx (rewinding) and nrftx
	(non-rewinding) are created. For compatibility, devices ftape and nftape are symlinks to rft0
	and nrft0.
CD-ROM Devices
scd[0-7]	SCSI CD players.
sonycd	Sony CDU-31A CD player.
mcd	Mitsumi CD player.
cdu535	Sony CDU-535 CD player.
lmscd	LMS/Philips CD player.
sbpcd{,1,2,3}	SoundBlaster CD player. The kernel is capable of supporting 16 CD-ROMs, each of which is
	accessed as sbpcd[0-9a-f]. These are assigned in groups of four to each controller. sbpcd is a
	symlink to sbpcd0.
Scanner
logiscan	Logitech ScanMan32 and ScanMan 256.
m105scan	Mustek M105 Handscanner.
ac4096	A4Tek Color Handscanner.
Audio
audio	This creates the audio devices used by the sound driver. These include mixer, sequencer, dsp,
	and audio.
pcaudio	Devices for the PC Speaker sound driver. These are pcmixer, pxsp, and pcaudio.

		Part VIII: Administration and Privileged Commands
	1324

Miscellaneous

sg	Generic SCSI devices. The devices created aresg0 through sg7. These allow arbitrary commands
	to be sent to any SCSI device. This allows for querying information about the device or
	controlling SCSI devices that are not one of disk, tape, or CD-ROM (for example, a scanner or
	writable CD-ROM).
fd	To allow an arbitrary program to be fed input from file descriptor x, use /dev/fd/x as the
	filename. This also creates BR/dev/stdin, BR/dev/stdout, and BR/dev/stderr. (Note that these are
	just symlinks into /proc/self/fd.)
ibcs2	Devices (and symlinks) needed by the IBCS2 emulation.
apm	Devices for power management.
dcf	Driver for DCF-77 radio clock.
helloworld	Kernel modules demonstration device. See the modules source.
Network devices	Linux used to have devices in /dev for controlling network devices, but that is no longer the
	case. To see what network devices are known by the kernel, look at /proc/net/dev.

SEE ALSO

Linux Allocated Devices, maintained by H. Peter Anvin ([e-mail])

AUTHOR

Nick Holloway

Linux, 14 August 1994

mke2fs

mke2fs—Create a Linux second extended filesystem.

SYNOPSIS

mke2fs [ -c | -l filename ] [ -b block-size ] [ -f fragment-size ]

[ -i bytes-per-inode ] [ -m reserved-blocks-percentage ] [ -q ][-v ][-S ] device [ blocks-count ]

DESCRIPTION

mke2fs is used to create a Linux second extended filesystem on corresponding to the device (such as /dev/hdXX). blocks-count automatically figures the filesystem size.

a device (usually a disk partition). device is the special file is the number of blocks on the device. If omitted, mke2fs

OPTIONS

-b block-size

-c

Specify the size of blocks in bytes.

Check the device for bad blocks before creating the filesystem using a fast read-only test.

-f fragment-size	Specify the size of fragments in bytes.
-i bytes-per-inode	Specify the bytes/inode ratio. mke2fs creates an inode for every bytes-per-inode bytes
	of space on the disk. This value defaults to 4096 bytes. bytes-per-inode must be at
	least 1024.
-l filename	Read the bad blocks list from filename.
-m reserved- blocks-percentage	Specify the percentage of reserved blocks for the super-user. This value defaults to 5
	percent.
-q	Quiet execution. Useful if mke2fs is run in a script.
-v	Verbose execution.

	mkfs
		1325
-S	Write superblock and group descriptors only. This is useful if all the superblock and
	backup superblocks are corrupted and a last-ditch recovery method is desired. It
	causes mke2fs to reinitialize the superblock and group descriptors while not touching
	the inode table and the block and inode bitmaps. The e2fsck program should be run
	immediately after this option is used, and there is no guarantee that any data will be
	salvageable.

AUTHOR

This version of mke2fs has been written by Theodore T’so ([e-mail]).

BUGS

mke2fs accepts the -f option but currently ignores it because the second extended filesystem does not support fragments yet. There may be some other bugs. Please report them to the author.

AVAILABILITY

mke2fs is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs.

SEE ALSO

badblocks(8), dumpe2fs(8), e2fsck(8), tune2fs(8)

Version 0.5b, November 1994

mkfs

mkfs—Build a Linux filesystem.

SYNOPSIS

mkfs [ -V ][-t fstype ][fs-options ] filesys [ blocks ]

DESCRIPTION

mkfs is used to build a Linux filesystem on a device, usually a hard disk partition. filesys is either the device name (such as / dev/hda1, /dev/sdb2) or the mount point (such as /, /usr, /home) for the filesystem. blocks is the number of blocks to be used for the filesystem.

The exit code returned by mkfs is 0 on success and 1 on failure.

In actuality, mkfs is simply a front end for the various filesystem builders (mkfs.fstype) available under Linux. The filesystemspecific builder is searched for in /etc/fs first, then in /etc, and finally in the directories listed in the PATH environment variable. Please see the filesystem-specific builder manual pages for further details.

OPTIONS

-V	Produce verbose output, including all filesystem-specific commands that are executed.
	Specifying this option more than once inhibits execution of any filesystem-specific commands.
	This is really only useful for testing.
-tfstype	Specifies the type of filesystem to be built. If not specified, the type is deduced by searching for
	filesys in /etc/fstab and using the corresponding entry. If the type cannot be deduced, the
	default filesystem type (currently minix) is used.
fs-options	Filesystem-specific options to be passed to the real filesystem builder. Although not guaranteed,
	the following options are supported by most filesystem builders.
-c	Check the device for bad blocks before building the filesystem.
-lfilename	Read the bad blocks list from filename.
-v	Produce verbose output.

		Part VIII: Administration and Privileged Commands
	1326

BUGS

All generic options must precede and not be combined with filesystem-specific options. Some filesystem-specific programs do not support the -v (verbose) option nor return meaningful exit codes. Also, some filesystem-specific programs do not automatically detect the device size and require the blocks parameter to be specified.

AUTHORS

David Engel ([e-mail]), Fred N. van Kempen ([e-mail]), and Ron Sommeling ([e-mail]). The manual page was shamelessly adapted from Remy Card’s version for the ext2 filesystem.

SEE ALSO

fsck(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8)

Version 1.9, June 1995

mkfs

mkfs—Make a Linux MINIX filesystem.

SYNOPSIS

mkfs [ -c ] [ -nnamelength ] [ –i inodecount ] device size-in-blocks mkfs [ -l filename ] device size-in-blocks

DESCRIPTION

mkfs creates a Linux MINIX filesystem on a device (usually a disk partition).

The device is usually of the following form:

/dev/hda[1-8] /dev/hdb[1-8] /dev/sda[1-8] /dev/sdb[1-8]

The size-in-blocks parameter is the desired size of the filesystem in blocks. This information can be determined from the fdisk(8) program. Only block counts strictly greater than 10 and strictly less than 65,536 are allowed.

OPTIONS

-c	Check the device for bad blocks before creating the filesystem. If any are found, the count is
	printed.
-nnamelength	Specify the maximum length of filenames. No space is allowed between the -n and the
	namelength. Currently, the only allowable values are 14 and 30. 30 is the default.
-i inodecount	Specify the number of inodes for the filesystem.
-l filename	Read the bad blocks list from filename. The file has one bad block number per line. The count
	of bad blocks read is printed.

EXIT CODES

The exit code returned by mkfs.minix is one of the following:

0	No errors
8	Operational error
16	Usage or syntax error

SEE ALSO

fsck(8), mkefs(8), efsck(8), reboot(8)

mklost+found 1327

AUTHOR

Linus Torvalds ([e-mail]). Error code values by Rik Faith ([e-mail]). Inode request feature by Scott Heavner ([e-mail]). Support for the filesystem valid flag by Dr. Wettstein ([e-mail]).

Check to prevent mkfs of mounted filesystem and boot sector clearing by Daniel Quinlan ([e-mail]).

Linux 0.99, 10 January 1994

mklost+found

mklost+found—Create a lost+found directory on a mounted Linux second extended filesystem.

SYNOPSIS

mklost+found

DESCRIPTION

mklost+found is used to create a lost+found directory in the current working directory on a Linux second extended filesystem. mklost+found pre-allocates disk blocks to the directory to make it usable by e2fsck.

OPTIONS

There are none.

AUTHOR

mklost+found was written by Remy Card ([e-mail]), the developer and maintainer of the ext2 fs.

BUGS

There are none. :-)

AVAILABILITY

mklost+found is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs.

SEE ALSO

e2fsck(8), mke2fs(8)

Version 0.5b, November 1994

mkswap

mkswap—Set up a Linux swap area.

SYNOPSIS

mkswap [ -c ] device [size-in-blocks]

DESCRIPTION

mkswap sets up a Linux swap area on a device or in a file.

The device is usually of the following form:

/dev/hda[1-8] /dev/hdb[1-8] /dev/sda[1-8] /dev/sdb[1-8]

SWAP-SPACE

		Part VIII: Administration and Privileged Commands
	1328

The size-in-blocks parameter is the desired size of the filesystem in blocks. This information is determined automatically by mkswap if it is omitted. Block counts are rounded down so that the total size is an integer multiple of the machine’s page size. Only block counts in the range MINCOUNT..MAXCOUNT are allowed. If the block count exceeds the MAXCOUNT, it is truncated to that value and a warning message is issued.

The MINCOUNT and MAXCOUNT values for a swap area are

MINCOUNT = 10 * PAGE_SIZE / 1024

MAXCOUNT = (PAGE_SIZE-10)*8 *PAGE_SIZE / 1024

For example, on a machine with 4KB pages (such as x86), we get

MINCOUNT = 10 * 4096 / 1024 = 40

MAXCOUNT = (4096 - 10) * 8 * 4096 / 1024 = 130752

As each block is 1KB, the swap area in this example could have a size that is anywhere in the range from 40KB to 127.6875MB.

If you don’t know the page size that your machine uses, you may be able to look it up with cat /proc/cpuinfo.

The reason for the limit on MAXCOUNT is that a single page is used to hold the swap bitmap at the start of the swap area, where each bit represents a single page. The reason for the -10, is that the signature is – 10 characters.

To set up a swap file, it is necessary to create that file before running mkswap. A sequence of commands similar to the following is reasonable for this purpose:

#dd if=/dev/zero of=swapfile bs=1024 count=8192

#mkswap swapfile 8192

#sync

#swapon swapfile

Note that a swap file must not contain any holes (so using cp(1) to create the file is not acceptable).

OPTIONS

-c	Check the device for bad blocks before creating the filesystem. If any are found, the count
	is printed. This option is meant to be used for swap partitions only and should not be
	used for regular files! To make sure that regular files do not contain bad blocks, the
	partition that contains the regular file should have been created with mkfs -c.

SEE ALSO

fsck(8), mkfs(8), fdisk(8)

AUTHOR

Linus Torvalds ([e-mail])

Linux 1.0, 8 February 1995

mount, umount

mount, umount—Mount and dismount filesystems.

SYNOPSIS

mount [-afrwuvn] [-t vfstype]

mount [-frwuvn] [-o remount [,...]] special | node mount [-frwun] [-t vfstype] [-o options] special | node umount [-an] [-t vfstype]

umount special | node

mount, unmount
	1329

DESCRIPTION

The mount command calls the mount(2) system call to prepare and graft a special device onto the filesystem tree at the point node. If either special or node are not provided, the appropriate information is taken from the fstab(5) file. The special keyword none can be used instead of a path or node specification. This is useful when mounting the proc filesystem.

The system maintains a list of currently mounted filesystems. If no arguments are given to mount, this list is printed.

Options available for the mount command:

-f	Causes everything to be done except for the actual system call; if it’s not obvious, this
	“fakes” mounting the filesystem. This option is useful in conjunction with the -v flag to
	determine what the mount command is trying to do.
-o	Options are specified with a -o flag followed by a comma-separated string of options.
	Note that many of these options are only useful when they appear in the /etc/fstab file.
	The following options apply to any filesystem that is being mounted:
async	All I/O to the filesystem should be done asynchronously.
auto	Can be mounted with the -a option.
defaults	Use default options: rw, suid, dev, exec, auto, nouser, and async.
dev	Interpret character or block special devices on the filesystem.
exec	Permit execution of binaries.
noauto	Can only be mounted explicitly (that is, the -a option does not cause the filesystem to
	be mounted).
nodev	Do not interpret character or block special devices on the filesystem. This option is
	useful for a server that has filesystems containing special devices for architectures other
	than its own.
noexec	Do not allow execution of any binaries on the mounted filesystem. This option is useful
	for a server that has filesystems containing binaries for architectures other than its own.
nosuid	Do not allow set-user-identifier or set-group-identifier bits to take effect.
nouser	Forbid an ordinary (that is, non-root) user to mount the filesystem.
remount	Attempt to remount an already-mounted filesystem. This is commonly used to change
	the mount flags for a filesystem, especially to make a read-only filesystem writable.
ro	Mount the filesystem read-only.
rw	Mount the filesystem read-write.
suid	Allow set-user-identifier or set-group-identifier bits to take effect.
sync	All I/O to the filesystem should be done synchronously.
user	Allow an ordinary user to mount the filesystem. Ordinary users always have the
	following options activated: noexec, nosuid, and nodev (unless overridden by the super-
	user by using, for example, the following option line: user,exec,dev,suid.

The following options apply only to certain filesystems:

case=value	For the hpfs filesystem, specify case as lower or asis.
check=value	Tells the ext2 filesystem kernel code to do some more checks while the filesystem is
	mounted. Currently (0.99.15), the following values can be specified with this option:
none	No extra check is performed by the kernel code.
normal	The inodes and blocks bitmaps are checked when the filesystem is mounted (this is the
	default).
strict	In addition to the normal checks, block deallocation checks that the block to free is in
	the data zone.
check=value	For the msdos filesystem, three different levels of specificity can be chosen:

		Part VIII: Administration and Privileged Commands
	1330

relaxed	Uppercase and lowercase are accepted and equivalent, long name parts are truncated (for
	example, verlongname.foobar becomes verylong.foo), leading and embedded spaces are
	accepted in each name part (name and extension).
normal	Like relaxed but many special characters (*, ?, <, spaces, and so on) are rejected. This is
	the default.
strict	Like normal, but names may not contain long parts and special characters that are
	sometimes used on Linux but are not accepted by MS-DOS are rejected (+, =, spaces,
	and so on).
conv=value	For the msdos, hpfs, and iso9660 filesystems, specify file conversion as binary, text, or
	auto. The iso9660 filesystem also allows value to be mtext.
	The msdos filesystem can perform CRLF<–>NL (MS-DOS text format to UNIX text
	format) conversion in the kernel. The following conversion modes are available:
binary	No translation is performed. This is the default.
text	CRLF<–>NL translation is performed on all files.
auto	CRLF<–>NL translation is performed on all files that don’t have a well-known binary
	extension. The list of known extensions can be found at the beginning of
	fs/msdos/misc.c (as of 09913r, the list is exe, com, bin, app, sys, drv, ovl, ovr, obj, lib,
	dll, pif, arc, zip, lha, lzh, zoo, tar, z, arj, tz, taz, tzp, tpz, gif, bmp, tif, gl, jpg, pcx,
	tfm, vf, gf, pk, pxl, and dvi).

Programs that do computed lseeks won’t like in-kernel text conversion.

For filesystems mounted in binary mode, a conversion tool (fromdos/todos) is available.

block=value	For the iso9660 filesystem, set the block size.
bsdgroups	See grpid.
cruft	For the iso9660 filesystem, set the cruft flag to y. This option is available because there
	are buggy premastering programs out there that leave junk in the top byte of the file
	size. This option clears the top byte but restricts files to 16MB maximum in the process.
debug	For the msdos filesystem, turn on the debug flag. A version string and a list of filesystem
	parameters is printed. (These data are also printed if the parameters appear to be
	inconsistent.)
debug	For the ext2fs filesystem, cause the kernel code to display the filesystem parameters
	when the filesystem is mounted.
errors=value	For the ext2fs filesystem, specify the error behavior:
continue	No special action is taken on errors (except marking the filesystem as erroneous). This is
	the default.
remount, ro	The filesystem is remounted read only, and subsequent writes are refused.
panic	When an error is detected, the system panics.
fat=value	For the msdos filesystem, specify either a 12-bit fat or a 16-bit fat. This overrides the
	automatic FAT type detection routine. Use with caution!
gid=value	For the msdos and hpfs filesystems, give every file a gid equal to value.
B grpid	Causes the ext2fs to use the BSD behavior when creating files: Files are created with the
	group ID of their parent directory.
map=value	For the iso9660 filesystem, specify mapping as off or normal. In general, non-Rock
	Ridge discs have all the filenames in uppercase, and all the filenames have a ;1
	appended. The map option strips the ;1 and makes the name lowercase. (See also
	norock.)
nocheck	For the ext2fs, turns off checking (see check=none).
nogrpid	Causes the ext2fs to use the System V behavior when creating files. Files are created
	with the group ID of the creating process, unless the setgid bit is set on the parent
	directory. This is the default for all Linux filesystems.

	mount, unmount
			1331
norock	Normal iso9600 filenames appear in a 8.3 format (that is, DOS-like restrictions on
	filename length), and in addition, all characters are in uppercase. Also there is no field
	for file ownership, protection, number of links, provision for block/character devices,
	and so on.
	Rock Ridge is an extension to iso9660 that provides all of these UNIX-like features.
	Basically, there are extensions to each directory record that supply all of the additional
	information, and when Rock Ridge is in use, the filesystem is indistinguishable from a
	normal UNIX filesystem (except that it is read only, of course).
	The norock switch disables the use of Rock Ridge extensions, even if available. (See also
	map.)
quiet	For the msdos filesystem, turn on the quiet flag. Attempts to chown or chmod files do not
	yield errors, although they fail. Use with caution!
sb=value	For the ext2 filesystem, use an alternate superblock located at block value. value is
	numbered in 1024-byte blocks. An ext2 filesystem usually has backups of the superblock
	at blocks 1, 8193, 16385, and so on.
sysvgroups	See nogrpid.
uid=value	For the msdos and hpfs filesystems, give every file a uid equal to value.
umask=value	For the msdos and hpfs filesystems, give every file a umask of value. The radix defaults to
	octal.

The full set of options applied is determined by first extracting the options for the filesystem from the fstab table, then applying any options specified by the -o argument, and finally applying the -r or -w option.

If the msdos filesystem detects an inconsistency, it reports an error and sets the filesystem to read only. The filesystem can be made writable again by remounting it.

-r	The filesystem object is to be mounted read only.
-t vfstype	The argument following the -t is used to indicate the filesystem type. The filesystem
	types that are currently supported are listed in linux/fs/filesystems.c: minux, ext, ext2,
	xiafs, msdos, hpfs, proc, nfs, iso9660, sysv, xenix, coherent. Note that that last three are
	equivalent and that xenix and coherent will be removed at some point in the future; use
	sysv instead.
	The type minix is the default. If no -t option is given, or if the auto type is specified, the
	superblock is probed for the filesystem type (minix, ext, ext2, and xia are supported). If
	this probe fails and /proc/filesystems exists, then all the filesystems listed are tried,
	except for those labeled nodev (such as proc and nfs).
	Note that the auto type may be useful for user-mounted floppies. For example, the mount
	command mounts all filesystems except those of type msdos and ext:
	mount -a -t nomsdos,ext
-v	Verbose mode.
-w	The filesystem object is to be read and write.
-n	Mount without writing in /etc/mtab.

umount removes the special device grafted at point node from the filesystem tree.

Options for the umount command:

-a		All of the filesystems described in /etc/mtab are unmounted.
-t	vfstype	Is used to indicate the actions should only be taken on filesystems of the specified type.
		More than one type may be specified in a comma-separated list. The list of filesystem
		types can be prefixed with no to specify the filesystem types on which no action should
		be taken. (See example for the mount command.)

		Part VIII: Administration and Privileged Commands
	1332

FILES

/etc/fstab

/etc/mtab~

/etc/mtab.tmp

Filesystem table Lock file Temporary file

SEE ALSO

mount(2), umount(2), fstab(5), swapon(8)

BUGS

It is possible for a corrupted filesystem to cause a crash.

Some Linux filesystems don’t support -o synchronous (the ext2fs does support synchronous updates (a la BSD) when mounted with the sync option).

The -o remount may not be able to change mount parameters (all ext2fs parameters, except sb, are changeable with a remount, for example, but you can’t change gid or umask for the dosfs).

HISTORY

A mount command appeared in Version 6, AT&T UNIX.

AUTHORS AND CONTRIBUTORS

The Linux mount command has a long and continuing history. The following major releases are noted with the name of the primary modifier:

0.97.3: Doug Quale ([e-mail])

0.98.5: H.J. Lu ([e-mail])

0.99.2: Rick Sladkey ([e-mail])

0.99.6: Rick Sladkey ([e-mail])

0.99.10: Stephen Tweedie ([e-mail])

0.99.14: Rick Sladkey ([e-mail])

(Filesystem-specific information added to man page on 27 November 1993 by Rik Faith with a lot of information and text from the following filesystem authors: Werner Almesberger, Eric Youngdale, and Remy Card.)

Linux 1.1, 8 February 1995

mountd

mountd—NFS mount daemon.

SYNOPSIS

/usr/etc/rpc.mountd [\-f\--exports-file\][\-dhnprv\] [\--debug\][\--exports-file=file\] [\--help\] [\--allow-non-root\][\--re-export\][\--version\]

DESCRIPTION

The mountd program is an NFS mount daemon.

OPTIONS

-f or --exports-file	This option specifies the exports file, listing the clients that this server is prepared to
	serve and parameters to apply to each such mount (see exports(5)). By default, exports
	are read from /etc/exports.

	named-xfer
		1333
-d or --debug	Log each transaction verbosely to the syslog.
-h or --help	Provide a short help summary.
-n or --allow-non-root	Allow incoming mount requests to be honored even if they do not originate from
	reserved IP ports. Some older NFS client implementations require this. Some newer
	NFS client implementations don’t believe in reserved port checking.
-p or --promiscuous	Put the server into promiscuous mode where it will serve any host on the network.
-r or --re-export	Allow imported NFS filesystems to be exported. This can be used to turn a machine
	into an NFS multiplier. Caution should be used when reexporting loopback NFS
	mounts because reentering the mount point results in deadlock between the NFS client
	and the NFS server.
-v or --version	Report the current version number of the program.

SEE ALSO

exports(5), nfsd(8), ugidd(8C)

BUGS

The current implementation (still) does not keep track of remote mounts.

13 October 1993

named-xfer

named-xfer—Ancillary agent for inbound zone transfers.

SYNOPSIS

named-xfer -z zone_to_transfer -f db_file -s serial_no [ -d debuglevel ] [-l debug_log_file ][-t trace_file ][-p port# ][-S ] nameserver

DESCRIPTION

named-xfer is an ancillary program executed by named(8) to perform an inbound zone transfer. It is rarely executed directly and only by system administrators who are trying to debug a zone transfer problem. See RFCs 1033, 1034, and 1035 for more information on the Internet name-domain system.

Options are
-z	Specifies the name of the zone to be transferred.
-f	Specifies the name of the file into which the zone should be dumped when it is received
	from the primary server.
-s	Specifies the serial number of the current copy of this zone. If the SOA RR you get from
	the primary server does not have a serial number higher than this, the transfer is aborted.
-d	Print debugging information. A number after the d determines the level of messages
	printed.
-l	Specifies a log file for debugging messages. The default is system-dependent but is
	usually in /var/tmp or /usr/tmp. Note that this only applies if -d is also specified.
-t	Specifies a trace file that contains a protocol trace of the zone transfer. This is probably
	only of interest to people debugging the nameserver itself.
-p	Use a different port number. The default is the standard port number as returned by
	getservbyname(3) for service “domain”.
-S	Perform a restricted transfer of only the SOA, NS records, and glue A records for the
	zone. The SOA record is not loaded by named but is used to determine when to verify
	the NS records. See the stubs directive in named(8) for more information.

		Part VIII: Administration and Privileged Commands
	1334

Additional arguments are taken as nameserver addresses in so-called “dotted-quad” syntax only; no hostnames are allowed here. At least one address must be specified. Any additional addresses are tried in order if the first one fails to transfer successfully.

SEE ALSO

named(8), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, Name Server Operations Guide for BIND

26 June 1993

named

named—Internet domain nameserver.

SYNOPSIS

named [ -d debuglevel ][-p port#[/localport#]][{–b} bootfile ][-q ][-r ]

DESCRIPTION

named is the Internet domain nameserver. See RFCs 1033, 1034, and 1035 for more information on the Internet namedomain system. Without any arguments, named reads the default boot file /etc/named.boot, reads any initial data, and listens for queries.

Options are
-d	Print debugging information. A number after the d determines the level of messages
	printed.
-p	Use nonstandard port numbers. The default is the standard port number as returned by
	getservbyname(3) for service “domain”. The argument can specify two port numbers
	separated by a slash (/), in which case the first port is that used when contacting remote
	servers and the second one is the service port bound by the local instance of named. This
	is used mostly for debugging purposes.
-b	Use an alternate boot file. This is optional and allows you to specify a file with a leading
	dash.
-q	Trace all incoming queries if named has been compiled with QRYLOG defined. Note that
	this option is deprecated in favor of the boot file directive options query-log.
-r	Turns recursion off in the server. Answers can come only from local (primary or
	secondary) zones. This can be used on root servers. Note that this option is deprecated
	in favor of the boot file directive options no-recursion.

Any additional argument is taken as the name of the boot file. If multiple boot files are specified, only the last is used.

The boot file contains information about where the nameserver is to get its initial data. Lines in the boot file cannot be continued on subsequent lines. The following is a small example:

;

;boot file for name server

directory /usr/local/adm/named

;type domain source host/file backup file cache . root.cache

primary Berkeley.EDU berkeley.edu.zone primary 32.128.IN-ADDR.ARPA ucbhosts.rev

secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak primary 0.0.127.IN-ADDR.ARPA localhost.rev

transfers-in

$INCLUDE

named 1335

forwarders 10.0.0.78 10.2.0.78 limit transfers-in 10

limit datasize 64M

options forward-only query-log fake-iquery

The directory line causes the server to change its working directory to the directory specified. This can be important for the correct processing of files in primary zone files.

The cache line specifies that data in root.cache is to be placed in the backup cache.

Its main use is to specify data such as locations of root domain servers. This cache is not used during normal operation, but is used as “hints” to find the current root servers. The file root.cache is in the same format as berkeley.edu.zone. There can be more than one cache file specified. The root.cache file should be retrieved periodically from FTP.RS.INTERNIC.NET because it contains a list of root servers, and this list changes periodically.

The first sample primary line states that the file berkeley.edu.zone contains authoritative data for the Berkeley.EDU zone. The file berkeley.edu.zone contains data in the master file format described in RFC 883. All domain names are relative to the origin, in this case, Berkeley.EDU (see below for a more detailed description). The second primary line states that the file ucbhosts.rev contains authoritative data for the domain 32.128.IN-ADDR.ARPA, which is used to translate addresses in network 128.32 to hostnames. Each master file should begin with an SOA record for the zone (see below).

The first sample secondary line specifies that all authoritative data under CC.Berkeley.EDU is to be transferred from the nameserver at 128.32.137.8. If the transfer fails, it tries 128.32.137.3 and continues trying the addresses, up to ten, listed on this line. The secondary copy is also authoritative for the specified domain. The first non-dotted-quad address on this line is taken as a filename in which to back up the transferred zone. The nameserver loads the zone from this backup file if it exists when it boots, providing a complete copy even if the master servers are unreachable. Whenever a new copy of the domain is received by automatic zone transfer from one of the master servers, this file is updated. If no filename is given, a temporary file is used and deleted after each successful zone transfer. This is not recommended because it is a needless waste of bandwidth. The second sample secondary line states that the address-to-hostname mapping for the subnet 128.32.136 should be obtained from the same list of master servers as the previous zone.

The forwarders line specifies the addresses of sitewide servers that will accept recursive queries from other servers. If the boot file specifies one or more forwarders, then the server sends all queries for data not in the cache to the forwarders first. Each forwarder is asked in turn until an answer is returned or the list is exhausted. If no answer is forthcoming from a forwarder, the server continues as it would have without the forwarders line unless it is in forward-only mode. The forwarding facility is useful to cause a large sitewide cache to be generated on a master and to reduce traffic over links to outside servers. It can also be used to allow servers to run that do not have direct access to the Internet but want to look up exterior names anyway.

The slave line (deprecated) is allowed for backward compatibility. Its meaning is identical to options forward-only.

The sortlist line can be used to indicate networks that are to be preferred over other networks. Queries for host addresses from hosts on the same network as the server receive responses with local network addresses listed first, then addresses on the sort list, and then other addresses.

The xfrnets directive (not shown) can be used to implement primitive access control. If this directive is given, your nameserver only answers zone transfer requests from hosts that are on networks listed in your xfrnets directives. This directive may also be given as tcplist for compatibility with older, interim servers.

The include directive (not shown) can be used to process the contents of some other file as though they appeared in place of the include directive. This is useful if you have a lot of zones or if you have logical groupings of zones that are maintained by different people. The include directive takes one argument, the name of the file whose contents are to be included. No quotes are necessary around the filename.

The bogusns directive (not shown) tells BIND that no queries are to be sent to the specified nameserver addresses (which are specified as dotted quads, not as domain names). This is useful when you know that some popular server has bad data in a zone or cache, and you want to avoid contamination while the problem is being fixed.

The limit directive can be used to change BIND’s internal limits, some of which (datasize, for example) are implemented by the system and others (such as ) by BIND itself. The number following the limit name can be scaled by

		Part VIII: Administration and Privileged Commands
	1336

postfixing a k, m, or g for kilobytes, megabytes, and gigabytes respectively. datasize’s argument sets the process data size enforced by the kernel. Note that not all systems provide a call to implement this; on such systems, the use of the datasize parameter of limit results in a warning message. transfers-in’s argument is the number of named-xfer subprocesses that BIND will spawn at any one time. transfers-per-ns’s argument is the maximum number of zone transfers to be simultaneously initiated to any given remote nameserver.

The options directive introduces a Boolean specifier that changes the behavior of BIND. More than one option can be specified in a single directive. The currently defined options are as follows: no-recursion, which causes BIND to answer with a referral rather than actual data whenever it receives a query for a name it is not authoritative for. Don’t set this on a server that is listed in any host’s resolv.conf file. no-fetch-glue keeps BIND from fetching missing glue when constructing the “additional data” section of a response; this can be used in conjunction with no-recursion to prevent BIND’s cache from ever growing in size or becoming corrupted. query-log causes all queries to be logged via syslog(3). This is a lot of data; don’t turn it on lightly. forward-only causes the server to query only its forwarders. This option is usually used on a machine that wants to run a server but for physical or administrative reasons cannot be given access to the Internet. fake-iquery tells BIND to send back a useless and bogus reply to “inverse queries” rather than respond with an error. This is helpful if you have a lot of microcomputers or SunOS hosts or both.

The max-fetch directive (not shown) is allowed for backward compatibility; its meaning is identical to limit transfers-in.

The master file consists of control information and a list of resource records for objects in the zone of the forms:

$INCLUDE <filename><opt_domain> $ORIGIN <domain>

<domain><opt_ttl> <opt_class><type><resource_record_data>

domain is . for root, @ for the current origin, or a standard domain name. If domain is a standard domain name that does not end with ., the current origin is appended to the domain. Domain names ending with . are unmodified. The opt_domain field is used to define an origin for the data in an included file. It is equivalent to placing a $ORIGIN statement before the first line of the included file. The field is optional. Neither the opt_domain field nor $ORIGIN statements in the included file modify the current origin for this file. The opt_ttl field is an optional integer number for the time-to-live field. It defaults to 0, meaning the minimum value specified in the SOA record for the zone. The opt_class field is the object address type; currently only one type is supported, IN, for objects connected to the DARPA Internet. The type field contains one of the following tokens; the data expected in the resource_record_data field is in parentheses:

A	A host address (dotted quad).
NS	An authoritative nameserver (domain).
MX	A mail exchanger (domain), preceded by a preference value (0..32767) with lower
	numeric values representing higher logical preferences.
CNAME	The canonical name for an alias (domain).
SOA	Marks the start of a zone of authority (domain of originating host, domain address of
	maintainer, a serial number and the following parameters in seconds: refresh, retry,
	expire, and minimum TTL (see RFC 883)).
NULL	A null resource record (no format or data).
RP	A responsible person for some domain name (mailbox, TXT-referral).
PTR	A domain name pointer (domain).
HINFO	Host information (cpu_type, OS_type).

Resource records usually end at the end of a line but may be continued across lines between opening and closing parentheses. Comments are introduced by semicolons and continue to the end of the line.

Note that there are other resource record types, not shown here. You should consult the BIND Operations GUIDe (BOG) for the complete list. Some resource record types may have been standardized in newer RFCs but not yet implemented in this version of BIND.

Each master zone file should begin with an SOA record for the zone. A sample SOA record follows:

named 1337

@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( 1989020501 ; serial

10800 ; refresh

3600 ; retry

3600000 ; expire

86400 ) ; minimum

The SOA specifies a serial number, which should be changed each time the master file is changed. Note that the serial number can be given as a dotted number, but this is a very unwise thing to do because the translation to normal integers is via concatenation rather than multiplication and addition. You can spell out the year, month, day of month, and 0..99 version number and still fit inside the unsigned 32-bit size of this field. It’s true that we will have to rethink this strategy in the year 4294, but we’re not worried about it. Secondary servers check the serial number at intervals specified by the refresh time in seconds; if the serial number changes, a zone transfer is done to load the new data. If a master server cannot be contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted. If a master server cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. The minimum value is the time-to-live (TTL) used by records in the file with no explicit time-to-live value.

NOTES

The boot file directives domain and suffixes have been obsoleted by a more useful resolver-based implementation of suffixing for partially qualified domain names. The prior mechanisms could fail under a number of situations, especially when then local nameserver did not have complete information.

The following signals have the specified effect when sent to the server process using the kill(1) command:

SIGHUP	Causes server to read named.boot and reload the database. If the server is built with the
	FORCED RELOAD compile-time option, then SIGHUP also causes the server to check the serial
	number on all secondary zones. Usually, the serial numbers are only checked at the
	SOA-specified intervals.
SIGINT	Dumps the current database and cache to /var/tmp/named_dump.db.
SIGIOT	Dumps statistics data into /var/tmp/named.stats if the server is compiled with -DSTATS.
	Statistics data is appended to the file. Some systems use SIGABRT rather than SIGIOT for
	this.
SIGSYS	Dumps the profiling data in /var/tmp if the server is compiled with profiling (the server
	forks, changes directories, and exits).
SIGTERM	Dumps the primary and secondary database files. Used to save modified data on
	shutdown if the server is compiled with dynamic updating enabled.
SIGUSR1	Turns on debugging; each SIGUSR1 increments debug level (SIGEMT on older systems
	without SIGUSR1).
SIGUSR2	Turns off debugging completely (SIGFPE on older systems without SIGUSR2).
SIGWINCH	Toggles logging of all incoming queries via syslog(3) (requires server to have been built
	with the QRYLOG option).

FILES

/etc/named.boot	Nameserver configuration boot file
/etc/named.pid	The process ID (on older systems)
/var/run/named.pid	The process ID (on newer systems)
/var/tmp/named_dump.db	Dump of the nameserver database
/var/tmp/named.run	Debug output
/var/tmp/named.stats	Nameserver statistics data

		Part VIII: Administration and Privileged Commands
	1338

SEE ALSO

kill(1), gethostbyname(3), signal(2), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, Name Server Operations GUIDe for BIND

20 June 1995

named.reload

named.reload—Cause the nameserver to synchronize its database.

DESCRIPTION

This command sends a SIGHUP to the running nameserver. This signal is documented in named(8).

BUGS

It does not check to see if the nameserver is actually running and could use a stale pid cache file, which may result in the death of an unrelated process.

SEE ALSO

named(8), named.restart(8)

26 June 1993

named.restart

named.restart—Stop and restart the nameserver.

DESCRIPTION

This command sends a SIGKILL to the running nameserver and then starts a new one.

BUGS

It does not check to see if the nameserver is actually running and could use a stale pid cache file, which may result in the death of an unrelated process.

It does not wait after killing the old server before starting a new one. Because the server could take some time to die and the new one experiences a fatal error if the old one isn’t gone by the time it starts, you can be left in a situation where you have no nameserver at all.

SEE ALSO

named(8), named.reload(8)

26 June 1993

ndc

ndc—Name daemon control interface.

SYNOPSIS

ndc directive [ ... ]

netstat 1339

DESCRIPTION

This command allows the nameserver administrator to send various signals to the nameserver or to restart it. Zero or more directives may be given from the following list:

status	Displays the current status of named as shown by ps(1).
dumpdb	Causes named to dump its database and cache to /var/tmp/named_dump.db (uses the INT
	signal.)
reload	Causes named to check the serial numbers of all primary and secondary zones and to
	reload those that have changed (uses the HUP signal.)
stats	Causes named to dump its statistics to /var/tmp/named.stats (uses the IOT or ABRT signal.)
trace	Causes named to increment its “tracing level” by one. Whenever the tracing level is
	nonzero, trace information is written to /var/tmp/named.run. Higher tracing levels result
	in more detailed information (uses the USR1 signal).
notrace	Causes named to set its “tracing level” to zero, closing /var/tmp/named.run if it is open
	(uses the USR2 signal).
querylog	Causes named to toggle the “query logging” feature, which results in a syslog(3) of each
	incoming query (uses the WINCH signal). Note that query logging consumes quite a lot of
	log file space. This directive may also be given as qrylog.
start	Causes named to be started as long as it isn’t already running.
stop	Causes named to be stopped if it is running.
restart	Causes named to be killed and restarted.

BUGS

Arguments to named are not preserved by restart or known by start. Some mechanism for controlling the parameters and environment should exist.

Implemented as a sh(1) script.

AUTHOR

Paul Vixie (Internet Software Consortium)

SEE ALSO

named(8), named.reload(8), named.restart(8)

27 November 1994

netstat

netstat—Display active network connections

SYNOPSIS

netstat [[-a | [-t | -u | -w]] [-n | -o] | -x] [-c] netstat -r [-c] [-n]

netstat -v

DESCRIPTION

netstat displays the status of network connections on either TCP, UDP, or RAW sockets to the system. By default, netstat only displays status on those TCP sockets that are not in the LISTEN state (that is, connections to active processes). To obtain information about the kernel routing table, netstat may be invoked with the option -r. A listing of internal UNIX connections can be obtained by invoking netstat with the option -x.

		Part VIII: Administration and Privileged Commands
	1340

netstat’s display includes the following information for each socket:

Proto	The protocol (either TCP or UDP) used by the socket.
Recv-Q	The count of bytes not copied by the user program connected to this socket.
Send-Q	The count of bytes not acknowledged by the remote host.
Local Address	The local address (local hostname) and port number of the socket. Unless the -n switch
	is given, the socket address is resolved to its canonical hostname, and the port number is
	translated into the corresponding service name.
Foreign Address	The remote address (remote hostname) and port number of the socket. As with the local
	address:port, the -n switch turns off hostname and service name resolution.
(State)	The state of the socket. Because there are no states in RAW and usually no states used in
	UDP, this row may be left blank. Usually, this can be one of several values:
ESTABLISHED	The socket has an established connection.
SYN SENT	The socket is actively attempting to establish a connection.
SYN RECV	The connection is being initialized.
FIN WAIT1	The socket is closed, and the connection is shutting down.
FIN WAIT2	Connection is closed, and the socket is waiting for a shutdown from the remote end.
TIME WAIT	The socket is waiting after close for remote shutdown re-transmission.
CLOSED	The socket is not being used.
CLOSE WAIT	The remote end has shut down, waiting for the socket to close.
LAST ACK	The remote end shut down, and the socket is closed. Waiting for acknowledgment.
LISTEN	The socket is listening for incoming connections.
UNKNOWN	The state of the socket is unknown.

If netstat is invoked with the option -o, additional information is displayed after the state info. This information is shown like this: keyword (time/backoff) and an optional asterisk. The keyword shows the state of the timer belonging to the socket, the time displayed (in seconds) is how long it will take the timer to expire, the backoff value indicates the current retry count for data transmission, and the asterisk indicates that this timer is in the expiration queue. The latter might be removed in future but is helpful for debugging the TCP-Code for now.

Invoked with the option -x, netstat displays a list of all active UNIX internal communication sockets.

netstat’s display includes the following information for each socket:

Proto	The protocol (usually UNIX) used by the socket.
RefCnt	The reference count (attached processes via this socket).
Flags	The only known flag to me is SO ACCEPTON (displayed as ACC); otherwise, left blank.
	SO ACCEPTON is used on unconnected sockets if their corresponding processes are waiting
	for a connect request.

Type

SOCK DGRAM

SOCK STREAM SOCK RAW SOCK RDM

SOCK SEQPACKET SOCK PACKET

There are several types of socket access:

The socket is used in Datagram (connectionless) mode. This is a stream (connection) socket.

The socket is used as a raw socket.

This one serves reliably delivered messages. This is a sequential packet socket.

This socket type is used as a Linux-specific way to get packets at the dev (kernel) level. It is assumed to be used to write things such as RARP (Reverse Address Resolution Protocol) and similar things on the user level.

UNKNOWN	Who ever knows, what future will bring; just fill in here. :-)
State	This field will contain one of the following keywords:
FREE	The socket is not allocated.

	netstat
		1341
LISTENING	The socket is listening for a connection request.
UNCONNECTED	The socket is not connected to another one.
CONNECTING	The socket is about to establish a connection.
CONNECTED	The socket is connected.
DISCONNECTING	The socket is disconnecting.
UNKNOWN	This state should never happen.
Path	This displays the pathname that the corresponding processes attached to the socket.

The network routing table (invoked with netstat -r) shows up the following information:

Destination net/address	The destination address of a resolved host or hand-entered network is displayed. Unless
	the option -n is given, the hosts or nets are resolved. An entry named default shows up
	the default route for the kernel.
Gateway address	If there is no asterisk (*) displayed, any data is routed to the dedicated gateway.
Flags	Possible routing flags are
	U	This route is usable.
	G	Destination is a gateway.
	H	Destination is a host entry.
	N	Destination is a Net entry.
	R	Route will be reinstated after timeout.
	D	This one is created dynamically (by redirection).
	M	This one is modified dynamically (by redirection).
RefCnt	Reference count for this route.
Use	How many times this route was used yet.
Iface	This is the name of the interface where this route belongs.
OPTIONS
-a	Display information about all Internet sockets, such as TCP, UDP, and RAW,
	including those sockets that are listening only.
-c	Generate a continuous listing of network status: network status is displayed every second
	until the program is interrupted.
-n	Causes netstat not to resolve hostnames and service names when displaying remote and
	local address and port information.
-o	Display timer states, expiration times, and backoff state.
-r	Display kernel routing table.
-t	Display information about TCP sockets only, including those that are listening.
-u	Display information about UDP sockets only.
-v	Print version information.
-w	Display information about raw sockets.
-x	Display information about UNIX domain sockets.
FILES
/proc/net/tcp	TCP socket information
/proc/net/udp	UDP socket information
/proc/net/raw	RAW socket information
/proc/net/unix	UNIX domain socket information

		Part VIII: Administration and Privileged Commands
	1342

/proc/net/route	Kernel routing information
/etc/services	The services translation

BUGS

None reported yet (5/20/93).

AUTHORS

The netstat user interface was written by Fred Baumgarten ([e-mail]). The man page is basically by Matt Welsh ([e-mail]).

Cohesive Systems, 20 May 1993

makeactive, makehistory, newsrequeue

makeactive, makehistory, newsrequeue—Tools to recover Usenet databases

SYNOPSIS

makeactive [ -m ][-o ]

makehistory [ -b ][-f filename ][-i ][-n ][-o ][-r ][-s size ] [-T tmpdir ][-u [ -v]]

newsrequeue [ -a active ][-h history ][-d days ][-l ][-n newsfeeds ][input ]

DESCRIPTION

makeactive invokes find(1) to get a list of all directories in the news spool tree, /news/spool. It discards directories named lost+found as well as those that have a period in them. It scans all other directories for all-numeric filenames and determines the highest and lowest number. The program’s output is a set of active(5) file lines. Because there is no way to know if a group is moderated or disabled, the fourth field of all entries is y. Also, mid-level directories that aren’t newsgroups are also created as newsgroups with no entries. (For example, there is a comp.sources.unix group, but no comp.sources.)

If the –o flag is used, makeactive reads an existing active file for the list of group names and just renumber all groups. It preserves the fourth field of the active file if one is present. This is analogous to the ctlinnd(8) renumber command, except that innd(8) should be throttled or not running. Do not use this flag with output redirected to the standard active file!

If the –m flag is given, then makeactive attempts to adjust the highest and lowest article numbers wherever possible. If articles are found in a newsgroup, the numbers reflect what was found. If no articles are found in a newsgroup, the high number from the old file is kept, and the low number is set to one more than the high number. This flag may only be used if the –o flag is used.

makeactive exits with nonzero status if any problems occur. A typical way to use the program is with the following /bin/sh commands:

ctlinnd throttle “Rebuilding active file” TEMP=${TMPDIR-/tmp}/act$$

if [ -f /var/lib/news/active ] ; then if makeactive -o >${TEMP} ; then

mv ${TEMP} /var/lib/news/active

fi

else

if makeactive >${TEMP} ; then

#Edit to restore moderated

#and aliased groups.

...

mv ${TEMP} /var/lib/news/active

fi

fi

ctlinnd reload active “New active file”

makeactive, makehistory, newsrequeue	1343

makehistory rebuilds the history(5) text file and the associated dbz(3) database. The default name of the text file is /news/lib/history; to specify a different name, use the –f flag. makehistory scans the active(5) file to determine which newsgroup directories within the spool directory, /news/spool, should be scanned. (If a group is removed, but its spool directory still exists, makehistory ignores it.) The program reads each file found and writes a history line for it. If the –b flag is used, then makehistory removes any articles that do not have valid Message-ID headers in them.

After the text file is written, makehistory builds the dbz database. If the –f flag is used, then the database files are named file.dir and file.pag. If the –f flag is not used, then a temporary link to the name history.n is made and the database files are written as history.n.pag and history.n.dir. If the –o flag is used, then the link is not made and any existing history files are overwritten. If the old database exists, makehistory uses it to determine the size of the new database. To ignore the old database, use the –i flag. Using the –o flag implies the –i flag. The program also ignores any old database if the –s flag is used to specify the approximate number of entries in the new database. Accurately specifying the size is an optimization that creates a more efficient database. (The size should be the estimated eventual size of the file, typically the size of the old file.) For more information, see the discussion of dbzfresh and dbzsize in dbz(3).

If the –u flag is given, then makehistory assumes that innd is running. It pauses the server while scanning and then sends addhist commands (see ctlinnd(8)) to the server for any article that is not found in the dbz database. The command makehistory –bu is useful after a system crash to delete any mangled articles and bring the article database back into a more consistent state. If the –v flag is used with the –u flag, then makehistory puts a copy of all added lines on its standard output.

To scan the spool directory without rebuilding the dbz files, use the –n flag. If used with -u, the server is not paused while scanning. To just build the dbz files from an existing text file, use the –r flag. The –i or –s flags can be useful if there are no valid dbz files to use. A typical way to use this program is with the following /bin/sh commands:

ctlinnd throttle “Rebuilding history file” cd /news/lib

if makehistory –n –f history.n ; then

:

else

echo Error creating history file! exit 1

fi

#The following line can be used to retain expired history.

#It is not necessary for the history file to be sorted.

#awk ‘NF==2 { print; }’ <history >>history.n

#View history file for mistakes.

if makehistory –r –s ‘wc –l <history’ –f history.n; then mv history.n history

mv history.n.dir history.dir mv history.n.pag history.pag fi

ctlinnd go “

makehistory needs to create a temporary file that contains one line for each article it finds, which can become very large. This file is created in the /tmp directory. The TMPDIR environment variable may be used to specify a different directory. Alternatively, the –T flag may be used to specify a temporary directory. In addition, the sort(1) that is invoked during the build writes large temporary files (often to /var/tmp, but see your system man pages). If the –T flag is used, then the flag and its value are passed to sort. On most systems, this changes the temporary directory that sort uses. If used, this flag and its value are passed on to the sort(1) command that is invoked during the build.

makehistory does not handle symbolic links. If the news spool area is split across multiple partitions, the following commands should probably be run before the database is regenerated:

cd /news/spool

find . -type l -name ‘[1-9]*’ -print | xargs -t rm

Make sure to run the command on all the appropriate partitions!

		Part VIII: Administration and Privileged Commands
	1344

newsrequeue can be used to rewrite batchfiles after a system crash. It operates in two modes. In the first mode, it first reads the active and newsfeeds(5) files to determine where the different newsgroups are to be distributed. To specify alternate locations for these files, use the –a or –n flags. It then opens the history database. To specify a different file, use the –h flag.

Once the files are opened, newsrequeue reads from the specified input file or standard input if no file is specified. Each line should have a single Message-ID, surrounded in angle brackets; any other text on the line is ignored. For example, the history file (or a trailing subset of it) is acceptable input to the program operating in this mode. If the –d flag is used, then only articles that were received within the specified number of days are processed.

newsrequeue uses the first two fields of the newsfeed entry—the sitename and the excludes field and the patterns and distribs field. It ignores all flags in the third field except for the N field and also ignores the fourth field altogether.

The second mode is used if the –l flag is used. In this mode, it reads from the specified input file or standard input if no file is specified. Each line should look like an innd log entry. It parses entries for accepted articles, looks up the Message-ID in the history database to get the filename, and then scans the list of sites.

In either mode, the output of newsrequeue consists of one line for each article that should be forwarded. Each such line contains the Message-ID, the filename, and the list of sites that should receive the article. The output is suitable for piping into filechan(8).

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

active(5), ctlinnd(8), dbz(3), filechan(8), history(5), innd(8), newsfeeds(5)

news.daily

news.daily—Do regular Usenet system administration

SYNOPSIS

news.daily [ keyword... ]

innwatch [ -t sleeptime ][-f controlfile ][-l logfile ] expirerm file

inncheck [ -v ][-pedantic ][-perms [ -fix ]][-noperms ][file... ]

DESCRIPTION

news.daily performs a number of important Usenet administrative functions. This includes producing a status report, removing old news articles, processing log files, rotating the archived log files, renumbering the active file, removing any old socket files found in the firewall directory, and collecting the output. This program should be run under the news administrator’s ID, not as root.

By default, news.daily performs all its functions and mails the output to the news administrator, usenet. By specifying keywords on the command line, it is possible to modify the functions performed, as well as change the arguments given to expire(8) and expireover(8).

news.daily should be run once a day, typically out of cron(8). It may be run more often, but such invocations should at least use the norotate keyword to prevent the log files from being processed and rotated too fast.

The shlock(1) program is used to prevent simultaneous executions.

The following keywords may be used:

delayrm	This uses the –z flag when invoking expire and expireover. The names of articles to be
	removed are written to a temporary file and then removed after expiration by calling
	expirerm.

	news.daily
			1345
nostat	This keyword disables the status report generated by innstat (see newslog(8)). Without
	this keyword, the status report is the first function performed, just prior to obtaining the
	news.daily lock.
noexpire	By default, expire is invoked to remove old news articles. Using this keyword disables
	this function.
noexplog	expire usually appends information to /var/log/news/expire.log (see newslog(5)). Using
	this keyword causes the expire output to be handled as part of news.daily’s output. It
	has no effect if the noexpire keyword is used.
flags=’expire\args’	By default, expire is invoked with the an argument of –v1. Using this keyword changes
	the arguments to those specified. Be careful to use quotes if multiple arguments are
	needed. This keyword has no effect if the noexpire keyword is used.
nologs	After expiration, scanlogs(8) is invoked to process the log files. Using this keyword
	disables all log processing functions.
norotate	By default, log processing includes rotating and cleaning out log files. Using this
	keyword disables the rotating and cleaning aspect of the log processing. The log files are
	only scanned for information and no contents are altered. This keyword has no effect if
	the nologs keyword is used.
norenumber	This keyword disables the ctlinnd(8) renumber operation. Usually, the low watermark
	for all newsgroups (see active(5)) is reset.
norm	By default, any socket ctlinnd socket that has not been modified for two days is
	removed. Using this keyword disables this function.
nomail	news.daily usually sends a mail message containing the results to the administrator.
	Using this keyword causes this message to be sent to stdout and stderr instead. Usually,
	all utilities invoked by the script have their stdout and stderr redirected into a file. If the
	file is empty, no message is sent.
expireover	The expireover program is called after expiration to purge the overview databases.
expireoverflags=’expireovernargs’	If the expireover keyword is used, this keyword may be used to specify the flags to be
	passed to expireover. If the delayrm keyword is used, then the default value is –z and the
	list of deleted files; otherwise, the default value is –s.
/full/path	The program specified by the given path is executed just before any expiration is done.
	A typical use is to specify an alternate expiration program and use the noexpire keyword.
	Multiple programs may be specified; they are invoked in order.

The norotate keyword is passed on to scanlogs if it is invoked. expirerm is a script that removes a list of files. The specified file lists the files. It is sorted and then fed into a pipeline responsible for doing the removal, usually fastrm(8). If there seemed to be a problem removing the files, then mail is sent to the news administrator. If there were no problems, then file is renamed to /var/log/news/expire.list where it is kept (for safety) until the next day’s expiration.

innwatch is a script that can be started at news boot time. It periodically—every sleeptime seconds— examines the load average and the number of free blocks and inodes on the spool partition, as described by its control file, innwatch.ctl(5). If the load gets too high or the disk gets too full, it throttles the server. When the condition restores, it unblocks the server. In addition, on each pass through the loop, it checks the specified log file to see if it has been modified and sends mail to the news administrator if so. It is usually a good idea to set this to the syslog(3) file that receives critical news messages. Upon receipt of an interrupt signal, innwatch reports its status in the file /news/lib/innwatch.status.

inncheck is a perl(1) script that verifies the syntax and permissions of all InterNetNews configuration files. If no files are specified, it checks all files. A filename may be followed by an equal sign and a path to indicate the pathname to use for the file. For example, newsfeeds=/tmp/nf checks the syntax of a new newsfeeds(5) without requiring it to be installed. If the –v flag is used, it prints status information as it checks each file. If the –pedantic flag is used, it checks the files for omissions that are not strictly errors but might indicate a configuration error.

If any file is specified, only the permissions on those files are checked. The –noperms flag suppresses this check. If the –perms flag is used, the script verifies the ownership and permissions of all files. The –fix flag can also be used so that the output can be executed as a shell script.

		Part VIII: Administration and Privileged Commands
	1346

HISTORY

news.daily and this manual page were written by Landon Curt Noll ([e-mail]) and Rich $alz ([e-mail]).

inncheck was written by Brendan Kehoe ([e-mail]) and Rich.

innwatch was written by Mike Cooper ([e-mail]) and ([e-mail]).

SEE ALSO

active(5), ctlinnd(8), expire(8), fastrm(8), newslog(5), newslog(8), innwatch.ctl(5), shlock(1)

newslog

newslog—Maintenance of Usenet log files

SYNOPSIS

scanlogs [ norotate ][nonn ] writelog name text...

innstat tally.unwanted tally.control innlog.awk

DESCRIPTION

scanlogs summarizes the information recorded in the INN log files (see newslog(5)). By default, it also rotates and cleans out the logs. It is usually invoked by the news.daily(8) script.

The following keywords are accepted:

norotate

Using this keyword disables the rotating and cleaning aspect of the log processing: The logs files are only scanned for information and no contents are altered.

nonn	Usually, the nn log file is scanned and rotated. Using this keyword disables this
	function.

If scanlogs is invoked more than once a day, the norotate keyword should be used to prevent premature log cleaning.

The writelog script is used to write a log entry or send it as mail. The name parameter specifies the name of the log file where the entry should be written. If it is the word mail, then the entry is mailed to the news administrator, Usenet. The data that is written or sent consists of the text given on the command line, followed by standard input indented by four spaces. shlock(1) is used to avoid simultaneous updates to a single log file.

The innstat script prints a snapshot of the INN system. It displays the operating mode of the server, as well as disk usage and the status of all log and lock files.

The rest of the scripts described here are usually invoked by scanlogs. They parse log files that are described in newslog(5) and the server’s article log file described in innd(8).

tally.unwanted script parses the article log file to update the cumulative list of articles posted to unwanted newsgroups, unwanted.log.

tally.control reads its standard input, which should be the newgroup.log and rmgroup.log log files. It updates the cumulative list of newsgroup creations and deletions, control.log.

innlog.awk is an awk(1) script that summarizes the activity that innd and nnrpd(8) report to syslog.

HISTORY

Written by Landon Curt Noll ([e-mail]) and Rich $alz ([e-mail]) for InterNetNews.

nnrpd 1347

SEE ALSO

innd(8) newslog(5), news.daily(8), nnrpd(8)

nfsd

nfsd—NFS service daemon.

SYNOPSIS

/usr/etc/rpc.nfsd [\-f\exports-file\][\-dhnprv\] [\--debug\][\--exports-file=file\] [\--help\] [\--allow-non-root\][\--re-export\][\--version\]

DESCRIPTION

The nfsd program is an NFS service daemon that handles client filesystem requests. Unlike nfsd on some other systems, nfsd operates as a normal user-level process. The server also differs from other NFS server implementations in that it mounts an entire file hierarchy not limited by the boundaries of physical filesystems. The implementation allows the clients read-only or read-write access to the file hierarchy of the server machine.

The mountd program starts an ancillary user-level mount daemon.

OPTIONS

-f or --exports-file	This option specifies the exports file, listing the clients that this server is prepared to
	serve and parameters to apply to each such mount (see exports(5)). By default, exports
	are read from /etc/exports.
-d or --debug	Log each transaction verbosely to the syslog.
-h or --help	Provide a short help summary.
-n or --allow-non-root	Allow incoming NFS requests to be honored even if they do not originate from reserved
	IP ports. Some older NFS client implementations require this. Some newer NFS client
	implementations don’t believe in reserved port checking.
-p or --promiscuous	Put the server into promiscuous mode where it serves any host on the network.
-r or --re-export	Allow imported NFS filesystems to be exported. This can be used to turn a machine
	into an NFS multiplier. Caution should be used when re-exporting loopback NFS
	mounts because re-entering the mount point results in deadlock between the NFS client
	and the NFS server.
-v or --version	Report the current version number of the program.

SEE ALSO

exports(5), mountd(8), ugidd(8C)

AUTHORS

Mark Shand wrote the original unfsd. Don Becker extended unfsd to support authentication and allow read-write access and called it hnfs. Rick Sladkey added host matching, showmount -e support, mountd authentication, inetd support, and all the portability and configuration code.

13 October 1993

nnrpd

nnrpd—NNTP server for on-campus hosts.

		Part VIII: Administration and Privileged Commands
	1348

SYNOPSIS

nnrpd [ -r reason ][-s title padding ][-S host ][-t ]

DESCRIPTION

nnrpd is an NNTP server for newsreaders. It accepts commands on its standard input and responds on its standard output. It is usually invoked by innd(8) with those descriptors attached to a remote client connection.

If the –r flag is used, then nnrpd rejects the incoming connection giving reason as the text. This flag is used by innd when it is paused or throttled.

Unlike innd, nnrpd supports all NNTP commands for user-oriented reading and posting.

nnrpd uses the nnrp.access(5) file to control who is authorized to access the Usenet database. It also rejects connections if the load average is greater than 16.

As each command is received, nnrpd tries to change its argv array so that ps(1) prints the command being executed. To get a full display, the –s flag may be used with a long string as its argument, which is overwritten when the program changes its title.

On exit, nnrpd reports usage statistics through syslog(3).

If the –t flag is used, all client commands and initial responses are traced by reporting them in syslog. This flag is set by innd under the control of the ctlinnd(8) trace command and is toggled upon receipt of a SIGHUP; see signal(2).

If the –S flag is used, all postings are forwarded to the specified host, which should be the master NNTP server. This flag is set by innd if it is started with the –S flag.

nnrpd can accept multimedia postings that follow the MIME standard as long as such postings are also acceptable as SMTP messages. See the discussion of the MIME headers in inn.conf(5).

PROTOCOL DIFFERENCES

nnrpd implements the NNTP commands defined in RFC 977 with the following differences:

■The ihave command is not implemented. Users should be using the post command to post articles.

■The slave command is not implemented. This command has never been fully defined.

■The list command may be followed by the optional word active.times, distributions, distrib.pats, newsgroups, or overview.fmt to get a list of when newsgroups where created, a list of valid distributions, a file specifying default distribution patterns, a one-per-line description of the current set of newsgroups, or a listing of the overview.fmt(5) file. The command list active is equivalent to the list command. This is a common extension.

■The xhdr, authinfo user, and authinfo pass commands are implemented. These are based on the reference UNIX implementation; no other documentation is available.

■A new command, xpat header range|MessageID pat [morepat...], is provided. The first argument is the case-insensitive name of the header to be searched. The second argument is either an article range or a single Message-ID as specified in RFC 977. The third argument is a wildmat(3)-style pattern; if there are additional arguments, they are joined together separated by a single space to form the complete pattern. This command is similar to the xhdr command. It returns a 221 response code, followed by the text response of all article numbers that match the pattern.

■The listgroup group command is provided. This is a comment extension. It is equivalent to the group command, except that the reply is a multi-line response containing the list of all article numbers in the group.

■The xgtitle [group] command is provided. This extension is used by ANU-News. It returns a 282 reply code, followed by a one-line description of all newsgroups that match the pattern. The default is the current group.

■The xover [range] command is provided. It returns a 224 reply code, followed by the overview data for the specified range; the default is to return the data for the current article.

■The xpath MessageID command is provided; see innd(8).

■The date command is provided; this is based on the draft NNTP protocol revision. It returns a one-line response code of 111 followed by the GMT date and time on the server in the form YYYYMMDDhhmmss.

nntpsend 1349

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews. Overview support added by Rob Robertston ([e-mail]) and Rich in January 1993.

SEE ALSO

ctlinnd(8), innd(8), inn.conf(5), nnrp.access(5), signal(2), wildmat(3)

nntpsend

nntpsend—Send Usenet articles to remote site.

SYNOPSIS

nntpsend [ -d ][-p ][-r ][-S ][-s size ][-t timeout ]

[-T timelimit ][sitename fqdn ] ...

DESCRIPTION

nntpsend is a front end that invokes innxmit(1) to send Usenet articles to a remote NNTP site.

The sites to be fed may be specified by giving sitename fqdn pairs on the command line. If no such pairs are given, nntpsend defaults to the information given in the nntpsend.ctl(5) config file.

The sitename should be the name of the site as specified in the newsfeeds(5) file. The fqdn should be the hostname or IP address of the remote site. An innxmit is launched for sites with queued news. All innxmit processes are spawned in the background and the script waits for them all to finish before returning. Output is sent to the file /var/log/news/nntpsend.log. To avoid overwhelming the local system, nntpsend waits five seconds before spawning each child. The flag –a is always given as a flag to innxmit.

nntpsend expects that the batchfile for a site is named /news/spool/out.going/sitename. To prevent batchfile corruption, shlock(1) is used to “lock” these files.

The –p, –r, –S, -t, and -T flags are passed on to the child innxmit program. Note that if the –p flag is used then no connection is made and no articles are fed to the remote site. It is useful to have cron(8) invoke nntpsend with this flag in case a site cannot be reached for an extended period of time.

If the –s flag is used, then shrinkfile(1) is invoked to perform a tail truncation on the batchfile and the flag is passed to it.

When sitename fqdn pairs are given on the command line, any flags given on the command completely describe how innxmit and shrinkfile operate. When no such pairs are given on the command line, then the information found in nntpsend.ctl becomes the default flags for that site. Any flags given on the command line override the default flags for the site.

For example, with the following control file:

nsavax:erehwon.nsavax.gov::-S -t60 group70:group70.org:: walldrug:walldrug.com:1m:-T1800 -t300

The command

nntpsend

will result in the following:

Sitename	Truncation	Innxmit flags
nsavax	(none)	-a -S -t60
group70	(none)	-a	-t180
walldrug	1m	-a	-T1800 -t300

		Part VIII: Administration and Privileged Commands
	1350

The command

nntpsend -d -T1200

will result in the following:

Sitename	Truncation	Innxmit flags
nsavax	(none)	-a -d -S -T1200 -t60
group70	(none)	-a	-d	-T1200	-t180
walldrug	1m	-a	-d	-T1200	-t300

The command

nntpsend -s 5m -T1200 nsavax erehwon.nsavax.gov group70 group70.org

will result in the following:

Sitename	Truncation	Innxmit flags
nsavax	5m	-a	-T1200	-t180
group70	5m	-a	-T1200	-t180

Remember that –a is always given, and –t defaults to 180.

HISTORY

Written by Landon Curt Noll ([e-mail]) and Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

innxmit(1), newsfeeds(5), nntpsend.ctl(5), shrinkfile(1)

nslookup

nslookup—Query Internet nameservers interactively.

SYNOPSIS

nslookup [ -option ... ] [ host-to-find | –[server ]]

DESCRIPTION

nslookup is a program to query Internet domain nameservers. nslookup has two modes: interactive and non-interactive. Interactive mode allows the user to query nameservers for information about various hosts and domains or to print a list of hosts in a domain. Non-interactive mode is used to print just the name and requested information for a host or domain.

ARGUMENTS

Interactive mode is entered in the following cases:

■When no arguments are given (the default nameserver is used)

■When the first argument is a hyphen (–) and the second argument is the hostname or Internet address of a nameserver

Non-interactive mode is used when the name or Internet address of the host to be looked up is given as the first argument. The optional second argument specifies the host name or address of a nameserver.

The options listed under the set command can be specified in the .nslookuprc file in the user’s home directory if they are listed one per line. Options can also be specified on the command line if they precede the arguments and are prefixed with a hyphen. For example, to change the default query type to host information, and the initial timeout to 10 seconds, type:

nslookup –query=hinfo –timeout=10

nslookup 1351

INTERACTIVE COMMANDS

Commands may be interrupted at any time by typing Ctrl+C. To exit, type Ctrl+D (EOF) or type exit. The command-line length must be less than 256 characters. To treat a built-in command as a hostname, precede it with an escape character (n). Note that an unrecognized command is interpreted as a hostname.

host [server]

server domain, lserver domain

root

finger [name][> filename], finger [name][>> filename]

ls [option] domain [> filename], ls [option] domain [>> filename]

class=value

Look up information for host using the current default server or using server if specified. If host is an Internet address and the query type is A or PTR, the name of the host is returned. If host is a name and does not have a trailing period, the default domain name is appended to the name. (This behavior depends on the state of the

set options domain, srchlist, defname, and search). To look up a host not in the current domain, append a period to the name.

Change the default server to domain. lserver uses the initial server to look up information about domain, whereas server uses the current default server. If an authoritative answer can’t be found, the names of servers that might have the answer are returned.

Changes the default server to the server for the root of the domain name space. Currently, the host ns.internic.net is used. (This command is a synonym for lserver ns.internic.net.) The name of the root server can be changed with the set root command.

Connects with the finger server on the current host. The current host is defined when a previous lookup for a host was successful and returned address information (see the set query-type= A command). name is optional. > and >> can be used to redirect output in the usual manner.

List the information available for domain, optionally creating or appending to filename. The default output contains hostnames and their Internet addresses. option can be one of the following:

-t querytype	Lists all records of the specified type (see
	querytype).
-a	Lists aliases of hosts in the domain. Synonym for
	-t CNAME.
-d	Lists all records for the domain. Synonym for
	-t ANY.
-h	Lists CPU and operating system information for
	the domain. Synonym for -t HINFO.
-s	Lists well-known services of hosts in the domain.
	Synonym for -t WKS. When output is directed to a
	file, hash marks are printed for every 50 records
	received from the server.
view filename	Sorts and lists the output of previous ls commands
	with more(1).
help, ?	Prints a brief summary of commands.
exit	Exits the program.
set keyword[=value]	This command is used to change state information
	that affects the lookups. Valid keywords are:
all	Prints the current values of the frequently used
	options to set. Information about the current
	default server and host is also printed.
Change the query class to one of the following:
IN	The Internet class.
CHAOS	The Chaos class.

		Part VIII: Administration and Privileged Commands
	1352

	HESIOD	The MIT Athena Hesiod class.
	ANY	Wildcard (any of the above).
	The class specifies the protocol group of the information. (Default = IN, abbreviation =
	cl.)
[no]debug	Turn debugging mode on. A lot more information is printed about the packet sent to
	the server and the resulting answer. (Default = nodebug, abbreviation = [no]deb.)
[no]d2	Turn exhaustive debugging mode on. Essentially, all fields of every packet are printed.
	(Default = nod2.)
domain=name	Change the default domain name to name. The default domain name is appended to a
	lookup request depending on the state of the defname and search options. The domain
	search list contains the parents of the default domain if it has at least two components in
	its name. For example, if the default domain is CC.Berkeley.EDU, the search list is
	CC.Berkeley.EDU and Berkeley.EDU. Use the set srchlist command to specify a different
	list. Use the set all command to display the list. (Default = value from hostname,
	/etc/resolv.conf, or LOCALDO-MAIN, abbreviation = do.)
srchlist=name1/name2/...	Change the default domain name to name1 and the domain search list to name1, name2,
	and so on. A maximum of six names separated by slashes (/) can be specified. For
	example, set srchlist=lcs.MIT.EDU/ai.MIT.EDU/MIT.EDU sets the domain to lcs.MIT.EDU
	and the search list to the three names. This command overrides the default domain
	name and search list of the set domain command. Use the set all command to display
	the list. (Default = value based on hostname, /etc/resolv.conf, or LOCAL-DOMAIN,
	abbreviation = srchl.)
[no]defname	If set, append the default domain name to a single-component lookup request (that is,
	one that does not contain a period). (Default = defname, abbreviation = [no]def.)
[no]search	If the lookup request contains at least one period but doesn’t end with a trailing period,
	append the domain names in the domain search list to the request until an answer is
	received. (Default = search, abbreviation = [no]sea.)
port=value	Change the default TCP/UDP nameserver port to value. (Default = 53, abbreviation =
	po.)
querytype=value, type=value	Change the type of information query to one of the following:
	A	The host’s Internet address.
	CNAME	The canonical name for an alias.
	HINFO	The host CPU and operating system type.
	MINFO	The mailbox or mail list information.
	MX	The mail exchanger.
	NS	The nameserver for the named zone.
	PTR	The host name if the query is an Internet address; otherwise, the pointer
		to other information.
	SOA	The domain’s “start-of-authority” information.
	TXT	The text information.
	UINFO	The user information.
	WKS	The supported well-known services.
	Other types (ANY, AXFR, MB, MD, MF, NULL) are described in the RFC-1035 document.
	(Default = A, abbreviations = q, ty.)
[no]recurse	Tell the nameserver to query other servers if it does not have the information. (Default =
	recurse, abbreviation = [no]rec.)
retry=number	Set the number of retries to number. When a reply to a request is not received within a
	certain amount of time (changed with set timeout), the timeout period is doubled and
	the request is resent. The retry value controls how many times a request is resent before
	giving up. (Default = 4, abbreviation = ret.)

	overchan
		1353
root=host	Change the name of the root server to host. This affects the root command. (Default =
	ns.internic.net, abbreviation = ro.)
timeout=number	Change the initial timeout interval for waiting for a reply to number seconds. Each retry
	doubles the timeout period. (Default = 5 seconds, abbreviation = ti.)
[no]vc	Always use a virtual circuit when sending requests to the server. (Default = novc,
	abbreviation = [no]v.)
[no]ignoretc	Ignore packet truncation errors. (Default = noignoretc, abbreviation = [no]ig.)

DIAGNOSTICS

If the lookup request was not successful, an error message is printed. Possible errors are

Timed out	The server did not respond to a request after a certain amount of time (changed with
	set timeout=value) and a certain number of retries (changed with set retry=value).
No response from server	No nameserver is running on the server machine.
No records	The server does not have resource records of the current query type for the host,
	although the hostname is valid. The query type is specified with the set querytype
	command.
Non-existent domain	The host or domain name does not exist.
Connection refused,	The connection to the name or finger server could not be made at the current time.
Network is unreachable	This error commonly occurs with ls and finger requests.
Server failure	The nameserver found an internal inconsistency in its database and could not return a
	valid answer.
Refused	The nameserver refused to service the request.
Format error	The nameserver found that the request packet was not in the proper format. It may
	indicate an error in nslookup.

FILES

/Etc/Resolv.Conf

$HOME/.nslookuprc

/usr/share/misc/nslookup.help

Initial domain name and nameserver addresses. User’s initial options.

Summary of commands.

ENVIRONMENT

HOSTALIASES	File containing host aliases.
LOCALDOMAIN	Overrides default domain.

SEE ALSO

resolver(3), resolver(5), named(8), RFC 1034 “Domain Names – Concepts and Facilities,” RFC 1035 “Domain Names – Implementation and Specification”

AUTHOR

Andrew Cherenson

24 June 1990

overchan

overchan—Update the news overview database.

		Part VIII: Administration and Privileged Commands
	1354

SYNOPSIS

overchan [ -D dir ][-c ][file... ]

DESCRIPTION

overchan reads article data from files or standard input if none are specified. (A single dash in the file list means to read standard input.) It uses this information to update the news overview database. overchan is designed to be used by InterNetNews or the C News mkov packages to update the database as the articles come in. The database for each newsgroup is stored in a file named .overview in a newsgroup directory within the overview database tree.

overchan locks the database file (by locking an auxiliary file) before appending the new data. To purge data after articles have been expired, see expireover(8).

By default, overchan processes its input as an INN overview stream written as a WO entry in the newsfeeds(5) file:

overview:*:Tc,WO:/news/bin/overchan

This data consists of a line of text separated into two parts by a tab. The first part is a list of all relative pathnames where the article has been written with a single space between entries. The second part is the data to be written into the overview file, except that the initial article number is omitted.

To process the output of the mkov(8) program, use the –c flag. This format is described in the nov distribution.

The –D flag can be used to specify where the databases are stored. The default directory is /news/spool.

HISTORY

Written by Rob Robertson ([e-mail]) and Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

newsfeeds(5), newsoverview(5), newsoverview(8)

pac

pac—Printer/plotter accounting information.

SYNOPSIS

pac [-P printer] [-c] [-m] [-p price] [-s] [-r] [name ...]

DESCRIPTION

pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) or feet (for raster devices) of paper consumed by each user and printing how much each user consumed in pages or feet and dollars.

Options and operands available:
-P printer	Accounting is done for the named printer. Usually, accounting is done for the default
	printer (site dependent), or the value of the environment variable PRINTER is used.
-c	Flag causes the output to be sorted by cost; usually, the output is sorted alphabetically
	by name.
-m	Flag causes the hostname to be ignored in the accounting file. This allows for a user on
	multiple machines to have all his printing charges grouped together.
-p price	The value price is used for the cost in dollars instead of the default value of 0.02 or the
	price specified in /etc/printcap.
-r	Reverse the sorting order.
-s	Accounting information is summarized on the summary accounting file; this summari-
	zation is necessary because on a busy system, the accounting file can grow by several
	lines per day.

pcnfsd 1355

names	Statistics are only printed for users named; usually, statistics are printed for every user
	who has used any paper.

FILES

/var/account/?acct

/var/account/?_sum

/etc/printcap

Raw accounting files Summary accounting files Printer capability database

SEE ALSO

printcap(5)

BUGS

The relationship between the computed price and reality is as yet unknown.

HISTORY

The pac command appeared in BSD 4.0.

BSD 4.2, 16 March 1991

pcnfsd

pcnfsd—(PC)NFS authentication and print request server

SYNOPSIS

/usr/etc/rpc.pcnfsd

AVAILABILITY

This program is freely redistributable.

DESCRIPTION

pcnfsd is an RPC server that supports ONC clients on PC (DOS, OS/2, Macintosh, and other) systems. This page describes version 2 of the pcnfsd server.

rpc.pcnfsd may be started from /etc/rc.local or by the inetd(8) superdaemon. It reads the configuration file /etc/pcnfsd.conf if present and then services RPC requests directed to program number 150001. This release of the pcnfsd daemon supports both version 1 and version 2 of the pcnfsd protocol. Consult the rpcgen source file pcnfsd.x for details of the protocols.

The requests serviced by pcnfsd fall into three categories: authentication, printing, and other. Only the authentication and printing services have administrative significance.

AUTHENTICATION

When pcnfsd receives a PCNFSD AUTH or PCNFSD2 AUTH request, it “logs in” the user by validating the username and password and returning the corresponding UID, GIDs, home directory, and umask. If pcnfsd was built with the WTMP compile-time option, it also appends a record to the wtmp(5) database. If you do not want to record PC logins in this way, you should add a line of the form

wtmp off

to the /etc/pcnfsd.conf file.

By default, pcnfsd only allows authentication or print requests for users with UIDs in the range 101 to 60002. (This corresponds in SVR4 to the range for non-system accounts.) To override this, you may add a line of the form

		Part VIII: Administration and Privileged Commands
	1356

uidrange range[,range]...

to the /etc/pcnfsd.conf file. Here, each range is of the form uid or uid-uid, indicating an inclusive range.

PRINTING

pcnfsd supports a printing model based on the use of NFS to transfer the actual print data from the client to the server. The client system issues a PCNFSD_PR_INIT or PCN-FSD2_PR_INIT request, and the server returns the path to a spool directory that the client may use and which is exported by NFS. pcnfsd creates a subdirectory for each of its clients: The parent directory is usually /usr/spool/pcnfs and the subdirectory is the hostname of the client system. If you want to use a different parent directory, you should add a line of the form

spooldir path

to the /etc/pcnfsd.conf file.

Once a client has mounted the spool directory using NFS and has transferred print data to a file in this directory, it issues a PCNFSD_PR_START or PCNFSD2_PR_START request. pcnfsd handles this, and most other print-related requests, by constructing a command based on the printing services of the server operating system and executing the command using the identity of the PC user. Because this involves set-user-ID privileges, pcnfsd must be run as root.

Every print request from the client includes the name of the printer that is to be used. In Linux, this name corresponds to a printer definition in the /etc/printcap(5) database. If you want to define a non-standard way of processing print data, you should define a new printer and arrange for the client to print to this printer. There are two ways of setting up a new printer. The first involves the addition of an entry to /etc/printcap(5) and the creation of filters to perform the required processing. This is outside the scope of this discussion. In addition, pcnfsd includes a mechanism by which you can define virtual printers known only to pcnfsd clients. Each printer is defined by a line in the /etc/pcnfsd.conf file of the following form:

printer name alias-for command

name is the name of the printer you want to define. alias-for is the name of a “real” printer that corresponds to this printer. For example, a request to display the queue for name is translated into the corresponding request for the printer alias-for. If you have defined a printer in such a way that there is no “real” printer to which it corresponds, use a single - for this field. (See the definition of the printer test for an example.) command is a command that will be executed whenever a file is printed on name. This command is executed by the shell at /bin/sh using the -c option. For complex operations, you should construct an executable shell program and invoke that in command.

Consider the following sample /etc/pcnfsd.conf file:

printer rotated lw /usr/local/bin/enscript -2r $FILE printer test - /usr/bin/cp $FILE/usr/tmp/$HOST$USER

If a client system prints a job on the printer rotated, the utility enscript is invoked to pre-process the file $FILE. In this case, the -2r option causes the file to be printed in two-column rotated format on the default PostScript printer. If the client requests a list of the print queue for the printer rotated, the pcnfsd daemon translates this into a request for a listing for the printer lw.

The printer test is used only for testing. Any file sent to this printer is copied into /usr/tmp. Any request to list the queue, check the status, and so on of printer test is rejected because the alias-for is specified as -.

plipconfig 1357

RECONFIGURATION

pcnfsd detects when printers are added or deleted and rebuilds its list of valid printers. To do this, it checks the modification time of /etc/printcap. However, it does not monitor the file /etc/pcnfsd.conf for updates; if you change this file, it is still necessary to kill and restart pcnfsd so the changes can take effect.

FILE

/etc/pcnfsd.conf

SEE ALSO

lpr(1), lprm(1), lpc(8), lpq(1)

25 June 1995

plipconfig

plipconfig—Fine-tune PLIP device parameters.

SYNOPSIS

plipconfig interface

plipconfig interface [nibble NN] [trigger NN] [unit NN]

DESCRIPTION

plipconfig is used to improve PLIP performance by changing the default timing parameters used by the PLIP protocol. Results are dependent on the parallel port hardware, cable, and the CPU speed of each machine on each end of the PLIP link.

If the single interface argument is given, plipconfig displays the status of the given interface only. Otherwise, it tries to set the options.

OPTIONS

nibble NN		Sets the nibble wait value in microseconds. Default is 3000.
trigger	NN	Sets the trigger wait value in microseconds. Default is 500.
unit NN		Sets the number of units of delay. Default is 1.

In some cases, PLIP speed can be improved by lowering the default values. Values that are too low might cause excess use of CPU, poor interrupt response time resulting in serial ports dropping characters, or in dropping PLIP packets. Changing the plip MTU can also affect PLIP speed.

SEE ALSO

ifconfig(8)

BUGS

None so far.

AUTHOR

John Paul Morrison ([e-mail], [e-mail])

1 July 1994

		Part VIII: Administration and Privileged Commands
	1358

ping

ping—Send ICMP ECHO_REQUEST packets to network hosts.

SYNOPSIS

/etc/ping [ -r ][-v ] host [ packetsize ][count ]

DESCRIPTION

The DARPA Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking a single-point hardware or software failure can often be difficult. Ping utilizes the ICMP protocol’s mandatory ECHO_REQUEST datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (“pings”) have an IP and ICMP header, followed by a struct timeval and then an arbitrary number of “pad” bytes used to fill out the packet. Default datagram length is 64 bytes, but this may be changed using the command-line option. Other options are

-r	Bypass the normal routing tables and send directly to a host on an attached network. If
	the host is not on a directly attached network, an error is returned. This option can be
	used to ping a local host through an interface that has no route through it (for example,
	after the interface was dropped by routed(8C)).
-v	Verbose output. ICMP packets other than ECHO_RESPONSE that are received are listed.

When using ping for fault isolation, it should first be run on the local host to verify that the local network interface is up and running. Then, hosts and gateways further away should be pinged. Ping sends one datagram per second and prints one line of output for every ECHO_RESPONSE returned. No output is produced if there is no response. If an optional count is given, only that number of requests is sent. Round-trip times and packet-loss statistics are computed. When all responses have been received or the program times out (with a count specified), or if the program is terminated with a SIGINT, a brief summary is displayed.

This program is intended for use in network testing, measurement, and management. It should be used primarily for manual fault isolation. Because of the load it could impose on the network, it is unwise to use ping during normal operations or from automated scripts.

AUTHOR

Mike Muuss

SEE ALSO

netstat(1), ifconfig(8)

19 September 1988

portmap

portmap—DARPA port to RPC program number mapper.

SYNOPSIS

portmap [-d]

DESCRIPTION

portmap is a server that converts RPC program numbers into DARPA protocol port numbers. It must be running in order to make RPC calls.

When an RPC server is started, it tells portmap what port number it is listening to and what RPC program numbers it is prepared to serve. When a client wants to make an RPC call to a given program number, it first contacts portmap on the server machine to determine the port number where RPC packets should be sent.

powerd 1359

portmap must be started before any RPC servers are invoked.

Usually, portmap forks and dissociates itself from the terminal like any other daemon. Portmap then logs errors using syslog(3).

Option available:

-d (debug) prevents portmap from running as a daemon and causes errors and debugging information to be printed to the standard error output.

SEE ALSO

inetd.conf(5), rpcinfo(8), inetd(8)

BUGS

If portmap crashes, all servers must be restarted.

HISTORY

The portmap command appeared in BSD 4.3.

BSD 4.3, 16 March 1991

powerd

powerd—Monitor a serial line connected to a UPS.

SYNOPSIS

/etc/powerd serial-device

DESCRIPTION

powerd is a daemon process that sits in the background and monitors the state of the DCD line of the serial device. It is meant that this line is connected to a UPS (Uninterruptible Power Supply) so that it knows about the state of the UPS. As soon as powerd senses that the power is failing (it sees that DCD goes low) it notifies init(8) and init executes the powerwait and powerfail entries. If powerd senses that the power has been restored, it notifies init again and init executes the powerokwait entries.

ARGUMENTS

serial-device

Some serial port that is not being used by some other device and does not share an interrupt with any other serial port.

DIAGNOSTICS

powerd regularly checks the DSR line to see if it’s high. DSR should be directly connected to DTR and powerd keeps that line high, so if DSR is low, something is wrong with the connection. powerd notifies you about this fact every two minutes. When it sees that the connection is restored, it will say so.

IMPLEMENTATION

It’s pretty simple to connect your UPS to the Linux machine. The steps are easy:

1.Make sure you have an UPS with a simple relais output: it should close its connections (make) if the power is gone, and it should open its connections (break) if the power is good.

2.Buy a serial plug. Connect the DTR line to the DSR line directly. Connect the DTR line and the DCD line with a 10 kilo ohm resistor. Connect the relais-output of the UPS to GROUND and the DCD line. If you don’t know what pins DSR, DTR, DCD and GROUND are, you can always ask at the store where you bought the plug.

3.You’re all set.

		Part VIII: Administration and Privileged Commands
	1360

BUGS

Well, it’s not a real bug but powerd should be able to do a broadcast or something on the Ethernet in case more Linux-boxes are connected to the same UPS and only one of them is connected to the UPS status line.

SEE ALSO

shutdown(8), init(8), inittab(5)

AUTHOR

Miquel van Smoorenburg ([e-mail])

14 February 1994

pppd

pppd—Point-to-Point Protocol daemon.

SYNOPSIS

pppd [ tty_name ][speed ][options ]

DESCRIPTION

The Point-to-Point Protocol (PPP) provides a method for transmitting datagrams over serial point-to-point links. PPP is composed of three parts: a method for encapsulating datagrams over serial links, an extensible Link Control Protocol (LCP), and a family of Network Control Protocols (NCP) for establishing and configuring different network-layer protocols.

The encapsulation scheme is provided by driver code in the kernel. pppd provides the basic LCP, authentication support, and an NCP for establishing and configuring the Internet Protocol (IP) (called the IP Control Protocol, IPCP).

FREQUENTLY USED OPTIONS

tty_name	Communicate over the named device. The string /dev/ is prepended if necessary. If no
	device name is given, or if the name of the controlling terminal is given, pppd uses the
	controlling terminal and does not fork to put itself in the background.
speed	Set the baud rate to speed (a decimal number). On systems such as 4.4BSD and
	NetBSD, any speed can be specified. Other systems (such as SunOS) allow only a
	limited set of speeds.
asyncmap map	Set the async character map to map. This map describes which control characters cannot
	be successfully received over the serial line. pppd asks the peer to send these characters as
	a 2-byte escape sequence. The argument is a 32-bit hex number with each bit represent-
	ing a character to escape. Bit 0 (00000001) represents the character 0x00; bit 31 (80000000)
	represents the character 0x1f or ˆ. If multiple asyncmap options are given, the values are
	ORed together. If no asyncmap option is given, no async character map is negotiated for
	the receive direction; the peer should then escape all control characters.
auth	Require the peer to authenticate itself before allowing network packets to be sent or
	received.
connect p	Use the executable or shell command specified by p to set up the serial line. This script
	typically uses the chat(8) program to dial the modem and start the remote PPP session.
crtscts	Use hardware flow control (that is, RTS/CTS) to control the flow of data on the serial
	port. If neither the crtscts nor the -crtscts option is given, the hardware flow control
	setting for the serial port is left unchanged.
defaultroute	Add a default route to the system routing tables, using the peer as the gateway, when
	IPCP negotiation is successfully completed. This entry is removed when the PPP
	connection is broken.

	pppd
			1361
disconnect p	Run the executable or shell command specified by p after pppd has terminated the link.
	This script could, for example, issue commands to the modem to cause it to hang up if
	hardware modem control signals were not available.
escape xx,yy,...	Specifies that certain characters should be escaped on transmission (regardless of whether
	the peer requests them to be escaped with its async control character map). The
	characters to be escaped are specified as a list of hex numbers separated by commas.
	Note that almost any character can be specified for the escape option, unlike the
	asyncmap option, which only allows control characters to be specified. The characters
	that cannot be escaped are those with hex values 0x20 - 0x3f or 0x5e.
file f	Read options from file f (the format is described later).
lock	Specifies that pppd should create a UUCP-style lock file for the serial device to ensure
	exclusive access to the device.
mru n	Set the MRU (Maximum Receive Unit) value to n for negotiation. pppd asks the peer to
	send packets of no more than n bytes. The minimum MRU value is 128. The default
	MRU value is 1500. A value of 296 is recommended for slow links (40 bytes for TCP/IP
	header plus 256 bytes of data).
mtu n	Set the MTU (Maximum Transmit Unit) value to n. Unless the peer requests a smaller
	value via MRU negotiation, pppd requests that the kernel networking code send data
	packets of no more than n bytes through the PPP network interface.
netmask n	Set the interface netmask to n, a 32-bit netmask in decimal dot notation (such as
	255.255.255.0). If this option is given, the value specified is ORed with the default
	netmask. The default netmask is chosen based on the negotiated remote IP address; it is
	the appropriate network mask for the class of the remote IP address ORed with the
	netmasks for any non–point-to-point network interfaces in the system that are on the
	same network.
passive	Enables the passive option in the LCP. With this option, pppd attempts to initiate a
	connection; if no reply is received from the peer, pppd then waits passively for a valid
	LCP packet from the peer (instead of exiting as it does without this option).
silent	With this option, pppd does not transmit LCP packets to initiate a connection until a
	valid LCP packet is received from the peer (as for the passive option with ancient
	versions of pppd).
OPTIONS
local IP address:remote IP address	Set the local and/or remote interface IP addresses. Either one may be
	omitted. The IP addresses can be specified with a host name or in decimal
	dot notation (such as 150.234.56.78). The default local address is the
	(first) IP address of the system (unless the noipdefault option is given).
	The remote address is obtained from the peer if not specified in any
	option. Thus, in simple cases, this option is not required. If a local and/or
	remote IP address is specified with this option, pppd does not accept a
	different value from the peer in the IPCP negotiation, unless the
	ipcp-accept-local and/or ipcp-accept-remote options are given.
-ac	Disable Address/Control compression negotiation (use default, address/
	control field compression disabled).
-all	Don’t request or allow negotiation of any options for LCP and IPCP (use
	default values).
-am	Disable asyncmap negotiation (use the default asyncmap; that is, escape all
	control characters).
-as n	Same as asyncmap n.

-ip-protocol

dns-addr

		Part VIII: Administration and Privileged Commands
	1362

bsdcomp nr,nt

-bsdcomp

+chap

-chap chap-interval n

chap-max-challenge n

chap-restart n

-crtscts

-d debug

-defaultroute

-detach

dns-addr n

domain d

-ip

+ip-protocol

-ip-protocol

+ipx-protocol

Request that the peer compress packets that it sends, using the BSD-Compress scheme, with a maximum code size of nr bits and agree to compress packets sent to the peer with a maximum code size of nt bits. If nt is not specified, it defaults to the value given for nr. Values in the range 9 to 15 may be used for nr and nt; larger values give better compression but consume more kernel memory for compression dictionaries. Alternatively, a value of 0 for nr or nt disables compression in the corresponding direction.

Disables compression; pppd does not request or agree to compress packets using the BSD-Compress scheme.

Require the peer to authenticate itself using CHAP (Cryptographic Handshake Authentication Protocol) authentication.

Don’t agree to authenticate using CHAP.

If this option is given, pppd rechallenges the peer every n seconds.

Set the maximum number of CHAP challenge transmissions to u (default is 10).

Set the CHAP restart interval (retransmission timeout for challenges) to n seconds (default is 3).

Disable hardware flow control (RTS/CTS) on the serial port. If neither the crtscts nor the -crtscts option is given, the hardware flow control setting for the serial port is left unchanged.

Increase debugging level (same as the debug option).

Increase debugging level (same as -d). If this option is given, pppd logs the contents of all control packets sent or received in a readable form. The packets are logged through syslog with facility daemon and level debug. This information can be directed to a file by setting up /etc/syslog.conf appropriately (see syslog.conf(5)).

Disable the defaultroute option. The system administrator who wants to prevent users from creating default routes with pppd can do so by placing this option in the /etc/ppp/options file.

Don’t fork to become a background process (otherwise, pppd will do so if a serial device other than its controlling terminal is specified).

This option sets the IP address or addresses for the Domain Name Server. It is used by Microsoft Windows clients. The primary DNS address is specified by the first instance of the option. The secondary is specified by the second instance.

Append the domain name d to the local hostname for authentication purposes. For example, if gethost-name() returns the name porsche, but the fully qualified domain name is porsche.Quotron.COM, you use the domain option to set the domain name to Quotron.COM.

Disable IP address negotiation. If this option is used, the remote IP address must be specified with an option on the command line or in an options file.

Enable the IPCP and IP protocols. This is the default condition. This option is only needed if the default setting is .

Disable the IPCP and IP protocols. This should only be used if you know you are using a client that only understands IPX and you don’t want to confuse the client with the IPCP protocol.

Enable the IPXCP and IPX protocols. This is the default condition if your kernel supports IPX. This option is only needed if the default setting is -ipx-protocol. If your kernel does not support IPX, this option has no effect.

pppd 1363

-ipx-protocol

Disable the IPXCP and IPX protocols. This should only be used if you know you are using a client that only understands IP and you don’t want to confuse the client with the IPXCP protocol.

ipcp-accept-local	With this option, pppd accepts the peer’s idea of a local IP address, even if
	the local IP address was specified in an option.
ipcp-accept-remote	With this option, pppd accepts the peer’s idea of its (remote) IP address,
	even if the remote IP address was specified in an option.
ipcp-max-configure n	Set the maximum number of IPCP configure-request transmissions to n
	(default is 10).
ipcp-max-failure n	Set the maximum number of IPCP configure-NAKs returned before
	starting to send configure-Rejects instead to n (default is 10).
ipcp-max-terminate n	Set the maximum number of IPCP terminate-request transmissions to n
	(default is 3).
ipcp-restart n	Set the IPCP restart interval (retransmission timeout) to n seconds
	(default is 3).
ipparam string	Provides an extra parameter to the ip-up and ip-down scripts. If this
	option is given, the string supplied is given as the sixth parameter to
	those scripts.
ipx-network n	Set the IPX network number in the IPXCP configure request frame to n.
	There is no valid default. If this option is not specified, the network
	number is obtained from the peer. If the peer does not have the network
	number, the IPX protocol is not started. This is a hexadecimal number
	and is entered without any leading sequence such as 0x. It is related to the
	ipxcp-accept-network option.
ipx-node n:m	Set the IPX node numbers. The two node numbers are separated from
	each other with a colon character. The first number n is the local node
	number. The second number m is the peer’s node number. Each node
	number is a hexadecimal number to the maximum of ten significant
	digits. The node numbers on the ipx-network must be unique. There is
	no valid default. If this option is not specified, the node number is
	obtained from the peer. This option is a related to the ipxcp-accept-local
	and ipxcp-accept-remote options.

ipx-router-name string

Set the name of the router. This is a string and is sent to the peer as information data.

ipx-routing n	Set the routing protocol to be received by this option. More than one
	instance of ipx-routing may be specified. The none option (0) may be
	specified as the only instance of ipx-routing. The values are 0 for none, 2
	for RIP/SAP, and 4 for NLSP.

ipxcp-accept-local

Accept the peer’s NAK for the node number specified in the ipx-node option. If a node number was specified and it is nonzero, the default is to insist that the value be used. If you include this option, you permit the peer to override the entry of the node number.

ipxcp-accept-network

Accept the peer’s NAK for the network number specified in the ipxnetwork option. If a network number was specified and it is nonzero, the default is to insist that the value be used. If you include this option, you permit the peer to override the entry of the node number.

ipxcp-accept-remote

Use the peer’s network number specified in the configure request frame. If a node number was specified for the peer and this option was not specified, the peer is forced to use the value that you specified.

ipxcp-max-configure n	Set the maximum number of IPXCP configure request frames that the
	system sends to n. The default is 10.

		Part VIII: Administration and Privileged Commands
	1364

ipxcp-max-failure n	Set the maximum number of IPXCP NAK frames that the local system
	sends before it rejects the options. The default value is 3.
ipxcp-max-terminate n	Set the maximum number of IPXCP terminate request frames before the
	local system considers that the peer is not listening to them. The default
	value is 3.
kdebug n	Enable debugging code in the kernel-level PPP driver. The argument n is
	a number that is the sum of the following values: 1 to enable general
	debug messages, 2 to request that the contents of received packets be
	printed, and 4 to request that the contents of transmitted packets be
	printed.
lcp-echo-failure n	If this option is given, pppd presumes the peer is dead if n LCP echo-
	requests are sent without receiving a valid LCP echo-reply. If this
	happens, pppd terminates the connection. Use of this option requires a
	nonzero value for the lcp-echo-interval parameter. This option can be
	used to enable pppd to terminate after the physical connection has been
	broken (for example, the modem has hung up) in situations where no
	hardware modem control lines are available.
lcp-echo-interval n	If this option is given, pppd sends an LCP echo-request frame to the peer
	every n seconds. Under Linux, the echo-request is sent when no packets
	are received from the peer for n seconds. Usually, the peer should respond
	to the echo-request by sending an echo-reply. This option can be used
	with the lcp-echo-failure option to detect that the peer is no longer
	connected.
lcp-max-configure n	Set the maximum number of LCP configure-request transmissions to n
	(default is 10).
lcp-max-failure n	Set the maximum number of LCP configure-NAKs returned before
	starting to send configure-Rejects instead to n (default is 10).
lcp-max-terminate n	Set the maximum number of LCP terminate-request transmissions to n
	(default is 3).
lcp-restart n	Set the LCP restart interval (retransmission timeout) to n seconds (default
	is 3).
local	Don’t use the modem control lines. With this option, pppd ignores the
	state of the CD (Carrier Detect) signal from the modem and does not
	change the state of the DTR (Data Terminal Ready) signal.
login	Use the system password database for authenticating the peer using PAP,
	and record the user in the system wtmp file.
modem	Use the modem control lines. This option is the default. With this
	option, pppd waits for the CD (Carrier Detect) signal from the modem to
	be asserted when opening the serial device (unless a connect script is
	specified), and it drops the DTR (Data Terminal Ready) signal briefly
	when the connection is terminated and before executing the connect
	script. On Ultrix, this option implies hardware flow control, as for the
	crtscts option.
-mn	Disable magic number negotiation. With this option, pppd cannot detect
	a looped-back line.
-mru	Disable MRU (MaximumReceive Unit) negotiation. With this option,
	pppd uses the default MRU value of 1500 bytes.
name n	Set the name of the local system for authentication purposes to n.
noipdefault	Disables the default behavior when no local IP address is specified, which
	is to determine (if possible) the local IP address from the hostname. With
	this option, the peer must supply the local IP address during IPCP

	pppd
			1365
	negotiation (unless it specified explicitly on the command line or in an
	options file).
-p	Same as the passive option.
+pap	Require the peer to authenticate itself using PAP.
-pap	Don’t agree to authenticate using PAP.
papcrypt	Indicates that all secrets in the /etc/ppp/pap-secrets file, which are used
	for checking the identity of the peer, are encrypted, and thus pppd should
	not accept a password (before encryption) that is identical to the secret
	from the /etc/ppp/pap-secrets file.
pap-max-authreq n	Set the maximum number of PAP authenticate-request transmissions to n
	(default is 10).
pap-restart n	Set the PAP restart interval (retransmission timeout) to n seconds (default
	is 3).
pap-timeout n	Set the maximum time that pppd waits for the peer to authenticate itself
	with PAP to n seconds (0 means no limit).
-pc	Disable protocol field compression negotiation (use default, protocol field
	compression disabled).
persist	Do not exit after a connection is terminated; instead, try to reopen the
	connection.
pred1comp	Attempt to request that the peer send the local system frames, which have
	been compressed by the Predictor-1 compression. The compression
	protocols must be loaded or this option is ignored.
-pred1comp	Do not accept Predictor-1 compression, even if the peer wants to send
	this type of compression and support has been defined in the kernel.
proxyarp	Add an entry to this system’s ARP (Address Resolution Protocol) table
	with the IP address of the peer and the Ethernet address of this system.
-proxyarp	Disable the proxyarp option. The system administrator who wants to
	prevent users from creating proxy ARP entries with pppd can do so by
	placing this option in the /etc/ppp/options file.
remotename n	Set the assumed name of the remote system for authentication purposes
	to n.
+ua p	Agree to authenticate using PAP (Password Authentication Protocol) if
	requested by the peer and use the data in file p for the user and password
	to send to the peer. The file contains the remote username, followed by a
	newline, followed by the remote password, followed by a newline. This
	option is obsolescent.
usehostname	Enforce the use of the hostname as the name of the local system for
	authentication purposes (overrides the name option).
user u	Set the username to use for authenticating this machine with the peer
	using PAP to u.
-vj	Disable negotiation of Van Jacobson-style TCP/IP header compression
	(use default, no compression).
-vjccomp	Disable the connection-ID compression option in Van Jacobson style
	TCP/IP header compression. With this option, pppd does not omit the
	connection-ID byte from Van Jacobson compressed TCP/IP headers or
	ask the peer to do so.
vj-max-slots n	Sets the number of connection slots to be used by the Van Jacobson
	TCP/IP header compression and decompression code to n, which must be
	between 2 and 16 (inclusive).

		Part VIII: Administration and Privileged Commands
	1366

xonxoff	Use software flow control (XON/XOFF) to control the flow of data on
	the serial port. This option is only implemented on Linux systems at
	present.

OPTIONS FILES

Options can be taken from files as well as the command line. pppd reads options from the files /etc/ppp/options and ~/.ppprc before looking at the command line. An options file is parsed into a series of words, delimited by whitespace. Whitespace can be included in a word by enclosing the word in quotes (“). A backslash (\) quotes the following character. A hash (#) starts a comment, which continues until the end of the line.

AUTHENTICATION

pppd provides system administrators with sufficient access control so that PPP access to a server machine can be provided to legitimate users without fear of compromising the security of the server or the network it’s on. In part, this is provided by the /etc/ppp/options file, where the administrator can place options to require authentication whenever pppd is run, and in part by the PAP and CHAP secrets files, where the administrator can restrict the set of IP addresses that individual users can use.

The default behavior of pppd is to agree to authenticate if requested and to not require authentication from the peer. However, pppd does not agree to authenticate itself with a particular protocol if it has no secrets that can be used to do so.

Authentication is based on secrets, which are selected from secrets files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP). Both secrets files have the same format, and both can store secrets for several combinations of server (authenticating peer) and client (peer being authenticated). Note that pppd can be both a server and client and that different protocols can be used in the two directions if desired.

A secrets file is parsed into words as for an options file. A secret is specified by a line containing at least three words, in the order client name, server name, and secret. Any following words on the same line are taken to be a list of acceptable IP addresses for that client. If there are only three words on the line, it is assumed that any IP address is okay; to disallow all IP addresses, use -. If the secret starts with an @, what follows is assumed to be the name of a file from which to read the secret. A * as the client or server name matches any name. When selecting a secret, pppd takes the best match—that is, the match with the fewest wildcards.

A secrets file contains both secrets for use in authenticating other hosts and secrets that you use for authenticating yourself to others. Which secret to use is chosen based on the names of the host (the local name) and its peer (the remote name). The local name is set as follows:

If the usehostname option is given,	The local name is the hostname of this machine (with the domain
	appended, if given).
If the name option is given	Use the argument of the first name option seen.
If the local IP address is specified with a	Use that name. Otherwise, use the hostname of this machine (with the
hostname	domain appended, if given).

When authenticating yourself using PAP, there is also a username, which is the local name by default, but can be set with the user option or the +ua option.

The remote name is set as follows:

If the remotename option is given

If the remote IP address is specified with a hostname

Secrets are selected from the PAP secrets file as follows:

Use the argument of the last remote-name option seen.

Use that host name. Otherwise, the remote name is the null string “”.

■For authenticating the peer, look for a secret with client == username specified in the PAP authenticate-request and server == local name.

■For authenticating yourself to the peer, look for a secret with client == your username and server == remote name.

pppd 1367

When authenticating the peer with PAP, a secret of “” matches any password supplied by the peer. If the password doesn’t match the secret, the password is encrypted using crypt( ) and checked against the secret again; thus secrets for authenticating the peer can be stored in encrypted form. If the papcrypt option is given, the first (unencrypted) comparison is omitted for better security.

If the login option was specified, the username and password are also checked against the system password database. Thus, the system administrator can set up the pap-secrets file to allow PPP access only to certain users and to restrict the set of IP addresses that each user can use. Typically, when using the login option, the secret in /etc/ppp/pap-secrets is “” to avoid the need to have the same secret in two places.

Secrets are selected from the CHAP secrets file as follows:

■For authenticating the peer, look for a secret with client == name specified in the CHAP-Response message and server == local name.

■For authenticating yourself to the peer, look for a secret with client == local name and server == name specified in the CHAP-Challenge message.

Authentication must be satisfactorily completed before IPCP (or any other Network Control Protocol) can be started. If authentication fails, pppd terminates the link (by closing LCP). If IPCP negotiates an unacceptable IP address for the remote host, IPCP is closed. IP packets can only be sent or received when IPCP is open.

In some cases, it is desirable to allow some hosts that can’t authenticate themselves to connect and use one of a restricted set of IP addresses, even when the local host generally requires authentication. If the peer refuses to authenticate itself when requested, pppd takes that as equivalent to authenticating with PAP using the empty string for the username and password. Thus, by adding a line to the pap-secrets file, which specifies the empty string for the client and password, it is possible to allow restricted access to hosts that refuse to authenticate themselves.

ROUTING

When IPCP negotiation is completed successfully, pppd informs the kernel of the local and remote IP addresses for the PPP interface. This is sufficient to create a host route to the remote end of the link, which enables the peers to exchange IP packets. Communication with other machines generally requires further modification to routing tables and/or ARP (Address Resolution Protocol) tables. In some cases, this is done automatically through the actions of the routed or gated daemons, but in most cases, some further intervention is required.

Sometimes it is desirable to add a default route through the remote host, as in the case of a machine whose only connection to the Internet is through the PPP interface. The defaultroute option causes pppd to create such a default route when IPCP comes up and delete it when the link is terminated.

In some cases, it is desirable to use proxy ARP—for example, on a server machine connected to a LAN—to allow other hosts to communicate with the remote host. The proxyarp option causes pppd to look for a network interface on the same subnet as the remote host (an interface supporting broadcast and ARP, which is up and not a point-to-point or loopback interface). If found, pppd creates a permanent, published ARP entry with the IP address of the remote host and the hardware address of the network interface found.

EXAMPLES

In the simplest case, you can connect the serial ports of two machines and issue a command like

pppd /dev/ttya 9600 passive

to each machine, assuming there is no getty running on the serial ports. If one machine has a getty running, you can use kermit or tip on the other machine to log in to the first machine and issue a command like

pppd passive

Then exit from the communications program (making sure the connection isn’t dropped) and issue a command like

pppd /dev/ttya 9600

		Part VIII: Administration and Privileged Commands
	1368

The process of logging in to the other machine and starting pppd can be automated by using the connect option to run chat:

pppd /dev/ttya 38400 connect ‘chat “” “” “login:” “username” “Password:” “pass-word” “% “ “exec pppd passive”’

(Note, however, that running chat like this leaves the password visible in the parameter list of pppd and chat.)

If your serial connection is any more complicated than a piece of wire, you might need to arrange for some control characters to be escaped. In particular, it is often useful to escape XON (^Q) and XOFF (^S), using asyncmap a0000. If the path includes a telnet, you probably should escape ˆ] as well (asyncmap 200a0000). If the path includes an rlogin, you need to use the escape ff option on the end that is running the rlogin client because many rlogin implementations are not transparent; they remove the sequence (0xff, 0xff, 0x73, 0x73, followed by any 8 bytes) from the stream.

DIAGNOSTICS

Messages are sent to the syslog daemon using the facility LOG_DAEMON. (This can be overridden by recompiling pppd with the macro LOG_PPP defined as the desired facility.) To see the error and debug messages, you need to edit your /etc/syslog.conf file to direct the messages to the desired output device or file.

The debug option causes the contents of all control packets sent or received to be logged—that is, all LCP, PAP, CHAP, or IPCP packets. This can be useful if the PPP negotiation does not succeed. If debugging is enabled at compile time, the debug option also causes other debugging messages to be logged.

Debugging can also be enabled or disabled by sending a SIGUSR1 to the pppd process. This signal acts as a toggle.

FILES

/var/run/pppn.pid (BSD or Linux)	Process-ID for pppd process on PPP interface unit n.
/etc/ppp/pppn.pid (others)
/etc/ppp/ip-up	A program or script that is executed when the link is available for sending and
	receiving IP packets (that is, IPCP has come up). It is executed with the
	parameters interface-name tty-device speed local-IP-address remote-IP-address
	and with its standard input, output and error streams redirected to /dev/null.
	This program or script is executed with the same real and effective user-ID as
	pppd—that is, at least the effective user-ID and possibly the real user-ID will be
	root. This is so that it can be used to manipulate routes, run privileged daemons
	(such as send-mail), and so on. Be careful that the contents of the /etc/ppp/ip-up
	and /etc/ppp/ip-down scripts do not compromise your system’s security.
/etc/ppp/ip-down	A program or script that is executed when the link is no longer available for
	sending and receiving IP packets. This script can be used for undoing the effects
	of the /etc/ppp/ip-up script. It is invoked with the same parameters as the ip-up
	script, and the same security considerations apply because it is executed with the
	same effective and real user-IDs as pppd.
/etc/ppp/ipx-up	A program or script that is executed when the link is available for sending and
	receiving IPX packets (that is, IPXCP has come up). It is executed with the
	parameters interface-name tty-device speed network-number local-IPX-node-
	address remote-IPX-node-address local-IPX-routing-protocol remote-IPX-
	routing-protocol local-IPX-router-name remote-IPX-router-name ipparam pppd-
	pid and with its standard input, output, and error streams redirected to
	/dev/null.
	The local-IPX-routing-protocol and remote-IPX-routing-protocol field may be
	one of the following:

	pppstats
			1369
	NONE to indicate that there is no routing protocol. RIP to indicate that RIP/SAP
	should be used. NLSP to indicate that Novell NLSP should be used. RIP NLSP to
	indicate that both RIP/SAP and NLSP should be used.
	This program or script is executed with the same real and effective user-ID as
	pppd—that is, at least the effective user-ID and possibly the real user-ID will be
	root. This is so that it can be used to manipulate routes, run privileged daemons
	(such as ripd), and so on. Be careful that the contents of the /etc/ppp/ipx-up and
	/etc/ppp/ipx-down scripts do not compromise your system’s security.
/etc/ppp/ipx-down	A program or script that is executed when the link is no longer available for
	sending and receiving IPX packets. This script can be used for undoing the
	effects of the /etc/ppp/ipx-up script. It is invoked with the same parameters as
	the ipx-up script, and the same security considerations apply because it is
	executed with the same effective and real user-IDs as pppd.
/etc/ppp/pap-secrets	Usernames, passwords, and IP addresses for PAP authentication.
/etc/ppp/chap-secrets	Names, secrets, and IP addresses for CHAP authentication.
/etc/ppp/options	System default options for pppd, read before user default options or command-
	line options.

~/.ppprc

/etc/ppp/options.ttyname

User default options, read before command-line options.

System default options for the serial port being used, read after command-line options.

SEE ALSO

RFC 1144	Jacobson, V. Compressing TCP/IP headers for low-speed serial links. February
	1990.
RFC 1321	Rivest, R. The MD5 Message-Digest Algorithm. April 1992.
RFC 1332	McGregor, G. PPP Internet Protocol Control Protocol (IPCP). May 1992.
RFC 1334	Lloyd, B.; Simpson, W.A. PPP authentication protocols. 1992 October.
RFC 1548	Simpson, W.A. The Point–to–Point Protocol (PPP). December 1993.
RFC 1549	Simpson, W.A. PPP in HDLC Framing. December 1993.

NOTES

The following signals have the specified effect when sent to the pppd process:

SIGINT, SIGTERM	These signals cause pppd to terminate the link (by closing LCP), restore the serial
	device settings, and exit.
SIGHUP	This signal causes pppd to terminate the link, restore the serial device settings, and
	close the serial device. If the persist option has been specified, pppd tries to
	reopen the serial device and start another connection. Otherwise, pppd exits.
SIGUSR2	This signal causes pppd to renegotiate compression. This can be useful to re-
	enable compression after it has been disabled as a result of a fatal decompression
	error. With the BSD Compress scheme, fatal decompression errors generally
	indicate a bug in one or another implementation.

AUTHORS

Drew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad Parker, and Paul Mackerras ([e-mail])

pppstats

pppstats—Print PPP statistics.

		Part VIII: Administration and Privileged Commands
	1370

SYNOPSIS

pppstats [ -v ][-r ][-c ][-i secs][unit# ]

DESCRIPTION

pppstats prints PPP-related statistics.

The -v flag causes pppstats to display additional statistics, such as the number of packets tossed (that is, which the VJ TCP header decompression code rejected).

The -r flag causes pppstats to display the overall packet compression rate. The rate value is between 0 and 1, with 0 meaning that the data is incompressible.

The -c flag is used to specify an alternate display mode that shows packet compression statistics: the number of packets and bytes uncompressed (that is, before compression or after decompression), compressed, and incompressible (packets that did not shrink on compression and were transmitted uncompressed), and the recent compression rate. This rate reflects the recent performance of the compression code rather than the overall rate the code compression was enabled.

The -i flag is used to specify the interval between printouts. The default is 5 seconds.

unit# specifies which interface to use for gathering statistics.

2 May 1995

prunehistory

prunehistory—Remove filenames from Usenet history file.

SYNOPSIS

prunehistory [ -f filename ][-p ][input ]

DESCRIPTION

prunehistory modifies the history(5) text file to remove a set of filenames from it. The filenames are removed by overwriting them with spaces so that the size and position of any following entries do not change.

prunehistory reads the named input file or standard input if no file is given. The input is taken as a set of lines. Blank lines and lines starting with a number sign (#) are ignored. All other lines should consist of a Message-ID followed by zero or more filenames. prunehistory usually complains about lines that do not follow this format. If the –p flag is used, then the program silently prints any invalid lines on its standard output. (Blank lines and comment lines are also passed through.) This can be useful when prunehistory is used as a filter for other programs such as reap.

The Message-ID is used as the dbz(3) key to get an offset into the text file. If no filenames are mentioned on the input line, then all filenames in the text are removed. If any filenames are mentioned, they are converted into the history file notation. If they appear in the line for the specified Message-ID, they are removed.

The default name of the history file is /news/lib/history; to specify a different name, use the –f flag.

Because innd(8) only appends to the text file, prunehistory does not need to have any interaction with it.

It is a good idea to delete purged entries and rebuild the dbz database every so often by using a script such as the following:

ctlinnd throttle “Rebuilding history database” cd /news/lib

awk ‘NF > 2 {

printf “%s\t%s\t%s”,$1,$2,$3; for (i = 4; i <= NF; i++) printf “ %s”, $i;

print “\n”;

}’ <history >history.n

if makehistory –r –f history.n ; then

quotacheck 1371

mv history.n history

mv history.n.pag history.pag mv history.n.dir history.dir else

echo ‘Problem rebuilding history; old file not replaced’ fi

ctlinnd go “Rebuilding history database”

Note that this keeps no record of expired articles.

HISTORY

Written by Rich $alz ([e-mail]) for InterNetNews.

SEE ALSO

dbz(3), history(5), innd(8)

quotacheck

quotacheck—Scan a filesystem for disk usages.

SYNOPSIS

quotacheck [-g] [-u] [-v] -a

quotacheck [-g] [-u] [-v] filesys ...

DESCRIPTION

quotacheck performs a filesystem scan for usage of files and directories, used by either user or group. The output is the quota file for the corresponding filesystem. By default, the names for these files are

A user scan	quota.user
A group scan	quota.group

The resulting file consists of a struct dqblk for each possible ID up to the highest existing UID or GID and contains the values for the disk file and block usage and possibly excess time for these values. (For definitions of struct dqblk, see linux/quota.h.)

quotacheck should be run each time the system boots and mounts non-valid filesystems. This is most likely to happen after a system crash.

The speed of the scan decreases with the amount of directories increasing. The time needed doubles when disk usage is doubled as well. A 100MB partition used for 94 percent is scanned in one minute; the same partition used for 50 percent is done in 25 seconds.

OPTIONS

-v	This way, the program will give some useful information about what it is doing, plus
	some fancy stuff.
-d	This means debug. It will result in a lot of information that can be used in debugging
	the program. The output is very verbose and the scan will not be fast.
-u	This flag tells the program to scan the disk and to count the files and directories used by
	a certain UID. This is the default action.
-g	This flag forces the program to count the files and directories used by a certain GID.
NOTE

checkquota should only be run as superuser. Non-privileged users are presumably not allowed to read all the directories on the given filesystem.

		Part VIII: Administration and Privileged Commands
	1372

SEE ALSO

quota(1), quotactl(2), fstab(5), quotaon(8), quotaoff(8), edquota(8), repquota(8), fsck(8), efsck(8), e2fsck(8), xfsck(8)

FILES

quota.user

quota.group

/etc/fstab

AUTHOR

Edvard Tuinder ([e-mail], [e-mail]), Marco van Wieringen ([e-mail], [e-mail]).

21 August 1993

quotaon, quotaoff

quotaon, quotaoff—Turn filesystem quotas on and off.

SYNOPSIS

/usr/etc/quotaon [ -vug ] filesystem...

/usr/etc/quotaon [ -avug ]

/usr/etc/quotaoff [ -vug ] filesystem...

/usr/etc/quotaoff [ -avug ]

DESCRIPTION

quotaon announces to the system that disk quotas should be enabled on one or more filesystems. The filesystem quota files must be present in the root directory of the specified filesystem and be named quota.user for user quota or quota.group for group quota.

quotaoff announces to the system that filesystems specified should have any disk quotas turned off.

OPTIONS quotaon

-a	All filesystems in /etc/fstab marked read-write with quotas will have their quotas
	turned on. This is usually used at boot time to enable quotas.
-v	Display a message for each filesystem where quotas are turned on.
-u	Manipulate user quotas. This is the default.
-g	Manipulate group quotas.

quotaoff

-a	Force all filesystems in /etc/fstab to have their quotas disabled.
-v	Display a message for each filesystem affected.
-u	Manipulate user quotas. This is the default.
-g	Manipulate group quotas.

FILES

quota.user	User quota file at the filesystem root
quota.group	Group quota file at the filesystem root
/etc/fstab	Default filesystems

rdev 1373

SEE ALSO

quotactl(2), fstab(5)

8 June 1993

rarp

rarp—Manipulate the system RARP table.

SYNOPSIS

rarp [-v] [-t type] -a [hostname] rarp [-v] -d hostname ...

rarp [-v] [-t type] -s hostname hw_addr

DESCRIPTION

rarp manipulates the kernel’s RARP table in various ways. The primary options are clearing an address mapping entry and manually setting up one. For debugging purposes, the rarp program also allows a complete dump of the RARP table.

OPTIONS

-v	Tell the user what is going on by being verbose.
-t type	When setting or reading the RARP table, this optional parameter tells rarp which class
	of entries it should check for. The default value of this parameter is ether (hardware
	code 0x01 for IEEE 802.3 10Mbps Ethernet). Other values might include network
	technologies such as AX.25 (ax25).
-a [hostname]	Shows the entries of the specified hosts. If the hostname parameter is not used, all entries
	are displayed.

-d hostname

Remove the entries of the specified host. This can be used if the indicated host is brought down, for example.

-s hostname hw_addr	Create an RARP address mapping entry for host hostname with hardware address set to
	hw_addr class, but for most classes, you can assume that the usual presentation can be
	used. For the Ethernet class, this is 6 bytes in hexadecimal, separated by colons.

FILES

/proc/net/rarp

AUTHORS

Ross D. Martin ([e-mail]), Fred N. van Kempen ([e-mail]).

11 June 1994

rdev

rdev—Query/set image root device, swap device, RAM disk size, or video mode.

SYNOPSIS

rdev [ -rsvh ] [ -o offset ][image [ value [ offset ]]]

rdev [ -o offset ][image [ root_device [ offset ]]]

swapdev [ -o offset ][image [ swap_device [ offset ]]]

ramsize [ -o offset ][image [ size [ offset ]]]

vidmode [ -o offset ][image [ mode [ offset ]]]

rootflags [ -o offset ][image [ flags [ offset ]]]

		Part VIII: Administration and Privileged Commands
	1374

DESCRIPTION

With no arguments, rdev outputs an /etc/mtab line for the current root filesystem. With no arguments, swapdev, ramsize, vidmode, and rootflags print usage information.

In a bootable image for the Linux kernel, there are several pairs of bytes that specify the root device, the video mode, the size of the RAM disk, and the swap device. These pairs of bytes, by default, begin at offset 504 (decimal) in the kernel image:

498 Root flags

(500 and 502 Reserved)

504 RAM Disk Size

506 VGA Mode

508 Root Device

(510 Boot Signature)

rdev changes these values.

Typical values for the image parameter, which is a bootable Linux kernel image, are as follows:

/vmlinux

/vmlinux.test

/vmunix

/vmunix.test

/dev/fd0

/dev/fd1

When using the rdev or swapdev commands, the root device or swap device parameter are as follows:

/dev/hda[1-8] /dev/hdb[1-8] /dev/sda[1-8] /dev/sdb[1-8]

For the ramsize command, the size parameter specifies the size of the RAM disk in kilobytes.

For the rootflags command, the flags parameter contains extra information used when mounting root. Currently, the only effect of these flags is to force the kernel to mount the root filesystem in read-only mode if flags is nonzero.

For the vidmode command, the mode parameter specifies the video mode:

-3	Prompt
-2	Extended VGA
-1	Normal VGA
0	As if 0 was pressed at the prompt
1	As if 1 was pressed at the prompt
2	As if 2 was pressed at the prompt
n	As if n was pressed at the prompt

If the value is not specified, the image is examined to determine the current settings.

OPTIONS

-s	Causes rdev to act like swapdev.
-r	Causes rdev to act like ramsize.
-R	Causes rdev to act like rootflags.
-v	Causes rdev to act like vidmode.
-h	Provides help.

renice 1375

BUGS

For historical reasons, there are two methods for specifying alternative values for the offset.

The user interface is cumbersome, non-intuitive, and should probably be rewritten from scratch, allowing multiple kernel image parameters to be changed or examined with a single command.

If LILO is used, rdev is no longer needed for setting the root device and the VGA mode because the parameters that rdev modifies can be set from the LILO prompt during a boot. However, rdev is still needed at this time for setting the RAM disk size. Users are encouraged to find the LILO documentation for more information and to use LILO when booting their systems.

AUTHORS

Originally by Werner Almesberger ([e-mail]). Modified by Peter MacDonald ([e-mail]). rootflags support added by Stephen Tweedie ([e-mail]).

Linux 0.99, 20 November 1993

renice

renice—Alter priority of running processes.

SYNOPSIS

renice priority [[-p] pid ...

] [[ -g] pgrp ...

] [[-u] user ...

]

DESCRIPTION

renice alters the scheduling priority of one or more running processes. The following “who” parameters are interpreted as process IDs, process group IDs, or user names. reniceing a process group causes all processes in the process group to have their scheduling priority altered. reniceing a user causes all processes owned by the user to have their scheduling priority altered. By default, the processes to be affected are specified by their process IDs.

Options supported by renice:

-g

-u

-p

Force who parameters to be interpreted as process group IDs. Force the who parameters to be interpreted as usernames. Reset the who interpretation to be (the default) process IDs.

The following example changes the priority of process IDs 987 and 32 and all processes owned by users daemon and root:

renice +1 987 -u daemon root -p 32

Users other than the superuser can only alter the priority of processes they own and can only monotonically increase their “nice value” within the range 0 to PRIO_MAX (20). (This prevents overriding administrative fiats.) The superuser can alter the priority of any process and set the priority to any value in the range PRIO_MIN (–20) to PRIO_MAX. Useful priorities are: 20 (the affected processes run only when nothing else in the system wants to), 0 (the “base” scheduling priority), and anything negative (to make things go very fast).

FILES

/etc/passwd to map usernames to user IDs

SEE ALSO

getpriority(2), setpriority(2)

BUGS

Non-superusers cannot increase scheduling priorities of their own processes, even if they were the ones that decreased the priorities in the first place.

		Part VIII: Administration and Privileged Commands
	1376

HISTORY

The renice command appeared in BSD 4.0.

BSD 4, 9 June 1993

repquota

repquota—Summarize quotas for a filesystem.

SYNOPSIS

/usr/etc/repquota [ -vug ] filesystem...

/usr/etc/repquota [ -avug ]

DESCRIPTION

repquota prints a summary of the disk usage and quotas for the specified filesystems. For each user, the current number of files and amount of space (in kilobytes) is printed, along with any quotas created with edquota(8).

OPTIONS

-a	Report on all filesystems indicated in /etc/fstab to be read-write with quotas.
-v	Report all quotas even if there is no usage.
-g	Report quotas for groups.
-u	Report quotas for users. This is the default.

Only the superuser can view quotas that are not their own.

FILES

quotas	Quota file at the filesystem root
/etc/fstab	Default filesystems

SEE ALSO

quota(1), quotactl(2), edquota(8), quotacheck(8), quotaon(8)

8 June 1993

rexecd

rexecd—Remote execution server.

SYNOPSIS

rexecd

DESCRIPTION

rexecd is the server for the rexec(3) routine. The server provides remote execution facilities with authentication based on usernames and passwords.

rexecd listens for service requests at the port indicated in the exec service specification; see services(5). When a service request is received, the following protocol is initiated:

1.The server reads characters from the socket up to a null \0 byte. The resultant string is interpreted as an ASCII number, base 10.

rlogind 1377

2.If the number received in Step 1 is nonzero, it is interpreted as the port number of a secondary stream to be used for the stderr. A second connection is then created to the specified port on the client’s machine.

3.A null-terminated username of at most 16 characters is retrieved on the initial socket.

4.A null-terminated, unencrypted password of at most 16 characters is retrieved on the initial socket.

5.A null-terminated command to be passed to a shell is retrieved on the initial socket. The length of the command is limited by the upper bound on the size of the system’s argument list.

6.rexecd then validates the user as is done at login time and, if the authentication was successful, changes to the user’s home directory and establishes the user and group protections of the user. If any of these steps fail, the connection is aborted with a diagnostic message returned.

7.A null byte is returned on the initial socket and the command line is passed to the normal login shell of the user. The shell inherits the network connections established by rexecd.

DIAGNOSTICS

Except for the last one listed, all diagnostic messages are returned on the initial socket, after which any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in Step 7 upon successful completion of all the steps prior to the command execution).

username too long password too long command too long

The name is longer than 16 characters. The password is longer than 16 characters.

The command line passed exceeds the size of the argument list (as configured into the system).

Login incorrect.	No password file entry for the username existed or the wrong password was supplied.
No remote directory.	The chdir command to the home directory failed.
Try again.	A fork by the server failed.
<shellname>: ...	The user’s login shell could not be started. This message is returned on the connection
	associated with the stderr and is not preceded by a flag byte.

SEE ALSO

rexec(3)

BUGS

A facility to allow all data and password exchanges to be encrypted should be present.

HISTORY

The rexecd command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

rlogind

rlogind—Remote login server.

SYNOPSIS

rlogind [-aln]

DESCRIPTION

rlogind is the server for the rlogin(1) program. The server provides a remote login facility with authentication based on privileged port numbers from trusted hosts.

		Part VIII: Administration and Privileged Commands
1378
	Options supported by rlogind:

-a	Ask hostname for verification.
-l	Prevent any authentication based on the user’s .rhosts file unless the user is logging in
	as the superuser.
-n	Disable keep-alive messages.

rlogind listens for service requests at the port indicated in the “login” service specification; see services(5). When a service request is received, the following protocol is initiated:

1.The server checks the client’s source port. If the port is not in the range 512-1023, the server aborts the connection.

2.The server checks the client’s source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), and named(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. If the hostname is in the same domain as the server (according to the last two components of the domain name), or if the -a option is given, the addresses for the hostname are requested, verifying that the name and address correspond. Normal authentication is bypassed if the address verification fails.

Once the source port and address have been checked, rlogind proceeds with the authentication process described in rshd(8). It then allocates a pseudo terminal (see pty(4)) and manipulates file descriptors so that the slave half of the pseudo terminal becomes the stdin, stdout, and stderr for a login process. The login process is an instance of the login(1) program, invoked with the -f option if authentication has succeeded. If automatic authentication fails, the user is prompted to log in as if on a standard terminal line.

The parent of the login process manipulates the master side of the pseudo terminal, operating as an intermediary between the login process and the client instance of the rlogin program. In normal operation, the packet protocol described in pty(4) is

^ ^

invoked to provide S/Q type facilities and propagate interrupt signals to the remote programs. The login process propagates the client terminal’s baud rate and terminal type, as found in the environment variable, TERM; see environ(7). The screen or window size of the terminal is requested from the client, and window size changes from the client are propagated to the pseudo terminal.

Transport-level keep-alive messages are enabled unless the -n option is present. The use of keep-alive messages allows sessions to be timed out if the client crashes or becomes unreachable.

DIAGNOSTICS

All initial diagnostic messages are indicated by a leading byte with a value of 1, after which any network connections are closed. If there are no errors before login is invoked, a null byte is returned as in indication of success.

Try again.

A fork by the server failed.

SEE ALSO

login(1), ruserok(3), rshd(8)

BUGS

The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is insecure but is useful in an “open” environment.

A facility to allow all data exchanges to be encrypted should be present.

A more extensible protocol should be used.

HISTORY

The rlogind command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

route 1379

route

route—Show/manipulate the IP routing table.

SYNOPSIS

route [ -vn ]

route [ -v ] add [ -net | -host ] XXXX [gw GGGG] [metric MMMM] [netmask NNNN] [mss NNNN] [window NNNN] [dev DDDD]

route [ -v ] del XXXX

DESCRIPTION

route manipulates the kernel’s IP routing table. Its primary use is to set up static routes to specific hosts or networks via an interface after it has been configured with the ifconfig(8) program. This version of route is intended solely for use with kernel versions 0.99pl14n and newer kernels.

OPTIONS

(none)	Prints out the kernel routing table, listing destination address, gateway, netmask for
	route (“Genmask”), flags (U = Up, H = Host, G = Gateway, D = dynamic, M = Modified),
	Metric (currently not supported), Ref, Use, and Iface (which device the route maps to).
-n	Same as previous but shows numerical addresses instead of trying to determine symbolic
	host names.
-v	A flag for verbose (not actually used).
del XXXX	Deletes the route associated with the destination address XXXX.

add[-net | -host ] XXXX [gw GGGG] Adds a route to the IP address XXXX. The route is a network route if the -net modifier is

[metric MMMM] [netmask NNNN]	used or XXXX is found in /etc/networks by the getnetbyname() library function and no
[dev DDDD]	-host modifier is used.
	The gw GGGG argument means that any IP packets sent to this address will be routed
	through the specified gateway. Note: The specified gateway must be reachable first. This
	usually means that you have to set up a static route to the gateway beforehand.
	The metric MMMM modifier is not yet implemented (and with the -v option will actually
	print a warning).
	The netmask NNNN modifier specifies the netmask of the route to be added. This only
	makes sense for a network route and when the address XXXX actually makes sense with
	the specified netmask. If no netmask is given, route guesses it instead, so for most
	normal setups, you won’t need to specify a netmask.
	The mss NNNN modifier specifies the TCP mss for the route to be added. This is usually
	used only for fine optimization of routing setups.
	The window NNNN modifier specifies the TCP window for the route to be added. This is
	typically only used on AX.25 networks and with drivers unable to handle back-to-back
	frames—such as the 3c501 or DE600.
	The dev DDDD modifier forces the route to be associated with the specified device because
	the kernel will otherwise try to determine the device on its own (by checking already
	existing routes and device specifications and where the route is added to). In most
	normal networks, you won’t need this.
	If dev DDDD is the last option on the command line, the word dev may be omitted
	because it’s the default. Otherwise, the order of the route modifiers (metric, netmask, gw,
	and dev) doesn’t matter.

		Part VIII: Administration and Privileged Commands
	1380
	EXAMPLES

route add -net 127.0.0.0	Adds the normal loopback entry, using netmask 255.0.0.0 (Class A net determined from
	the destination address) and associated with the lo device (assuming this device was
	previously set up correctly with ifconfig(8)).
route add -net 192.56.76.0	Adds a route to the network 192.56.76.x via eth0. The Class C netmask modifier is not
netmask 255.255.255.0 dev eth0	really necessary here because 192.* is a Class C IP address. The word dev can be omitted
	here.
route add default gw mango-gw	Adds a default route (which will be used if no other route matches). All packets using
	this route will be gatewayed through mango-gw. The device that will actually be used for
	that route depends on how you can reach mango-gw; the static route to mango-gw will have
	to be set up before.

route add ipx4 sl0 route add -net 192.57.66.0 netmask 255.255.255.0 gw ipx4

This command sequence adds the route to the ipx4 host via the SLIP interface (assuming that ipx4 is the SLIP host) and then adds the net 192.57.66.0 to be gatewayed through that host.

FILES

/proc/net/route

/etc/networks

/etc/hosts

SEE ALSO

ifconfig(8)

HISTORY

route for Linux was originally written by Fred N. van Kempen ([e-mail]) and then modified by Johannes Stille and Linus Torvalds for pl15. Alan Cox added the mss and window options for Linux 1.1.22.

14 June 1994

routed

routed—Network routing daemon.

SYNOPSIS

routed [-d] [-g] [-q] [-s] [-t] [logfile]

DESCRIPTION

routed is invoked at boot time to manage the network routing tables. The routing daemon uses a variant of the Xerox NS Routing Information Protocol in maintaining up-to-date kernel routing table entries. It used a generalized protocol capable of use with multiple address types but is currently used only for Internet routing within a cluster of networks.

In normal operation, routed listens on the udp(4) socket for the route(8) service (see services(5)) for routing information packets. If the host is an internetwork router, it periodically supplies copies of its routing tables to any directly connected hosts and networks.

When routed is started, it uses the SIOCGIFCONF ioctl(2) to find those directly connected interfaces configured into the system and marked “up” (the software loopback interface is ignored). If multiple interfaces are present, it is assumed that the host will forward packets between networks. routed then transmits a request packet on each interface (using a broadcast packet if the interface supports it) and enters a loop, listening for request and response packets from other hosts.

routed 1381

When a request packet is received, routed formulates a reply based on the information maintained in its internal tables. The response packet generated contains a list of known routes, each marked with a “hop count” metric (a count of 16, or greater, is considered “infinite”). The metric associated with each route returned provides a metric relative to the sender.

Response packets received by routed are used to update the routing tables if one of the following conditions is satisfied:

No routing table entry exists for the destination network or host, and the metric indicates the destination is “reachable” (the hop count is not infinite).

The source host of the packet is the same as the router in the existing routing table entry. That is, updated information is being received from the very internetwork router through which packets for the destination are being routed.

The existing entry in the routing table has not been updated for some time (defined to be 90 seconds) and the route is at least as cost effective as the current route.

The new route describes a shorter route to the destination than the one currently stored in the routing tables; the metric of the new route is compared against the one stored in the table to decide this.

When an update is applied, routed records the change in its internal tables and updates the kernel routing table. The change is reflected in the next response packet sent.

In addition to processing incoming packets, routed also periodically checks the routing table entries. If an entry has not been updated for three minutes, the entry’s metric is set to infinity and marked for deletion. Deletions are delayed an additional 60 seconds to ensure the invalidation is propagated throughout the local Internet.

Hosts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly connected hosts and networks. The response is sent to the broadcast address on nets capable of that function, to the destination address on point-to-point links, and to the router’s own address on other networks. The normal routing tables are bypassed when sending gratuitous responses. The reception of responses on each network is used to determine that the network and interface are functioning correctly. If no response is received on an interface, another route may be chosen to route around the interface, or the route may be dropped if no alternative is available.

Options supported by routed:

-d -g

Enable additional debugging information to be logged, such as bad packets received.

This flag is used on internetwork routers to offer a route to the “default” destination. This is typically used on a gateway to the Internet or on a gateway that uses another routing protocol whose routes are not reported to other local routers.

-s	Supplying this option forces routed to supply routing information whether it is acting as
	an internetwork router or not. This is the default if multiple network interfaces are
	present or if a point-to-point link is in use.
-q	This is the opposite of the -s option.
-t	If the -t option is specified, all packets sent or received are printed on the standard
	output. In addition, routed will not divorce itself from the controlling terminal so that
	interrupts from the keyboard will kill the process.

Any other argument supplied is interpreted as the name of file in which routed’s actions should be logged. This log contains information about any changes to the routing tables and, if not tracing all packets, a history of recent messages sent and received that are related to the changed route.

In addition to the facilities described previously, routed supports the notion of “distant” passive and active gateways. When routed is started, it reads the file to find gateways that might not be located using only information from the SIOGIFCONFioctl

(2). Gateways specified in this manner should be marked passive if they are not expected to exchange routing information, whereas gateways marked active should be willing to exchange routing information (that is, they should have a routed process running on the machine). Routes through passive gateways are installed in the kernel’s routing tables once upon startup. Such routes are not included in any routing information transmitted. Active gateways are treated equally to network interfaces. Routing information is distributed to the gateway, and if no routing information is received for a period of the time, the associated route is deleted. Gateways marked external are also passive but are not placed in the kernel routing table

		Part VIII: Administration and Privileged Commands
	1382

nor are they included in routing updates. The function of external entries is to inform routed that another routing process will install such a route and that alternate routes to that destination should not be installed. Such entries are only required when both routers might learn of routes to the same destination.

The /etc/gateways is comprised of a series of lines, each in the following format:

<net|host> name1 gateway name2 metric value <passive|active|external>

The net or host keyword indicates if the route is to a network or specific host.

name1 is the name of the destination network or host. This can be a symbolic name located in or known to the name server if started after named(8) or an Internet address specified in “dot” notation; see inet(3).

name2 is the name or address of the gateway to which messages should be forwarded.

value is a metric indicating the hop count to the destination host or network.

One of the keywords passive, active, or external indicates if the gateway should be treated as passive or active (as described previously) or whether the gateway is external to the scope of the routed protocol.

Internetwork routers that are directly attached to the ARPAnet or Milnet should use the Exterior Gateway Protocol (EGP) to gather routing information rather than use a static routing table of passive gateways. EGP is required in order to provide routes for local networks to the rest of the Internet system. Sites needing assistance with such configurations should contact the Computer Systems Research Group at Berkeley.

FILES

/etc/gateways for distant gateways

SEE ALSO

udp(4), icmp(4), XNSrouted(8), htable(8)

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard

BUGS

The kernel’s routing tables may not correspond to those of routed when redirects change or add routes. routed should note any redirects received by reading the ICMP packets received via a raw socket.

routed should incorporate other routing protocols, such as Xerox NS, XNSrouted(8), and EGP . Using separate processes for each requires configuration options to avoid redundant or competing routes.

routed should listen to intelligent interfaces, such as an IMP, to gather more information. It does not always detect unidirectional failures in network interfaces (such as when the output side fails).

HISTORY

The routed command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

rpc.rusersd

rpc.rusersd—Logged-in users server.

SYNOPSIS

/usr/libexec/rpc.rusersd

DESCRIPTION

rpc.rusersd is a server that returns information about users currently logged in to the system.

rpcinfo 1383

The currently logged-in users are queried using the rusers(1) command. The rpc.rusersd daemon is usually invoked by inetd(8).

rpc.rusersd uses an RPC protocol defined in /usr/include/rpcsvc.

SEE ALSO

rusers(1), who(1), w(1), inetd(8)

BSD 4.3, 7 June 1993

rpc.rwalld

rpc.rwalld—Write messages to users currently logged in to the server.

SYNOPSIS

/usr/libexec/rpc.rwalld

DESCRIPTION

rpc.rwalld is a server that will send a message to users currently logged in to the system. This server invokes the wall(1) command to actually write the messages to the system.

Messages are sent to this server by the rwall(1) command. The rpc.rwalld daemon is usually invoked by inetd(8).

rpc.rwalld uses an RPC protocol defined in /usr/include/rpcsvc/rwall.x.

SEE ALSO

rwall(1), wall(1), inetd(8)

BSD 4.3, 7 June 1993

rpcinfo

rpcinfo—Report RPC information.

SYNOPSIS

rpcinfo -p [host]

rpcinfo [-n portnum] -u host program [version] rpcinfo [-n portnum] -t host program [version] rpcinfo -b program version

rpcinfo -d program version

DESCRIPTION

rpcinfo makes an RPC call to an RPC server and reports what it finds.

OPTIONS

-p	Probe the port mapper on host and print a list of all registered RPC programs. If host is
	not specified, it defaults to the value returned by hostname(1).
-u	Make an RPC call to procedure 0 of program on the specified host using UDP and
	report whether a response was received.
-t	Make an RPC call to procedure 0 of program on the specified host using TCP and report
	whether a response was received.
-n	Use portnum as the port number for the -t and -u options instead of the port number
	given by the port mapper.

1384

-b

-d

Part VIII: Administration and Privileged Commands

Make an RPC broadcast to procedure 0 of the specified program and version using UDP and report all hosts that respond.

Delete registration for the RPC service of the specified program and version. This option can be exercised only by the superuser.

The program argument can be either a name or a number. If a version is specified, rpcinfo attempts to call that version of the specified program. Otherwise, rpcinfo attempts to find all the registered version numbers for the specified program by calling version 0 (which is presumed not to exist; if it does exist, rpcinfo attempts to obtain this information by calling an extremely high version number instead) and attempts to call each registered version. Note that the version number is required for -b and -d options.

EXAMPLES

To show all the RPC services registered on the local machine, use

rpcinfo -p

To show all of the RPC services registered on the machine named klaxon, use

rpcinfo -p klaxon

To show all machines on the local net that are running the Yellow Pages service, use

rpcinfo -b ypserv ‘version’ -- uniq

‘version’ is the current Yellow Pages version obtained from the results of the -p switch above.

To delete the registration for version 1 of the walld service, use

rpcinfo -d walld 1

SEE ALSO

rpc(5), portmap(8), RPC Programming Guide

BUGS

In releases prior to SunOS 3.0, the Network File System (NFS) did not register itself with the port mapper; rpcinfo cannot be used to make RPC calls to the NFS server on hosts running such releases.

17 December 1987

rquotad, rpc.rquotad

rquotad, rpc.rquotad—Remote quota server.

SYNOPSIS

/usr/etc/rpc.rquotad

DESCRIPTION

rquotad is an rpc(3N) server that returns quotas for a user of a local filesystem that is mounted by a remote machine over the NFS. The results are used by quota(1) to display user quotas for remote filesystems. The rquotad daemon is usually started at boot time from the rc.net script.

FILES

quotas

Quota file at the filesystem root

SEE ALSO

quota(1), rpc(3N), nfs(4P), services(5) inetd(8C)

17 December 1987

rshd 1385

rshd

rshd—Remote shell server.

SYNOPSIS

rshd [-alnL]

DESCRIPTION

The rshd server is the server for the rcmd(3) routine and, consequently, for the rsh(1) program. The server provides remote execution facilities with authentication based on privileged port numbers from trusted hosts.

The rshd server listens for service requests at the port indicated in the cmd service specification; see services(5). When a service request is received, the following protocol is initiated:

1.The server checks the client’s source port. If the port is not in the range 512-1023, the server aborts the connection.

2.The server reads characters from the socket up to a null (\0) byte. The resultant string is interpreted as an ASCII number, base 10.

3.If the number received in Step 2 is nonzero, it is interpreted as the port number of a secondary stream to be used for the stderr. A second connection is then created to the specified port on the client’s machine. The source port of this second connection is also in the range 512-1023.

4.The server checks the client’s source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), and named(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. If the hostname is in the same domain as the server (according to the last two components of the domain name), or if the -a option is given, the addresses for the hostname are requested, verifying that the name and address correspond. If address verification fails, the connection is aborted with the message, Host address mismatch.

5.A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted as the user identity on the client’s machine.

6.A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted as a user identity to use on the server’s machine.

7.A null-terminated command to be passed to a shell is retrieved on the initial socket. The length of the command is limited by the upper bound on the size of the system’s argument list.

8.rshd then validates the user using ruserok(3), which uses the file and the file found in the user’s home directory. The -l option prevents ruserok(3) from doing any validation based on the user’s .rhosts file, unless the user is the superuser.

9.A null byte is returned on the initial socket and the command line is passed to the normal login shell of the user. The shell inherits the network connections established by rshd.

Transport-level keep-alive messages are enabled unless the -n option is present. The use of keep-alive messages allows sessions to be timed out if the client crashes or becomes unreachable.

The -L option causes all successful accesses to be logged to syslogd(8) as auth.info messages and all failed accesses to be logged as auth.notice.

DIAGNOSTICS

Except for the last one listed, all diagnostic messages are returned on the initial socket, after which any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in Step 9 upon successful completion of all the steps prior to the execution of the login shell).

Locuser too long. Ruser too long. Command too long.

The name of the user on the client’s machine is longer than 16 characters. The name of the user on the remote machine is longer than 16 characters.

The command line passed exceeds the size of the argument list (as configured into the system).

Login incorrect.	No password file entry for the username existed.
Remote directory.	The chdir command to the home directory failed.

		Part VIII: Administration and Privileged Commands
	1386

Permission		denied.	The authentication procedure described previously failed.
Can’t	make	pipe.	The pipe needed for the stderr wasn’t created.
Can’t	fork; try again.		A fork by the server failed.
<shellname>: ...			The user’s login shell could not be started. This message is returned on the connection
			associated with the stderr and is not preceded by a flag byte.

SEE ALSO

rsh(1), rcmd(3), ruserok(3)

BUGS

The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is insecure but is useful in an “open” environment.

A facility to allow all data exchanges to be encrypted should be present.

A more extensible protocol (such as Telnet) should be used.

BSD 4.2, 30 April 1991

rwhod

rwhod—System status server.

SYNOPSIS

rwhod

DESCRIPTION

rwhod is the server that maintains the database used by the rwho(1) and ruptime(1) programs. Its operation is predicated on the ability to broadcast messages on a network.

rwhod operates as both a producer and consumer of status information. As a producer of information, it periodically queries the state of the system and constructs status messages that are broadcast on a network. As a consumer of information, it listens for other rwhod servers’ status messages, validating them and then recording them in a collection of files located in the directory.

The server transmits and receives messages at the port indicated in the rwho service specification; see services(5). The messages sent and received are of the form:

struct outmp {

char out_line[8]; /* tty name */ char out_name[8]; /* user id */ long out_time; /* time on */

};

struct whod {
char	wd_vers;
char	wd_type;
char	wd_fill[2];
int	wd_sendtime;
int	wd_recvtime;
char	wd_hostname[32];
int	wd_loadav[3];
int	wd_boottime;
struct	whoent {
	struct outmp we_utmp;

sendmail 1387

int we_idle;

} wd_we[1024 / sizeof (struct whoent)];

};

All fields are converted to network byte order prior to transmission. The load averages are as calculated by the w(1) program and represent load averages over the 5-, 10-, and 15-minute intervals prior to a server’s transmission; they are multiplied by 100 for representation in an integer. The hostname included is that returned by the gethostname(2) system call, with any trailing domain name omitted. The array at the end of the message contains information about the users logged in to the sending machine. This information includes the contents of the utmp(5) entry for each non-idle terminal line and a value indicating the time in seconds since a character was last received on the terminal line.

Messages received by the rwho server are discarded unless they originated at an rwho server’s port. In addition, if the host’s name, as specified in the message, contains any unprintable ASCII characters, the message is discarded. Valid messages received by rwhod are placed in files named in the directory. These files contain only the most recent message, in the format described previously.

Status messages are generated approximately once every three minutes. rwhod performs an nlist(3) every 30 minutes to guard against the possibility that this file is not the system image currently operating.

SEE ALSO

rwho(1), ruptime(1)

BUGS

There should be a way to relay status information between networks. Status information should be sent only upon request rather than continuously. People often interpret the server dying or network communication failures as a machine going down.

HISTORY

The rwhod command appeared in BSD 4.2.

BSD 4.2, 16 March 1991

sendmail

sendmail—Send mail over the Internet.

SYNOPSIS

sendmail [flags] [address ...	]
newaliases
mailq [-v]
smtpd
bsmtp
runq

DESCRIPTION

sendmail sends a message to one or more recipients, routing the message over whatever networks are necessary. sendmail does internetwork forwarding as necessary to deliver the message to the correct place.

sendmail is not intended as a user interface routine. Other programs provide user-friendly front ends. sendmail is used only to deliver preformatted messages.

With no flags, sendmail reads its standard input up to an end-of-file or a line consisting only of a single dot and sends a copy of the message found there to all the addresses listed. It determines the networks to use based on the syntax and contents of the addresses.

		Part VIII: Administration and Privileged Commands
	1388

Local addresses are looked up in a file and aliased appropriately. Aliasing can be prevented by preceding the address with a backslash. Usually, the sender is not included in any alias expansions; for example, if john sends to group and group includes john in the expansion, then the letter will not be delivered to john.

Flags are
-ba	Go into ARPANET mode. All input lines must end with a CR-LF, and all messages will
	be generated with a CR-LF at the end. Also, the From: and Sender: fields are examined
	for the name of the sender.
-bd	Run as a daemon. This requires Berkeley IPC. sendmail will fork and run in the
	background, listening on socket 25 for incoming SMTP connections. This is usually run
	from /etc/rc.

-bi	Initialize the alias database.
-bm	Deliver mail in the usual way (default).
-bp	Print a listing of the queue.
-bs	Use the SMTP protocol as described in
	flag implies all the operations of the -ba

RFC 821 on standard input and output. This flag that are compatible with SMTP.

-bb	Read batched SMTP (BSMTP) commands from standard input.
-bt	Run in address test mode. This mode reads addresses and shows the steps in parsing; it is
	used for debugging configuration tables.
-bv	Verify names only; do not try to collect or deliver a message. Verify mode is usually used
	for validating users or mailing lists.
-bz	Create the configuration freeze file.
-C file	Use alternate configuration file. sendmail refuses to run as root if an alternate configura-
	tion file is specified. The frozen configuration file is bypassed.
-d X	Set debugging value to X.
-F fullname	Set the full name of the sender.
-f name	Sets the name of the “from” person (the sender of the mail). -f can only be used by
	trusted users (usually root, daemon, and network) or if the person you are trying to
	become is the same as the person you are.
-h N	Set the hop count to N. The hop count is incremented every time the mail is processed.
	When it reaches a limit, the mail is returned with an error message, the victim of an
	aliasing loop. If not specified, Received: lines in the message are counted.
-n	Don’t do aliasing.
-o x value	Set option x to the specified value. Options are described later in this section.
-q time	Processed saved messages in the queue at given intervals. If time is omitted, process the
	queue once. time is given as a tagged number, with s being seconds, m being minutes, h
	being hours, d being days, and w being weeks. For example, -q1h30m or -q90m both set the
	time-out to 1 hour, 30 minutes. If time is specified, sendmail runs in background. This
	option can be used safely with -bd.
-M ident	Process the queued message with the queue ID ident.
-R addr	Process the queued messages that have the string addr in one of the recipient addresses.
-S addr	Process the queued messages that have the string addr in the sender address.
-r name	An alternate and obsolete form of the -f flag.
-t	Read message for recipients. To:, Cc:, and Bcc: lines are scanned for recipient addresses.
	The Bcc: line is deleted before transmission. Any addresses in the argument list are
	suppressed; that is, they do not receive copies even if listed in the message header.
-v	Go into verbose mode. Alias expansions are announced and so on.

sendmail 1389

There are also a number of processing options that can be set. Usually, these will only be used by a system administrator. Options can be set either on the command line using the -o flag or in the configuration file. These are described in detail in the Sendmail Installation and Operation Guide. The options are

A file	Use alternate alias file.
c	On mailers that are considered “expensive” to connect to, don’t initiate immediate
	connection. This requires queuing.
d x	Set the delivery mode to x. Delivery modes are i for interactive (synchronous) delivery,
	b for background (asynchronous) delivery, and q for queue only (actual delivery is done
	the next time the queue is run).
D	Try to automatically rebuild the alias database if necessary.
e x	Set error processing to mode x. Valid modes are m to mail back the error message, w to
	“write” back the error message (or mail it back if the sender is not logged in), p to print
	the errors on the terminal (default), q to throw away error messages (only exit status is
	returned), and e to do special processing for the BerkNet. If the text of the message is
	not mailed back by modes m or w and if the sender is local to this machine, a copy of the
	message is appended to the file in the sender’s home directory.
F mode	The mode to use when creating temporary files.
f	Save UNIX–style From: lines at the front of messages.
g N	The default group ID to use when calling mailers.
H file	The SMTP help file.
i	Do not take dots on a line by themselves as a message terminator.
k N	Checkpoint the queue file after every N successful deliveries (default is 10). This avoids
	excessive duplicate deliveries when sending to long mailing lists interrupted by system
	crashes.
L n	The log level.
m	Send also to “me” (the sender) if I am in an alias expansion.
o	If set, this message may have old style headers. If not set, this message is guaranteed to
	have new style headers (commas instead of spaces between addresses). If set, an adaptive
	algorithm is used that will correctly determine the header format in most cases.
Q queuedir	Select the directory in which to queue messages.
r timeout	The time-out on reads; if none is set, sendmail will wait forever for a mailer. This option
	violates the word (if not the intent) of the SMTP specification, so the timeout should
	probably be fairly large.
S file	Save statistics in the named file.
s	Always instantiate the queue file, even under circumstances where it is not strictly
	necessary. This provides safety against system crashes during delivery.
T time	Set the time-out on undelivered messages in the queue to the specified time. After
	delivery has failed (for example, because of a host being down) for this amount of time,
	failed messages will be returned to the sender. The default is three days.
t stz, dtz	Set the name of the time zone.
U userdatabase	If set, a user database is consulted to get forwarding information. You can consider this
	an adjunct to the aliasing mechanism, except that the database is intended to be
	distributed; aliases are local to a particular host. This might not be available if your
	sendmail does not have the USERDB option compiled in.
u N	Set the default user ID for mailers.
w	If not set, name server lookups will use a query type of ANY to find types CNAME, A, and MX
	and will cause all existing records to be cached by the local server. If there is (or might
	be) a wildcard MX in the local domain or its parents that are searched, you must set this

		Part VIII: Administration and Privileged Commands
	1390

option, which uses a query type of CNAME only; otherwise, it causes all fully qualified names to match as names in the local domain.

In aliases, the first character of a name can be a vertical bar to cause interpretation of the rest of the name as a command to pipe the mail to. It might be necessary to quote the name to keep sendmail from suppressing the blanks between arguments. For example, a common alias is

msgs: “|/usr/bin/msgs -s”

Aliases can also have the syntax to ask sendmail to read the named file for a list of recipients. For example, an alias such as

poets: “:include:/usr/local/lib/poets.list”

would read for the list of addresses making up the group.

sendmail returns an exit status describing what it did. The codes are defined in sysexits.h:

EX_OK EX_NOUSER EX_UNAVAILABLE EX_SYNTAX EX_SOFTWARE EX_OSERR EX_NOHOST EX_TEMPFAIL

Successful completion on all addresses. Username not recognized.

Catchall meaning necessary resources were not available. Syntax error in address.

Internal software error, including bad arguments. Temporary operating system error, such as cannot fork. Hostname not recognized.

Message could not be sent immediately but was queued.

If invoked as newaliases, sendmail rebuilds the alias database. If invoked as mailq, sendmail prints the contents of the mail queue. If invoked as smtpd, sendmail forks and runs as a daemon. If invoked as bsmtp, sendmail processes batched SMTP on standard input. If invoked as runq, sendmail runs through the mail queue and makes what deliveries are possible.

FILES

Except for the file /etc/sendmail.cf itself, the following pathnames are all specified in /etc/sendmail.cf. Thus, these values are only approximations.

/etc/aliases raw data for alias names

/etc/aliases.pag

/etc/aliases.dir database of alias names

/etc/sendmail.cf configuration file

/etc/sendmail.fc frozen configuration

/etc/sendmail.hf help file

/var/log/sendmail.st collected statistics

/var/spool/mqueue/* temp files

SEE ALSO

binmail(1), mail(1), rmail(1), syslog(3), aliases(5), mailaddr(7), rc(8); DARPA Internet Request for Comments RFC 819, RFC 821, RFC 822; “Sendmail: An Internetwork Mail Router,” SMM and No.16, “Sendmail Installation and Operation Guide,” SMM and No.7.

HISTORY

The sendmail command appeared in BSD 4.2.

BSD 4, 5 August 1991

setserial 1391

setfdprm

setfdprm—Sets user-provided floppy disk parameters.

SYNOPSIS

setfdprm [ -p ] device name

setfdprm [ -p ] device size sectors heads tracks stretch gap rate spec1 fmt_gap setfdprm [ -c ] device

setfdprm [ -y ] device setfdprm [ -n ] device

DESCRIPTION

setfdprm is a utility that can be used to load disk parameters into the auto-detecting floppy devices, to clear old parameter sets, and to disable or enable diagnostic messages.

Without any options, setfdprm loads the device (usually /dev/fd0 or /dev/fd1) with a new parameter set with the name entry found in /etc/fdprm (usually named 360/360 and so on). These parameters stay in effect until the media is changed.

OPTIONS

-p device name	Permanently loads a new parameter set for the specified auto-configuring floppy device
	for the configuration with name in /etc/fdprm. Alternatively, the parameters can be given
	directly from the command line.
-c device	Clears the parameter set of the specified auto-configuring floppy device.
-y device	Enables format detection messages for the specified auto-configuring floppy device.
-n device	Disables format detection messages for the specified auto-configuring floppy device.

BUGS

This documentation is grossly incomplete.

FILES

/etc/fdprm

AUTHOR

Werner Almesberger ([e-mail])

Linux 0.99, 20 November 1993

setserial

setserial—Get/set Linux serial port information.

SYNOPSIS

setserial [ -abqvVW ] device [ parameter1 [ arg ] ] ...

setserial -g [ -abv ] device1 ...

DESCRIPTION

setserial is a program designed to set or report the configuration information associated with a serial port. This information includes what I/O port and IRQ a particular serial port is using, whether the break key should be interpreted as the Secure Attention Key, and so on.

During the normal bootup process, only COM ports 1-4 are initialized, using the default I/O ports and IRQ values, as listed. To initialize any additional serial ports, or to change the COM 1-4 ports to a nonstandard configuration, the setserial program should be used. Typically, it is called from an rc.serial script, which is usually run out of /etc/rc.local.

/dev/cua[0-3]

		Part VIII: Administration and Privileged Commands
	1392

The device argument or arguments specify the serial device that should be configured or interrogated. It will usually have the following form: .

If no parameters are specified, setserial prints the port type (such as 8250, 16450, 16550, 16550A), the hardware I/O port, the hardware IRQ line, its “baud base,” and some of its operational flags.

If the -g option is given, the arguments to setserial are interpreted as a list of devices for which the characteristics of those devices should be printed.

Without the -g option, the first argument to setserial is interpreted as the device to be modified or characteristics to be printed, and any additional arguments are interpreted as parameters that should be assigned to that serial device.

For the most part, superuser privilege is required to set the configuration parameters of a serial port. A few serial port parameters can be set by normal users, however, and these are noted as exceptions in this manual page.

OPTIONS

setserial accepts the following options:

-a	When reporting the configuration of a serial device, print all available information.
-b	When reporting the configuration of a serial device, print a summary of the device’s
	configuration, which might be suitable for printing during the bootup process during
	the /etc/rc script.
-q	Be quiet. setserial will print fewer lines of output.
-v	Be verbose. setserial will print additional status output.
-V	Display version and exit.
-W	Do wild interrupt initialization and exit.

PARAMETERS

The following parameters can be assigned to a serial port.

All argument values are assumed to be in decimal unless preceded by 0x.

port port_number	The port option sets the I/O port as described previously.
irq irq_number	The irq option sets the hardware IRQ as described previously.
uart uart_type	This option is used to set the UART type. The permitted types are none, 8250, 16450,
	16550, and 16550A. Because the 8250 and 16450 UARTs do not have FIFOs, and
	because the original 16550 have bugs that make the FIFOs unusable, the FIFO will only
	be used on chips identified as 16550A UARTs. Setting the UART type to 8250, 16450,
	or 16550 will enable the serial port without trying to use the FIFO. Using the UART
	type none will disable the port. Some internal modems are billed as having a “16550A
	UART with a 1KB buffer.” This is a lie. They do not really have a 16550A-compatible
	UART; instead, what they have is a 16450-compatible UART with a 1KB receive buffer
	to prevent receiver overruns. This is important because they do not have a transmit
	FIFO. Hence, they are not compatible with a 16550A UART, and the autocon-
	figuration process will correctly identify them as 16450s. If you attempt to override this
	using the uart parameter, you see dropped characters during file transmissions. These
	UARTs usually have other problems: The skip test parameter also often must be
	specified.
autoconfig	When this parameter is given, setserial asks the kernel to attempt to automatically
	configure the serial port. The I/O port must be correctly set; the kernel will attempt to
	determine the UART type, and if the auto_irq parameter is set, Linux will attempt to
	automatically determine the IRQ. The autoconfigure parameter should be given after
	the port, auto_irq, and skip_test parameters have been specified.

	setserial
			1393
auto_irq	During autoconfiguration, try to determine the IRQ. This feature is not guaranteed to
	always produce the correct result; some hardware configurations will fool the Linux
	kernel. It is generally safer not to use the auto_irq feature but rather to specify the IRQ
	to be used explicitly, using the irq parameter.
^auto_irq	During autoconfiguration, do not try to determine the IRQ.
skip_test	During autoconfiguration, skip the UART test. Some internal modems do not have
	National Semiconductor compatible UARTs but have cheap imitations instead. Some of
	these cheesy imitation UARTs do not fully support the loopback detection mode, which
	is used by the kernel to make sure there really is a UART at a particular address before
	attempting to configure it. For certain internal modems, you will need to specify this
	parameter so Linux can initialize the UART correctly.
^skip_test	During autoconfiguration, do not skip the UART test.
baud_base baud_base	This option sets the base baud rate, which is the clock frequency divided by 16. Usually,
	this value is 115200, which is also the fastest baud rate, which the UART can support.
spd_hi	Use 57.6KB when the application requests 38.4KB. This parameter can be specified by
	a non-privileged user.
spd_vhi	Use 115KB when the application requests 38.4KB. This parameter can be specified by a
	non-privileged user.
spd_cust	Use the custom divisor to set the speed when the application requests 38.4KB. In this
	case, the baud rate is the baud_base divided by the divisor. This parameter can be
	specified by a non-privileged user.
spd_normal	Use 38.4KB when the application requests 38.4KB. This parameter can be specified by
	a non-privileged user.
divisor divisor	This option sets the custom divisor. This divisor will be used when the spd_cust option
	is selected and the serial port is set to 38.4KB by the application. This parameter can be
	specified by a non-privileged user.
sak	Set the break key at the Secure Attention Key.
^sak	Disable the Secure Attention Key.
fourport	Configure the port as an AST Fourport card.
^fourport	Disable AST Fourport configuration.
close_delay delay	Specify the amount of time, in hundredths of a second, that DTR should remain low on
	a serial line after the callout device is closed before the blocked dial-in device raises DTR
	again. The default value of this option is 50, or a half-second delay.
Session_lockout	Lock out callout port (/dev/cuaXX) accesses across different sessions. That is, once a
	process has opened a port, do not allow a process with a different session ID to open
	that port until the first process has closed it.
^session_lockout	Do not lock out callout port accesses across different sessions.
pgrp_lockout	Lock out callout port (/dev/cuaXX) accesses across different process groups. That is, once
	a process has opened a port, do not allow a process in a different process group to open
	that port until the first process has closed it.
^pgrp_lockout	Do not lock out callout port accesses across different process groups.
hup_notify	Notify a process blocked on opening a dial-in line when a process has finished using a
	callout line (either by closing it or by the serial line being hung up) by returning EAGAIN
	to the open.
	The application of this parameter is for gettys that are blocked on a serial port’s dial-in
	line. This allows the getty to reset the modem (which may have had its configuration
	modified by the application using the callout device) before blocking on the open again.
^hup_notify	Do not notify a process blocked on opening a dial-in line when the callout device is
	hung up.

		Part VIII: Administration and Privileged Commands
	1394

split_termios

Treat the termios settings used by the callout device and the termios settings used by the dial-in devices as separate.

^split_termios

Use the same termios structure to store both the dial-in and callout ports. This is the default option.

callout_nohup	If this particular serial port is opened as a callout device, do not hang up the tty when
	carrier detect is dropped.
^callout_nohup	Do not skip hanging up the tty when a serial port is opened as a callout device. Of
	course, the HUPCL termios flag must be enabled if the hangup is to occur.

CONSIDERATIONS OF CONFIGURING SERIAL PORTS

It is important to note that setserial merely tells the Linux kernel where it should expect to find the I/O port and IRQ lines of a particular serial port. It does not configure the hardware, the actual serial board, to use a particular I/O port. To do that, you need to physically program the serial board, usually by setting some jumpers or by switching some DIP switches.

This section provides some pointers in helping you decide how you want to configure your serial ports.

The “standard MS-DOS” port associations are
/dev/ttyS0 (COM1), port 0x3f8	IRQ 4
/dev/ttyS1 (COM2), port 0x2f8	IRQ 3
/dev/ttyS2 (COM3), port 0x3e8	IRQ 4
/dev/ttyS3 (COM4), port 0x2e8	IRQ 3

Due to the limitations in the design of the AT/ISA bus architecture, an IRQ line usually cannot be shared between two or more serial ports. If you attempt to do this, one or both serial ports will become unreliable if you try to use both simultaneously. This limitation can be overcome by special multiport serial port boards, which are designed to share multiple serial ports over a single IRQ line. Multiport serial cards supported by Linux include the AST FourPort, the Accent Async board, the Usenet Serial II board, the Bocaboard BB-1004, BB-1008, and BB-2016 boards, and the HUB-6 serial board.

The selection of an alternative IRQ line is difficult because most of them are already used. The following table lists the “standard MS-DOS” assignments of available IRQ lines:

IRQ 3	COM2
IRQ 4	COM1
IRQ 5	LPT2
IRQ 7	LPT1

Most people find that IRQ 5 is a good choice, assuming that there is only one parallel port active in the computer. Another good choice is IRQ 2 (a.k.a. IRQ 9), although this IRQ is sometimes used by network cards, and very rarely will VGA cards be configured to use IRQ 2 as a vertical retrace interrupt. If your VGA card is configured this way, try to disable it so you can reclaim that IRQ line for some other card. It’s not necessary for Linux and most other operating systems.

The only other available IRQ lines are 3, 4, and 7, and these are probably used by the other serial and parallel ports. (If your serial card has a 16-bit card edge connector and supports higher interrupt numbers, then IRQ 10, 11, 12, and 15 are also available.)

On AT class machines, IRQ 2 is seen as IRQ 9, and Linux will interpret it in this manner.

IRQs other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15 should not be used because they are assigned to other hardware and cannot, in general, be changed. Here are the “standard” assignments:

IRQ 0	Timer channel 0
IRQ 1	Keyboard
IRQ 2	Cascade for controller 2
IRQ 3	Serial port 2
IRQ 4	Serial port 1

setsid 1395

IRQ 5	Parallel port 2 (Reserved in PS/2)
IRQ 6	Floppy diskette
IRQ 7	Parallel port 1
IRQ 8	Real-time clock
IRQ 9	Redirected to IRQ2
IRQ 10	Reserved
IRQ 11	Reserved
IRQ 12	Reserved (Auxiliary device in PS/2)
IRQ 13	Math coprocessor
IRQ 14	Hard disk controller
IRQ 15	Reserved

CAUTION

Using an invalid port can lock up your machine.

FILES

/etc/rc.local

/etc/rc.serial

SEE ALSO

tty(4), ttys(4), kernel/chr_drv/serial.c

AUTHOR

The original version of setserial was written by Rick Sladkey ([e-mail]) and was modified by Michael K. Johnson ([e-mail]).

This version has since been rewritten from scratch by Theodore Ts’o ([e-mail]) on 1/1/93. Any bugs or problems are solely his responsibility.

setserial 2.10, 27 August 1994

setsid

setsid—Run a program in a new session.

SYNOPSIS

setsid program [ arg ... ]

DESCRIPTION

setsid runs a program in a new session.

SEE ALSO

setsid(2)

AUTHOR

Rick Sladkey ([e-mail])

Linux 0.99, 20 November 1993

		Part VIII: Administration and Privileged Commands
	1396

showmount

showmount—Show mount information for an NFS server.

SYNOPSIS

/usr/etc/showmount [\-adehv\][\--all\][\--directories\] [\--exports\][\--help\] [\--version\][\host\]

DESCRIPTION

showmount queries the mount daemon on a remote host for information about the state of the NFS server on that machine. With no options, showmount lists the set of clients who are mounting from that host. The output from showmount is designed to appear as though it were processed through sort -u.

OPTIONS

-a or --all	List both the client hostname and mounted directory in host:dir format.
-d or --directories	List only the directories mounted by some client.
-e or --exports	Show the NFS server’s export list.
-h or --help	Provide a short help summary.
-v or --version	Report the current version number of the program.
--no-headers	Suppress the descriptive headings from the output.

SEE ALSO

rpc.mountd(8), rpc.nfsd(8)

BUGS

The completeness and accuracy of the information that showmount displays varies according to the NFS server’s implementation. Because showmount sorts and uniques the output, it is impossible to determine from the output whether a client is mounting the same directory more than once.

AUTHOR

Rick Sladkey ([e-mail])

6 October 1993

shutdown

shutdown—Close down the system.

SYNOPSIS

shutdown [ -h | -r ] [ -fqs ] [ now | hh:ss | +mins ] reboot [ -h | -r ] [ -fqs ] [ now | hh:ss | +mins ] fastboot [ -h | -r ] [ -fqs ] [ now | hh:ss | +mins ] halt [ -h | -r ] [ -fqs ] [ now | hh:ss | +mins ] fasthalt [ -h | -r ] [ -fqs ] [ now | hh:ss | +mins ]

DESCRIPTION

In general, shutdown prepares the system for a power down or reboot. An absolute or delta time can be given, and periodic messages will be sent to all users warning of the shutdown.

halt is the same as shutdown -h -q now.

fasthalt is the same as shutdown -h -q -f now.

simpleinit 1397

reboot is the same as shutdown -r -q now.

fastboot is the same as shutdown -r -q -f now.

The default delta time, if none is specified, is two minutes.

Five minutes before shutdown (or immediately, if shutdown is less than five minutes away), the /etc/nologin file is created with a message stating that the system is going down and that logins are no longer permitted. The login(1) program will not allow non-superusers to log in during this period. A message will be sent to all users at this time.

When the shutdown time arrives, shutdown notifies all users, tells init(8) not to spawn more getty(8)s, writes the shutdown time into the /var/log/wtmp file, kills all other processes on the system, sync(2)s, unmounts all the disks, sync(2)s again, waits for a second, and then either terminates or reboots the system.

OPTIONS

-h	Halt the system. Do not reboot. This option is used when powering down the system.
-r	Reboot the system.
-f	Fast. When the system is rebooted, the filesystems will not be checked. This is arranged
	by creating /fastboot, which /etc/rc must detect (and delete).
-q	Quiet. This uses a default broadcast message and does not prompt the user for one.
-s	Reboot in single-user mode. This is arranged by creating /etc/singleboot, which
	simpleinit(8) detects (and deletes).

FILES

/etc/rc

/fastboot

/etc/singleboot

/etc/nologin

/var/log/wtmp

SEE ALSO

umount(8), login(1), reboot(2), simpleinit(8), init(8)

BUGS

Unlike the BSD shutdown, users are notified of shutdown only once or twice, instead of many times, and at shorter and shorter intervals as “apocalypse approaches.”

AUTHOR

[e-mail]. Modified by [e-mail].

Linux 0.99, 20 November 1993

simpleinit

simpleinit—Process control initialization.

SYNOPSIS

init [ single ]

		Part VIII: Administration and Privileged Commands
	1398

DESCRIPTION

init is invoked as the last step in the Linux boot sequence. If the single option is used, or if the file /etc/singleboot exists, then single-user mode will be entered, by starting /bin/sh. If the file /etc/securesingle exists, then the root password will be required to start single-user mode. If the root password does not exist, or if /etc/passwd does not exist, the checking of the password will be skipped.

If the file /etc/TZ exists, then the contents of that file will be read and used to set the TZ environment variable for each process started by simpleinit. This “feature” is only available if it’s configured at compile time. It’s not usually needed.

After single-user mode is terminated, the /etc/rc file is executed, and the information in /etc/inittab will be used to start processes.

While init is running, several signals are trapped with special action taken. Because init has PID 1, sending signals to the init process is easy with the kill(1) command.

If init catches a SIGHUP (hangup) signal, the /etc/inittab will be read again. If init catches a SIGTSTP (terminal stop) signal, no more processes will be spawned. This is a toggle, which is reset if init catches another SIGTSTP signal.

If init catches a SIGINT (interrupt) signal, init will sync a few times and try to start reboot. Failing this, init will execute the system reboot(2) call. Under Linux, it is possible to configure the Ctrl+Alt+Del sequence to send a signal to init instead of rebooting the system.

THE inittab FILE

Because of the number of init programs that are appearing in the Linux community, the documentation for the /etc/inittab file, which is usually found with the inittab(5) man page, is presented here:

The format is

ttyline:termcap-entry:getty-command

An example follows:

tty1:console:/sbin/getty 9600 tty1 tty2:console:/sbin/getty 9600 tty2 tty3:console:/sbin/getty 9600 tty3 tty4:console:/sbin/getty 9600 tty4

#tty5:console:/sbin/getty 9600 tty5

#ttyS1:dumb:/sbin/getty 9600 ttyS1

#ttyS2:dumb:/sbin/getty -m -t60 2400 ttyS2

Lines beginning with the # character are treated as comments. Please see documentation for the getty(8) command that you are using because there are several of these in the Linux community at this time.

FILES

/etc/inittab

/etc/singleboot

/etc/securesingle

/etc/TZ

/etc/passwd

/etc/rc

SEE ALSO

inittab(5), ctrlaltdel(8) reboot(8), termcap(5), getty(8), agetty(8), shutdown(8)

sliplogin 1399

BUGS

This program is called simpleinit to distinguish it from the System V compatible versions of init that are starting to appear in the Linux community. simpleinit should be linked to, or made identical with, init for correct functionality.

AUTHOR

Peter Orbaek ([e-mail]), version 1.20, with patches for single-user mode by Werner Almesberger.

Linux 0.99, 20 November 1993

slattach

slattach—Attach a network interface to a serial line.

SYNOPSIS

slattach [-v] [-p proto] [-s speed] [tty]

DESCRIPTION

slattach is a little program that can be used to put a normal terminal (“serial”) line into one of several “network” modes, thus allowing you to use it for point-to-point links to other computers.

OPTIONS

[-v]	Enable debugging output. Useful when determining why a given setup doesn’t work.
[-p proto]	Set a specific kind of protocol to use on the line. The default is set to cslip, compressed
	SLIP. Other possible values are slip (normal SLIP), ppp (Point-to-Point Protocol), and
	kiss (AX.25 TNC protocol).
[-s speed]	Set a specific line speed other than the default.
	If no arguments are given, the current terminal line (usually the login device) is used.
	Otherwise, an attempt is made to claim the indicated terminal port, lock it, and open it.

FILES

/dev/cua*

BUGS

None so far.

AUTHOR

Fred N. van Kempen ([e-mail])

20 September 1993

sliplogin

sliplogin—Attach a serial line network interface.

SYNOPSIS

sliplogin [loginname]

DESCRIPTION

sliplogin is used to turn the terminal line on standard input into a serial line IP SLIP link to a remote host. To do this, the program searches the file for an entry matching loginname (which defaults to the current login name if omitted). If a

		Part VIII: Administration and Privileged Commands
	1400

matching entry is found, the line is configured appropriately for slip (8-bit transparent I/O) and converted to slip line discipline. Then a shell script is invoked to initialize the slip interface with the appropriate local and remote IP address, netmask, and so on.

The usual initialization script is /etc/slip/slip.lgin, but if particular hosts need special initialization, the file /etc/slip/slip.login.loginname will be executed instead if it exists. The script is invoked with the parameters

slipunit	The unit number of the slip interface assigned to this line, such as 0 for sl0.
speed	The speed of the line.
args	The arguments from the entry, in order starting with loginname.

Only the superuser can attach a network interface. The interface is automatically detached when the other end hangs up or the sliplogin process dies. If the kernel slip module has been configured for it, all routes through that interface will also disappear at the same time. If there is other processing a site wants done upon hangup, the file /etc/slip/slip.logout or /etc/slip/slip.logout.loginname is executed if it exists. It is given the same arguments as the login script.

FORMAT OF /etc/slip.hosts

Comments (lines starting with a #) and blank lines are ignored. Other lines must start with a loginname, but the remaining arguments can be whatever is appropriate for the file that will be executed for that name. Arguments are separated by whitespace and follow normal sh(1) quoting conventions (however, loginname cannot be quoted). Usually, lines have the form loginname local-address remote-address netmask opt-args. local-address and remote-address are the IP hostnames or addresses of the local and remote ends of the slip line, and netmask is the appropriate IP netmask. These arguments are passed directly to ifconfig(8). opt-args are optional arguments used to configure the line.

EXAMPLE

The normal use of sliplogin is to create a entry for each legal, remote slip site with sliplogin as the shell for that entry, such as

Sfoo:ikhuy6:2010:1:slip line to foo:/tmp:/usr/sbin/sliplogin.

(Our convention is to name the account used by remote host hostname as Shostname.) Then an entry is added that looks like

Sfoo ‘hostname’ foo netmask

‘hostname’ will be evaluated by sh to the local hostname and netmask is the local host IP netmask.

Note that sliplogin must be setuid to root, and although it’s not a security hole, moral defectives can use it to place terminal lines in an unusable state or deny access to legitimate users of a remote slip line. To prevent this, a site can create a group, say slip, that only the slip login accounts are put in and then make sure that /sbin/sliplogin is in group slip and mode 4550 (setuid root, only group slip can execute binary).

DIAGNOSTICS

sliplogin logs various information to the system log daemon, syslogd(8), with a facility code of daemon. The messages are listed here, grouped by severity level.

Error Severity

ioctl	(TCGETS): reason	A TCGETS	ioctl to get the line parameters failed.
ioctl	(TCSETS): reason	A TCSETS	ioctl to set the line parameters failed.
/etc/slip.hosts: reason		The file could not be opened.
access denied for user		No entry for user was found in /etc/slip/slip.hosts

Notice Severity

“attaching slip unit” unit for

loginname SLIP unit

Unit was successfully attached.

sync 1401

SEE ALSO

slattach(8), syslogd(8)

HISTORY

The sliplogin command is currently in beta test.

5 August 1991

swapon, swapoff

swapon, swapoff—Enable/disable devices and files for paging and swapping.

SYNOPSIS

/sbin/swapon –a

/sbin/swapon specialfile ...

/sbin/swapoff –a

/sbin/swapoff specialfile ...

DESCRIPTION

swapon is used to specify devices on which paging and swapping are to take place. Calls to swapon usually occur in the system multiuser initialization file /etc/rc making all swap devices available, so that the paging and swapping activity is interleaved across several devices and files.

Usually, the first form is used:

-a All devices marked as sw swap devices in /etc/fstab are made available.

swapoff disables swapping on the specified devices and files or on all swap entries in /etc/fstab when the -a flag is given.

SEE ALSO

swapon(2), swapoff(2), fstab(5), init(8), mkswap(8), rc(8), mount(8)

FILES

/dev/hd[ab]?	Standard paging devices
/dev/sd[ab]?	Standard (SCSI) paging devices
/etc/fstab	ASCII filesystem description table

HISTORY

The swapon command appeared in 4.0 BSD.

AUTHORS

See the Linux mount(8) man page for a complete author list. Primary contributors include Doug Quale, H.J. Lu, Rick Sladkey, and Stephen Tweedie.

Linux 0.99, 27 November 1993

sync

sync—Flush Linux filesystem buffers.

SYNOPSIS

sync

		Part VIII: Administration and Privileged Commands
	1402

DESCRIPTION

sync executes sync(2), which flushes the filesystem buffers to disk. sync should be called before the processor is halted in an unusual manner (before causing a kernel panic when debugging new kernel code). In general, the processor should be halted using the reboot(8) or halt(8) commands, which attempt to put the system in a quiescent state before calling sync(2).

From Linus: “Note that sync is only guaranteed to schedule the dirty blocks for writing: It can actually take a short time before all the blocks are finally written. If you are doing the sync with the expectation of killing the machine soon after, please take this into account and sleep for a few seconds. (The reboot(8) command takes these precautions.)”

SEE ALSO

sync(2), update(8), reboot(8), halt(8)

AUTHOR

Linus Torvalds ([e-mail])

Linux 0.99, 20 November 1993

sysklogd

sysklogd—Linux system logging utilities.

DESCRIPTION

sysklogd provides two system utilities, which provide support for system logging and kernel message trapping. Support of both inetd and UNIX domain sockets enables this utility package to support both local and remote logging.

System logging is provided by a version of syslogd derived from the stock BSD sources. Support for kernel logging is provided by the klogd utility, which allows kernel logging to be conducted in either a stand-alone fashion or as a client of syslogd.

Although the syslogd sources have been heavily modified, a couple of notes are in order. First of all, there has been a systematic attempt to ensure that syslogd follows standard BSD behavior as its default. The second important concept to note is that this version of syslogd interacts transparently with the version of syslog found in the standard libraries. If a binary linked to the standard shared libraries fails to function correctly, we want an example of the anomalous behavior.

CONFIGURATION FILE SYNTAX DIFFERENCES

syslogd uses a slightly different syntax for its configuration file from that of the original BSD sources. Originally, all messages of a specific priority and above were forwarded to the log file.

For example, the following line caused all output from the daemon facilities to go into /usr/adm/daemons:

# Sample syslog.conf daemon.debug /usr/adm/daemons

Under the new scheme, this behavior remains the same. The difference is the addition of two new wildcard specifiers: the asterisk (*) and the equals sign (=). The * specifies that all messages for the indicated facility are to be directed to the destination. Note that this behavior is degenerate with specifying a priority level of debug. Users have indicated that the asterisk notation is more intuitive.

The = wildcard is used to restrict logging to the specified priority class. This allows, for example, routing only debug messages to a particular logging source.

For example, the following line in syslog.conf directs debug messages from all sources to the /usr/adm/debug file:

# Sample syslog.conf daemon.=debug /usr/adm/debug

sysklogd 1403

This may take some acclimatization for those individuals used to the pure BSD behavior, but testers have indicated that this syntax is somewhat more flexible than the BSD behavior. Note that these changes should not affect standard syslog.conf files. You must specifically modify the configuration files to obtain the enhanced behavior.

SUPPORT FOR REMOTE LOGGING

These modifications provide network support to the syslogd facility. Network support means that messages can be forwarded from one node running syslogd to another node running syslogd where they will be actually logged to a disk file.

The strategy is to have syslogd listen on a UNIX domain socket for locally generated log messages. This behavior will allow syslogd to interoperate with the syslog found in the standard C library. At the same time, syslogd listens on the standard syslog port for messages forwarded from other hosts. To have this work correctly, the services files (typically found in /usr/etc/inet) must have the following entry:

syslog 514/udp

To cause messages to be forwarded to another host, replace the normal file line in the syslog.conf file with the name of the host to which the messages is to be sent prepended with an @.

For example, to forward all messages to a remote host, use the following syslog.conf entry:

#Sample syslogd configuration file to

#messages to a remote host forward all.

.* @hostname

To forward all kernel messages to a remote host, the configuration file is

#Sample configuration file to forward all kernel

#messages to a remote host.

kern.* @hostname

OUTPUT TO NAMED PIPES (FIFOS)

This version of syslogd has support for logging output to named pipes (FIFOs). A FIFO or named pipe can be used as a destination for log messages by prepending a | to the name of the file. This is handy for debugging. Note that the FIFO must be created with the mkfifo command before syslogd is started.

The following configuration file routes debug messages from the kernel to a FIFO:

#Sample configuration to route kernel debugging

#messages ONLY to /usr/adm/debug which is a

#named pipe.

kern.=debug |/usr/adm/debug

INSTALLATION CONCERNS

There is probably one important consideration when installing this version of syslogd. This version of syslogd is dependent on proper formatting of messages by the syslog function. The functioning of the syslog function in the shared libraries changed somewhere in the region of libc.so.4.[2-4].n. The specific change was to null-terminate the message before transmitting it to the /dev/log socket. Proper functioning of this version of syslogd is dependent on null-termination of the message.

This problem will typically manifest itself if old statically linked binaries are being used on the system. Binaries using old versions of the syslog function will cause empty lines to be logged, followed by the message with the first character in the message removed. Relinking these binaries to newer versions of the shared libraries will correct this problem.

SECURITY THREATS

There is the potential for the syslogd daemon to be used as a conduit for a denial of service attack. Thanks go to John Morrison ([e-mail]) for alerting me to this potential. A rogue programmer could very easily flood the syslogd daemon with syslog messages resulting in the log files consuming all the remaining space on the filesystem.

		Part VIII: Administration and Privileged Commands
	1404

Activating logging over the inet domain sockets will of course expose a system to risks outside of programs or individuals on the local machine.

Version 1.2 of the utility set will address this problem. In the meantime, there are a number of methods for protecting a machine:

1.Logging can be directed to an isolated or non-root filesystem, which, if filled, will not impair the machine.

2.The ext2 filesystem can be used, which can be configured to limit a certain percentage of a filesystem to usage by root only. Note that this will require syslogd to be run as a non-root process. Also note that this will prevent usage of remote logging because syslogd will be unable to bind to the 514/UDP socket.

3.Disabling inet domain sockets will limit risk to the local machine.

4.Use Step 3 and if the problem persists and is not secondary to a rogue program or daemon, get a 3.5 foot (approximately 1 meter) length of sucker rod and have a chat with the user in question. A sucker rod is 3/4-, 7/8-, or 1-inch hardened steel rod, male threaded on each end. Its primary use in the oil industry in Western North Dakota and other locations is to pump-suck oil from oil wells. Secondary uses are for the construction of cattle feed lots and for dealing with the occasional recalcitrant or belligerent individual.

FILES

/etc/syslog.conf

BUGS

Primarily, security concerns will be addressed in version 1.2.

SEE ALSO

klogd(1)

COLLABORATORS

Dr. Greg Wettstein ([e-mail]) Enjellic Systems Development

Oncology Research Division Computing Facility Roger Maris Cancer Center

Fargo, ND

Stephen Tweedie

Department of Computer Science

Edinburgh University, Scotland Juha Virtanen

([e-mail])

Shane Alderton ([e-mail])

Version 1.1, 28 January 1994

syslogd

syslogd—Log systems messages.

SYNOPSIS

syslogd [-f config_file] [-m mark_interval] [-p log_socket]

DESCRIPTION

syslogd reads and logs messages to the system console, log files, and other machines or users as specified by its configuration file. The options are as follows:

	talkd
		1405
-f	Specify the pathname of an alternate configuration file; the default is /etc/syslog.conf.
-m	Select the number of minutes between “mark” messages; the default is 20 minutes.
-p	Specify the pathname of an alternate log socket; the default is /dev/log.

syslogd reads its configuration file when it starts up and whenever it receives a hangup signal. For information on the format of the configuration file, see syslog.conf(5).

syslogd reads messages from the UNIX domain socket /dev/log, from an Internet domain socket specified in /etc/services, and from the special device /dev/klog (to read kernel messages).

syslogd creates the file /var/run/syslog.pid and stores its process ID there. This can be used to kill or reconfigure syslogd.

The message sent to syslogd should consist of a single line. The message can contain a priority code, which should be a preceding decimal number in angle braces, such as <5>. This priority code should map into the priorities defined in the include file <sys/syslog.h>.

FILES

/etc/syslog.conf	The configuration file
/var/run/syslog.pid	The process ID of current syslogd
/dev/log	Name of the UNIX domain datagram log socket
/dev/klog	The kernel log device

SEE ALSO

logger(1), syslog(3), services(5), syslog.conf(5)

HISTORY

The syslogd command appeared in BSD 4.3.

BSD 4.2, 16 March 1991

talkd

talkd—Remote user communication server.

SYNOPSIS

talkd

DESCRIPTION

talkd is the server that notifies a user that someone else wants to initiate a conversation. It acts a repository of invitations, responding to requests by clients who want to rendezvous to hold a conversation. In normal operation, a client, the caller, initiates a rendezvous by sending a CTL MSG to the server of type LOOK UP (see protocols/talkd.h). This causes the server to search its invitation tables to check if an invitation currently exists for the caller (to speak to the callee specified in the message). If the lookup fails, the caller then sends an ANNOUNCE message, causing the server to broadcast an announcement on the callee’s login ports requesting contact. When the callee responds, the local server uses the recorded invitation to respond with the appropriate rendezvous address and the caller and callee client programs establish a stream connection through which the conversation takes place.

SEE ALSO

talk(1), write(1)

		Part VIII: Administration and Privileged Commands
	1406

HISTORY

The talkd command appeared in BSD 4.3.

BSD 4.3, 16 March 1991

telnetd

telnetd—DARPA Telnet protocol server.

SYNOPSIS

/etc/telnetd [-debug [port]] [-l][-D options][-D report] [-D exercise][-D netdata] [-D ptydata]

DESCRIPTION

telnetd is a server that supports the DARPA standard Telnet virtual terminal protocol. telnetd is invoked by the Internet server (see inetd(8)), usually for requests to connect to the Telnet port as indicated by the /etc/services file (see services(5)). If desired the -debug can be used, to start up telnetd manually, instead of through inetd(8). If started up this way, port may be specified to run telnetd on an alternate TCP port number.

The -D option can be used for debugging purposes. This allows Telnet to print debugging information to the connection, allowing the user to see what telnetd is doing. There are several modifiers: options prints information about the negotiation of Telnet options, report prints the options information, plus some additional information about what processing is going on, netdata displays the data stream received by telnetd, ptydata displays data written to the pty, and exercise has not been implemented yet.

telnetd operates by allocating a pseudo-terminal device (see pty(4)) for a client) and then creating a login process that has the slave side of the pseudo-terminal as stdin, stdout, and stderr. telnetd manipulates the master side of the pseudo-terminal, implementing the Telnet protocol and passing characters between the remote client and the login process.

When a Telnet session is started, telnetd sends Telnet options to the client side, indicating a willingness to do a remote echo of characters, to suppress go ahead, to do remote flow control, and to receive terminal type information, terminal speed information, and window size information from the remote client. If the remote client is willing, the remote terminal type is propagated in the environment of the created login process. The pseudo-terminal allocated to the client is configured to operate in cooked mode and with XTABS and CRMOD enabled (see tty(4)).

telnetd is willing to do echo, binary, suppress go ahead, and timing mark. telnetd is willing to have the remote client

do linemode, binary, terminal type, terminal speed, window size, toggle flow control, environment, X display location, and suppress go ahead.

If the file /etc/issue.net is present, telnetd will show its contents before the login prompt of a Telnet session (see issue.net(5)).

SEE ALSO

telnet(1), issue.net(5)

BUGS

Some Telnet commands are only partially implemented.

Because of bugs in the original 4.2 BSD telnet(1), telnetd performs some dubious protocol exchanges to try to discover if the remote client is, in fact, a 4.2 BSD telnet(1).

Binary mode has no common interpretation except between similar operating systems (UNIX, in this case).

timed 1407

The terminal type name received from the remote client is converted to lowercase. telnetd never sends Telnet go ahead commands.

20 April 1991

tftpd

tftpd—DARPA Trivial File Transfer Protocol server.

SYNOPSIS

tftpd [directory ...]

DESCRIPTION

tftpd is a server that supports the DARPA Trivial File Transfer Protocol. The TFTP server operates at the port indicated in the tftp service description; see services(5). The server is usually started by inetd(8).

The use of tftp(1) does not require an account or password on the remote system. Due to the lack of authentication information, tftpd will allow only publicly readable files to be accessed. Files may be written only if they already exist and are publicly writable. Note that this extends the concept of public to include all users on all hosts that can be reached through the network; this may not be appropriate on all systems, and its implications should be considered before enabling the tftp service. The server should have the user ID with the lowest possible privilege.

SEE ALSO

tftp(1), inetd(8)

HISTORY

The tftpd command appeared in BSD 4.2.

BSD 4.2, 13 May 1991

timed

timed—Time server daemon.

SYNOPSIS

timed [-M] [-t] [-d] [-i network] [-n network] [-F host1 host2 ...

]

DESCRIPTION

timed is a time server daemon and is usually invoked at boot time from the rc(8) file. It synchronizes the host’s time with the time of other machines in a local area network running timed(8). These time servers will slow down the clocks of some machines and speed up the clocks of others to bring them to the average network time. The average network time is computed from measurements of clock differences using the ICMP timestamp request message.

The service provided by timed is based on a master-slave scheme. When timed(8) is started on a machine, it asks the master for the network time and sets the host’s clock to that time. After that, it accepts synchronization messages periodically sent by the master and calls adjtime(2) to perform the needed corrections on the host’s clock.

It also communicates with date(1) to set the date globally and with timedc(8), a timed control program. If the machine running the master crashes, then the slaves elect a new master from among slaves running with the -M flag. A timed running without the -M or -F flags remains a slave. The -t flag enables timed to trace the messages it receives in the file /var/log/timed.log. Tracing can be turned on or off by the program timedc(8). The -d flag is for debugging the daemon. It causes the program to not put itself into the background. Usually, timed checks for a master time server on each network

		Part VIII: Administration and Privileged Commands
	1408

to which it is connected, except as modified by the options. It requests synchronization service from the first master server located. If permitted by the -M flag, it provides synchronization service on any attached networks on which no current master server is detected. Such a server propagates the time computed by the top-level master. The -n flag, followed by the name of a network that the host is connected to (see networks(5)), overrides the default choice of the network addresses made by the program. Each time the -n flag appears, that network name is added to a list of valid networks. All other networks are ignored. The -i flag, followed by the name of a network to which the host is connected (see networks(5)), overrides the default choice of the network addresses made by the program. Each time the -i flag appears, that network name is added to a list of networks to ignore. All other networks are used by the time daemon. The -n and -i flags are meaningless if used together.

timed checks for a master time server on each network to which it is connected, except as modified by the -n and -i options. If it finds masters on more than one network, it chooses one network on which to be a “slave” and then periodically checks the other networks to see if the masters there have disappeared.

One way to synchronize a group of machines is to use an NTP daemon to synchronize the clock of one machine to a distant standard or a radio receiver and -F hostname to tell its timed daemon to trust only itself.

Messages printed by the kernel on the system console occur with interrupts disabled. This means that the clock stops while they are printing. A machine with many disk or network hardware problems and consequent messages cannot keep good time by itself. Each message typically causes the clock to lose a dozen milliseconds. A time daemon can correct the result.

Messages in the system log about machines that failed to respond usually indicate machines that crashed or were turned off. Complaints about machines that failed to respond to initial time settings are often associated with “multi-homed” machines that looked for time masters on more than one network and eventually chose to become a slave on the other network.

WARNING

If two or more time daemons, whether timed, NTP, try to adjust the same clock, temporal chaos will result. If both this and another time daemon are run on the same machine, ensure that the -F flag is used, so that timed never attempts to adjust the local clock.

The protocol is based on UDP/IP broadcasts. All machines within the range of a broadcast that are using the TSP protocol must cooperate. There cannot be more than a single administrative domain using the -F flag among all machines reached by a broadcast packet. Failure to follow this rule is usually indicated by complaints concerning “untrusted” machines in the system log.

FILES

/var/log/timed.log tracing file for timed

/var/log/timed.masterlog log file for master timed

SEE ALSO

date(1), adjtime(2), gettimeofday(2), icmp(4), timedc(8), “TSP: The Time Synchronization Protocol for UNIX 4.3 BSD,” R. Gusella, S. Zatti.

HISTORY

The timed daemon appeared in BSD 4.3.

BSD 4.3, 11 May 1993

timedc

timedc—Timed control program.

SYNOPSIS

timedc [command] [argument ...]

traceroute 1409

DESCRIPTION

timedc is used to control the operation of the timed(8) program. It may be used to

Measure the differences between machines’ clocks

Find the location where the master time server is running

Enable or disable tracing of messages received by timed

Perform various debugging actions

Without any arguments, timedc will prompt for commands from the standard input. If arguments are supplied, timedc interprets the first argument as a command and the remaining arguments as parameters to the command. The standard input may be redirected, causing timedc to read commands from a file. Commands may be abbreviated; recognized commands are

? [command ...] help [command ...]

Print a short description of each command specified in the argument list or, if no arguments are given, a list of the recognized commands.

clockdiff host ...	Compute the differences between the clock of the host machine and the clocks of the
	machines given as arguments.

msite [host ...] trace {on | off} election host

Show the master time server for specified hosts.

Enable or disable the tracing of incoming messages to timed in the file.

Asks the daemon on the target host to reset its “election” timers and to ensure that a time master has been elected.

quit Exit from timedc

Other commands may be included for use in testing and debugging timed; the help command and the program source may be consulted for details.

FILES

/var/log/timed.log tracing file for timed

/var/log/timed.masterlog log file for master timed

SEE ALSO

date(1), adjtime(2), icmp(4), timed(8), “TSP: The Time Synchronization Protocol for UNIX 4.3 BSD,” R. Gusella, S. Zatti.

DIAGNOSTICS

?Ambiguous command

?Invalid command

?Privileged command

Abbreviation matches more than one command No match found

Command can be executed by root only

HISTORY

The timedc command appeared in BSD 4.3.

BSD 4.3, 11 May 1993

traceroute

traceroute—Print the route that packets take to the network host.

SYNOPSIS

traceroute [-m max_ttl] [-n] [-p port] [-q nqueries]

[-r] [-s src_addr] [-t tos] [-w waittime] host [packetsize]

		Part VIII: Administration and Privileged Commands
	1410

DESCRIPTION

The Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route one’s packets follow (or finding the miscreant gateway that’s discarding your packets) can be difficult. traceroute utilizes the IP protocol time-to-live field and attempts to elicit an ICMP TIME_EXCEEDED response from each gateway along the path to some host.

The only mandatory parameter is the destination hostname or IP number. The default probe datagram length is 38 bytes, but this can be increased by specifying a packet size (in bytes) after the destination hostname.

Other options are
-m maxttl	Set the max time-to-live (max number of hops) used in outgoing probe packets. The
	default is 30 hops (the same default used for TCP connections).
-n	Print hop addresses numerically rather than symbolically and numerically (saves a
	nameserver address-to-name lookup for each gateway found on the path).
-p port	Set the base UDP port number used in probes (default is 33434). traceroute hopes that
	nothing is listening on UDP ports base to base + nhops -1 at the destination host (so an
	ICMP PORT_UNREACHABLE message will be returned to terminate the route tracing). If
	something is listening on a port in the default range, this option can be used to pick an
	unused port range.
-q nqueries	Set the number of probes per ttl to nqueries (default is three probes).
-r	Bypass the normal routing tables and send directly to a host on an attached network. If
	the host is not on a directly attached network, an error is returned. This option can be
	used to ping a local host through an interface that has no route through it (for example,
	after the interface was dropped by routed(8)).
-s src_addr	Use the following IP address (which must be given as an IP number, not a hostname) as
	the source address in outgoing probe packets. On hosts with more than one IP address,
	this option can be used to force the source address to be something other than the IP
	address of the interface the probe packet is sent on. If the IP address is not one of this
	machine’s interface addresses, an error is returned and nothing is sent.
-t tos	Set the type-of-service in probe packets to the following value (default zero). The value
	must be a decimal integer in the range 0 to 255. This option can be used to see if
	different types of service result in different paths. (If you are not running a BSD 4.3
	tahoe or later system, this may be academic because the normal network services such as
	Telnet and FTP don’t let you control the TOS). Not all values of TOS are legal or
	meaningful; see the IP spec for definitions. Useful values are probably (low delay) and
	(high throughput).
-v	Verbose output. Received ICMP packets other than TIME_EXCEEDED and UNREACHABLEs are
	listed.
-w	Set the time (in seconds) to wait for a response to a probe (default is 3 seconds).

This program attempts to trace the route an IP packet would follow to some Internet host by launching UDP probe packets with a small ttl (time to live) and then listening for an ICMP “time exceeded” reply from a gateway. We start our probes with a ttl of one and increase by one until we get an ICMP “port unreachable” (which means we got to “host”) or hit a max (which defaults to 30 hops and can be changed with the -m flag). Three probes (changed with the -q flag) are sent at each ttl setting and a line is printed showing the ttl, address of the gateway, and round-trip time of each probe. If the probe answers come from different gateways, the address of each responding system will be printed. If there is no response within a three second time-out interval (changed with the -w flag), a * is printed for that probe.

We don’t want the destination host to process the UDP probe packets, so the destination port is set to an unlikely value (if some clod on the destination is using that value, it can be changed with the -p flag).

traceroute 1411

A sample use and output might be

[yak 71]% traceroute nis.nsf.net.
traceroute to nis.nsf.net (35.1.1.48), 30						hops max,
	56 byte packet
1	helios.ee.lbl.gov (128.3.112.1)			19 ms			19 ms		0	ms
2	lilac-dmc.Berkeley.EDU (128.32.216.1)					39		ms	39	ms	19	ms
3	lilac-dmc.Berkeley.EDU (128.32.216.1)					39		ms	39	ms	19	ms
4	ccngw-ner-cc.Berkeley.EDU (128.32.136.23)							39	ms	40 ms		39 ms
5	ccn-nerif22.Berkeley.EDU (128.32.168.22)							39 ms		39	ms	39 ms
6	128.32.197.4 (128.32.197.4)		40	ms	59	ms		59	ms
7	131.119.2.5 (131.119.2.5)	59 ms		59 ms			59 ms
8	129.140.70.13 (129.140.70.13)		99 ms			99	ms		80 ms
9	129.140.71.6 (129.140.71.6)		139 ms		239		ms		319	ms
10	129.140.81.7 (129.140.81.7)		220 ms			199		ms	199 ms
11	nic.merit.edu (35.1.1.48)	239		ms	239 ms			239 ms

Note that Lines 2 and 3 are the same. This is due to a buggy kernel on the second hop system—lbl-csam.arpa—that forwards packets with a zero ttl (a bug in the distributed version of 4.3 BSD). Note that you have to guess what path the packets are taking cross-country because the NSFNet (129.140) doesn’t supply address-to-name translations for its NSSs.

A more interesting example is

[yak 72]% traceroute allspice.lcs.mit.edu.
traceroute to allspice.lcs.mit.edu (18.26.0.115), 30										hops max
1	helios.ee.lbl.gov (128.3.112.1)		0 ms		0 ms			0	ms
2	lilac-dmc.Berkeley.EDU (128.32.216.1)				19	ms		19		ms	19 ms
3	lilac-dmc.Berkeley.EDU (128.32.216.1)				39	ms		19		ms	19 ms
4	ccngw-ner-cc.Berkeley.EDU (128.32.136.23)						19 ms			39 ms		39 ms
5	ccn-nerif22.Berkeley.EDU (128.32.168.22)					20 ms				39	ms	39 ms
6	128.32.197.4 (128.32.197.4)	59 ms		119 ms				39	ms
7	131.119.2.5 (131.119.2.5) 59 ms		59 ms 39 ms
8	129.140.70.13 (129.140.70.13)	80 ms			79 ms			99 ms
9	129.140.71.6 (129.140.71.6)	139 ms		139 ms				159		ms
10	129.140.81.7 (129.140.81.7)	199 ms			180	ms		300		ms
11	129.140.72.17 (129.140.72.17)		300 ms		239		ms		239		ms
12	* * *
13	128.121.54.72 (128.121.54.72)		259 ms		499		ms		279		ms

14* * *

15* * *

16* * *

17* * *

18ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms

Note that the gateways 12, 14, 15, 16, and 17 hop away. Either don’t send ICMP “time exceeded” messages or send them with a ttl too small to reach us. Lines 14–17 are running the MIT C Gateway code that doesn’t send “time exceeded”s. God only knows what’s going on with 12.

The silent gateway 12 may be the result of a bug in the 4.[23] BSD network code (and its derivatives): 4.x (x <= 3) sends an unreachable message using whatever ttl remains in the original datagram. Because for gateways the remaining ttl is zero, the ICMP “time exceeded” is guaranteed to not make it back to us. The behavior of this bug is slightly more interesting when it appears on the destination system:

1	helios.ee.lbl.gov (128.3.112.1) 0	ms	0 ms		0 ms
2	lilac-dmc.Berkeley.EDU (128.32.216.1)		39 ms		19 ms		39	ms
3	lilac-dmc.Berkeley.EDU (128.32.216.1)		19	ms	39	ms	19	ms
4	ccngw-ner-cc.Berkeley.EDU (128.32.136.23)			39	ms	40 ms		19 ms
5	ccn-nerif35.Berkeley.EDU (128.32.168.35)			39	ms	39	ms	39	ms
6	csgw.Berkeley.EDU (128.32.133.254)	39	ms	59	ms	39 ms

7***

8***

		Part VIII: Administration and Privileged Commands
	1412

9***

10* * *

11* * *

12* * *

13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms

!

Notice that there are 12 “gateways” (13 is the final destination) and exactly the last half of them are “missing.” What’s really happening is that rip (a Sun-3 running Sun OS3.5) is using the ttl from our arriving datagram as the ttl in its ICMP reply. The reply will time out on the return path (with no notice sent to anyone because ICMPs aren’t sent for ICMPs) until we probe with a ttl that’s at least twice the path length. That is, rip is really only seven hops away. A reply that returns with a ttl of 1 is a clue this problem exists. traceroute prints a ! after the time if the ttl is less than or equal to 1. Because vendors ship a lot of obsolete (DEC Ultrix, Sun 3.x) or non-standard HPUX software, expect to see this problem frequently or take care picking the target host of your probes. Other possible annotations after the time are !H, !N, !P (got a host, network, or protocol unreachable), !S, or !F (source route failed or fragmentation needed—neither of these should ever occur and the associated gateway is busted if you see one). If almost all the probes result in some kind of unreachable, traceroute will give up and exit.

This program is intended for use in network testing, measurement, and management. It should be used primarily for manual fault isolation. Because of the load it could impose on the network, it is unwise to use traceroute during normal operations or from automated scripts.

AUTHOR

Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged by a cast of thousands with particularly cogent suggestions or fixes from C. Philip Wood, Tim Seaver, and Ken Adelman.

SEE ALSO

netstat(1), ping(8)

BSD 4.3, 6 June 1993

tune2fs

tune2fs—Adjust tunable filesystem parameters on second extended filesystems.

SYNOPSIS

tune2fs [ -l ][-c max-mount-counts ][-e errors-behavior ]

[-i interval-between-checks ][ -m reserved-blocks-percentage ] [-r reserved-blocks-count ][-u user ][-g group ]device

DESCRIPTION

tune2fs adjusts tunable filesystem parameters on a Linux second extended filesystem.

Never use tune2fs on a read/write mounted filesystem to change parameters!

OPTIONS

-c	max-mount-counts	Adjust the maximal mounts count between two filesystem checks.
-e	errors-behavior	Change the behavior of the kernel code when errors are detected. errors-behavior can
		be one of the following:

continue

remount-ro

panic

Continue normal execution. Remount the filesystem read-only. Causes a kernel panic.

tunelp 1413

-g group	Set the user group that can benefit from the reserved blocks. group can be a numerical
	GID or a group name.

-i interval-between-checks[d|m|w]

-l

-m reserved-blocks-percentage

-r reserved-blocks-count

-u user

Adjust the maximal time between two filesystem checks. No postfix or d results in days, m in months, and w in weeks. A value of 0 will disable the time-dependent checking.

List the contents of the filesystem superblock.

Adjust the reserved blocks percentage on the given device. Adjust the reserved blocks count on the given device.

Set the user who can benefit from the reserved blocks. user can be a numerical UID or a username.

BUGS

We didn’t find any bugs. Perhaps there are bugs, but it’s unlikely.

WARNING

Use this utility at your own risk. You’re modifying filesystems.

AUTHOR

tune2fs was written by Remy Card ([e-mail]), the developer and maintainer of the ext2 filesystem. tune2fs uses the ext2fs library written by Theodore T’so ([e-mail]). This manual page was written by Christian Kuhtz ([e-mail]). Time-dependent checking was added by Uwe Ohse ([e-mail]).

AVAILABILITY

tune2fs is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs.

SEE ALSO

dumpe2fs(8), e2fsck(8), mke2fs(8)

Version 0.5b, November 1994

tunelp

tunelp—Set various parameters for the lp device.

SYNOPSIS

tunelp device [-i IRQ | -t TIME | -c CHARS

| -w WAIT | -a [on|off] | -o [on|off] | -C [on|off] | -r | -s | -q [on|off] ]

DESCRIPTION

tunelp sets several parameters for the /dev/lp? devices, for better performance (or for any performance at all, if your printer won’t work without it…). Without parameters, tunelp tells whether the device is using interrupts, and if so, which one. With parameters, tunelp sets the device characteristics accordingly. The parameters are as follows:

-i <IRQ>	The IRQ to use for the parallel port in question. If this is set to something nonzero, -t
	and -c have no effect. If your port does not use interrupts, this option will make
	printing stop. tunelp -i 0 restores non-interrupt driven (polling) action, and your
	printer should work again. If your parallel port does support interrupts, interrupt-driven
	printing should be somewhat faster and efficient and will probably be desirable.
-t <TIME>	The amount of time in jiffies that the driver waits if the printer doesn’t take a character
	for the number of tries dictated by the -c parameter. 10 is the default value. If you want
	the fastest possible printing and don’t care about system load, you can set this to 0. If

		Part VIII: Administration and Privileged Commands
	1414
		you don’t care how fast your printer goes or are printing text on a slow printer with a
		buffer, then 500 (5 seconds) should be fine and will give you very low system load. This
		value generally should be lower for printing graphics than text, by a factor of approxi-
		mately 10, for best performance.

-c <CHARS>	The number of times to try to output a character to the printer before sleeping for
	-t <TIME>. It is the number of times around a loop that tries to send a character to the
	printer. 120 appears to be a good value for most printers. 250 is the default because there
	are some printers that require a wait this long, but feel free to change this. If you have a
	very fast printer like an HP Laserjet 4, a value of 10 might make more sense. If you have
	a really old printer, you can increase this.
	Setting -t <TIME> to 0 is equivalent to setting -c <CHARS> to infinity.
-w <WAIT>	The busy loop counter for the strobe signal. Although most printers appear to be able to
	deal with an extremely short strobe, some printers demand a longer one. Increasing this
	from the default 0 might make it possible to print with those printers. This can also
	make it possible to use longer cables.
-a [on|off]	This is whether to abort on printer error; the default is not to. If you are sitting at your
	computer, you probably want to be able to see an error and fix it and have the printer go
	on printing. On the other hand, if you aren’t, you might rather that your printer spooler
	find out that the printer isn’t ready, quit trying, and send you mail about it. The choice
	is yours.
-o [on|off]	This option is much like -a. It makes any open() of this device check to see that the
	device is online and not reporting any out-of-paper or other errors. This is the correct
	setting for most versions of lpd.
-C [on|off]	This option adds extra (“careful”) error checking. When this option is on, the printer
	driver will ensure that the printer is online and not reporting any out-of-paper or other
	errors before sending data. This is particularly useful for printers that usually appear to
	accept data when turned off.
-s	This option returns the current printer status, both as a decimal number from 0 to 255
	and as a list of active flags. When this option is specified, -q off, turning off the display
	of the current IRQ, is implied.
	-o, -C, and -s all require a Linux kernel version of 1.1.76 or later.
-r	This option resets the port. It requires a Linux kernel version of 1.1.80 or later.
-q [on|off]	This option sets printing the display of the current IRQ setting.
	Cohesive Systems, 26 August 1992

update_state

update_state—Update system state.

SYNOPSIS

update_state

DESCRIPTION

update_state updates a bunch of system states. It takes a long time to execute and would be suitable for execution in a cron job.

Currently, update_state performs the following functions: updates the locate database (in /usr/lib/locate), updates the whatis database(in /usr/man, /usr/local/man, /usr/X386/man, and /usr/interviews/man), and updates the TeX ls-R cache file (in /usr/lib/texmf).

uucico 1415

BUGS

The script expects things to be where the FSSTND says they are. For example, if you have makewhatis(8) in /usr/lib, where it is traditionally, then you lose, because it should be in /usr/bin.

SEE ALSO

cron(8), find(1), locate(1)

AUTHOR

Rik Faith ([e-mail])

Linux 1.0 8, July 1994

uucico

uucico—UUCP file transfer daemon.

SYNOPSIS

uucico [ options ]

DESCRIPTION

The uucico daemon processes file transfer requests queued by uucp(1) and uux(1). It is started when uucp or uux is run (unless they are given the -r option). It is also typically started periodically using entries in the crontab tables.

When invoked with -r1, --master, -s, --system, or -S, the daemon will place a call to a remote system, running in master mode. Otherwise, the daemon will start in slave mode, accepting a call from a remote system. Typically, a special login name will be set up for UUCP, which automatically invokes uucico when a call is made.

When uucico terminates, it invokes the uuxqt(8) daemon, unless the -q work orders created by uux(1) on a remote system and any work orders which they were waiting.

or --nouuxqt option is given; uuxqt(8) executes any created locally that have received remote files for

If a call fails, uucico will usually refuse to retry the call until a certain (configurable) amount of time has passed. This may be overridden by the -f, -force, or -S option.

The -l, --prompt, -e, or --loop options may be used to force uucico to produce its own prompts of login: and Password:. When another daemon calls in, it will see these prompts and log in as usual. The login name and password are usually checked against a separate list kept specially for uucico rather than the /etc/passwd file; it is possible on some systems to direct uucico to use the /etc/passwd file. The -l or -prompt option will prompt once and then exit; in this mode, the UUCP administrator or the superuser may use the -u or -login option to force a login name, in which case uucico will not prompt for one. The -e or -loop option will prompt again after the first session is over; in this mode, uucico will permanently control a port.

If uucico receives a SIGQUIT, SIGTERM, or SIGPIPE signal, it will cleanly abort any current conversation with a remote system and exit. If it receives a SIGHUP signal, it will abort any current conversation, but will continue to place calls to (if invoked with -r1 or --master) and accept calls from (if invoked with -e or --loop) other systems. If it receives a SIGINT signal, it will finish the current conversation but will not place or accept any more calls.

OPTIONS

The following options may be given to uucico:

-r1, ---master	Start in master mode (call out to a system); implied by -s, --system, or -S. If no system
	is specified, call any system for which work is waiting to be done.
-r0, ---slave	Start in slave mode. This is the default.
-s system, ---system system	Call the named system.

		Part VIII: Administration and Privileged Commands
	1416

-S system	Call the named system, ignoring any required wait. This is equivalent to -s system –f.
-f, ---force	Ignore any required wait for any systems to be called.
-l, ---prompt	Prompt for login name and password using login: and Password:. This allows uucico to
	be easily run from inetd(8). The login name and password are checked against the
	UUCP password file, which probably has no connection to the file /etc/passwd. The
	--login option may be used to force a login name, in which case uucico will only
	prompt for a password.
-p port, ---port port	Specify a port to call out on or to listen to.
-e, ---loop	Enter endless loop of login/password prompts and slave mode daemon execution. The
	program will not stop by itself; you must use kill(1) to shut it down.
-w, ---wait	After calling out (to a particular system when -s, --system, or -S is specified or to all
	systems that have work when just -r1 or --master is specified), begin an endless loop as
	with --loop.
-q, ---nouuxqt	Do not start the uuxqt(8) daemon when finished.
-c, ---quiet	If no calls are permitted at this time, then don’t make the call, but also do not put an
	error message in the log file and do not update the system status (as reported by
	uustat(1)). This can be convenient for automated polling scripts, which may want to
	simply attempt to call every system rather than worry about which particular systems
	may be called at the moment. This option also suppresses the log message indicating
	that there is no work to be done.
-C, ---ifwork	Only call the system named by -s, --system, or -S if there is work for that system.
-D, ---nodetach	Do not detach from the controlling terminal. Normally, uucico detaches from the
	terminal before each call out to another system and before invoking uuxqt. This option
	prevents this.
-u name, ---login name	Set the login name to use instead of that of the invoking user. This option may only be
	used by the UUCP administrator or the superuser. If used with --prompt, this will cause
	uucico to prompt only for the password, not the login name.
-z, ---try-next	If a call fails after the remote system is reached, try the next alternate rather than simply
	exiting.
-i type, ---stdin type	Set the type of port to use when using standard input. The only support port type is
	TLI, and this is only available on machines that support the TLI networking interface.
	Specifying -iTLI causes uucico to use TLI calls to perform I/O.
-x type, –X type, ---debug type	Turn on particular debugging types. The following types are recognized: abnormal, chat,
	handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing.
	Multiple types may be given, separated by commas, and the --debug option may appear
	multiple times. A number may also be given, which will turn on that many types from
	the foregoing list; for example, --debug 2 is equivalent to --debug abnormal,chat.
	The debugging output is sent to the debugging file, usually one of /usr/spool/uucp/Debug,
	/usr/spool/uucp/DEBUG, or /usr/spool/uucp/.Admin/audit.local.
-I file, ---config file	Set configuration file to use. This option may not be available, depending on how
	uucico was compiled.
-v, ---version	Report version information and exit.
--help	Print a help message and exit.
-u login	This option is ignored. It is only included because some versions of uucpd invoke uucico
	with it.

FILES

The filenames may be changed at compilation time or by the configuration file, so these are only approximations:

/usr/lib/uucp/config	Configuration file.
/usr/lib/uucp/passwd	Default UUCP password file.

vmstat 1417

/usr/spool/uucp	UUCP spool directory.
/usr/spool/uucp/Log	UUCP log file.
/usr/spool/uucppublic	Default UUCP public directory.
/usr/spool/uucp/Debug	Debugging file.

SEE ALSO

kill(1), uucp(1), uux(1), uustat(1), uuxqt(8)

AUTHOR

Ian Lance Taylor ([e-mail])

Taylor UUCP 1.05

vmstat

vmstat—Report virtual memory statistics.

SYNOPSIS

vmstat [ -n ] [ delay [ count ] ]

DESCRIPTION

vmstat reports information about processes, memory, paging, block IO, traps, and CPU activity.

The first report produced gives averages since the last reboot. Additional reports give information on a sampling period of length delay. The process and memory reports are instantaneous in either case.

OPTIONS

The -n switch causes the header to be displayed only once rather than periodically.

delay is the delay between updates in seconds. If no delay is specified, only one report is printed with the average values since boot.

count is the number of updates. If no count is specified and delay is defined, count defaults to infinity.

FIELD DESCRIPTIONS

Procs

r	The number of processes waiting for runtime.
b	The number of processes in uninterruptible sleep.
w	The number of processes swapped out but otherwise runnable.
	This field is calculated, but Linux never desperation swaps.
Memory
swpd	The amount of virtual memory used (KB).
free	The amount of idle memory (KB).
buff	The amount of memory used as buffers (KB).
Swap
si	Amount of memory swapped in from disk (KB/s).
so	Amount of memory swapped to disk (KB/s).

		Part VIII: Administration and Privileged Commands
	1418

IO

bi	Blocks sent to a block device (blocks/s).
bo	Blocks received from a block device (blocks/s).
System
in	The number of interrupts per second, including the clock.
cs	The number of context switches per second.
CPU (These are percentages of total CPU time.)
us	User time.
sy	System time.
id	Idle time.

NOTES

vmstat does not require special permissions.

These reports are intended to help identify system bottlenecks. Linux vmstat does not count itself as a running process. All Linux blocks are currently 1KB, except for CD-ROM blocks, which are 2KB.

FILES

/proc/meminfo

/proc/stat

/proc/*/stat

SEE ALSO

ps(1), top(1), free(1)

BUGS

vmstat does not tabulate the block IO per device or count the number of system calls.

AUTHOR

Written by Henry Ware ([e-mail])

Throatwobbler Ginkgo Labs, 27 July 1994

vipw

vipw—Edit the password file.

SYNOPSIS

vipw

DESCRIPTION

vipw edits the password file after setting the appropriate locks and does any necessary processing after the password file is unlocked. If the password file is already locked for editing by another user, vipw will ask you to try again later. The default editor for vipw is vi(1).

zic 1419

ENVIRONMENT

If the following environment variable exists, it will be utilized by vipw:

EDITOR	The editor specified by the string. EDITOR will be invoked instead of the default editor
	vi(1).

SEE ALSO

passwd(1), vi(1), passwd(5)

HISTORY

The vipw command appeared in BSD 4.0.

BSD 4, 16 March 1991

zdump

zdump—Time zone dumper.

SYNOPSIS

zdump [ -v ][-c cutoffyear ] [ zonename ...

]

DESCRIPTION

zdump prints the current time in each zonename named on the command line. These options are available:

-v	For each zonename on the command line, print the current time, the time at the lowest
	possible time value, the time one day after the lowest possible time value, the times both
	one second before and exactly at each detected time discontinuity, the time at one day
	less than the highest possible time value, and the time at the highest possible time value.
	Each line ends with isdst=1 if the given time is Daylight Saving Time or isdst=0
	otherwise.

-c cutoffyear

Cut off the verbose output near the start of the given year.

SEE ALSO

newctime(3), tzfile(5), zic(8)

zic

zic—Time zone compiler.

SYNOPSIS

zic [ -v ][-d directory ][-l localtime ][-p posixrules ] [-L leapsecondfilename ][-s ] [ -y command ][filename ... ]

DESCRIPTION

zic reads text from the files named on the command line and creates the time conversion information files specified in this input. If a filename is –, the standard input is read.

These options are available:
-d directory	Create time conversion information files in the named directory rather than in the
	standard directory named below.

		Part VIII: Administration and Privileged Commands
	1420

-l timezone	Use the given time zone as local time. zic will act as if the input contained a link line of
	the form.
	Link timezone localtime.
-p timezone	Use the given time zone’s rules when handling POSIX-format time zone environment
	variables. zic will act as if the input contained a link line of the form.
	Link timezone posixrules.

-L leapsecondfilename

Read leap second information from the file with the given name. If this option is not used, no leap second information appears in output files.

-v	Complain if a year that appears in a data file is outside the range of years representable
	by time(2) values.
-s	Limit time values stored in output files to values that are the same whether they’re taken
	to be signed or unsigned. You can use this option to generate SVVS-compatible files.
-y command	Use the given command rather than yearistype when checking year types.

Input lines are made up of fields. Fields are separated from one another by any number of whitespace characters. Leading and trailing whitespace on input lines is ignored. An unquoted sharp character (#) in the input introduces a comment that extends to the end of the line the sharp character appears on. Whitespace characters and sharp characters may be enclosed in double quotes (“) if they’re to be used as part of a field. Any line that is blank (after comment stripping) is ignored. Nonblank lines are expected to be of one of three types: rule lines, zone lines, and link lines.

A rule line has the form

Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S

For example:

Rule US 1967 1973 – Apr lastSun 2:00 1:00 D

The fields that make up a rule line are
NAME	Gives the (arbitrary) name of the set of rules this rule is part of.
FROM	Gives the first year in which the rule applies. Any integer year can be supplied; the
	Gregorian calendar is assumed. The word minimum (or an abbreviation) means the
	minimum year representable as an integer. The word maximum (or an abbreviation) means
	the maximum year representable as an integer. Rules can describe times that are not
	representable as time values, with the unrepresentable times ignored; this allows rules to
	be portable among hosts with differing time value types.
TO	Gives the final year in which the rule applies. In addition to minimum and maximum,
	the word only (or an abbreviation) may be used to repeat the value of the FROM field.
TYPE	Gives the type of year in which the rule applies. If TYPE is –, the rule applies in all years
	between FROM and TO inclusive. If TYPE is something else, then zic executes the command
	yearistype year type
	to check the type of a year. An exit status of zero is taken to mean that the year is of the
	given type; an exit status of one is taken to mean that the year is not of the given type.
IN	Names the month in which the rule takes effect. Month names may be abbreviated.
ON	Gives the day on which the rule takes effect. Recognized forms include
	5	The fifth of the month
	lastSun	The last Sunday in the month
	lastMon	The last Monday in the month
	Sun>=8	First Sunday on or after the eighth
	Sun<=25	Last Sunday on or before the 25th
		Names of days of the week may be abbreviated or spelled out in full.
		Note that there must be no spaces within the ON field.

		zic
				1421
AT	Gives the time of day at which the rule takes effect. Recognized forms include
	2	Time in hours
	2:00	Time in hours and minutes
	15:00	24-hour format time (for times after noon)
	1:28:14	Time in hours, minutes, and seconds
	Any of these forms may be followed by the letter w if the given time is local wall clock
	time, s if the given time is local standard time, or u (or g or z) if the given time is
	universal time; in the absence of an indicator, wall clock time is assumed.
SAVE	Gives the amount of time to be added to local standard time when the rule is in effect.
	This field has the same format as the AT field (although, of course, the w and s suffixes
	are not used).
LETTER/S	Gives the variable part (for example, the S or D in EST or EDT) of time-zone abbrevia-
	tions to be used when this rule is in effect. If this field is –, the variable part is null.

A zone line has the form

Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL]

For example:

Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00

The fields that make up a zone line are

NAME	The name of the time zone. This is the name used in creating the time conversion
	information file for the zone.
GMTOFF	The amount of time to add to GMT to get standard time in this zone. This field has the
	same format as the AT and SAVE fields of rule lines; begin the field with a minus sign if
	time must be subtracted from GMT.
RULES/SAVE	The name of the rules that apply in the time zone or, alternately, an amount of time to
	add to local standard time. If this field is –, standard time always applies in the time
	zone.
FORMAT	The format for time zone abbreviations in this time zone. The pair of characters %s is
	used to show where the variable part of the time-zone abbreviation goes. Alternately, a
	slash (/) separates standard and daylight abbreviations.
UNTIL	The time at which the GMT offset or the rules change for a location. It is specified as a
	year, a month, a day, and a time of day. If this is specified, the time-zone information is
	generated from the given GMT offset and rule change until the time specified.
	The next line must be a continuation line; this has the same form as a zone line except
	that the string Zone and the name are omitted because the continuation line will place
	information starting at the time specified as the UNTIL field in the previous line in the file
	used by the previous line. Continuation lines may contain an UNTIL field, just as zone
	lines do, indicating that the next line is a further continuation.
A link line has the form
Link LINK-FROM LINK-TO
For example:
Link US/Eastern EST5EDT

The LINK-FROM field should appear as the NAME field in some zone line; the LINK-TO field is used as an alternate name for that zone.

Except for continuation lines, lines may appear in any order in the input.

Lines in the file that describe leap seconds have the following form:

		Part VIII: Administration and Privileged Commands
	1422

Leap YEAR MONTH DAY HH:MM:SS CORR R/S

For example:

Leap 1974 Dec 31 23:59:60 + S

The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second happened. The CORR field should be + if a second was added or – if a second was skipped. The R/S field should be (an abbreviation of) Stationary if the leap second time given by the other fields should be interpreted as GMT or (an abbreviation of) Rolling if the leap second time given by the other fields should be interpreted as local wall clock time.

NOTE

For areas with more than two types of local time, you may need to use local standard time in the AT field of the earliest transition time’s rule to ensure that the earliest transition time recorded in the compiled file is correct.

FILE

/usr/local/etc/zoneinfo standard directory used for created files.

SEE ALSO

newctime(3), tzfile(5), zdump(8)

1423

Part IX:

Kernel Reference

Guide

add_timer

del_timer

		Part IX: Kernel Reference Guide
	1424

add_timer, del_timer, init_timer

add_timer, del_timer, init_timer—Manage event timers.

SYNOPSIS

#include <asm/param.h> #include <linux/timer.h>

extern void add_timer(struct timer_list * timer); extern int del_timer(struct timer_list * timer);

extern inline void init_timer(struct timer_list * timer);

DESCRIPTION

add_timer schedules an event, adding it to a linked list of events maintained by the kernel. del_timer deletes a scheduled event. timer points to a

struct timer_list { struct timer_list *next; struct timer_list *prev; unsigned long expires; unsigned long data;

void (*function)(unsigned long); };

init_timer sets next and prev to NULL. This is required for the argument of add_timer. expires is the desired duration of the timer in jiffies, where there are HZ (typically 100) jiffies per second. When the timer expires, function is called with data as its argument. It is the responsibility of function to delete the event. If the same function is managing several timers, the argument can be used to distinguish which one expired.

RETURN VALUE

del_timer returns zero on error—if next or prev are not NULL, but the timer was not found. time remaining before the timer expires and sets next and prev to NULL. Thus, calling

is a no-op provided a kernel tick does not occur between the two calls.

del_timer also sets expires to the followed immediately by

AUTHOR

Linus Torvalds

Linux 1.2.8, 31 May 1995

adjust_clock

adjust_clock—Adjusts startup time counter to tick in GMT.

SYNOPSIS

linux/kernel/sys.c void adjust_clock();

DESCRIPTION

This routine adjusts the startup time by adding the time zone information to it. The goal is to get the startup time ticking in GMT time.

NOTES

This routine is called from settimeofday(2) when the time-zone information is first set.

file_table 1425

AUTHOR

Theodore T’so ([e-mail])

SEE ALSO

settimeofday(2)

Linux 0.99.10, 7 July 1993

ctrl_alt_del

ctrl_alt_del—Routes the keyboard interrupt Ctrl+Alt+Del key sequence.

SYNOPSIS

linux/kernel/sys.c

void ctrl_alt_del(void);

DESCRIPTION

This simple routine tests the variable C_A_D for a true/false condition. If it is true, a hard reset is done by the system. Otherwise, a signal SIGINT is sent to the process with the process ID 1, usually a program called init.

WARNINGS

This routine is in interrupt mode. It cannot sync() your system. Data loss may occur. It is recommended that you configure your system to send a signal to init, where you can control the shutdown.

NOTES

The default of this function is to do hard resets immediately.

AUTHOR

Linus Torvalds

SEE ALSO

reboot(2), reset_hard_now(9), sync(2)

Linux 0.99.10, 6 July 1993

file_table

file_table—Detailed description of the table and table entry.

SYNOPSIS

From #include <linux/fs.h>

struct file { mode_t f_mode;

dev_t f_rdev; /* needed for /dev/tty */ off_t f_pos;

unsigned short f_flags; unsigned short f_count; unsigned short f_reada; struct file *f_next, *f_prev; struct inode *f_inode;

		Part IX: Kernel Reference Guide
	1426

struct file_operations *f_op; };

From linux/fs/file_table.c

struct file *first_file; int nr_files = 0;

DESCRIPTION

The file table is fundamentally important to any UNIX system. It is where all open files (Linux includes closed files as well) are stored and managed by the kernel. For Linux, you can hardly do anything without referencing it in some way.

Linux stores its file table as a double circular linked list. The root pointer to the “head” of this list is first_file. Also, a count of how many entries are in the file table is maintained, called nr_files. Under this scheme, the file table for Linux could be as large as memory could hold. Unfortunately, this would be unmanageable in most cases. Your computer would be in the kernel most of the time when processes are more important. To keep this from happening, nr_files is tested against NR_FILE to limit the number of file table entries.

UNDERSTANDING THE STRUCTURE OF THE FILE TABLE

The file table is organized as a double circular linked list. Imagine a circle of people with everyone facing the same direction. Each person is facing so that one arm is in the circle and the other arm is outside the circle. Now, if each person put his or her right hand on the shoulder of the person in front of him or her and if each person touched the person behind him or her with his or her left hand. You have formed two circles of arms, one inside and the other outside. The right arms represent pointers to the next entry (or person). The left arms represent pointers to the previous entry (or person).

THE FILE STRUCTURE, A FILE TABLE ENTRY

At first glance, a table entry looks quite simple. An entry contains how a file was opened, what tty device, a reference count, pointers to other entries, pointer to v-node (the vfs i-node) filesystem-specific i-node information, and so on.

f_mode	After ANDing with O ACCMODE, this is what bits 0 and 1 mean:
00	No permissions needed
01	Read-permission
10	Write-permission
11	Read-write
f_rdev	It is used only with tty lines. It contains the major and minor numbers of the tty device.
f_pos	The current position in a file, if meaningful.
f_flags	Storage for the flags from open() and fcntl()
f_count	Reference counter
f_reada	This is a Boolean variable where True means that an actual read is needed.
f_next, f_prev	Pointers to other entries
f_inode	Pointer to v-node and filesystem-specific i-node information
f_op	Pointer to a file’s operations

AUTHOR

Linus Torvalds

SEE ALSO

insert_file_free(9), remove_file_free(9), put_last_free(9) grow_files(9), file_table_init(9), get_empty_filp(9)

Linux 0.99.10, 11 July 1993

super_block stored.

filesystems 1427

file_table_init

file_table_init—Initializes the file table in the kernel.

SYNOPSIS

linux/fs/file_table.c unsigned long file_table_init( unsigned long start, unsigned long end);

DESCRIPTION

This routine is called from kernel_start() in linux/init/main.c. It sets first_file, a struct file pointer, to NULL. This is the head of the linked list of open files maintained in the kernel, the infamous file table in all UNIXs.

RETURN VALUE

Returns start.

NOTES

Because this is part of the kernel’s startup routine, it has the option to allocate memory, in kernel space, for itself. It does not need to do this and returns the new start of memory for the next initializing section. In this case, start is returned unmodified.

AUTHOR

Linus Torvalds

Linux 0.99.10, 9 July 1993

filesystems

filesystems—Details the table of configured filesystems.

SYNOPSIS

linux/fs/filesystems.c

From #include <linux/fs.h>

struct file system type {

struct super_block *(*read_super) (struct super_block *, void *, int); char *name;

int requires dev; };

DESCRIPTION

This source code makes a data structure call file_systems[], which contains all the configured filesystems for the kernel. It is used primarily in linux/fs/super.c for many of the mounting of filesystems functions.

THE MEANINGS

This first member, in struct file_system_type, is a function pointer to a routine that will read in the super_block. A generically means an i-node or special place on the device where information about the overall filesystem is

The name is just the string representation of the name of a specific filesystem, such as ext2 or minix.

The final member, int_requires_dev, is a Boolean value. If it is True, then the filesystem requires a block device. For False, it is unclear what happens, but an unnamed device is used, such as proc and nfs.

NR_FILE

		Part IX: Kernel Reference Guide
	1428

AUTHOR

Linus Torvalds

Linux 0.99.10, 12 July 1993

get_empty_filp

get_empty_filp—Fetches an unreferenced entry from the file table.

SYNOPSIS

linux/fs/file table.c

struct file *get_empty_filp(void);

DESCRIPTION

This routine will seek out an entry that is not being referenced by any processes. If none are found, then it will add new entries to the file table, minimum of entries.

NOTES

Due to grow_files(), a whole page of entries is created at one time. This may make more than NR_FILE entries. Also when an unreferenced entry is found, it is moved to the “end” of the file table. This heuristic is used to speed up finding unreferenced entries.

RETURN VALUE

NULL—No entries were found and the file table is full.

Returns a pointer to the entry in the file table.

AUTHOR

Linus Torvalds

SEE ALSO

grow_files(9)

Linux 0.99.10, 12 July 1993

grow_files

grow_files—Adds entries to the file table.

SYNOPSIS

linux/fs/file table.c void grow_files(void);

DESCRIPTION

This function adds entries to the file table. First, it allocates a page of memory. It fills the entire page with entries, adding each to the file table.

AUTHOR

Linus Torvalds

file_table

insert_ file_ free	1429

SEE ALSO

insert_file_free(9), remove_file_free(9), put_last_free(9)

Linux 0.99.10, 12 July 1993

in_group_p

in_group_p—Searches group IDs for a match.

SYNOPSIS

linux/kernel/sys.c

int in_group_p(gid_t grp);

DESCRIPTION

Searches supplementary group IDs and the effective group ID for a match with grp.

RETURN VALUE

Returns True (1) if found; otherwise, false (0).

AUTHOR

Linus Torvalds

SEE ALSO

getgroups(2), getgid(2), getregid(2), setgid(2), setregid(2), setgroups(2)

Linux 0.99.10, 7 July 1993

insert_file_free

insert_file_free—Adds a file entry into the file table.

SYNOPSIS

linux/fs/file_table.c

static void insert_file_free(struct file *file);

DESCRIPTION

This nightmare of pointers adds file into the file table with the root pointer at file. This is a building block of the file table management.

AUTHOR

Linus Torvalds

SEE ALSO

file_table_init(9), remove_file_free(9), put_last_free(9)

See (9) for details on the file table structure.

Linux 0.99.10

		Part IX: Kernel Reference Guide
	1430

kernel_mktime

kernel_mktime—Convert startup struct mktime into the number of seconds since 00:00:00 January 1, 1970.

SYNOPSIS

linux/kernel/mktime.c

long kernel_mktime(struct mktime * time);

DESCRIPTION

This routine is called from time_init(void), linux/init/main.c. kernel_mktime() converts struct mktime (initialized from CMOS) into an encoded long.

CONVERSION METHOD

First an array, month[12], is created, holding how many seconds have passed to reach a peculiar month for a leap year. Next, it subtracts 70 from the current year, making 1970 the beginning year. It is math magic after this point; please look yourself. If you know why it does this, then send e-mail (see nroff source).

RETURN VALUE

Returns the encoded time in a long.

FILES

linux/kernel/mktime.c home of routine

NOTES

This routine is called only during startup of the kernel.

Historically, the value (encoded long) counts the number of seconds since the Epoch, which occurred at 00:00:00 January 1, 1970, and is called Coordinated Universal Time (UTC). In older manuals, this event is called Greenwich Mean Time (GMT).

WARNINGS

kernel_mktime() doesn’t check to see if the year is greater than 1969. Be sure your CMOS is set correctly. It is customary to set on-board clocks to GMT and let processes who ask for the time to convert it to local time, if necessary.

RESTRICTIONS

For kernel use only.

AUTHOR

Linus Torvalds

Linux 0.99.10, 5 July 1993

proc_sel

proc_sel—Select a process by a criterion.

SYNOPSIS

linux/kernel/sys.c #include <linux/resource.h>

static int proc_sel(struct task_struct *p, int which, int who);

remove_ file_ free	1431

DESCRIPTION

Compares a task p to supplied information or the current task in some aspect of priority. If who is zero, the comparison is task p and the current task. Otherwise, who and *p are the supplied information for the comparison.

OPTIONS

Valid values of which:
PRIO_PROCESS	Compares process ID numbers. There is an exception here. If who is not zero and task p is
	the current task, then True is always returned.
PRIO_PGRP	Compares process group leader numbers.
PRIO_USER	Compares user ID numbers.

RETURN VALUE

Returns truth values (0, 1).

AUTHOR

Linus Torvalds

SEE ALSO

sys_setpriority(2), sys_getpriority(2)

Linux 0.99.10, 7 July 1993

put_file_last

put_file_last—Moves a file to the “end” of the file table.

SYNOPSIS

linux/fs/file table.c

static void put_last_free(struct file *file);

DESCRIPTION

This function will remove file from the file table and insert it again at the end. You can access by

first_file->prev

AUTHOR

Linus Torvalds

SEE ALSO

insert_file_free(9), remove_file_free(9)

Linux 0.99.10, 11 July 1993

remove_file_free

remove_file_free—Remove a file table entry from the linked list.

SYNOPSIS

linux/fs/file table.c

static void remove_file_free(struct file *file);

		Part IX: Kernel Reference Guide
	1432

DESCRIPTION

This routine removes the file from the table. This is used mostly for moving a file to the “end” of the list.

AUTHOR

Linus Torvalds

SEE ALSO

insert_file_free(9), put_file_last(9)