diff options
Diffstat (limited to 'share/man')
36 files changed, 531 insertions, 455 deletions
diff --git a/share/man/man9/audio.9 b/share/man/man9/audio.9 index 929c9d408f4..eb6d7aef549 100644 --- a/share/man/man9/audio.9 +++ b/share/man/man9/audio.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: audio.9,v 1.3 2000/04/27 18:29:26 mickey Exp $ +.\" $OpenBSD: audio.9,v 1.4 2000/10/12 18:05:57 aaron Exp $ .\" $NetBSD: audio.9,v 1.14 2000/02/11 22:56:15 kleink Exp $ .\" .\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc. @@ -44,9 +44,9 @@ .Sh DESCRIPTION The audio device driver is divided into a high level, hardware independent layer, and a low level hardware -dependent layer. The interface between these is -the -.Va audio_hw_if +dependent layer. +The interface between these is the +.Va audio_hw_if structure. .Bd -literal struct audio_hw_if { @@ -55,7 +55,7 @@ struct audio_hw_if { int (*drain)__P((void *)); int (*query_encoding)__P((void *, struct audio_encoding *)); - int (*set_params)__P((void *, int, int, + int (*set_params)__P((void *, int, int, struct audio_params *, struct audio_params *)); int (*round_blocksize)__P((void *, int)); @@ -118,10 +118,11 @@ This call should be struct device *dev; .Ed .Pp -The +The .Va audio_hw_if -struct is as shown above. The -.Va hdl +struct is as shown above. +The +.Va hdl argument is a handle to some low level data structure. It is sent as the first argument to all the functions in @@ -131,13 +132,14 @@ when the high level driver calls them. is the device struct for the hardware device. .Pp The upper layer of the audio driver allocates one buffer for playing -and one for recording. It handles the buffering of data from the -user processes in these. The data is presented to the lower level -in smaller chunks, called blocks. If there, during playback, is -no data available from the user process when the hardware request -another block a block of silence will be used instead. Furthermore, -if the user process does not read data quickly enough during recording -data will be thrown away. +and one for recording. +It handles the buffering of data from the user processes in these. +The data is presented to the lower level in smaller chunks, called blocks. +If there, during playback, is no data available from the user process +when the hardware requests another block, a block of silence will be +used instead. +Furthermore, if the user process does not read data quickly enough during +recording, data will be thrown away. .Pp The fields of .Va audio_hw_if @@ -145,8 +147,9 @@ are described in some more detail below. Some fields are optional and can be set to 0 if not needed. .Bl -tag -width indent .It Dv int open(void *hdl, int flags) -is called when the audio device is opened. It should initialize -the hardware for I/O. Every successful call to +is called when the audio device is opened. +It should initialize the hardware for I/O. +Every successful call to .Va open is matched by a call to .Va close . @@ -156,19 +159,21 @@ is called when the audio device is closed. .It Dv int drain(void *hdl) optional, is called before the device is closed or when .Dv AUDIO_DRAIN -is called. It should make sure that no samples remain -in to be played that could be lost when +is called. +It should make sure that no samples remain to be played that could +be lost when .Va close is called. Return 0 on success, otherwise an error code. .It Dv int query_encoding(void *hdl, struct audio_encoding *ae) is used when .Dv AUDIO_GETENC -is called. It should fill the +is called. +It should fill the .Va audio_encoding structure and return 0 or, if there is no encoding with the given number, return EINVAL. -.It Dv int set_params(void *hdl, int setmode, int usemode, +.It Dv int set_params(void *hdl, int setmode, int usemode, .Dv "struct audio_params *play, struct audio_params *rec)" .br Called to set the audio encoding mode. @@ -180,7 +185,7 @@ and flags to indicate which mode(s) are to be set. .Va usemode is also a combination of these flags, but indicates the current -mode of the device (i.e. the value of +mode of the device (i.e., the value of .Va mode in the .Va audio_info @@ -197,7 +202,7 @@ and .Va factor fields of these structures. The values of the structures may also be modified if the hardware -cannot be set to exactly the requested mode (e.g. if the requested +cannot be set to exactly the requested mode (e.g., if the requested sampling rate is not supported, but one close enough is). If the device does not have the .Dv AUDIO_PROP_INDEPENDENT @@ -215,15 +220,16 @@ Return 0 on success, otherwise an error code. .It Dv int round_blocksize(void *hdl, int bs) optional, is called with the block size, .Va bs , -that has been computed by the upper layer. It should return -a block size, possibly changed according to the needs of the +that has been computed by the upper layer. +It should return a block size, possibly changed according to the needs of the hardware driver. .It Dv int commit_settings(void *hdl) optional, is called after all calls to .Va set_params , and .Va set_port , -are done. A hardware driver that needs to get the hardware in +are done. +A hardware driver that needs to get the hardware in and out of command mode for each change can save all the changes during previous calls and do them all here. Return 0 on success, otherwise an error code. @@ -231,17 +237,17 @@ Return 0 on success, otherwise an error code. optional, is called before any output starts, but when the total .Va size of the output -.Va buffer -has been determined. It can be used to initialize looping DMA -for hardware that needs that. +.Va buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs it. Return 0 on success, otherwise an error code. .It Dv int init_input(void *hdl, void *buffer, int size) optional, is called before any input starts, but when the total .Va size of the input -.Va buffer -has been determined. It can be used to initialize looping DMA -for hardware that needs that. +.Va buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs it. Return 0 on success, otherwise an error code. .It Dv int start_output(void *hdl, void *block, int bsize, .Dv "void (*intr)(void*), void *intrarg)" @@ -250,9 +256,10 @@ is called to start the transfer of .Va bsize bytes from .Va block -to the audio hardware. The call should return when the data -transfer has been initiated (normally with DMA). When the -hardware is ready to accept more samples the function +to the audio hardware. +The call should return when the data +transfer has been initiated (normally with DMA). +When the hardware is ready to accept more samples the function .Va intr should be called with the argument .Va intrarg . @@ -268,9 +275,10 @@ is called to start the transfer of .Va bsize bytes to .Va block -from the audio hardware. The call should return when the data -transfer has been initiated (normally with DMA). When the -hardware is ready to deliver more samples the function +from the audio hardware. +The call should return when the data +transfer has been initiated (normally with DMA). +When the hardware is ready to deliver more samples the function .Va intr should be called with the argument .Va intrarg . @@ -291,11 +299,11 @@ in progress. Return 0 on success, otherwise an error code. .It Dv int speaker_ctl(void *hdl, int on) optional, is called when a half duplex device changes between -playing and recording. It can, e.g., be used to turn on -and off the speaker. +playing and recording. +It can, e.g., be used to turn the speaker on and off. Return 0 on success, otherwise an error code. .It Dv int getdev(void *hdl, struct audio_device *ret) -Should fill the +Should fill the .Va audio_device struct with relevant information about the driver. Return 0 on success, otherwise an error code. @@ -307,27 +315,31 @@ Return 0 on success, otherwise an error code. .It Dv int set_port(void *hdl, mixer_ctl_t *mc) is called in when .Dv AUDIO_MIXER_WRITE -is used. It should take data from the +is used. +It should take data from the .Va mixer_ctl_t struct at set the corresponding mixer values. Return 0 on success, otherwise an error code. .It Dv int get_port(void *hdl, mixer_ctl_t *mc) is called in when .Dv AUDIO_MIXER_READ -is used. It should fill the +is used. +It should fill the .Va mixer_ctl_t struct. Return 0 on success, otherwise an error code. .It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) is called in when .Dv AUDIO_MIXER_DEVINFO -is used. It should fill the +is used. +It should fill the .Va mixer_devinfo_t struct. Return 0 on success, otherwise an error code. .It Dv "void *allocm(void *hdl, int direction, size_t size, int type, int flags)" .br -optional, is called to allocate the device buffers. If not present +optional, is called to allocate the device buffers. +If not present .Xr malloc 9 is used instead (with the same arguments but the first two). The reason for using a device dependent routine instead of @@ -342,8 +354,8 @@ If not supplied is used. .It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) optional, is called at startup to determine the audio -buffer size. The upper layer supplies the suggested -size in +buffer size. +The upper layer supplies the suggested size in .Va bufsize , which the hardware driver can then change if needed. E.g., DMA on the ISA bus cannot exceed 65536 bytes. @@ -360,7 +372,7 @@ mapped with protection Returns -1 on failure, or a machine dependent opaque value on success. .It Dv int get_props(void *hdl) -Should return the device properties; i.e. a combination of +Should return the device properties; i.e., a combination of AUDIO_PROP_xxx. .It Dv int trigger_output(void *hdl, void *start, void *end, .Dv "int blksize, void (*intr)(void*), void *intrarg," @@ -375,8 +387,8 @@ and to the audio hardware, parameterized as in .Va param . The call should return when the data transfer has been initiated -(normally with DMA). When the hardware is finished transferring -each +(normally with DMA). +When the hardware is finished transferring each .Va bsize sized block, the function .Va intr @@ -399,8 +411,8 @@ to the circular buffer delimited by and .Va end . The call should return when the data transfer has been initiated -(normally with DMA). When the hardware is finished transferring -each +(normally with DMA). +When the hardware is finished transferring each .Va bsize sized block, the function .Va intr @@ -434,7 +446,7 @@ a control in the class of type .Dv AUDIO_MIXER_VALUE if recording level of the source can be set. -If the overall recording level can be changed (i.e. regardless +If the overall recording level can be changed (i.e., regardless of the input source) then this control should be named .Dv AudioNrecord and be of class @@ -456,7 +468,7 @@ a control in the class of type .Dv AUDIO_MIXER_VALUE if output level of the destination can be set. -If the overall output level can be changed (i.e. regardless +If the overall output level can be changed (i.e., regardless of the destination) then this control should be named .Dv AudioNmaster and be of class diff --git a/share/man/man9/boot.9 b/share/man/man9/boot.9 index 0e3fd3f8190..f29a9ad144f 100644 --- a/share/man/man9/boot.9 +++ b/share/man/man9/boot.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: boot.9,v 1.4 1999/09/02 17:28:06 espie Exp $ +.\" $OpenBSD: boot.9,v 1.5 2000/10/12 18:05:58 aaron Exp $ .\" $NetBSD: boot.9,v 1.1 1995/11/25 21:24:48 perry Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou @@ -44,8 +44,8 @@ The .Fn boot function handles final system shutdown, and either halts or reboots -the system. The exact action to be taken is determined by the -flags passed in +the system. +The exact action to be taken is determined by the flags passed in .Fa howto and by whether or not the system has finished autoconfiguration. .Pp @@ -73,7 +73,7 @@ and sets the time of day clock by calling .It Disables interrupts. .It -If rebooting after a crash (i.e. if +If rebooting after a crash (i.e., if .Dv RB_DUMP is set in .Fa howto , diff --git a/share/man/man9/copy.9 b/share/man/man9/copy.9 index e777fb8dd7a..3e0c6b2255f 100644 --- a/share/man/man9/copy.9 +++ b/share/man/man9/copy.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: copy.9,v 1.5 1999/09/02 17:28:06 espie Exp $ +.\" $OpenBSD: copy.9,v 1.6 2000/10/12 18:05:58 aaron Exp $ .\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ .\" .\" Copyright (c) 1996 Jason R. Thorpe. @@ -55,8 +55,8 @@ .Sh DESCRIPTION The .Nm -functions are designed to copy contiguous data from one address -to another. All but +functions are designed to copy contiguous data from one address to another. +All but .Fn copystr copy data from user-space to kernel-space or vice-versa. .Pp diff --git a/share/man/man9/ctxsw.9 b/share/man/man9/ctxsw.9 index f281c8bfed8..5f1e1186b89 100644 --- a/share/man/man9/ctxsw.9 +++ b/share/man/man9/ctxsw.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ctxsw.9,v 1.5 2000/04/26 21:27:59 mickey Exp $ +.\" $OpenBSD: ctxsw.9,v 1.6 2000/10/12 18:05:58 aaron Exp $ .\" $NetBSD: ctxsw.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -68,7 +68,7 @@ voluntarily relinquishes the CPU to wait for some resource to become available. .It After handling a trap -.Pq e.g. a system call or device interrupt +.Pq e.g., a system call or device interrupt when the kernel prepares a return to user-mode execution. This case is typically handled by machine-dependent trap-handling code after detection of a change in the signal disposition of the current process, or @@ -115,7 +115,7 @@ a process quickly. .Fn cpu_switch must remove the first process from the list on the queue with the highest priority -(lower indices in +(lower indices in .Va qs indicate higher priority), and assign the address of its process structure to the global variable diff --git a/share/man/man9/disk.9 b/share/man/man9/disk.9 index 251053e8cf8..a1753d69071 100644 --- a/share/man/man9/disk.9 +++ b/share/man/man9/disk.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: disk.9,v 1.12 2000/04/26 20:29:06 mickey Exp $ +.\" $OpenBSD: disk.9,v 1.13 2000/10/12 18:05:58 aaron Exp $ .\" $NetBSD: disk.9,v 1.2 1996/04/08 20:41:25 jtc Exp $ .\" .\" Copyright (c) 1995, 1996 Jason R. Thorpe. @@ -56,12 +56,12 @@ .Ft struct disk * .Fn disk_find "char *" .Sh DESCRIPTION -The +The .Ox generic disk framework is designed to provide flexible, scalable, and consistent handling of disk state and metrics information. The fundamental component of this framework is the -.Nm +.Nm structure, which is defined as follows: .Bd -literal struct disk { @@ -100,10 +100,12 @@ struct disk { .Ed .Pp The system maintains a global linked-list of all disks attached to the -system. This list, called +system. +This list, called .Nm disklist , may grow or shrink over time as disks are dynamically added and removed -from the system. Drivers which currently make use of the detachment +from the system. +Drivers which currently make use of the detachment capability of the framework are the .Nm ccd and @@ -124,19 +126,20 @@ timestamp, insert the disk into the disklist, and intrement the system disk count. .It Fn disk_detach Detatch a disk; free storage for the disklabel, remove the disk -from the disklist, and decrement the system disk count. If the count -drops below zero, panic. +from the disklist, and decrement the system disk count. +If the count drops below zero, panic. .It Fn disk_busy Increment the disk's .Dq busy counter . If this counter goes from 0 to 1, set the timestamp corresponding to this transfer. .It Fn disk_unbusy -Decrement a disk's busy counter. If the count drops below zero, print -a warning message. +Decrement a disk's busy counter. +If the count drops below zero, print a warning message. Get the current time, subtract it from the disk's timestamp, and add -the difference to the disk's running total. Set the disk's timestamp -to the current time. If the provided byte count is greater than 0, +the difference to the disk's running total. +Set the disk's timestamp to the current time. +If the provided byte count is greater than 0, add it to the disk's running total and increment the number of transfers performed by the disk. .It Fn disk_resetstat @@ -158,21 +161,24 @@ The function is provided as a utility function. .Sh USING THE FRAMEWORK This section includes a description on basic use of the framework -and example usage of its functions. Actual implementation of +and example usage of its functions. +Actual implementation of a device driver which utilizes the framework may vary. .Pp A special routine, .Fn disk_init , is provided to perform basic initialization of data structures used by -the framework. It is called exactly once by the system, in +the framework. +It is called exactly once by the system, in .Fn main , before device autoconfiguration. .Pp Each device in the system uses a .Dq softc structure which contains autoconfiguration and state information for that -device. In the case of disks, the softc should also contain one instance -of the disk stucture, eg: +device. +In the case of disks, the softc should also contain one instance +of the disk stucture, e.g.: .Bd -literal struct foo_softc { struct device *sc_dev; /* generic device information */ @@ -182,17 +188,21 @@ struct foo_softc { .Ed .Pp In order for the system to gather metrics data about a disk, the disk must -be registered with the system. The +be registered with the system. +The .Fn disk_attach routine performs all of the functions currently required to register a disk with the system including allocation of disklabel storage space, recording of the time since boot that the disk was attached, and insertion -into the disklist. Note that since this function allocates storage space +into the disklist. +Note that since this function allocates storage space for the disklabel, it must be called before the disklabel is read from the -media or used in any other way. Before +media or used in any other way. +Before .Fn disk_attach is called, a portions of the disk structure must be initialized with -data specific to that disk. For example, in the +data specific to that disk. +For example, in the .Dq foo disk driver, the following would be performed in the autoconfiguration .Dq attach @@ -220,25 +230,28 @@ The .Nm foodkdriver above is the disk's .Dq driver -switch. This switch currently includes a pointer to the disk's +switch. +This switch currently includes a pointer to the disk's .Dq strategy -routine. This switch needs to have global scope and sould be initialized -as follows: +routine. +This switch needs to have global scope and sould be initialized as follows: .Bd -literal void foostrategy __P((struct buf *)); struct dkdriver foodkdriver = { foostrategy }; .Ed .Pp -Once the disk is attached, metrics may be gathered on that disk. In order -to gather metrics data, the driver must tell the framework when the disk -starts and stops operations. This functionality is provided by the +Once the disk is attached, metrics may be gathered on that disk. +In order to gather metrics data, the driver must tell the framework +when the disk starts and stops operations. +This functionality is provided by the .Fn disk_busy and .Fn disk_unbusy -routines. The +routines. +The .Fn disk_busy routine should be called immediately before a command to the disk is -sent, eg: +sent, e.g.: .Bd -literal void foostart(sc) @@ -270,15 +283,18 @@ must be called at .Fn splbio . At the end of a transaction, the .Fn disk_unbusy -routine should be called. This routine performs some consistency checks, +routine should be called. +This routine performs some consistency checks, such as ensuring that the calls to .Fn disk_busy and .Fn disk_unbusy -are balanced. This routine also performs the actual metrics calculation. +are balanced. +This routine also performs the actual metrics calculation. A timestamp is taken, and the difference from the timestamp taken in .Fn disk_busy -is added to the disk's total running time. The disk's timestamp is then +is added to the disk's total running time. +The disk's timestamp is then updated in case there is more than one pending transfer on the disk. A byte count is also added to the disk's running total, and if greater than zero, the number of transfers the disk has performed is incremented. @@ -318,7 +334,8 @@ must be called at .Fn splbio . .Pp At some point a driver may wish to reset the metrics data gathered on a -particular disk. For this function, the +particular disk. +For this function, the .Fn disk_resetstat routine is provided. .Sh CODE REFERENCES @@ -327,10 +344,10 @@ The disk framework itself is implemented within the file Data structures and function prototypes for the framework are located in .Pa sys/sys/disk.h . .Pp -The +The .Ox -machine-independent SCSI disk and CD-ROM drivers utilize the -disk framework. They are located in +machine-independent SCSI disk and CD-ROM drivers utilize the disk framework. +They are located in .Pa sys/scsi/sd.c and .Pa sys/scsi/cd.c . @@ -348,9 +365,9 @@ They are located in and .Pa sys/dev/vnd.c . .Sh AUTHOR -The +The .Ox -generic disk framework was architected and implemented within +generic disk framework was architected and implemented within .Nx by Jason R. Thorpe <thorpej@NetBSD.ORG>. .Sh SEE ALSO @@ -359,7 +376,7 @@ by Jason R. Thorpe <thorpej@NetBSD.ORG>. .Xr vnd 4 , .Xr spl 9 . .Sh HISTORY -The +The .Ox -generic disk framework first appeared in +generic disk framework first appeared in .Nx 1.2 . diff --git a/share/man/man9/disklabel.9 b/share/man/man9/disklabel.9 index 8144ab6aa6f..d09dc85f0cc 100644 --- a/share/man/man9/disklabel.9 +++ b/share/man/man9/disklabel.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: disklabel.9,v 1.4 2000/04/26 21:28:00 mickey Exp $ +.\" $OpenBSD: disklabel.9,v 1.5 2000/10/12 18:05:58 aaron Exp $ .\" $NetBSD: disklabel.9,v 1.7 1999/03/06 22:09:29 mycroft Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS diff --git a/share/man/man9/extent.9 b/share/man/man9/extent.9 index 997a2c19bf1..aad63789d55 100644 --- a/share/man/man9/extent.9 +++ b/share/man/man9/extent.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: extent.9,v 1.3 1999/09/22 09:54:38 espie Exp $ +.\" $OpenBSD: extent.9,v 1.4 2000/10/12 18:05:59 aaron Exp $ .\" $NetBSD: extent.9,v 1.15 1999/03/16 00:40:47 garbled Exp $ .\" .\" Copyright (c) 1996, 1998 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -66,8 +66,8 @@ .Fn extent_print "struct extent *ex" .Sh DESCRIPTION The extent manager provides management of areas of memory or -other enumerable spaces (such as I/O ports). An opaque structure -called an +other enumerable spaces (such as I/O ports). +An opaque structure called an .Nm extent map keeps track of allocated regions within the enumerable space. .Pp @@ -76,7 +76,8 @@ creates an extent map managing the space from .Fa start to .Fa end -inclusive. All memory allocation will use the memory type +inclusive. +All memory allocation will use the memory type .Fa mtype .Po see @@ -84,12 +85,12 @@ see .Pc . The extent map will have the name .Fa name , -used for identification in case of errors or in -.Xr ddb 4 +used for identification in case of errors or in +.Xr ddb 4 .Ic show extents . If the flag .Dv EX_NOCOALESCE -is set, internal coalescing of regions is disabled, +is set, internal coalescing of regions is disabled, and only entire regions may be freed within the extent map, so that .Fn extent_free will never have to allocate a region descriptor. @@ -125,23 +126,25 @@ The caller should pass the flag .Dv EX_WAITOK or .Dv EX_NOWAIT -to extent functions that have a memory overhead, to specify whether -it is okay to wait. These functions are +to extent functions that have a memory overhead, to specify whether +it is okay to wait. +These functions are .Fn extent_create (non fixed extents), .Fn extent_free (unless -.Dv EX_NOCOALESCE +.Dv EX_NOCOALESCE is set), .Fn extent_alloc , -.Fn extent_alloc_subregion -and +.Fn extent_alloc_subregion +and .Fn extent_alloc_region . .Pp .Fn extent_destroy destroys the extent map .Fa ex , -freeing all allocated regions. If the extent is not a fixed extent, +freeing all allocated regions. +If the extent is not a fixed extent, the region and internal extent descriptors themselves are freed. This function always succeeds. .Pp @@ -150,8 +153,8 @@ allocates a region in the extent map .Fa ex of size .Fa size -that fits the provided parameters. There are two distinct allocation -policies, which are selected by the +that fits the provided parameters. +There are two distinct allocation policies, which are selected by the .Fa flags argument: .Bl -tag -offset indent -width "XXXXXXXXX" @@ -163,7 +166,7 @@ Allocate the smallest region that is capable of holding the request, thus minimizing fragmentation of the extent. .El .Pp -The caller may specify that it is okay to wait for space to become free in the +The caller may specify that it is okay to wait for space to become free in the extent by setting the flag .Dv EX_WAITSPACE . If @@ -173,36 +176,40 @@ satisfied without sleeping. .Pp The request will be aligned to a multiple of .Fa alignment . -That value must be a power of 2. If no alignment -is necessary, the value +That value must be a power of 2. +If no alignment is necessary, the value .Dv EX_NOALIGN -should be specified. If +should be specified. +If .Fa boundary is not -.Dv EX_NOBOUNDARY , +.Dv EX_NOBOUNDARY , the allocated region will not cross any boundary lines, spaced -.Fa boundary -apart. If the caller specifies the +.Fa boundary +apart. +If the caller specifies the .Dv EX_BOUNDZERO -flag, boundary lines begin at zero. Otherwise, boundary lines -begin at the beginning of the extent. The allocated region may begin on a -boundary line, but the end of the region will not touch nor cross a -boundary line. A +flag, boundary lines begin at zero. +Otherwise, boundary lines begin at the beginning of the extent. +The allocated region may begin on a +boundary line, but the end of the region will not touch nor cross a +boundary line. +A .Fa boundary -argument smaller than the size of the request is -invalid. Upon successful completion, +argument smaller than the size of the request is invalid. +Upon successful completion, .Fa *result will contain the start of the allocated region. .Pp .Fn extent_alloc_subregion is a generalized version of -.Fn extent_alloc +.Fn extent_alloc that also allows the caller to specify that the allocated region must fall within the subregion from .Fa substart to .Fa subend -inclusive. +inclusive. .Pp .Fn extent_alloc_region allocates the specific region in the extent map @@ -223,28 +230,29 @@ satisfied without sleeping. frees a region of .Fa size bytes starting at -.Fa start +.Fa start in the extent map .Fa ex . If the extent has the .Dv EX_NOCOALESCE -property, only entire regions may be freed. If the extent has the +property, only entire regions may be freed. +If the extent has the .Dv EX_NOCOALESCE property and the caller attempts to free a partial region, behavior is -undefined. +undefined. .Pp .Fn extent_print Prints out information about extent .Fa ex . -This function always succeeds. +This function always succeeds. .Sh RETURN VALUES The behavior of all extent manager functions is undefined if given invalid arguments. .Fn extent_create returns the extent map on success, or .Dv NULL -if it fails to allocate storage for the extent map. It always -succeeds when creating a fixed extent or when given the flag +if it fails to allocate storage for the extent map. +It always succeeds when creating a fixed extent or when given the flag .Dv EX_WAITOK . .Fn extent_alloc , .Fn extent_alloc_region , @@ -267,7 +275,7 @@ Requested region is not available and was not specified. .It Dv EINTR Process received a signal while waiting for the requested region to -become available in the extent. +become available in the extent. .El .Sh EXAMPLES Here is an example of a (useless) function that uses several of the @@ -301,7 +309,7 @@ func() /* * Give up the extent. */ - extent_destroy(foo_ex); + extent_destroy(foo_ex); } .Ed .\" @@ -311,21 +319,22 @@ func() .\" The flag .\" .Dv EX_CATCH .\" cannot be used to catch signals in all circumstances since -.\" .Xr malloc 9 +.\" .Xr malloc 9 .\" does not provide such a functionality. .Sh CODE REFERENCES The extent manager itself is implemented within the file .Pa sys/kern/subr_extent.c . .Pp The i386 bus management code uses the extent manager for managing I/O -ports and I/O memory. See +ports and I/O memory. +See .Pa sys/arch/i386/i386/machdep.c . .Sh AUTHOR The extent manager was designed and implemented by Jason -R. Thorpe <thorpej@NetBSD.ORG>. Matthias Drochner -<drochner@zelux6.zel.kfa-juelich.de> contributed to the initial -testing and optimization of the implementation. Chris Demetriou -<cgd@NetBSD.ORG> contributed many architectural suggestions. +R. Thorpe <thorpej@NetBSD.ORG>. +Matthias Drochner <drochner@zelux6.zel.kfa-juelich.de> contributed to the +initial testing and optimization of the implementation. +Chris Demetriou <cgd@NetBSD.ORG> contributed many architectural suggestions. .Sh SEE ALSO .Xr ddb 4 , .Xr malloc 9 diff --git a/share/man/man9/fork1.9 b/share/man/man9/fork1.9 index f860967e48b..6518d522699 100644 --- a/share/man/man9/fork1.9 +++ b/share/man/man9/fork1.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fork1.9,v 1.3 2000/02/07 04:38:38 art Exp $ +.\" $OpenBSD: fork1.9,v 1.4 2000/10/12 18:05:59 aaron Exp $ .\" $NetBSD: fork1.9,v 1.3 1999/03/16 00:40:47 garbled Exp $ .\" .\" Copyright (c) 1998 The NetBSD Foundation, Inc. @@ -46,18 +46,18 @@ .Fd #include <sys/types.h> .Fd #include <sys/proc.h> .Ft int -.Fn "fork1" "struct proc *p1" "int flags" "void *stack" "size_t stacksize" "register_t *retval" +.Fn "fork1" "struct proc *p1" "int flags" "void *stack" "size_t stacksize" "register_t *retval" .Sh DESCRIPTION .Fn fork1 creates a new process out of .Ar p1 , -which should be the current process. This function is used primarily -to implement the +which should be the current process. +This function is used primarily to implement the .Xr fork 2 , .Xr rfork 2 , .Xr vfork 2 system calls, as well as the -.Xr create_kthread 9 +.Xr create_kthread 9 function. .Pp The @@ -68,15 +68,18 @@ a bitwise-OR of the following values: .It Dv FORK_FORK The call is done by the .Xr fork 2 -system call. Used only for statistics. +system call. +Used only for statistics. .It Dv FORK_VFORK The call is done by the .Xr vfork 2 -system call. Used only for statistics. +system call. +Used only for statistics. .It Dv FORK_RFORK The call is done by the .Xr rfork 2 -system call. Used only for statistics. +system call. +Used only for statistics. .It Dv FORK_PPWAIT Suspend the parent process until the child is terminated (by calling .Xr _exit 2 @@ -92,17 +95,19 @@ The child starts with a clean file descriptor table created by .Xr fdinit 9 . .It Dv FORK_NOZOMBIE The child will be dissociated from the parent and will not leave a status -for the parent to collect. See +for the parent to collect. +See .Xr wait 2 . .It Dv FORK_SHAREVM -The child will share the parent's address space. The default behavior is +The child will share the parent's address space. +The default behavior is that the child gets a copy-on-write copy of the address space. .El .Pp If .Fa stack -is not -.Dv NULL , +is not +.Dv NULL , the area starting at .Fa stack of extent @@ -112,20 +117,21 @@ stack. .Pp If .Fa retval -is not -.Dv NULL , +is not +.Dv NULL , it will hold the following values after successful completion of the fork operation: .Bl -tag -width retval[0] .It Fa retval[0] This will contain the pid of the child process. .It Fa retval[1] -In the parent process, this will contain the value 0. In the child process, -this will contain 1. +In the parent process, this will contain the value 0. +In the child process, this will contain 1. .Sh RETURN VALUES Upon successful completion of the fork operation, .Fn fork1 -returns 0. Otherwise, the following error values are returned: +returns 0. +Otherwise, the following error values are returned: .Bl -tag -width [EAGAIN] .It Bq Er EAGAIN The limit on the total number of system processes would be exceeded. @@ -138,12 +144,12 @@ user id would be exceeded. .Sh CAVEATS The .Nm -function semantics are specific to +function semantics are specific to .Ox . Other BSD systems have different semantics. .Pp The system never uses -.Fn fork1 +.Fn fork1 with a non-null .Fa stack , so that feature is not even tested. diff --git a/share/man/man9/hz.9 b/share/man/man9/hz.9 index 8da7c556169..0bf15d706e4 100644 --- a/share/man/man9/hz.9 +++ b/share/man/man9/hz.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hz.9,v 1.2 1999/09/10 05:00:48 tholo Exp $ +.\" $OpenBSD: hz.9,v 1.3 2000/10/12 18:05:59 aaron Exp $ .\" .\" Copyright (c) 1999 Marc Espie .\" All rights reserved. @@ -37,7 +37,7 @@ .Nm tick , .Nm tickadj , .Nm stathz , -.Nm profhz +.Nm profhz .Nd system time model. .Sh SYNOPSIS .Va extern int hz; @@ -58,13 +58,13 @@ frequency, and are used to keep track of real time. .Pp On systems where another independent clock is available, it is set at .Va stathz -frequency, and used to gather timing statistics. Ideally, it would be -better to drive +frequency, and used to gather timing statistics. +Ideally, it would be better to drive .Va stathz with a slightly randomized clock, that is still a fixed number on average, -as this would prevent malicious processes from working around the -scheduler. If a separate clock is not available, -.Va stathz +as this would prevent malicious processes from working around the scheduler. +If a separate clock is not available, +.Va stathz is set to .Va hz . .Pp @@ -76,15 +76,15 @@ which must be a multiple of .Va stathz . This will give higher resolution profiling information. .Pp -Normally, +Normally, .Xr hardclock 9 increments .Va time -by +by .Va tick each time it is called. -If the system clock has drifted, -.Xr adjtime 2 +If the system clock has drifted, +.Xr adjtime 2 may be used to skew this increment, but by no more than ten times .Va tickadj . diff --git a/share/man/man9/hzto.9 b/share/man/man9/hzto.9 index 35bd4ea0792..a1e38294f24 100644 --- a/share/man/man9/hzto.9 +++ b/share/man/man9/hzto.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hzto.9,v 1.1 1999/09/01 20:52:12 espie Exp $ +.\" $OpenBSD: hzto.9,v 1.2 2000/10/12 18:05:59 aaron Exp $ .\" .\" Copyright (c) 1999 Marc Espie .\" All rights reserved. @@ -33,7 +33,7 @@ .Dt HZTO 9 .Os .Sh NAME -.Nm hzto +.Nm hzto .Nd translate absolute time to timeout delay. .Sh SYNOPSIS .Fd #include <sys/types.h> @@ -42,16 +42,16 @@ .Ft int .Fn hzto "struct timeval *tv" .Sh DESCRIPTION -The +The .Fn hzto -function computes the number of +function computes the number of .Va hz -until the specified time occurs. This is mainly used to translate a timeval -into a suitable argument for +until the specified time occurs. +This is mainly used to translate a timeval into a suitable argument for .Xr timeout 9 . .Sh CODE REFERENCES This function is implemented in the file .Pa sys/kern/kern_clock.c . .Sh SEE ALSO .Xr hz 9 , -.Xr timeout 9 +.Xr timeout 9 diff --git a/share/man/man9/inittodr.9 b/share/man/man9/inittodr.9 index 12b3c684bf5..66b8c44d146 100644 --- a/share/man/man9/inittodr.9 +++ b/share/man/man9/inittodr.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inittodr.9,v 1.6 1999/09/01 20:52:13 espie Exp $ +.\" $OpenBSD: inittodr.9,v 1.7 2000/10/12 18:06:00 aaron Exp $ .\" $NetBSD: inittodr.9,v 1.2 1996/03/27 21:16:06 jtc Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou @@ -73,8 +73,8 @@ variable. The .Fn inittodr function prints diagnostic messages if it has trouble figuring -out the system time. Conditions that can cause diagnostic -messages to be printed include: +out the system time. +Conditions that can cause diagnostic messages to be printed include: .Bl -bullet .It The battery-backed clock's time appears nonsensical. @@ -97,8 +97,8 @@ has to convert from a time expressed in terms of year, month, day, hours, minutes, and seconds to .Va time , -expressed in seconds. Many of the implementations could share code, -but do not. +expressed in seconds. +Many of the implementations could share code, but do not. .Pp Each system's heuristics for picking the correct time are slightly different. diff --git a/share/man/man9/intro.9 b/share/man/man9/intro.9 index 6b05d2c6a3b..a91bfcdb531 100644 --- a/share/man/man9/intro.9 +++ b/share/man/man9/intro.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: intro.9,v 1.4 1999/09/02 17:25:02 espie Exp $ +.\" $OpenBSD: intro.9,v 1.5 2000/10/12 18:06:00 aaron Exp $ .\" .\" Copyright (c) 1996 Michael Shalayeff .\" @@ -42,10 +42,11 @@ data structures, variables and functions. This section describes places within the .Ox source tree where actual code implementing or using kernel internals -can be found. All pathnames are relative to +can be found. +All pathnames are relative to .Pa /usr/src . .Sh HISTORY The -.Nm intro +.Nm section manual page appeared in .Ox 1.2 . diff --git a/share/man/man9/kthread.9 b/share/man/man9/kthread.9 index f1417140fa5..7a7ce18fa04 100644 --- a/share/man/man9/kthread.9 +++ b/share/man/man9/kthread.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: kthread.9,v 1.2 1999/09/05 16:23:11 espie Exp $ +.\" $OpenBSD: kthread.9,v 1.3 2000/10/12 18:06:00 aaron Exp $ .\" .\" Copyright (c) 1999 Marc Espie .\" All rights reserved. @@ -35,7 +35,7 @@ .Sh NAME .Nm kthread_create , .Nm kthread_exit , -.Nm kthread_create_deferred +.Nm kthread_create_deferred .Nd kernel threads. .Sh SYNOPSIS .Fd #include <sys/kthread.h> @@ -48,19 +48,20 @@ .Sh DESCRIPTION Kernel threads are system light-weight processes: cloned from process 0 (the swapper), sharing its memory map and limits, but with a copy of its -file descriptor table. They don't receive broadcast nor group signals and -they can't be swapped. +file descriptor table. +They don't receive broadcast nor group signals and they can't be swapped. .Pp Any process can call .Fn kthread_create -to create a kernel thread. The new process starts up executing +to create a kernel thread. +The new process starts up executing .Fa func with argument .Fa arg . -If -.Fa newpp -is not -.Dv NULL , +If +.Fa newpp +is not +.Dv NULL , it is filled with the address of the new process. .Fa fmt and the remaining arguments are used to name the process. @@ -72,21 +73,22 @@ with exit code .Pp Since the system has to be up and running for creating new processes, device drivers that want to create kernel threads early -(eg, at attach time) may use -.Fn kthread_create_deferred -instead. The system will call back the function +(e.g., at attach time) may use +.Fn kthread_create_deferred +instead. +The system will call back the function .Fa func with argument .Fa arg when it can create threads, so it is up to .Fa func to call -.Fn kthread_create +.Fn kthread_create at that point. .Sh SEE ALSO .Xr fork1 9 .Sh BUGS -There is currently no way to use +There is currently no way to use .Va ecode to any sensible purpose from .Fn kthread_exit . diff --git a/share/man/man9/log.9 b/share/man/man9/log.9 index ab481ce5a12..4b702ff396e 100644 --- a/share/man/man9/log.9 +++ b/share/man/man9/log.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: log.9,v 1.4 2000/04/26 21:28:00 mickey Exp $ +.\" $OpenBSD: log.9,v 1.5 2000/10/12 18:06:00 aaron Exp $ .\" $NetBSD: log.9,v 1.6 1999/08/17 05:24:06 enami Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -57,7 +57,7 @@ device .Sh DESCRIPTION The .Fn log -function allows the kernel to send formatted messages to user processes +function allows the kernel to send formatted messages to user processes listening on .Pa /dev/klog . Usually @@ -73,7 +73,7 @@ logged using facility and priority level .Fa level . .Pp -The +The .Fn addlog function is used to build a log message in steps, by adding information to an initial call to diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9 index b3b117bf94b..3cff0404152 100644 --- a/share/man/man9/malloc.9 +++ b/share/man/man9/malloc.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: malloc.9,v 1.12 2000/06/25 13:46:06 pjanzen Exp $ +.\" $OpenBSD: malloc.9,v 1.13 2000/10/12 18:06:00 aaron Exp $ .\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. @@ -78,7 +78,8 @@ free((caddr_t)(addr), type) .Pp Unlike its standard C library counterpart .Pq Xr malloc 3 , -the kernel version takes two more arguments. The +the kernel version takes two more arguments. +The .Fa flags argument further qualifies .Fn malloc No Ns 's diff --git a/share/man/man9/md5.9 b/share/man/man9/md5.9 index 8a99c43a91a..3017703509d 100644 --- a/share/man/man9/md5.9 +++ b/share/man/man9/md5.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: md5.9,v 1.3 1999/05/23 14:11:40 aaron Exp $ +.\" $OpenBSD: md5.9,v 1.4 2000/10/12 18:06:01 aaron Exp $ .\" .\" Copyright (c) 1996 Michael Shalayeff .\" All rights reserved. @@ -44,13 +44,15 @@ The .Nm module implements the RSA Data Security, Inc. MD5 Message-Digest Algorithm -(MD5). It produces 128-bit MD5 Digest of data. +(MD5). +It produces 128-bit MD5 Digest of data. .Pp .Bl -hang -width MD5Transform .It Pa MD5Init must be called just before .Fn MD5Transform -will be used to produce a digest. the +will be used to produce a digest. +The .Fa buf argument is the storage for the digest being produced on subsequent calls to the @@ -66,11 +68,9 @@ of new data passed in argument. .Sh COPYRIGHTS The code for MD5 transform was taken from Colin Plumb's -implementation, which has been placed in the public domain. The -MD5 cryptographic checksum was devised by Ronald Rivest, and is +implementation, which has been placed in the public domain. +The MD5 cryptographic checksum was devised by Ronald Rivest, and is documented in RFC 1321, "The MD5 Message Digest Algorithm". .Sh SEE ALSO -.Xr random 4 -, +.Xr random 4 , .Xr random 9 - diff --git a/share/man/man9/microtime.9 b/share/man/man9/microtime.9 index b0bdeb0e0f0..973c8ce94fb 100644 --- a/share/man/man9/microtime.9 +++ b/share/man/man9/microtime.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: microtime.9,v 1.2 1999/09/02 17:28:06 espie Exp $ +.\" $OpenBSD: microtime.9,v 1.3 2000/10/12 18:06:01 aaron Exp $ .\" $NetBSD: microtime.9,v 1.2 1999/03/16 00:40:47 garbled Exp $ .\" .\" Copyright (c) 1998 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS diff --git a/share/man/man9/panic.9 b/share/man/man9/panic.9 index b996a38792e..307527b3198 100644 --- a/share/man/man9/panic.9 +++ b/share/man/man9/panic.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: panic.9,v 1.4 1999/09/05 16:23:11 espie Exp $ +.\" $OpenBSD: panic.9,v 1.5 2000/10/12 18:06:01 aaron Exp $ .\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ .\" .\" Copyright (c) 1996 Michael Graff. @@ -44,11 +44,15 @@ .Sh DESCRIPTION The .Fn panic -function makes the OpenBSD system terminate. The message +function makes the +.Ox +system terminate. +The message .Fa fmt is a .Xr printf 9 -style format string. The message is printed to the console and the location +style format string. +The message is printed to the console and the location pointed to by the global char pointer .Fa panicstr is set to the address of the message text for retrieval from the OS diff --git a/share/man/man9/pfind.9 b/share/man/man9/pfind.9 index 97ac808289a..ad672a9ca82 100644 --- a/share/man/man9/pfind.9 +++ b/share/man/man9/pfind.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pfind.9,v 1.1 1999/09/02 17:24:35 espie Exp $ +.\" $OpenBSD: pfind.9,v 1.2 2000/10/12 18:06:01 aaron Exp $ .\" .\" Copyright (c) 1999 Marc Espie .\" All rights reserved. @@ -44,11 +44,11 @@ .Ft "struct pgrp *" .Fn pgfind "pid_t pgid" .Sh DESCRIPTION -The +The .Fn pfind -and +and .Fn pgfind -functions retrieve process and progress group structures from process and +functions retrieve process and progress group structures from process and process group ids. .Pp Both functions return NULL if the requested id can't be found. diff --git a/share/man/man9/pool.9 b/share/man/man9/pool.9 index edd2fca4a3c..bce6b7e8e8b 100644 --- a/share/man/man9/pool.9 +++ b/share/man/man9/pool.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pool.9,v 1.3 2000/04/26 21:21:38 mickey Exp $ +.\" $OpenBSD: pool.9,v 1.4 2000/10/12 18:06:01 aaron Exp $ .\" $NetBSD: pool.9,v 1.13 1999/04/03 14:50:21 msaitoh Exp $ .\" .\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -175,7 +175,7 @@ the client is responsible for providing enough storage to accommodate the number of pool items specified by .Fa nitems , as well as the space required by the pool's administrative overhead -.Pq i.e. the pool handle . +.Pq i.e., the pool handle . .\"The macro .\".Fn POOL_STORAGE_SIZE "size" "nitems" .\"can be used to determine the amount of storage needed to setup a pool, @@ -214,12 +214,12 @@ the system will panic .\"storage. .\" a bunch of other flags aren't documented. If both -.Dv PR_LIMITFAIL +.Dv PR_LIMITFAIL and .Dv PR_WAITOK -is specified, and the pool has reached its hard limit, -.Fn pool_get -will return +is specified, and the pool has reached its hard limit, +.Fn pool_get +will return .Dv NULL without waiting, allowing the caller to do its own garbage collection; however, it will still wait if the pool is not yet at its hard limit. diff --git a/share/man/man9/powerhook_establish.9 b/share/man/man9/powerhook_establish.9 index fc85e196c4d..4a80eac2e0f 100644 --- a/share/man/man9/powerhook_establish.9 +++ b/share/man/man9/powerhook_establish.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: powerhook_establish.9,v 1.1 2000/07/01 14:45:45 aaron Exp $ +.\" $OpenBSD: powerhook_establish.9,v 1.2 2000/10/12 18:06:02 aaron Exp $ .\" .\" Copyright (c) 2000 Aaron Campbell .\" All rights reserved. @@ -77,7 +77,7 @@ If successful, .Fn powerhook_establish returns an opaque pointer describing the newly established power hook. -Otherwise, it returns +Otherwise, it returns .Dv NULL . .Sh EXAMPLES It may be appropriate to use a power hook to disestablish interrupts and diff --git a/share/man/man9/printf.9 b/share/man/man9/printf.9 index 3829a3d3fa6..ccaf82372e6 100644 --- a/share/man/man9/printf.9 +++ b/share/man/man9/printf.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: printf.9,v 1.4 2000/04/26 21:28:00 mickey Exp $ +.\" $OpenBSD: printf.9,v 1.5 2000/10/12 18:06:02 aaron Exp $ .\" $NetBSD: kprintf.9,v 1.6 1999/03/16 00:40:47 garbled Exp $ .\" .\" Copyright (c) 1998 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -39,11 +39,11 @@ .Dt PRINTF 9 .Os .Sh NAME -.Nm printf , -.Nm sprintf , -.Nm vprintf, -.Nm uprintf, -.Nm ttyprintf, +.Nm printf , +.Nm sprintf , +.Nm vprintf , +.Nm uprintf , +.Nm ttyprintf , .Nm db_printf .Nd kernel formatted output conversion .Sh SYNOPSIS @@ -85,7 +85,7 @@ The .Fn vprintf , .Fn uprintf , .Fn ttyprintf , -and +and .Fn db_printf functions allow the kernel to send formatted messages to various output devices. @@ -107,14 +107,15 @@ sends formatted strings to the ddb console, and is only used to implement .Xr ddb 4 . .Pp Since each of these kernel functions is a variant of its user space -counterpart, -this page describes only the differences between the user space and kernel -versions. Refer to +counterpart, this page describes only the differences between the user +space and kernel versions. +Refer to .Xr printf 3 for functional details. .Ss FORMAT OPTIONS The kernel functions don't support any floating point formatting -specifiers. In addition to other formatting specifiers common with the user +specifiers. +In addition to other formatting specifiers common with the user space functions, the kernel functions accept the following format specifiers in the format string .Fa format : @@ -127,7 +128,7 @@ It displays an integer using a specified radix .Pq base and an interpretation of the bits within that integer as though they were flags. -It requires two arguments from the argument vector, the first argument being +It requires two arguments from the argument vector, the first argument being the bit field to be decoded .Pq "as an integer" and the second being a decoding directive string. @@ -173,7 +174,7 @@ argument vector from which to obtain the data to be formatted. Displays an integer using the current .Tn DDB radix. -This non-standard interpretation of +This non-standard interpretation of .Li %r is only available to .Fn db_printf . diff --git a/share/man/man9/random.9 b/share/man/man9/random.9 index f11380377a0..2cd669cdc35 100644 --- a/share/man/man9/random.9 +++ b/share/man/man9/random.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: random.9,v 1.8 2000/04/26 19:15:13 mickey Exp $ +.\" $OpenBSD: random.9,v 1.9 2000/10/12 18:06:02 aaron Exp $ .\" .\" Copyright (c) 1996,2000 Michael Shalayeff .\" All rights reserved. @@ -36,25 +36,25 @@ .Nd device kernel interface .Sh SYNOPSIS .Fd #include <dev/rndvar.h> -.Ft void +.Ft void .Fn add_true_randomness "int" -.Ft void +.Ft void .Fn add_timer_randomness "int" -.Ft void +.Ft void .Fn add_mouse_randomness "int" .Ft void .Fn add_tty_randomness "int" -.Ft void +.Ft void .Fn add_net_randomness "int" -.Ft void +.Ft void .Fn add_disk_randomness "int" -.Ft void +.Ft void .Fn add_audio_randomness "int" .Ft void .Fn get_random_bytes "void *buf" "size_t nbytes" -.Ft u_int8_t +.Ft u_int8_t .Fn arc4random_8 "void" -.Ft u_int32_t +.Ft u_int32_t .Fn arc4random "void" .br .Sh DESCRIPTION diff --git a/share/man/man9/ratecheck.9 b/share/man/man9/ratecheck.9 index bd7bf097ae6..64a62c72007 100644 --- a/share/man/man9/ratecheck.9 +++ b/share/man/man9/ratecheck.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ratecheck.9,v 1.2 2000/03/28 13:08:45 jakob Exp $ +.\" $OpenBSD: ratecheck.9,v 1.3 2000/10/12 18:06:02 aaron Exp $ .\" $NetBSD: ratecheck.9,v 1.1.2.1 2000/02/18 20:26:43 he Exp $ .\" .\" Copyright (c) 2000 The NetBSD Foundation, Inc. @@ -26,7 +26,7 @@ .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -57,22 +57,25 @@ and .Fa lasttime is less than the value given by the .Fa mininterval -argument, zero is returned. Otherwise, +argument, zero is returned. +Otherwise, .Fa lasttime is set to the current time and a non-zero value is returned. .Pp The motivation for implementing .Fn ratecheck was to provide a mechanism that could be used to add rate limiting to -diagnostic message output. If printed too often, diagnostic messages can -keep the system from doing useful work. If the repeated messages can -be caused by deliberate user action or network events, they can be -exploited to cause denial of system service. +diagnostic message output. +If printed too often, diagnostic messages can +keep the system from doing useful work. +If the repeated messages can be caused by deliberate user action or +network events, they can be exploited to cause denial of system service. .Pp Note that using a very short time interval (less than a second) for .Fa mininterval -defeats the purpose of this function. (It doesn't +defeats the purpose of this function. +(It doesn't take much to flood a 9600 baud serial console with output, for instance.) .Sh EXAMPLES Here is a simple example of use of the diff --git a/share/man/man9/resettodr.9 b/share/man/man9/resettodr.9 index ed8cb8ebbfc..353f8ffab59 100644 --- a/share/man/man9/resettodr.9 +++ b/share/man/man9/resettodr.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: resettodr.9,v 1.4 1999/09/02 17:28:06 espie Exp $ +.\" $OpenBSD: resettodr.9,v 1.5 2000/10/12 18:06:02 aaron Exp $ .\" $NetBSD: resettodr.9,v 1.1 1995/11/25 21:24:51 perry Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou @@ -55,4 +55,5 @@ On many systems, has to convert from .Va time to a time expressed in terms of year, month, day, hours, minutes, -and seconds. Many of the implementations could share code, but do not. +and seconds. +Many of the implementations could share code, but do not. diff --git a/share/man/man9/shutdownhook_establish.9 b/share/man/man9/shutdownhook_establish.9 index 9c8c2f69983..321d8edf526 100644 --- a/share/man/man9/shutdownhook_establish.9 +++ b/share/man/man9/shutdownhook_establish.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: shutdownhook_establish.9,v 1.8 2000/07/01 14:48:24 aaron Exp $ +.\" $OpenBSD: shutdownhook_establish.9,v 1.9 2000/10/12 18:06:02 aaron Exp $ .\" $NetBSD: shutdownhook_establish.9,v 1.1 1995/11/25 21:24:52 perry Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou @@ -49,7 +49,8 @@ function adds .Fa fn to the list of hooks invoked by .Xr doshutdownhooks 9 -at shutdown. When invoked, the hook function +at shutdown. +When invoked, the hook function .Fa fn will be passed .Fa arg @@ -59,15 +60,16 @@ The .Fn shutdownhook_disestablish function removes the hook described by the opaque pointer .Fa cookie -from the list of hooks to be invoked at shutdown. If +from the list of hooks to be invoked at shutdown. +If .Fa cookie is invalid, the result of .Fn shutdownhook_disestablish is undefined. .Pp Shutdown hooks should be used to perform one-time activities -that must happen immediately before the kernel exits. Because -of the environment in which they are run, shutdown hooks cannot +that must happen immediately before the kernel exits. +Because of the environment in which they are run, shutdown hooks cannot rely on many system services (including file systems, timeouts, and other interrupt-driven services) or even basic system integrity (because the system could be rebooting after a crash). @@ -75,7 +77,8 @@ integrity (because the system could be rebooting after a crash). If successful, .Fn shutdownhook_establish returns an opaque pointer describing the newly established -shutdown hook. Otherwise, it returns +shutdown hook. +Otherwise, it returns .Dv NULL . .Sh EXAMPLES It may be appropriate to use a shutdown hook to diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 index c4b054ecae5..fbe9bc95951 100644 --- a/share/man/man9/sleep.9 +++ b/share/man/man9/sleep.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sleep.9,v 1.3 1999/09/05 16:23:11 espie Exp $ +.\" $OpenBSD: sleep.9,v 1.4 2000/10/12 18:06:03 aaron Exp $ .\" $NetBSD: sleep.9,v 1.11 1999/03/24 06:15:12 mycroft Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. @@ -64,7 +64,7 @@ can not continue for any of the following reasons: The current process needs to await the results of a pending I/O operation. .It The current process needs resources -.Pq e.g. memory +.Pq e.g., memory which are temporarily unavailable. .It The current process wants access to data structures which are locked by diff --git a/share/man/man9/spl.9 b/share/man/man9/spl.9 index 798c96fd075..bdd8ad28394 100644 --- a/share/man/man9/spl.9 +++ b/share/man/man9/spl.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: spl.9,v 1.4 2000/07/07 09:08:25 ho Exp $ +.\" $OpenBSD: spl.9,v 1.5 2000/10/12 18:06:03 aaron Exp $ .\" $NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $ .\" .\" Copyright (c) 1997 Michael Long. @@ -78,9 +78,11 @@ at a higher priority level. A .Nm function exists for each distinct priority level which can exist in -the system. These macros and the corresponding priority levels are +the system. +These macros and the corresponding priority levels are used for various defined purposes, and may be divided into two main -types: hard and soft. Hard interrupts are generated by hardware +types: hard and soft. +Hard interrupts are generated by hardware devices, while soft interrupts are generated by callouts and called from the kernel's periodic timer interrupt service routine. .Pp @@ -88,29 +90,31 @@ In order of highest to lowest priority, the priority-raising macros are: .Bl -tag -width splsoftclockXX .It Fn splhigh -blocks all hard and soft interrupts. It is used for code that cannot -tolerate any interrupts, like hardware context switching code and -the +blocks all hard and soft interrupts. +It is used for code that cannot +tolerate any interrupts, like hardware context switching code and the .Xr ddb 4 in-kernel debugger. .It Fn spltty -blocks hard interrupts from serial interfaces. Code running at this -level may not access the tty subsystem. +blocks hard interrupts from serial interfaces. +Code running at this level may not access the tty subsystem. .It Fn splsched -blocks interrupts that may access scheduler data structures. Code -running at or above this level may not call +blocks interrupts that may access scheduler data structures. +Code running at or above this level may not call .Fn sleep , .Fn tsleep , or .Fn wakeup , nor may it post signals. .It Fn splclock -blocks the hardware clock interrupt. It is used by +blocks the hardware clock interrupt. +It is used by .Fn hardclock to update kernel and process times, and must be used by any other code that accesses time-related data. .It Fn splstatclock -blocks the hardware statistics clock interrupt. It is used by +blocks the hardware statistics clock interrupt. +It is used by .Fn statclock to update kernel profiling and other statistics, and must be used by any code that accesses that data. @@ -136,7 +140,8 @@ blocks soft network interrupts. blocks soft clock interrupts. .El .Pp -Two macros lower the system priority level. They are: +Two macros lower the system priority level. +They are: .Bl -tag -width spllowersoftclockXX .It Fn spllowersoftclock unblocks all interrupts but the soft clock interrupt. diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index b4a06cfce37..1d04bcb9595 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1995 FreeBSD Inc. +.\" Copyright (c) 1995 FreeBSD Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: style.9,v 1.7 2000/03/06 21:46:56 aaron Exp $ +.\" $OpenBSD: style.9,v 1.8 2000/10/12 18:06:03 aaron Exp $ .\" .Dd August 19, 1999 .Dt STYLE 9 @@ -33,12 +33,14 @@ .Sh DESCRIPTION This file specifies the preferred style for kernel source files in the .Ox -source tree. It is also a guide for preferred user land code style. +source tree. +It is also a guide for preferred user land code style. These guidelines should be followed for all new code. In general, code can be considered .Dq new code -when it makes up about 50% or more of the file(s) involved. This is enough -to break precedents in the existing code and use the current style guidelines. +when it makes up about 50% or more of the file(s) involved. +This is enough to break precedents in the existing code and use the +current style guidelines. .Bd -literal -offset 0i /* * Style guide for the OpenBSD KNF (Kernel Normal Form). @@ -56,7 +58,7 @@ to break precedents in the existing code and use the current style guidelines. */ .Ed .Pp -Kernel include files (i.e. +Kernel include files (i.e., .Pa Aq sys/*.h ) come first; normally, you'll need .Pa Aq sys/types.h @@ -106,9 +108,9 @@ Then, there's a blank line, and the user include files. .Pp All functions are prototyped somewhere. .Pp -Function prototypes for private functions (i.e. functions not used -elsewhere) go at the top of the first source module. In user land, -functions local to one source module should be declared +Function prototypes for private functions (i.e., functions not used +elsewhere) go at the top of the first source module. +In user land, functions local to one source module should be declared .Ql static . This should not be done in kernel land since it makes it impossible to use the kernel debugger. @@ -117,7 +119,7 @@ Functions used from other parts of the kernel are prototyped in the relevant include file. .Pp Functions that are used locally in more than one module go into a -separate header file, e.g. +separate header file, e.g., .Pa extern.h . .Pp When declaring a prototype, use the @@ -144,20 +146,21 @@ Use .Li __dead from .Pa Aq sys/cdefs.h -for functions that don't return, e.g. +for functions that don't return, e.g., .Bd -literal -offset 0i __dead void abort __P((void)); .Ed .Pp In header files, put function prototypes within .Dv __BEGIN_DECLS / __END_DECLS -matching pairs. This makes the header file usable from C++. +matching pairs. +This makes the header file usable from C++. .Pp Macros are capitalized and parenthesized, and should avoid side-effects. If they are an inline expansion of a function, the function is defined -all in lowercase; the macro has the same name all in uppercase. If the -macro needs more than a single line, use braces. Right-justify the -backslashes, as the resulting definition is easier to read. +all in lowercase; the macro has the same name all in uppercase. +If the macro needs more than a single line, use braces. +Right-justify the backslashes, as the resulting definition is easier to read. If the macro encapsulates a compound statement, enclose it in a .Dq Li do loop, @@ -180,17 +183,18 @@ enum enumtype { ONE, TWO } et; .Ed .Pp When declaring variables in structures, declare them sorted by use, then -by size, and then by alphabetical order. The first category normally -doesn't apply, but there are exceptions. Each one gets its own line. -Put a tab after the first word, i.e. use +by size, and then by alphabetical order. +The first category normally doesn't apply, but there are exceptions. +Each one gets its own line. +Put a tab after the first word, i.e., use .Ql int^Ix; and .Ql struct^Ifoo *x; . .Pp Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple -source files. Use of the structures should be by separate declarations -and should be +source files. +Use of the structures should be by separate declarations and should be .Dq Li extern if they are declared in a header file. .Bd -literal -offset 0i @@ -204,8 +208,8 @@ struct foo *foohead; /* Head of global foo list */ .Pp Use .Xr queue 3 -macros rather than rolling your own lists, whenever possible. Thus, -the previous example would be better written: +macros rather than rolling your own lists, whenever possible. +Thus, the previous example would be better written: .Bd -literal -offset 0i #include <sys/queue.h> struct foo { @@ -216,11 +220,12 @@ struct foo { LIST_HEAD(, foo) foohead; /* Head of global foo list */ .Ed .Pp -Avoid using typedefs for structure types. This makes it impossible +Avoid using typedefs for structure types. +This makes it impossible for applications to use pointers to such a structure opaquely, which is both possible and beneficial when using an ordinary struct tag. -When convention requires a typedef, make its name match the struct -tag. Avoid typedefs ending in +When convention requires a typedef, make its name match the struct tag. +Avoid typedefs ending in .Dq Li \&_t , except as specified in Standard C or by .Tn POSIX . @@ -250,14 +255,14 @@ main(int argc, char *argv[]) .Pp For consistency, .Xr getopt 3 -should be used to parse options. Options -should be sorted in the +should be used to parse options. +Options should be sorted in the .Xr getopt 3 call and the switch statement, unless -parts of the switch cascade. Elements in a switch statement that -cascade should have a FALLTHROUGH comment. Numerical arguments -should be checked for accuracy. Code that cannot be reached should -have a NOTREACHED comment. +parts of the switch cascade. +Elements in a switch statement that cascade should have a FALLTHROUGH comment. +Numerical arguments should be checked for accuracy. +Code that cannot be reached should not have a NOTREACHED comment. .Bd -literal -offset 0i while ((ch = getopt(argc, argv, "abn")) != -1) switch (ch) { /* Indent the switch. */ @@ -314,8 +319,9 @@ not } .Ed .Pp -Parts of a for loop may be left empty. Don't put declarations -inside blocks unless the routine is unusually complicated. +Parts of a for loop may be left empty. +Don't put declarations inside blocks unless the routine is +unusually complicated. .Bd -literal -offset 0i for (; cnt < 15; cnt++) { stmt1; @@ -333,8 +339,8 @@ Second level indents are four spaces. .Ed .Pp Do not add whitespace at the end of a line, and only use tabs -followed by spaces -to form the indentation. Do not use more spaces than a tab will produce +followed by spaces to form the indentation. +Do not use more spaces than a tab will produce and do not use spaces in front of tabs. .Pp Closing and opening braces go on the same line as the else. @@ -350,9 +356,9 @@ a compiler warning. stmt; .Ed .Pp -Do not use spaces after function names. Commas have a space after them. -Do not use spaces -after +Do not use spaces after function names. +Commas have a space after them. +Do not use spaces after .Sq \&( or .Sq \&[ @@ -366,10 +372,10 @@ characters. exit(error); .Ed .Pp -Unary operators don't require spaces, binary operators do. Don't -use parentheses unless they're required for precedence, the statement -is confusing without them, or the compiler generates a warning without -them. Remember that other people may be confused more easily than you. +Unary operators don't require spaces, binary operators do. +Don't use parentheses unless they're required for precedence, the statement +is confusing without them, or the compiler generates a warning without them. +Remember that other people may be confused more easily than you. Do YOU understand the following? .Bd -literal -offset 0i a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; @@ -398,14 +404,15 @@ function(a1, a2, fl, a4) .Ed .Pp When declaring variables in functions declare them sorted by size, -then in alphabetical order; multiple ones per line are okay. Old -style function declarations can go on the same line. ANSI style -function declarations should go in the include file +then in alphabetical order; multiple ones per line are okay. +Old style function declarations can go on the same line. +ANSI style function declarations should go in the include file .Dq Pa extern.h . If a line overflows reuse the type keyword. .Pp Be careful to not obfuscate the code by initializing variables in -the declarations. Use this feature only thoughtfully. +the declarations. +Use this feature only thoughtfully. DO NOT use function calls in initializers! .Bd -literal -offset 0i struct foo one, *two; @@ -418,24 +425,26 @@ DO NOT use function calls in initializers! .Pp Do not declare functions inside other functions; ANSI C says that such declarations have file scope regardless of the nesting of the -declaration. Hiding file declarations in what appears to be a local -scope is undesirable and will elicit complaints from a good compiler, -such as +declaration. +Hiding file declarations in what appears to be a local scope is +undesirable and will elicit complaints from a good compiler, such as .Dq Li gcc -Wtraditional . .Pp -Casts and sizeof's are not followed by a space. Note that +Casts and sizeof's are not followed by a space. +Note that .Xr indent 1 does not understand this rule. .Pp .Dv NULL -is the preferred null pointer constant. Use +is the preferred null pointer constant. +Use .Dv NULL instead of (type\ *)0 or (type\ *)NULL in contexts where the compiler knows the -type, e.g., in assignments. Use (type\ *)NULL in other contexts, -in particular for all function args. (Casting is essential for -variadic args and is necessary for other args if the function prototype -might not be in scope.) +type, e.g., in assignments. +Use (type\ *)NULL in other contexts, in particular for all function args. +(Casting is essential for variadic args and is necessary for other args +if the function prototype might not be in scope.) Test pointers against .Dv NULL , @@ -451,7 +460,7 @@ not: .Pp Don't use .Ql \&! -for tests unless it's a boolean, e.g. use +for tests unless it's a boolean, e.g., use .Bd -literal -offset 0i if (*p == '\e0') .Ed @@ -480,7 +489,7 @@ don't roll your own! .Ed .Pp Don't use ANSI function declarations unless you absolutely have to, -i.e. you're declaring functions with variable numbers of arguments. +i.e., you're declaring functions with variable numbers of arguments. .Pp ANSI function declarations look like this: .Bd -literal -offset 0i @@ -533,12 +542,14 @@ Use not fputs/puts/putchar/whatever; it's faster and usually cleaner, not to mention helpful in avoiding stupid bugs. .Pp -Usage statements should look like the manual pages. Options without +Usage statements should look like the manual pages. +Options without operands come first, in alphabetical order inside a single set of braces, followed by options with operands, in alphabetical order, each in braces, followed by required arguments in the order they are specified, followed by optional arguments in the order they -are specified. A bar +are specified. +A bar .Pq Sq \&| separates either-or options/arguments, and multiple options/arguments which are specified together are @@ -563,16 +574,15 @@ The guidelines for third-party maintained modules and device drivers are more relaxed but at a minimum should be internally consistent with their style. .Pp Stylistic changes (including whitespace changes) are hard on the source -repository and are to be avoided without good reason. Code that is -approximately KNF compliant in the repository must not diverge from -compliance. +repository and are to be avoided without good reason. +Code that is approximately KNF compliant in the repository must not diverge +from compliance. .Pp Whenever possible, code should be run through a code checker (e.g., .Dq Li gcc -Wall -W -Wtraditional -Wpointer-arith -Wbad-function-cast ... , .Xr lint 1 or lclint from the ports tree) and produce minimal warnings. - .Sh SEE ALSO .Xr indent 1 , .Xr err 3 , diff --git a/share/man/man9/time.9 b/share/man/man9/time.9 index 16074cfc008..90ddee39638 100644 --- a/share/man/man9/time.9 +++ b/share/man/man9/time.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: time.9,v 1.6 1999/09/02 17:28:07 espie Exp $ +.\" $OpenBSD: time.9,v 1.7 2000/10/12 18:06:03 aaron Exp $ .\" $NetBSD: time.9,v 1.1 1995/11/25 21:24:53 perry Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou @@ -61,7 +61,8 @@ system call and by periodic clock interrupts. .Pp The .Va boottime -variable holds the system boot time. It is set from +variable holds the system boot time. +It is set from .Va time at system boot, and is updated when the system time is adjusted with @@ -83,12 +84,12 @@ function, rather than being copied from .Pp The .Va mono_time -variable is a monotonically increasing system clock. It is set -from +variable is a monotonically increasing system clock. +It is set from .Va time -at boot, and is updated by the periodic timer interrupt. (It is -not updated by -.Xr settimeofday 2 .) +at boot, and is updated by the periodic timer interrupt. +(It is not updated by +.Xr settimeofday 2 . ) .Pp All of these variables contain times expressed in seconds and microseconds since midnight (0 hour), diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9 index c71a9ea4efd..96d309d08ef 100644 --- a/share/man/man9/timeout.9 +++ b/share/man/man9/timeout.9 @@ -1,19 +1,19 @@ -.\" $OpenBSD: timeout.9,v 1.10 2000/06/28 04:07:45 aaron Exp $ +.\" $OpenBSD: timeout.9,v 1.11 2000/10/12 18:06:03 aaron Exp $ .\" .\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org> -.\" All rights reserved. +.\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: .\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY @@ -24,7 +24,7 @@ .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF -.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd June 23, 1996 .Dt TIMEOUT 9 @@ -98,7 +98,8 @@ timeout in at least seconds. Negative values of .Fa ticks -are illegal. If the value is +are illegal. +If the value is .Sq 0 it will, in the current implementation, be treated as .Sq 1 , @@ -147,8 +148,7 @@ These functions are implemented in the file .Sh BUGS The .Fn timeout_add -function executes in linear time depending on the number of pending -timeouts. It will also block all interrupts while inserting the timeout -to the timeout queue. Thus it is not recommended to use a large number -of timeouts in the system. - +function executes in linear time depending on the number of pending timeouts. +It will also block all interrupts while inserting the timeout +to the timeout queue. +Thus it is not recommended to use a large number of timeouts in the system. diff --git a/share/man/man9/vm_allocate.9 b/share/man/man9/vm_allocate.9 index 7dbee03eadd..50135125be4 100644 --- a/share/man/man9/vm_allocate.9 +++ b/share/man/man9/vm_allocate.9 @@ -1,30 +1,30 @@ -.\" -.\" $OpenBSD: vm_allocate.9,v 1.1 1996/03/11 13:04:50 mickey Exp $ +.\" +.\" $OpenBSD: vm_allocate.9,v 1.2 2000/10/12 18:06:04 aaron Exp $ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. -.\" +.\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. -.\" +.\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. -.\" +.\" .\" Carnegie Mellon requests users of this software to return to -.\" +.\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 -.\" +.\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. -.\" +.\" .TH vm_allocate 9 9/19/93 .CM 4 .SH NAME @@ -54,54 +54,54 @@ Virtual address space to be affected. .TP 15 .B address -Starting address. If the +Starting address. If the .B anywhere -option is false, +option is false, an attempt is made to allocate virtual memory starting at this virtual address. If this address is not at the beginning -of a virtual page, it will be rounded down to one. +of a virtual page, it will be rounded down to one. If there is not enough space at this address, no memory will be allocated. If the anywhere option is true, the input value of this address will be ignored, and the space will be allocated wherever it is available. -In either case, the address at which memory was actually allocated will -be returned in +In either case, the address at which memory was actually allocated will +be returned in .B address . .TP 15 .B size -Number of bytes to allocate (rounded by the system in a +Number of bytes to allocate (rounded by the system in a machine dependent way to an integral number of virtual pages). .TP 15 .B anywhere -If true, the kernel should find and allocate any region of -the specified size, and return the address of the resulting region in +If true, the kernel should find and allocate any region of +the specified size, and return the address of the resulting region in .B address . If false, virtual memory will be allocated starting at .B address -, rounded to a virtual page boundary if there +, rounded to a virtual page boundary if there is sufficient space. .SH DESCRIPTION .B vm_allocate allocates a region of virtual memory, placing it in the specified task's address space. The physical memory is not actually -allocated until the new virtual memory is referenced. By default, -the kernel rounds all addresses down -to the nearest page boundary and all memory sizes up to the nearest page -size. The global variable +allocated until the new virtual memory is referenced. By default, +the kernel rounds all addresses down +to the nearest page boundary and all memory sizes up to the nearest page +size. The global variable .B cnt.vm_page_size contains the page size. Initially, the pages of allocated memory will be protected to allow all forms of access, and will be inherited in child tasks as -a copy. Subsequent calls to +a copy. Subsequent calls to .B vm_map_protect -and +and .B vm_map_inherit may -be used to change these properties. The allocated region is always -zero-filled. +be used to change these properties. The allocated region is always +zero-filled. .SH DIAGNOSTICS .TP 25 diff --git a/share/man/man9/vm_deallocate.9 b/share/man/man9/vm_deallocate.9 index 30052e89fab..381300349df 100644 --- a/share/man/man9/vm_deallocate.9 +++ b/share/man/man9/vm_deallocate.9 @@ -1,30 +1,30 @@ -.\" -.\" $OpenBSD: vm_deallocate.9,v 1.1 1996/03/11 13:04:51 mickey Exp $ +.\" +.\" $OpenBSD: vm_deallocate.9,v 1.2 2000/10/12 18:06:04 aaron Exp $ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. -.\" +.\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. -.\" +.\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. -.\" +.\" .\" Carnegie Mellon requests users of this software to return to -.\" +.\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 -.\" +.\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. -.\" +.\" .TH vm_deallocate 9 9/19/93 .CM 4 .SH NAME @@ -57,7 +57,7 @@ Starting address (will be rounded down to a page boundary). .TP 15 .B size -Number of bytes to deallocate (will be rounded up to give a +Number of bytes to deallocate (will be rounded up to give a page boundary). .SH DESCRIPTION @@ -66,9 +66,9 @@ relinquishes access to a region of a map's address space, causing further access to that memory to fail. This address range will be available for reallocation. Note, that because of the rounding to virtual page boundaries, more -than +than .B size -bytes may be deallocated. Use +bytes may be deallocated. Use .B cnt.vm_page_size find out the current virtual page size. @@ -77,9 +77,9 @@ in a message (via out of line data). In that case, the rounding should cause no trouble, since the region of memory was allocated as a set of pages. -The +The .B vm_deallocate -call affects only the map specified by the +call affects only the map specified by the .B map . Other maps which may have access to this memory may continue to reference it. diff --git a/share/man/man9/vm_map_copy.9 b/share/man/man9/vm_map_copy.9 index e429827cb62..c27d0f8c2fa 100644 --- a/share/man/man9/vm_map_copy.9 +++ b/share/man/man9/vm_map_copy.9 @@ -1,30 +1,30 @@ -.\" -.\" $OpenBSD: vm_map_copy.9,v 1.2 1998/09/06 22:23:21 aaron Exp $ +.\" +.\" $OpenBSD: vm_map_copy.9,v 1.3 2000/10/12 18:06:04 aaron Exp $ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. -.\" +.\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. -.\" +.\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. -.\" +.\" .\" Carnegie Mellon requests users of this software to return to -.\" +.\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 -.\" +.\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. -.\" +.\" .TH vm_map_copy 9 9/19/93 .CM 4 .SH NAME @@ -92,7 +92,7 @@ Either the destination region was not writable, or the source region was not readable. .TP 25 KERN_INVALID_ADDRESS -Illegal or non-allocated address specified or +Illegal or non-allocated address specified or insufficient memory allocated at one of the addresses. .SH BUGS The current implementation requires that \fBsrc_addr\fR, diff --git a/share/man/man9/vm_map_inherit.9 b/share/man/man9/vm_map_inherit.9 index c992edbeb82..22a4ce8b3b4 100644 --- a/share/man/man9/vm_map_inherit.9 +++ b/share/man/man9/vm_map_inherit.9 @@ -1,35 +1,35 @@ -.\" -.\" $OpenBSD: vm_map_inherit.9,v 1.2 1999/03/11 01:35:06 pjanzen Exp $ +.\" +.\" $OpenBSD: vm_map_inherit.9,v 1.3 2000/10/12 18:06:04 aaron Exp $ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. -.\" +.\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. -.\" +.\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. -.\" +.\" .\" Carnegie Mellon requests users of this software to return to -.\" +.\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 -.\" +.\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. -.\" +.\" .TH vm_map_inherit 9 9/19/93 .CM 4 .SH NAME .nf -vm_map_inherit \- specifies inheritence of address space +vm_map_inherit \- specifies inheritence of address space .SH SYNOPSIS .nf .ft B @@ -54,16 +54,16 @@ Virtual memory map to be affected. .B start Starting address (will be rounded down to a page -boundary). +boundary). .TP 15 .B end Ending address (will be rounded down to a page -boundary). +boundary). .TP 15 .B new_inheritance -How this memory is to be inherited in child maps. +How this memory is to be inherited in child maps. Inheritance is specified by using one of these following three values: .TP 15 .B @@ -86,15 +86,15 @@ Inheritance is an attribute of virtual pages; thus the addresses and size of memory to be set will be rounded out to refer to whole pages. -Setting +Setting .B vm_map_inherit -to +to .B VM_INHERIT_SHARE and forking a child map is the only way two .B tasks can share physical memory. -Remember that all the +Remember that all the .B theads of a given task share all the same memory. diff --git a/share/man/man9/vm_map_protect.9 b/share/man/man9/vm_map_protect.9 index 1dedcfc1ee9..e1979c7ab5e 100644 --- a/share/man/man9/vm_map_protect.9 +++ b/share/man/man9/vm_map_protect.9 @@ -1,30 +1,30 @@ -.\" -.\" $OpenBSD: vm_map_protect.9,v 1.1 1996/03/11 13:04:53 mickey Exp $ +.\" +.\" $OpenBSD: vm_map_protect.9,v 1.2 2000/10/12 18:06:04 aaron Exp $ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. -.\" +.\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. -.\" +.\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. -.\" +.\" .\" Carnegie Mellon requests users of this software to return to -.\" +.\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 -.\" +.\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. -.\" +.\" .TH vm_map_protect 9 9/19/93 .CM 4 .SH NAME @@ -69,7 +69,7 @@ A new protection value for this region; a set of: .TP 15 .B set_max -If set, make the protection change apply to the +If set, make the protection change apply to the maximum protection associated with this address range; otherwise, the current protection on this range is changed. If the maximum protection is reduced below the @@ -96,7 +96,7 @@ KERN_SUCCESS Memory protected. .TP 25 KERN_PROTECTION_FAILURE -An attempt was made to increase the current +An attempt was made to increase the current or maximum protection beyond the existing maximum protection value. .TP 25 KERN_INVALID_ADDRESS |