BSD 4_4_Lite2 release

[unix-history] / usr / src / share / doc / psd / 05.sysman / 1.1.t

diff --git a/usr/src/share/doc/psd/05.sysman/1.1.t b/usr/src/share/doc/psd/05.sysman/1.1.t
index 099a450..7af0e47 100644 (file)
--- a/usr/src/share/doc/psd/05.sysman/1.1.t
+++ b/usr/src/share/doc/psd/05.sysman/1.1.t
@@ -1,4 +1,4 @@
-.\" Copyright (c) 1983, 1993
+.\" Copyright (c) 1983, 1993, 1994

 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without


@@ -29,187 +29,324 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"

-.\"    @(#)1.1.t       8.1 (Berkeley) 6/8/93
+.\"    @(#)1.1.t       8.5 (Berkeley) 5/26/94

 .\"
 .\"

-.sh "Processes and protection
-.NH 3
-Host and process identifiers
+.Sh 2 "Processes and protection
+.Sh 3 "Host identifiers

 .PP
 .PP

-Each UNIX host has associated with it a 32-bit host id, and a host
-name of up to 64 characters (as defined by MAXHOSTNAMELEN in
+Each host has associated with it an integer host ID, and a host
+name of up to MAXHOSTNAMELEN (256) characters (as defined in

 \fI<sys/param.h>\fP).
 \fI<sys/param.h>\fP).

-These are set (by a privileged user)
-and returned by the calls:
+These identifiers are set (by a privileged user) and retrieved using the
+.Fn sysctl
+interface described in section
+.Xr 1.7.1 .
+The host ID is seldom used (or set), and is deprecated.
+For convenience and backward compatibility,
+the following library routines are provided:

 .DS
 .DS

-sethostid(hostid)
+.Fd sethostid 1 "set host identifier
+sethostid(hostid);

 long hostid;
 long hostid;

-
+.DE
+.DS
+.Fd gethostid 0 "get host identifier

 hostid = gethostid();
 result long hostid;
 hostid = gethostid();
 result long hostid;

-
-sethostname(name, len)
+.DE
+.DS
+.Fd sethostname 2 "set host name
+sethostname(name, len);

 char *name; int len;
 char *name; int len;

-
-len = gethostname(buf, buflen)
+.DE
+.DS
+.Fd gethostname 2 "get host name
+len = gethostname(buf, buflen);

 result int len; result char *buf; int buflen;
 .DE
 result int len; result char *buf; int buflen;
 .DE

-On each host runs a set of \fIprocesses\fP.
+.Sh 3 "Process identifiers
+Each host runs a set of \fIprocesses\fP.

 Each process is largely independent of other processes,
 having its own protection domain, address space, timers, and
 an independent set of references to system or user implemented objects.
 .PP
 Each process in a host is named by an integer
 Each process is largely independent of other processes,
 having its own protection domain, address space, timers, and
 an independent set of references to system or user implemented objects.
 .PP
 Each process in a host is named by an integer

-called the \fIprocess id\fP.  This number is
+called the \fIprocess ID\fP.  This number is

 in the range 1-30000
 in the range 1-30000

-and is returned by
-the \fIgetpid\fP routine:
+and is returned by the
+.Fn getpid
+routine:

 .DS
 .DS

+.Fd getpid 0 "get process identifier

 pid = getpid();
 pid = getpid();

-result int pid;
+result pid_t pid;

 .DE
 .DE

-On each UNIX host this identifier is guaranteed to be unique;
-in a multi-host environment, the (hostid, process id) pairs are
+On each host this identifier is guaranteed to be unique;
+in a multi-host environment, the (hostid, process ID) pairs are

 guaranteed unique.
 guaranteed unique.

-.NH 3
-Process creation and termination
-.PP
+The parent process identifier can be obtained using the
+.Fn getppid
+routine:
+.DS
+.Fd getppid 0 "get parent process identifier
+pid = getppid();
+result pid_t pid;
+.DE
+.Sh 3 "Process creation and termination
+.LP

 A new process is created by making a logical duplicate of an
 existing process:
 .DS
 A new process is created by making a logical duplicate of an
 existing process:
 .DS

+.Fd fork 0 "create a new process

 pid = fork();
 pid = fork();

