intro.2: Section RETURN VALUES is actually ERRORS

Reviewed by: imp, brooks
Pull Request: https://github.com/freebsd/freebsd-src/pull/1065

1 files changed, 281 insertions, 281 deletions

diff --git a/lib/libsys/intro.2 b/lib/libsys/intro.2
index e4ee662e96d2..c8eee277f268 100644
--- a/lib/libsys/intro.2
+++ b/lib/libsys/intro.2
@@ -45,7 +45,287 @@ their error returns, and other common definitions and concepts.
 .\".Sy System call restart
 .\".Pp
 .\"(more later...)
-.Sh RETURN VALUES
+.Sh DEFINITIONS
+.Bl -tag -width Ds
+.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
+.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
+.Pq see Xr procctl 2 ,
+normally
+.Xr init 8 .
+.It Process Group
+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
+.Pq see Xr termios 4
+and the job control mechanisms of
+.Xr csh 1 .
+.It Session
+A session is a set of one or more process groups.
+A session is created by a successful call to
+.Xr setsid 2 ,
+which causes the caller to become the only member of the only process
+group in the new session.
+.It Session leader
+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
+.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
+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
+.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.
+More precisely, a process group is orphaned
+when none of its members has a parent process that is in the same session
+as the group,
+but is in a different process group.
+Note that when a process exits, the parent process for its children
+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
+.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
+Each user on the system is identified by a positive integer
+termed the real user ID.
+.Pp
+Each user is also a member of one or more groups.
+One of these groups is distinguished from others and
+used in implementing accounting facilities.
+The positive
+integer corresponding to this distinguished group is termed
+the real group ID.
+.Pp
+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
+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
+group IDs, and it is unspecified whether the effective group ID is
+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
+.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
+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
+.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
+.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.
+.It Super-user
+A process is recognized as a
+.Em super-user
+process and is granted special privileges if its effective user ID is 0.
+.It Descriptor
+An integer assigned by the system when a file is referenced
+by
+.Xr open 2
+or
+.Xr dup 2 ,
+or when a socket is created by
+.Xr pipe 2 ,
+.Xr socket 2
+or
+.Xr socketpair 2 ,
+which uniquely identifies an access path to that file or socket from
+a given process or any of its children.
+.It File Name
+Names consisting of up to
+.Brq Dv NAME_MAX
+characters may be used to name
+an ordinary file, special file, or directory.
+.Pp
+These characters may be arbitrary eight-bit values,
+excluding
+.Dv NUL
+.Pq ASCII 0
+and the
+.Ql \&/
+character
+.Pq slash, ASCII 47 .
+.Pp
+Note that it is generally unwise to use
+.Ql \&* ,
+.Ql \&? ,
+.Ql \&[
+or
+.Ql \&]
+as part of
+file names because of the special meaning attached to these characters
+by the shell.
+.It Path Name
+A path name is a
+.Dv NUL Ns -terminated
+character string starting with an
+optional slash
+.Ql \&/ ,
+followed by zero or more directory names separated
+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.
+.Pp
+If a path name begins with a slash, the path search begins at the
+.Em root
+directory.
+Otherwise, the search begins from the current working directory.
+A slash by itself names the root directory.
+An empty
+pathname refers to the current directory.
+.It Directory
+A directory is a special type of file that contains entries
+that are references to other files.
+Directory entries are called links.
+By convention, a directory
+contains at least two links,
+.Ql .\&
+and
+.Ql \&.. ,
+referred to as
+.Em dot
+and
+.Em dot-dot
+respectively.
+Dot refers to the directory itself and
+dot-dot refers to its parent 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.
+A process's root directory need not be the root
+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
+.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
+through the
+.Xr chmod 2
+call.
+.Pp
+File access is broken down according to whether a file may be: read,
+written, or executed.
+Directory files use the execute
+permission to control if the directory may be searched.
+.Pp
+File access permissions are interpreted by the system as
+they apply to three different classes of users: the owner
+of the file, those users in the file's group, anyone else.
+Every file has an independent set of access permissions for
+each of these classes.
+When an access check is made, the system
+decides if permission should be granted by checking the access
+information applicable to the caller.
+.Pp
+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 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.
+.Pp
+The process's effective user ID does not match the user ID of the
+owner of the file, and either the process's effective
+group ID matches the group ID
+of the file, or the group ID of the file is in
+the process's group access list,
+and the group permissions allow the access.
+.Pp
+Neither the effective user ID nor effective group ID
+and group access list of the process
+match the corresponding user ID and group ID of the file,
+but the permissions for ``other users'' allow access.
+.Pp
+Otherwise, permission is denied.
+.It Sockets and Address Families
+A socket is an endpoint for communication between processes.
+Each socket has queues for sending and receiving data.
+.Pp
+Sockets are typed according to their communications properties.
+These properties include whether messages sent and received
+at a socket require the name of the partner, whether communication
+is reliable, the format used in naming message recipients, etc.
+.Pp
+Each instance of the system supports some
+collection of socket types; consult
+.Xr socket 2
+for more information about the types available and
+their properties.
+.Pp
+Each instance of the system supports some number of sets of
+communications protocols.
+Each protocol set supports addresses
+of a certain format.
+An Address Family is the set of addresses
+for a specific group of protocols.
+Each socket has an address
+chosen from the address family in which the socket was created.
+.El
+.Sh FILES
+.Bl -inset -compact
+.It Pa /usr/include/sys/syscall.h
+Table of currently available system calls.
+.El
+.Sh ERRORS
 Nearly all of the system calls provide an error number referenced via
 the external identifier
 .Va errno .
