git: 9e8df7900f52 - main - intro.2: Tweak grammar and syntax for consistency

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=9e8df7900f5285fb6815fbd333cf6e084679879c

commit 9e8df7900f5285fb6815fbd333cf6e084679879c
Author:     Alexander Ziaee <concussious@runbox.com>
AuthorDate: 2024-04-19 22:22:39 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-04-19 22:30:19 +0000

    intro.2: Tweak grammar and syntax for consistency
    
    Reviewed by: imp, brooks
    Pull Request: https://github.com/freebsd/freebsd-src/pull/1065
---
 lib/libsys/intro.2 | 224 ++++++++++++++++++++++++-----------------------------
 1 file changed, 101 insertions(+), 123 deletions(-)

diff --git a/lib/libsys/intro.2 b/lib/libsys/intro.2
index 11ed5b6be2f9..277b24c81eea 100644
--- a/lib/libsys/intro.2
+++ b/lib/libsys/intro.2
@@ -1,3 +1,6 @@
+.\"-
+.\" SPDX-License-Identifier: BSD-3-Clause
+.\"
 .\" Copyright (c) 1980, 1983, 1986, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -44,10 +47,11 @@ their error returns, and other common definitions and concepts.
 .\"(more later...)
 .Sh RETURN VALUES
 Nearly all of the system calls provide an error number referenced via
-the external identifier errno.
+the external identifier
+.Va errno .
 This identifier is defined in
 .In sys/errno.h
-as
+as:
 .Pp
 .Dl extern    int *       __error();
 .Dl #define   errno       (* __error())
@@ -65,12 +69,13 @@ variable that is compatible with the previous definition.
 .Pp
 When a system call detects an error,
 it returns an integer value
-indicating failure (usually -1)
+indicating failure
+.Pq usually -1
 and sets the variable
 .Va errno
 accordingly.
-(This allows interpretation of the failure on receiving
-a -1 and to take action accordingly.)
+This allows interpretation of the failure on receiving
+-1 and to take action accordingly.
 Successful calls never set
 .Va errno ;
 once set, it remains until another error occurs.
@@ -96,10 +101,8 @@ pathname was an empty string.
 No process could be found corresponding to that specified by the given
 process ID.
 .It Er 4 EINTR Em "Interrupted system call" .
-An asynchronous signal (such as
-.Dv SIGINT
-or
-.Dv SIGQUIT )
+An asynchronous signal
+.Pq such as Dv SIGINT or Dv SIGQUIT
 was caught by the process during the execution of an interruptible
 function.
 If the signal handler performs a normal return, the
@@ -107,7 +110,9 @@ interrupted system call will seem to have returned the error condition.
 .It Er 5 EIO Em "Input/output error" .
 Some physical input or output error occurred.
 This error will not be reported until a subsequent operation on the same file
-descriptor and may be lost (over written) by any subsequent errors.
+descriptor and may be lost
+.Pq over written
+by any subsequent errors.
 .It Er 6 ENXIO Em "Device not configured" .
 Input or output on a special file referred to a device that did not
 exist, or
@@ -118,9 +123,7 @@ loaded on a drive.
 .It Er 7 E2BIG Em "Argument list too long" .
 The number of bytes used for the argument and environment
 list of the new process exceeded the current limit
-.Dv ( NCARGS
-in
-.In sys/param.h ) .
+.Pq Dv NCARGS in In sys/param.h .
 .It Er 8 ENOEXEC Em "Exec format error" .
 A request was made to execute a file
 that, although it has the appropriate permissions,
@@ -128,13 +131,13 @@ was not in the format required for an
 executable file.
 .It Er 9 EBADF Em "Bad file descriptor" .
 A file descriptor argument was out of range, referred to no open file,
-or a read (write) request was made to a file that was only open for
-writing (reading).
+or a read
+.Pq write
+request was made to a file that was only open for writing
+.Pq reading .
 .It Er 10 ECHILD Em "\&No child processes" .
 A
-.Xr wait 2
-or
-.Xr waitpid 2
+.Xr wait 2 or Xr waitpid 2
 function was executed by a process that had no existing or unwaited-for
 child processes.
 .It Er 11 EDEADLK Em "Resource deadlock avoided" .
@@ -177,13 +180,11 @@ not a directory, when a directory was expected.
 An attempt was made to open a directory with write mode specified.
 .It Er 22 EINVAL Em "Invalid argument" .
 Some invalid argument was supplied.
-(For example,
-specifying an undefined signal to a
+For example, specifying an undefined signal to a
 .Xr signal 3
-function
-or a
+function or a
 .Xr kill 2
-system call).
+system call.
 .It Er 23 ENFILE Em "Too many open files in system" .
 Maximum number of open files allowable on the system
 has been reached and requests for an open cannot be satisfied