-result int pid;
+result pid_t pid;

 .DE
 .DE

-The \fIfork\fP call returns twice, once in the parent process, where
+The
+.Fn fork
+call returns twice, once in the parent process, where

 \fIpid\fP is the process identifier of the child,
 and once in the child process where \fIpid\fP is 0.
 \fIpid\fP is the process identifier of the child,
 and once in the child process where \fIpid\fP is 0.

-The parent-child relationship induces a hierarchical structure on
+The parent-child relationship imposes a hierarchical structure on

 the set of processes in the system.
 .PP
 the set of processes in the system.
 .PP

-A process may terminate by executing an \fIexit\fP call:
+For processes that are forking solely for the purpose of
+.Fn execve 'ing
+another program, the
+.Fn vfork
+system call provides a faster interface:

 .DS
 .DS

-exit(status)
+.Fd vfork 0 "create a new process
+pid = vfork();
+result pid_t pid;
+.DE
+Like
+.Fn fork ,
+the
+.Fn vfork
+call returns twice, once in the parent process, where
+\fIpid\fP is the process identifier of the child,
+and once in the child process where \fIpid\fP is 0.
+The parent process is suspended until the child process calls
+either \fIexecve\fP or \fIexit\fP.
+.LP
+A process may terminate by executing an
+.Fn exit
+call:
+.DS
+.Fd exit 1 "terminate a process
+exit(status);

 int status;
 .DE
 int status;
 .DE

-returning 8 bits of exit status to its parent.
+The lower 8 bits of exit status are available to its parent.

 .PP
 When a child process exits or
 terminates abnormally, the parent process receives
 .PP
 When a child process exits or
 terminates abnormally, the parent process receives

-information about any
-event which caused termination of the child process.  A
-second call provides a non-blocking interface and may also be used
-to retrieve information about resources consumed by the process during its
-lifetime.
-.DS
-#include <sys/wait.h>
-
-pid = wait(astatus);
-result int pid; result union wait *astatus;
-
-pid = wait3(astatus, options, arusage);
-result int pid; result union waitstatus *astatus;
+information about the
+event which caused termination of the child process.
+The interface allows the parent to wait for a particular process,
+process group, or any direct descendent and
+to retrieve information about resources consumed
+by the process during its lifetime.
+The request may be done either synchronously
+(waiting for one of the requested processes to exit),
+or asynchronously
+(polling to see if any of the requested processes have exited):
+.DS
+.Fd wait4 4 "collect exit status of child
+pid = wait4(wpid, astatus, options, arusage);
+result pid_t pid; pid_t wpid; result int *astatus;

 int options; result struct rusage *arusage;
 .DE
 .PP
 A process can overlay itself with the memory image of another process,
 passing the newly created process a set of parameters, using the call:
 .DS
 int options; result struct rusage *arusage;
 .DE
 .PP
 A process can overlay itself with the memory image of another process,
 passing the newly created process a set of parameters, using the call:
 .DS

-execve(name, argv, envp)
-char *name, **argv, **envp;
+.Fd execve 3 "execute a new program
+execve(name, argv, envp);
+char *name, *argv[], *envp[];

 .DE
 The specified \fIname\fP must be a file which is in a format recognized
 by the system, either a binary executable file or a file which causes
 the execution of a specified interpreter program to process its contents.
 .DE
 The specified \fIname\fP must be a file which is in a format recognized
 by the system, either a binary executable file or a file which causes
 the execution of a specified interpreter program to process its contents.

-.NH 3
-User and group ids
+If the set-user-ID mode bit is set,
+the effective user ID is set to the owner of the file;
+if the set-group-ID mode bit is set,
+the effective group ID is set to the group of the file.
+Whether changed or not, the effective user ID is then copied to the
+saved user ID, and the effective group ID is copied to the
+saved group ID.
+.Sh 3 "User and group IDs

 .PP
 .PP