@@ -463,286 +743,6 @@ command to return a different exit value to automate the running of
 .Xr fsck 8
 during a system boot.
 .El
-.Sh DEFINITIONS
-.Bl -tag -width Ds
-.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
-.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
-.Pq see Xr procctl 2 ,
-normally
-.Xr init 8 .
-.It Process Group
-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
-.Pq see Xr termios 4
-and the job control mechanisms of
-.Xr csh 1 .
-.It Session
-A session is a set of one or more process groups.
-A session is created by a successful call to
-.Xr setsid 2 ,
-which causes the caller to become the only member of the only process
-group in the new session.
-.It Session leader
-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
-.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
-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
-.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.
-More precisely, a process group is orphaned
-when none of its members has a parent process that is in the same session
-as the group,
-but is in a different process group.
-Note that when a process exits, the parent process for its children
-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
-.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
-Each user on the system is identified by a positive integer
-termed the real user ID.
-.Pp
-Each user is also a member of one or more groups.
-One of these groups is distinguished from others and
-used in implementing accounting facilities.
-The positive
-integer corresponding to this distinguished group is termed
-the real group ID.
-.Pp
-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
-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
-group IDs, and it is unspecified whether the effective group ID is
-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
-.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
-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
-.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
-.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.
-.It Super-user
-A process is recognized as a
-.Em super-user
-process and is granted special privileges if its effective user ID is 0.
-.It Descriptor
-An integer assigned by the system when a file is referenced
-by
-.Xr open 2
-or
-.Xr dup 2 ,
-or when a socket is created by
-.Xr pipe 2 ,
-.Xr socket 2
-or
-.Xr socketpair 2 ,
-which uniquely identifies an access path to that file or socket from
-a given process or any of its children.
-.It File Name
-Names consisting of up to
-.Brq Dv NAME_MAX
-characters may be used to name
-an ordinary file, special file, or directory.
-.Pp
-These characters may be arbitrary eight-bit values,
-excluding
-.Dv NUL
-.Pq ASCII 0
-and the
-.Ql \&/
-character
-.Pq slash, ASCII 47 .
-.Pp
-Note that it is generally unwise to use
-.Ql \&* ,
-.Ql \&? ,
-.Ql \&[
-or
-.Ql \&]
-as part of
-file names because of the special meaning attached to these characters
-by the shell.
-.It Path Name
-A path name is a
-.Dv NUL Ns -terminated
-character string starting with an
-optional slash
-.Ql \&/ ,
-followed by zero or more directory names separated
-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.
-.Pp
-If a path name begins with a slash, the path search begins at the
-.Em root
-directory.
-Otherwise, the search begins from the current working directory.
-A slash by itself names the root directory.
-An empty
-pathname refers to the current directory.
-.It Directory
-A directory is a special type of file that contains entries
-that are references to other files.
-Directory entries are called links.
-By convention, a directory
-contains at least two links,
-.Ql .\&
-and
-.Ql \&.. ,
-referred to as
-.Em dot
-and
-.Em dot-dot
-respectively.
-Dot refers to the directory itself and
-dot-dot refers to its parent 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.
-A process's root directory need not be the root
-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
-.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
-through the
-.Xr chmod 2
-call.
-.Pp
-File access is broken down according to whether a file may be: read,
-written, or executed.
-Directory files use the execute
-permission to control if the directory may be searched.
-.Pp
-File access permissions are interpreted by the system as
-they apply to three different classes of users: the owner
-of the file, those users in the file's group, anyone else.
-Every file has an independent set of access permissions for
-each of these classes.
-When an access check is made, the system
-decides if permission should be granted by checking the access
-information applicable to the caller.
-.Pp
-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 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.
-.Pp
-The process's effective user ID does not match the user ID of the
-owner of the file, and either the process's effective
-group ID matches the group ID
-of the file, or the group ID of the file is in
-the process's group access list,
-and the group permissions allow the access.
-.Pp
-Neither the effective user ID nor effective group ID
-and group access list of the process
-match the corresponding user ID and group ID of the file,
-but the permissions for ``other users'' allow access.
-.Pp
-Otherwise, permission is denied.
-.It Sockets and Address Families
-A socket is an endpoint for communication between processes.
-Each socket has queues for sending and receiving data.
-.Pp
-Sockets are typed according to their communications properties.
-These properties include whether messages sent and received
-at a socket require the name of the partner, whether communication
-is reliable, the format used in naming message recipients, etc.
-.Pp
-Each instance of the system supports some
-collection of socket types; consult
-.Xr socket 2
-for more information about the types available and
-their properties.
-.Pp
-Each instance of the system supports some number of sets of
-communications protocols.
-Each protocol set supports addresses
-of a certain format.
-An Address Family is the set of addresses
-for a specific group of protocols.
-Each socket has an address
-chosen from the address family in which the socket was created.
-.El
-.Sh FILES
-.Bl -inset -compact
-.It Pa /usr/include/sys/syscall.h
-Table of currently available system calls.
-.El
 .Sh SEE ALSO
 .Xr intro 3 ,
 .Xr perror 3