@@ -196,13 +197,14 @@ The
 .Xr getdtablesize 2
 system call will obtain the current limit.
 .It Er 25 ENOTTY Em "Inappropriate ioctl for device" .
-A control function (see
-.Xr ioctl 2 )
+A control function
+.Pq see Xr ioctl 2
 was attempted for a file or
 special device for which the operation was inappropriate.
 .It Er 26 ETXTBSY Em "Text file busy" .
-The new process was a pure procedure (shared text) file
-which was open for writing by another process, or
+The new process was a pure procedure
+.Pq shared text
+file which was open for writing by another process, or
 while the pure procedure file was being executed an
 .Xr open 2
 call requested write access.
@@ -220,34 +222,31 @@ on the file system.
 .It Er 29 ESPIPE Em "Illegal seek" .
 An
 .Xr lseek 2
-system call was issued on a socket, pipe or
-.Tn FIFO .
+system call was issued on a socket, pipe or FIFO.
 .It Er 30 EROFS Em "Read-only file system" .
 An attempt was made to modify a file or directory
 on a file system that was read-only at the time.
 .It Er 31 EMLINK Em "Too many links" .
-Maximum allowable hard links to a single file has been exceeded (limit
-of 32767 hard links per file).
+Maximum allowable hard links to a single file has been exceeded
+.Pq limit of 32767 hard links per file .
 .It Er 32 EPIPE Em "Broken pipe" .
-A write on a pipe, socket or
-.Tn FIFO
-for which there is no process
-to read the data.
+A write on a pipe, socket or FIFO for which there is no process to read
+the data.
 .It Er 33 EDOM Em "Numerical argument out of domain" .
 A numerical input argument was outside the defined domain of the mathematical
 function.
 .It Er 34 ERANGE Em "Result too large" .
 A numerical result of the function was too large to fit in the
-available space (perhaps exceeded precision).
+available space
+.Pq perhaps exceeded precision .
 .It Er 35 EAGAIN Em "Resource temporarily unavailable" .
 This is a temporary condition and later calls to the
 same routine may complete normally.
 .It Er 36 EINPROGRESS Em "Operation now in progress" .
-An operation that takes a long time to complete (such as
-a
-.Xr connect 2 )
-was attempted on a non-blocking object (see
-.Xr fcntl 2 ) .
+An operation that takes a long time to complete, such as
+.Xr connect 2 ,
+was attempted on a non-blocking object
+.Pq see Xr fcntl 2 .
 .It Er 37 EALREADY Em "Operation already in progress" .
 An operation was attempted on a non-blocking object that already
 had an operation in progress.
@@ -261,11 +260,7 @@ or some other network limit.
 .It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" .
 A protocol was specified that does not support the semantics of the
 socket type requested.
-For example, you cannot use the
-.Tn ARPA
-Internet
-.Tn UDP
-protocol with type
+For example, you cannot use the ARPA Internet UDP protocol with type
 .Dv SOCK_STREAM .
 .It Er 42 ENOPROTOOPT Em "Protocol not available" .
 A bad option or level was specified in a
@@ -292,10 +287,7 @@ system or no implementation for it exists.
 .It Er 47 EAFNOSUPPORT Em "Address family not supported by protocol family" .
 An address incompatible with the requested protocol was used.
 For example, you should not necessarily expect to be able to use
-.Tn NS
-addresses with
-.Tn ARPA
-Internet protocols.
+NS addresses with ARPA Internet protocols.
 .It Er 48 EADDRINUSE Em "Address already in use" .
 Only one usage of each address is normally permitted.
 .It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" .
@@ -329,7 +321,8 @@ request on a connected socket specified a destination
 when already connected.
 .It Er 57 ENOTCONN Em "Socket is not connected" .
 An request to send or receive data was disallowed because
-the socket was not connected and (when sending on a datagram socket)
+the socket was not connected and
+.Pq when sending on a datagram socket
 no address was supplied.
 .It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" .
 A request to send data was disallowed because the socket
@@ -343,8 +336,7 @@ or
 .Xr send 2
 request failed because the connected party did not
 properly respond after a period of time.
-(The timeout
-period is dependent on the communication protocol.)
+The timeout period is dependent on the communication protocol.
 .It Er 61 ECONNREFUSED Em "Connection refused" .
 No connection could be made because the target machine actively
 refused it.
@@ -361,10 +353,8 @@ characters, or an entire
 path name exceeded
 .Brq Dv PATH_MAX
 characters.
-(See also the description of
-.Dv _PC_NO_TRUNC
-in
-.Xr pathconf 2 . )
+See also the description of
+.Dv _PC_NO_TRUNC in Xr pathconf 2 .
 .It Er 64 EHOSTDOWN Em "Host is down" .
 A socket operation failed because the destination host was down.
 .It Er 65 EHOSTUNREACH Em "No route to host" .