-Each process in the system has associated with it two user-id's:
-a \fIreal user id\fP and a \fIeffective user id\fP, both 16 bit
-unsigned integers (type \fBuid_t\fP).
-Each process has an \fIreal accounting group id\fP and an \fIeffective
-accounting group id\fP and a set of
-\fIaccess group id's\fP.  The group id's are 16 bit unsigned integers
-(type \fBgid_t\fP).
-Each process may be in several different access groups, with the maximum
-concurrent number of access groups a system compilation parameter,
-the constant NGROUPS in the file \fI<sys/param.h>\fP,
-guaranteed to be at least 8.
-.PP
-The real and effective user ids associated with a process are returned by:
+Each process in the system has associated with it three user IDs:
+a \fIreal user ID\fP, an \fIeffective user ID\fP, and a \fIsaved user ID\fP,
+all unsigned integral types (\fBuid_t\fP).
+Each process has a \fIreal group ID\fP
+and a set of \fIaccess group IDs\fP,
+the first of which is the \fIeffective group ID\fP.
+The group IDs are unsigned integral types (\fBgid_t\fP).
+Each process may be in multiple access groups.
+The maximum concurrent number of access groups is a system compilation
+parameter,
+represented by the constant NGROUPS in the file \fI<sys/param.h>\fP.
+It is guaranteed to be at least 16.
+.LP
+The real group ID is used in process accounting and in testing whether
+the effective group ID may be changed; it is not otherwise used for
+access control.
+The members of the access group ID set are used for access control.
+Because the first member of the set is the effective group ID, which
+is changed when executing a set-group-ID program, that element is normally
+duplicated in the set so that access privileges for the original group
+are not lost when using a set-group-ID program.
+.LP
+The real and effective user IDs associated with a process are returned by:

 .DS
 .DS

+.Fd getuid 0 "get real user identifier

 ruid = getuid();
 result uid_t ruid;
 ruid = getuid();
 result uid_t ruid;

-
+.DE
+.DS
+.Fd geteuid 0 "get effective user identifier

 euid = geteuid();
 result uid_t euid;
 .DE
 euid = geteuid();
 result uid_t euid;
 .DE

-the real and effective accounting group ids by:
+the real and effective group IDs by:

 .DS
 .DS

+.Fd getgid 0 "get real group identifier

 rgid = getgid();
 result gid_t rgid;
 rgid = getgid();
 result gid_t rgid;

-
+.DE
+.DS
+.Fd getegid 0 "get effective group identifier

 egid = getegid();
 result gid_t egid;
 .DE
 egid = getegid();
 result gid_t egid;
 .DE

-The access group id set is returned by a \fIgetgroups\fP call*:
+The access group ID set is returned by a
+.Fn getgroups
+call:

 .DS
 .DS

+.Fd getgroups 2 "get access group set

 ngroups = getgroups(gidsetsize, gidset);
 ngroups = getgroups(gidsetsize, gidset);

-result int ngroups; int gidsetsize; result int gidset[gidsetsize];
+result int ngroups; int gidsetsize; result gid_t gidset[gidsetsize];
+.DE
+.LP
+The user and group IDs
+are assigned at login time using the
+.Fn setuid ,
+.Fn setgid ,
+and
+.Fn setgroups
+calls:
+.DS
+.Fd setuid 1 "set real, effective, and saved user identifiers
+setuid(uid);
+uid_t uid;
+.DE
+.DS
+.Fd setgid 1 "set real, effective, and saved group identifiers
+setgid(gid);
+gid_t gid;
+.DE
+.DS
+.Fd setgroups 2 "set access group set
+setgroups(gidsetsize, gidset);
+int gidsetsize; gid_t gidset[gidsetsize];
+.DE
+The
+.Fn setuid
+call sets the real, effective, and saved user IDs,
+and is permitted only if the specified \fIuid\fP is the current real user ID
+or if the caller is the super-user.
+The
+.Fn setgid
+call sets the real, effective, and saved group IDs;
+it is permitted only if the specified \fIgid\fP is the current real group ID
+or if the caller is the super-user.
+The
+.Fn setgroups
+call sets the access group ID set, and is restricted to the super-user.
+.LP
+The
+.Fn seteuid
+routine allows any process to set its effective user ID to either its
+real or saved user ID:
+.DS
+.Fd seteuid 1 "set effective user identifier
+seteuid(uid);
+uid_t uid;

 .DE
 .DE

