From d4155bf40214a508c4a41d2a26d0b12e900bd828 Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Sat, 9 Mar 2019 18:37:25 +0100 Subject: [PATCH] Use .Fn for function names in some manual pages. --- lib/libc/stdio/fopen.3 | 9 +++-- lib/libc/stdtime/timespec_get.3 | 2 +- lib/libc/sys/listen.2 | 14 ++++--- lib/libcam/cam.3 | 66 +++++++++++++++++++++------------ lib/libradius/libradius.3 | 14 ++++--- lib/libusb/libusb.3 | 10 +++-- lib/libusb/libusb20.3 | 19 ++++++---- libexec/rtld-elf/rtld.1 | 5 ++- sbin/dhclient/dhclient.8 | 9 +++-- sbin/hammer/hammer.8 | 19 ++++++---- share/man/man7/tuning.7 | 10 +++-- share/man/man9/microseq.9 | 20 ++++++---- 12 files changed, 128 insertions(+), 69 deletions(-) diff --git a/lib/libc/stdio/fopen.3 b/lib/libc/stdio/fopen.3 index 908b2b747b..0b938a8d97 100644 --- a/lib/libc/stdio/fopen.3 +++ b/lib/libc/stdio/fopen.3 @@ -89,10 +89,13 @@ For example 'r+' or 'w+'. The open will fail if the file already exists (C11). For example 'wx'. .It Dq Li e -Close-on-exec. The underlying descriptor will automatically be closed on -any exec() (glibc compatibility). +Close-on-exec. +The underlying descriptor will automatically be closed on any +.Fn exec +(glibc compatibility). .It Dq Li b -Binary mode. On UNIX systems file reading and writing is always in binary +Binary mode. +On UNIX systems file reading and writing is always in binary mode so this flag has no effect. .El .Pp diff --git a/lib/libc/stdtime/timespec_get.3 b/lib/libc/stdtime/timespec_get.3 index f8616773d3..94cdfa6ecd 100644 --- a/lib/libc/stdtime/timespec_get.3 +++ b/lib/libc/stdtime/timespec_get.3 @@ -36,7 +36,7 @@ .Os .Sh NAME .Nm timespec_get -.Nd Set specified timespec structure to a current time. +.Nd Set specified timespec structure to a current time .Sh LIBRARY .Lb libc .Sh SYNOPSIS diff --git a/lib/libc/sys/listen.2 b/lib/libc/sys/listen.2 index cc70ba657e..360374afa0 100644 --- a/lib/libc/sys/listen.2 +++ b/lib/libc/sys/listen.2 @@ -27,7 +27,6 @@ .\" .\" From: @(#)listen.2 8.2 (Berkeley) 12/11/93 .\" $FreeBSD: src/lib/libc/sys/listen.2,v 1.12.2.9 2002/05/09 02:24:40 silby Exp $ -.\" $DragonFly: src/lib/libc/sys/listen.2,v 1.5 2007/05/12 21:22:10 swildner Exp $ .\" .Dd November 3, 1995 .Dt LISTEN 2 @@ -76,9 +75,11 @@ and the introduction of the syncache, the .Fa backlog parameter also determined the length of the incomplete connection queue, which held TCP sockets in the process -of completing TCP's 3-way handshake. These incomplete connections +of completing TCP's 3-way handshake. +These incomplete connections are now held entirely in the syncache, which is unaffected by -queue lengths. Inflated +queue lengths. +Inflated .Fa backlog values to help handle denial of service attacks are no longer necessary. @@ -98,9 +99,12 @@ is silently forced to .Sh INTERACTION WITH ACCEPT FILTERS When accept filtering is used on a socket, a second queue will be used to hold sockets that have connected, but have not yet -met their accept filtering criteria. Once the criteria has been +met their accept filtering criteria. +Once the criteria has been met, these sockets will be moved over into the completed connection -queue to be accept()ed. If this secondary queue is full and a +queue to be +.Fn accept Ns ed. +If this secondary queue is full and a new connection comes in, the oldest socket which has not yet met its accept filter criteria will be terminated. .Pp diff --git a/lib/libcam/cam.3 b/lib/libcam/cam.3 index 2c9c90484e..4dbd334f5e 100644 --- a/lib/libcam/cam.3 +++ b/lib/libcam/cam.3 @@ -121,9 +121,9 @@ .Fc .Sh DESCRIPTION The CAM library consists of a number of functions designed to aid in -programming with the CAM subsystem. This man page covers the basic set of -library functions. More functions are documented in the man pages listed -below. +programming with the CAM subsystem. +This man page covers the basic set of library functions. +More functions are documented in the man pages listed below. .Pp Many of the CAM library functions use the .Va cam_device @@ -181,29 +181,35 @@ takes as arguments a string describing the device it is to open, and suitable for passing to .Xr open 2 . The "path" passed in may actually be most any type of string that contains -a device name and unit number to be opened. The string will be parsed by +a device name and unit number to be opened. +The string will be parsed by .Fn cam_get_device -into a device name and unit number. Once the device name and unit number +into a device name and unit number. +Once the device name and unit number are determined, a lookup is performed to determine the passthrough device that corresponds to the given device. .Fn cam_open_device is rather simple to use, but it isn't really suitable for general use -because its behavior isn't necessarily deterministic. Programmers writing +because its behavior isn't necessarily deterministic. +Programmers writing new applications should make the extra effort to use one of the other open routines documented below. .Pp .Fn cam_open_spec_device opens the .Xr pass 4 -device that corresponds to the device name and unit number passed in. The +device that corresponds to the device name and unit number passed in. +The .Ar flags should be flags suitable for passing to .Xr open 2 . The .Ar device -argument is optional. The user may supply pre-allocated space for the +argument is optional. +The user may supply pre-allocated space for the .Va cam_device -structure. If the +structure. +If the .Ar device argument is .Va NULL , @@ -219,11 +225,14 @@ is similar to except that it takes a .Tn SCSI bus, target and logical unit instead of a device name and unit number as -arguments. The +arguments. +The .Va path_id argument is the CAM equivalent of a .Tn SCSI -bus number. It represents the logical bus number in the system. The +bus number. +It represents the logical bus number in the system. +The .Ar flags should be flags suitable for passing to .Xr open 2 . @@ -238,10 +247,12 @@ takes as an argument the .Fa path of a .Xr pass 4 -device to open. No translation or lookup is performed, so the path passed +device to open. +No translation or lookup is performed, so the path passed in must be that of a CAM .Xr pass 4 -device. The +device. +The .Fa flags should be flags suitable for passing to .Xr open 2 . @@ -257,16 +268,21 @@ structure. .Fn cam_close_device frees the .Va cam_device -structure allocated by one of the above open() calls, and closes the file -descriptor to the passthrough device. This routine should not be called if -the user allocated space for the +structure allocated by one of the above +.Fn open +calls, and closes the file +descriptor to the passthrough device. +This routine should not be called if the user allocated space for the .Va cam_device -structure. Instead, the user should call +structure. +Instead, the user should call .Fn cam_close_spec_device . .Pp .Fn cam_close_spec_device -merely closes the file descriptor opened in one of the open() routines -described above. This function should be called when the +merely closes the file descriptor opened in one of the +.Fn open +routines described above. +This function should be called when the .Va cam_device structure was allocated by the caller, rather than the CAM library. .Pp @@ -297,7 +313,8 @@ takes as arguments a structure, and a string with length .Fa len . It creates a colon-terminated printing prefix string similar to the ones -used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". +used by the kernel, e.g.\& +.Dq (cd0:ahc1:0:4:0): . .Fn cam_path_string will place at most .Fa len Ns \-1 @@ -370,7 +387,8 @@ returns a value of -1 if an error occurred, and is set to indicate the error. .Pp .Fn cam_path_string -returns a filled printing prefix string as a convenience. This is the same +returns a filled printing prefix string as a convenience. +This is the same .Fa str that is passed into .Fn cam_path_string . @@ -403,11 +421,13 @@ The CAM library first appeared in .Fn cam_open_device doesn't check to see if the .Fa path -passed in is a symlink to something. It also doesn't check to see if the +passed in is a symlink to something. +It also doesn't check to see if the .Fa path passed in is an actual .Xr pass 4 -device. The former would be rather easy to implement, but the latter would +device. +The former would be rather easy to implement, but the latter would require a definitive way to identify a device node as a .Xr pass 4 device. diff --git a/lib/libradius/libradius.3 b/lib/libradius/libradius.3 index 77fad325a2..e5fdf2a2d2 100644 --- a/lib/libradius/libradius.3 +++ b/lib/libradius/libradius.3 @@ -467,17 +467,21 @@ To free the resources used by the RADIUS library, call .Fn rad_close . .Ss Server operation Server mode operates much alike to client mode, except packet send and receive -steps are swapped. To operate as server you should obtain server context with +steps are swapped. +To operate as server you should obtain server context with .Fn rad_server_open function, passing opened and bound UDP socket file descriptor as argument. You should define allowed clients and their secrets using .Fn rad_add_server -function. port, timeout and max_tries arguments are ignored in server mode. +function. +port, timeout and max_tries arguments are ignored in server mode. You should call .Fn rad_receive_request -function to receive request from client. If you do not want to block on socket -read, you are free to use any poll(), select() or non-blocking sockets for -the socket. +function to receive request from client. +If you do not want to block on socket read, you are free to use any +.Fn poll , +.Fn select +or non-blocking sockets for the socket. Received request can be parsed with same parsing functions as for client. To respond to the request you should call .Fn rad_create_response diff --git a/lib/libusb/libusb.3 b/lib/libusb/libusb.3 index 252aa413af..f40aa00f5a 100644 --- a/lib/libusb/libusb.3 +++ b/lib/libusb/libusb.3 @@ -465,7 +465,9 @@ are no threads currently handling events. Acquire the event_waiters lock. This lock is designed to be obtained in the situation where you want to be aware when events are completed, but some other -thread is event handling so calling libusb_handle_events() is not allowed. +thread is event handling so calling +.Fn libusb_handle_events +is not allowed. .Pp .Ft void .Fn libusb_unlock_event_waiters "libusb_context *ctx" @@ -475,10 +477,12 @@ Release the event_waiters lock. .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" Wait for another thread to signal completion of an event. Must be called -with the event waiters lock held, see libusb_lock_event_waiters(). +with the event waiters lock held, see +.Fn libusb_lock_event_waiters . This will block until the timeout expires or a transfer completes or a thread releases -the event handling lock through libusb_unlock_events(). +the event handling lock through +.Fn libusb_unlock_events . Returns 0 after a transfer completes or another thread stops event handling, and 1 if the timeout expired. diff --git a/lib/libusb/libusb20.3 b/lib/libusb/libusb20.3 index ba9efd502a..0b0ab76c5a 100644 --- a/lib/libusb/libusb20.3 +++ b/lib/libusb/libusb20.3 @@ -314,14 +314,16 @@ This function returns NULL in case of failure. . .Fn libusb20_tr_get_time_complete will return the completion time of an USB transfer in -millisecond units. This function is most useful for isochronous USB +millisecond units. +This function is most useful for isochronous USB transfers when doing echo cancelling. . .Pp . .Fn libusb20_tr_get_actual_frames will return the actual number of USB frames after an USB -transfer completed. A value of zero means that no data was transferred. +transfer completed. +A value of zero means that no data was transferred. . .Pp . @@ -683,7 +685,8 @@ Before this call will succeed the USB device must be opened. .Fa setup is a pointer to a decoded and host endian SETUP packet. .Fa data -is a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL. +is a pointer to a data transfer buffer associated with the control transaction. +This argument can be NULL. .Fa pactlen is a pointer to a variable that will hold the actual transfer length after the control transaction is complete. .Fa timeout @@ -785,9 +788,11 @@ The USB device need not be opened when calling this function. . .Fn libusb20_dev_alloc_config will read out and decode the USB config descriptor for -the given USB device and config index. This function returns a pointer +the given USB device and config index. +This function returns a pointer to the decoded configuration which must eventually be passed to -free(). NULL is returned in case of failure. +.Fn free . +NULL is returned in case of failure. . .Pp . @@ -959,8 +964,8 @@ returned. .Fn libusb20_be_alloc_freebsd .Fn libusb20_be_alloc_linux These functions are used to allocate a specific USB backend or the -operating system default USB backend. Allocating a backend is a way to -scan for currently present USB devices. +operating system default USB backend. +Allocating a backend is a way to scan for currently present USB devices. . .Pp . diff --git a/libexec/rtld-elf/rtld.1 b/libexec/rtld-elf/rtld.1 index 1b999cb34d..32f4d4cbde 100644 --- a/libexec/rtld-elf/rtld.1 +++ b/libexec/rtld-elf/rtld.1 @@ -287,8 +287,9 @@ at the same time. .Sh DIFFERENCES BETWEEN .1 and .2 ABI changes have been made to support TLS allocation and initialization and to give threading libraries a chance to complete initialization of the -TCB prior to the calling of the _init() functions for the dynamically loaded -libraries. +TCB prior to the calling of the +.Fn _init +functions for the dynamically loaded libraries. .Sh FILES .Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact .It Pa /var/run/ld-elf.so.hints diff --git a/sbin/dhclient/dhclient.8 b/sbin/dhclient/dhclient.8 index 3e9103d719..9f6d56ae2a 100644 --- a/sbin/dhclient/dhclient.8 +++ b/sbin/dhclient/dhclient.8 @@ -190,10 +190,13 @@ DHCP client configuration file. Database of acquired leases. .It Pa /var/run/dhclient..pid Pidfile for running instance. -While active, the pidfile is flock()'d by +While active, the pidfile is +.Fn flock Ap d +by .Nm -which can be tested by a program using flock() or by a script -using the +which can be tested by a program using +.Fn flock +or by a script using the .Xr lockf 1 utility, via a non-blocking lock attempt. .El diff --git a/sbin/hammer/hammer.8 b/sbin/hammer/hammer.8 index 227c0736f6..28d0f41e8d 100644 --- a/sbin/hammer/hammer.8 +++ b/sbin/hammer/hammer.8 @@ -140,8 +140,8 @@ This option is typically only used with diagnostic commands as kernel-supported commands will use the kernel's buffer cache. .It Fl R Ar restrictcmd This option is used by hammer ssh-remote to restrict the command later -on in the argument list. Multiple commands may be specified, separated -by a comma (all one argument). +on in the argument list. +Multiple commands may be specified, separated by a comma (all one argument). .It Fl T Ar restrictpath This option is used by hammer ssh-remote to restrict the filesystem path specified later on in the argument list. @@ -1599,8 +1599,9 @@ Tends to maintain inode number / directory name entry ordering better for files after minor renaming. .It 7 .Dx 4.8 . -Use the ISCSI crc32 algorithm instead of our custom polynomial. This makes -it easier to use faster cpu implementation of the crc algorithm. CPU +Use the ISCSI crc32 algorithm instead of our custom polynomial. +This makes it easier to use faster cpu implementation of the crc algorithm. +CPU overhead is reduced but performance is unlikely to be impacted a whole lot. .El .El @@ -1642,7 +1643,8 @@ and .Cm pfs-slave directives require that the PFS softlink be created under the main .Nm -filesystem mount. You may only access PFS softlinks via the main +filesystem mount. +You may only access PFS softlinks via the main .Nm filesystem mount. .Sh DOUBLE_BUFFER MODE @@ -1660,7 +1662,8 @@ node to 1 .Nm HAMMER will cache file data via the block device and copy it into the per-file -buffers as needed. The data will be double-cached at least until the +buffers as needed. +The data will be double-cached at least until the buffer cache throws away the file buffer. This mode is typically used in conjunction with .Xr swapcache 8 @@ -1794,7 +1797,9 @@ required for a flush sequence. Version 4 also implements the REDO log (see .Sx FSYNC FLUSH MODES below) which is capable -of fsync()ing with either one disk flush or zero disk flushes. +of +.Fn fsync Ns ing +with either one disk flush or zero disk flushes. .Sh UPGRADE INSTRUCTIONS HAMMER V4 TO V5 This upgrade brings in deduplication support. It is possible to upgrade a V4 file system to V5 in place. diff --git a/share/man/man7/tuning.7 b/share/man/man7/tuning.7 index 1c5b43c382..662c7c8cf4 100644 --- a/share/man/man7/tuning.7 +++ b/share/man/man7/tuning.7 @@ -178,10 +178,13 @@ on the system. .Pp The .Va kern.gettimeofday_quick -sysctl defaults to 0 (off). Setting this sysctl to 1 causes gettimeofday() +sysctl defaults to 0 (off). Setting this sysctl to 1 causes +.Fn gettimeofday calls in libc to use a tick-granular time from the kpmap instead of making a system call. Setting this feature can be useful when running benchmarks -which make large numbers of gettimeofday() calls, such as postgres. +which make large numbers of +.Fn gettimeofday +calls, such as postgres. .Pp The .Va kern.ipc.shm_use_phys @@ -663,7 +666,8 @@ wired kernel memory. .It mmu page tables Even though the underlying data pages themselves can be paged to swap, the page tables are usually wired into memory. -This can create problems when a large number of processes are mmap()ing +This can create problems when a large number of processes are +.Fn mmap Ns ing very large files. Sometimes turning on .Va machdep.pmap_mmu_optimize diff --git a/share/man/man9/microseq.9 b/share/man/man9/microseq.9 index feeb10f6e5..890a40094d 100644 --- a/share/man/man9/microseq.9 +++ b/share/man/man9/microseq.9 @@ -23,7 +23,6 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD: src/share/man/man9/microseq.9,v 1.9.2.6 2002/12/29 16:35:39 schweikh Exp $ -.\" $DragonFly: src/share/man/man9/microseq.9,v 1.5 2008/11/23 21:55:52 swildner Exp $ .\" .Dd June 6, 1998 .Dt MICROSEQ 9 @@ -61,8 +60,8 @@ Thus, any register described later has the same semantic than its counterpart in a PC parallel port. For more info about ISA/ECP programming, get the Microsoft standard referenced as "Extended Capabilities Port Protocol and -ISA interface Standard". Registers described later are standard parallel port -registers. +ISA interface Standard". +Registers described later are standard parallel port registers. .Pp Mask macros are defined in the standard ppbus include files for each valid bit of parallel port registers. @@ -301,13 +300,19 @@ This pointer is passed to any C call (see above). Parameter: .Bl -enum -offset indent .It -pointer to the buffer that shall be accessed by xxx_P() microsequence calls. -Note that this pointer is automatically incremented during xxx_P() calls +pointer to the buffer that shall be accessed by +.Fn xxx_P +microsequence calls. +Note that this pointer is automatically incremented during +.Fn xxx_P +calls .El .Pp Predefined macro: MS_PTR(ptr) .Ss MS_OP_ADELAY - do an Asynchronous DELAY -is used to make a tsleep() during microsequence execution. +is used to make a +.Fn tsleep +during microsequence execution. The tsleep is executed at PPBPRI level. .Pp @@ -473,7 +478,8 @@ and then execute the microsequence. .Ss The microsequencer The microsequencer is executed either at ppbus or adapter level (see .Xr ppbus 4 -for info about ppbus system layers). Most of the microsequencer is executed +for info about ppbus system layers). +Most of the microsequencer is executed at ppc level to avoid ppbus to adapter function call overhead. But some actions like deciding whereas the transfer is IEEE1284-1994 compliant are -- 2.41.0