@@ -388,33 +378,24 @@ exhausted, or the allocation of an inode for a newly
 created file failed because the user's quota of inodes
 was exhausted.
 .It Er 70 ESTALE Em "Stale NFS file handle" .
-An attempt was made to access an open file (on an
-.Tn NFS
-file system)
+An attempt was made to access an open file
+.Pq on an NFS file system
 which is now unavailable as referenced by the file descriptor.
-This may indicate the file was deleted on the
-.Tn NFS
-server or some
+This may indicate the file was deleted on the NFS server or some
 other catastrophic event occurred.
 .It Er 72 EBADRPC Em "RPC struct is bad" .
-Exchange of
-.Tn RPC
-information was unsuccessful.
+Exchange of RPC information was unsuccessful.
 .It Er 73 ERPCMISMATCH Em "RPC version wrong" .
-The version of
-.Tn RPC
-on the remote peer is not compatible with
+The version of RPC on the remote peer is not compatible with
 the local version.
 .It Er 74 EPROGUNAVAIL Em "RPC prog. not avail" .
 The requested program is not registered on the remote host.
 .It Er 75 EPROGMISMATCH Em "Program version wrong" .
 The requested version of the program is not available
 on the remote host
-.Pq Tn RPC .
+.Pq RPC .
 .It Er 76 EPROCUNAVAIL Em "Bad procedure for program" .
-An
-.Tn RPC
-call was attempted for a procedure which does not exist
+An RPC call was attempted for a procedure which does not exist
 in the remote program.
 .It Er 77 ENOLCK Em "No locks available" .
 A system-imposed limit on the number of simultaneous file
@@ -427,11 +408,9 @@ The file was the wrong type for the operation, or a data file had
 the wrong format.
 .It Er 80 EAUTH Em "Authentication error" .
 Attempted to use an invalid authentication ticket to mount a
-.Tn NFS
-file system.
+NFS file system.
 .It Er 81 ENEEDAUTH Em "Need authenticator" .
-An authentication ticket must be obtained before the given
-.Tn NFS
+An authentication ticket must be obtained before the given NFS
 file system may be mounted.
 .It Er 82 EIDRM Em "Identifier removed" .
 An IPC identifier was removed while the current process was waiting on it.
@@ -486,18 +465,18 @@ during a system boot.
 .El
 .Sh DEFINITIONS
 .Bl -tag -width Ds
-.It Process ID .
+.It Process ID
 Each active process in the system is uniquely identified by a non-negative
 integer called a process ID.
 The range of this ID is from 0 to 99999.
 .It Parent process ID
-A new process is created by a currently active process (see
-.Xr fork 2 ) .
+A new process is created by a currently active process
+.Pq see Xr fork 2 .
 The parent process ID of a process is initially the process ID of its creator.
 If the creating process exits,
 the parent process ID of each child is set to the ID of the calling process's
-reaper (see
-.Xr procctl 2 ) ,
+reaper
+.Pq see Xr procctl 2 ,
 normally
 .Xr init 8 .
 .It Process Group
@@ -505,9 +484,8 @@ Each active process is a member of a process group that is identified by
 a non-negative integer called the process group ID.
 This is the process
 ID of the group leader.
-This grouping permits the signaling of related
-processes (see
-.Xr termios 4 )
+This grouping permits the signaling of related processes
+.Pq see Xr termios 4
 and the job control mechanisms of
 .Xr csh 1 .
 .It Session
@@ -520,25 +498,22 @@ group in the new session.
 A process that has created a new session by a successful call to
 .Xr setsid 2 ,
 is known as a session leader.
-Only a session leader may acquire a terminal as its controlling terminal (see
-.Xr termios 4 ) .
+Only a session leader may acquire a terminal as its controlling terminal
+.Pq see Xr termios 4 .
 .It Controlling process
 A session leader with a controlling terminal is a controlling process.
 .It Controlling terminal
 A terminal that is associated with a session is known as the controlling
 terminal for that session and its members.
-.It "Terminal Process Group ID"
+.It Terminal Process Group ID
 A terminal may be acquired by a session leader as its controlling terminal.
 Once a terminal is associated with a session, any of the process groups
 within the session may be placed into the foreground by setting
 the terminal process group ID to the ID of the process group.
 This facility is used
-to arbitrate between multiple jobs contending for the same terminal;
-(see
-.Xr csh 1
-and
-.Xr tty 4 ) .
-.It "Orphaned Process Group"
+to arbitrate between multiple jobs contending for the same terminal
+.Pq see Xr csh 1 and Xr tty 4 .
+.It Orphaned Process Group
 A process group is considered to be
 .Em orphaned
 if it is not under the control of a job control shell.
@@ -551,9 +526,10 @@ is normally changed to be
 .Xr init 8 ,
 which is in a separate session.
 Not all members of an orphaned process group are necessarily orphaned