-.FS
-* The type of the gidset array in getgroups and setgroups
-remains integer for compatibility with 4.2BSD.
-It may change to \fBgid_t\fP in future releases.
-.FE
+The
+.Fn setegid
+routine allows any process to set its effective group ID to either its
+real or saved group ID:
+.DS
+.Fd setegid 1 "set effective group identifier
+setegid(gid);
+gid_t gid;
+.DE
+.Sh 3 "Sessions

 .PP
 .PP

-The user and group id's
-are assigned at login time using the \fIsetreuid\fP, \fIsetregid\fP,
-and \fIsetgroups\fP calls:
-.DS
-setreuid(ruid, euid);
-int ruid, euid;
-
-setregid(rgid, egid);
-int rgid, egid;
-
-setgroups(gidsetsize, gidset)
-int gidsetsize; int gidset[gidsetsize];
-.DE
-The \fIsetreuid\fP call sets both the real and effective user-id's,
-while the \fIsetregid\fP call sets both the real
-and effective accounting group id's.
-Unless the caller is the super-user, \fIruid\fP
-must be equal to either the current real or effective user-id,
-and \fIrgid\fP equal to either the current real or effective
-accounting group id.  The \fIsetgroups\fP call is restricted
-to the super-user.
-.NH 3
-Process groups
+When a user first logs onto the system,
+they are put into a session with a controlling process
+(usually a shell).
+The session is created with the call:
+.DS
+.Fd setsid 0 "create a new session
+pid = setsid();
+result pid_t pid;
+.DE
+All subsequent processes created by the user
+(that do not call
+.Fn setsid )
+will be part of the session.
+The session also has a login name associated with it
+which is set using the privileged call:
+.DS
+.Fd setlogin 1 "set login name
+setlogin(name);
+char *name;
+.DE
+The login name can be retrieved using the call:
+.DS
+.Fd getlogin 0 "get login name
+name = getlogin();
+result char *name;
+.DE
+Unlike historic systems, the value returned by
+.Fn getlogin
+is stored in the kernel and can be trusted.
+.Sh 3 "Process groups

 .PP
 .PP

-Each process in the system is also normally associated with a \fIprocess
+Each process in the system is also associated with a \fIprocess

 group\fP.  The group of processes in a process group is sometimes
 referred to as a \fIjob\fP and manipulated by high-level system
 software (such as the shell).
 group\fP.  The group of processes in a process group is sometimes
 referred to as a \fIjob\fP and manipulated by high-level system
 software (such as the shell).

+All members of a process group are members of the same session.

 The current process group of a process is returned by the
 The current process group of a process is returned by the

-\fIgetpgrp\fP call:
+.Fn getpgrp
+call:

 .DS
 .DS

-pgrp = getpgrp(pid);
-result int pgrp; int pid;
+.Fd getpgrp 0 "get process group
+pgrp = getpgrp();
+result pid_t pgrp;

 .DE
 When a process is in a specific process group it may receive
 software interrupts affecting the group, causing the group to
 suspend or resume execution or to be interrupted or terminated.
 In particular, a system terminal has a process group and only processes
 .DE
 When a process is in a specific process group it may receive
 software interrupts affecting the group, causing the group to
 suspend or resume execution or to be interrupted or terminated.
 In particular, a system terminal has a process group and only processes

-which are in the process group of the terminal may read from the
-terminal, allowing arbitration of terminals among several different jobs.
-.PP
-The process group associated with a process may be changed by
-the \fIsetpgrp\fP call:
+which are in the process group of the terminal may read from the terminal,
+allowing arbitration of a terminal among several different jobs.
+.LP
+The process group associated with a process may be changed by the
+.Fn setpgid
+call:

 .DS
 .DS

-setpgrp(pid, pgrp);
-int pid, pgrp;
+.Fd setpgid 2 "set process group
+setpgid(pid, pgrp);
+pid_t pid, pgrp;

 .DE
 .DE

-Newly created processes are assigned process id's distinct from all
+Newly created processes are assigned process IDs distinct from all

 processes and process groups, and the same process group as their
 processes and process groups, and the same process group as their

-parent.  A normal (unprivileged) process may set its process group equal
-to its process id.  A privileged process may set the process group of any
-process to any value.
+parent.
+Any process may set its process group equal to its process ID or
+to the value of any process group within its session.