-processes (those whose creating process has exited).
+processes
+.Pq those whose creating process has exited .
 The process group of a session leader is orphaned by definition.
-.It "Real User ID and Real Group ID"
+.It Real User ID and Real Group ID
 Each user on the system is identified by a positive integer
 termed the real user ID.
 .Pp
@@ -567,42 +543,46 @@ the real group ID.
 All processes have a real user ID and real group ID.
 These are initialized from the equivalent attributes
 of the process that created it.
-.It "Effective User Id, Effective Group Id, and Group Access List"
+.It Effective User Id, Effective Group Id, and Group Access List
 Access to system resources is governed by two values:
 the effective user ID, and the group access list.
 The first member of the group access list is also known as the
 effective group ID.
-(In POSIX.1, the group access list is known as the set of supplementary
+In POSIX.1, the group access list is known as the set of supplementary
 group IDs, and it is unspecified whether the effective group ID is
-a member of the list.)
+a member of the list.
 .Pp
 The effective user ID and effective group ID are initially the
 process's real user ID and real group ID respectively.
 Either
-may be modified through execution of a set-user-ID or set-group-ID
-file (possibly by one its ancestors) (see
-.Xr execve 2 ) .
-By convention, the effective group ID (the first member of the group access
-list) is duplicated, so that the execution of a set-group-ID program
-does not result in the loss of the original (real) group ID.
+may be modified through execution of a set-user-ID or set-group-ID file
+.Pq possibly by one its ancestors
+.Pq see Xr execve 2 .
+By convention, the effective group ID
+.Pq the first member of the group access list
+is duplicated, so that the execution of a set-group-ID program
+does not result in the loss of the original
+.Pq real
+group ID.
 .Pp
 The group access list is a set of group IDs
 used only in determining resource accessibility.
 Access checks
 are performed as described below in ``File Access Permissions''.
-.It "Saved Set User ID and Saved Set Group ID"
+.It Saved Set User ID and Saved Set Group ID
 When a process executes a new file, the effective user ID is set
 to the owner of the file if the file is set-user-ID, and the effective
-group ID (first element of the group access list) is set to the group
-of the file if the file is set-group-ID.
+group ID
+.Pq first element of the group access list
+is set to the group of the file if the file is set-group-ID.
 The effective user ID of the process is then recorded as the saved set-user-ID,
 and the effective group ID of the process is recorded as the saved set-group-ID.
 These values may be used to regain those values as the effective user
-or group ID after reverting to the real ID (see
-.Xr setuid 2 ) .
-(In POSIX.1, the saved set-user-ID and saved set-group-ID are optional,
+or group ID after reverting to the real ID
+.Pq see Xr setuid 2 .
+In POSIX.1, the saved set-user-ID and saved set-group-ID are optional,
 and are used in setuid and setgid, but this does not work as desired
-for the super-user.)
+for the super-user.
 .It Super-user
 A process is recognized as a
 .Em super-user
@@ -629,12 +609,11 @@ an ordinary file, special file, or directory.
 These characters may be arbitrary eight-bit values,
 excluding
 .Dv NUL
-.Tn ( ASCII
-0) and the
+.Pq ASCII 0
+and the
 .Ql \&/
-character (slash,
-.Tn ASCII
-47).
+character
+.Pq slash, ASCII 47 .
 .Pp
 Note that it is generally unwise to use
 .Ql \&* ,
@@ -656,7 +635,7 @@ by slashes, optionally followed by a file name.
 The total length of a path name must be less than
 .Brq Dv PATH_MAX
 characters.
-(On some systems, this limit may be infinite.)
+On some systems, this limit may be infinite.
 .Pp
 If a path name begins with a slash, the path search begins at the
 .Em root
@@ -681,7 +660,7 @@ and
 respectively.
 Dot refers to the directory itself and
 dot-dot refers to its parent directory.
-.It "Root Directory and Current Working Directory"
+.It Root Directory and Current Working Directory
 Each process has associated with it a concept of a root directory
 and a current working directory for the purpose of resolving path
 name searches.
@@ -690,8 +669,8 @@ directory of the root file system.
 .It File Access Permissions
 Every file in the file system has a set of access permissions.
 These permissions are used in determining whether a process
-may perform a requested operation on the file (such as opening
-a file for writing).
+may perform a requested operation on the file
+.Pq such as opening a file for writing .
 Access permissions are established at the
 time a file is created.
 They may be changed at some later time
@@ -717,8 +696,7 @@ Read, write, and execute/search permissions on
 a file are granted to a process if:
 .Pp
 The process's effective user ID is that of the super-user.
-(Note:
-even the super-user cannot execute a non-executable file.)
+Note that even the super-user cannot execute a non-executable file.
 .Pp
 The process's effective user ID matches the user ID of the owner
 of the file and the owner permissions allow the access.