Release 1.2.3.

[checkpath] / checkpath.3

diff --git a/checkpath.3 b/checkpath.3
index 8bc8faf..921dec7 100644 (file)
--- a/checkpath.3
+++ b/checkpath.3
@@ -8,6 +8,10 @@ checkpath \- library for examining path security
 
 .BI "int checkpath(const char *" path ,
 .BI "              const struct checkpath *" cp ");"
+.BI "int checkpath_addgid(struct checkpath *" cp ", gid_t " g ");"
+.BI "void checkpath_setuid(struct checkpath *" cp ");"
+.BI "int checkpath_setgid(struct checkpath *" cp ");"
+.BI "int checkpath_setgroups(struct checkpath *" cp ");"
 .BI "void checkpath_setids(struct checkpath *" cp ");"
 .fi
 .SH DESCRIPTION
@@ -17,7 +21,7 @@ function checks a path for security.  It ensures that only acceptble
 users and groups can change the files or file contents accessible
 through the path.
 .PP
-The function is given a 
+The function is given a
 .I path
 to be checked, and a pointer
 .I cp
@@ -30,7 +34,7 @@ of the problems.
 This structure contains the following members:
 .TP
 .B "uid_t cp_uid"
-The user running the check.  Files and directories owned by 
+The user running the check.  Files and directories owned by
 .B root
 (uid 0) and by
 .B cp_uid
@@ -38,7 +42,7 @@ are considered safe.
 .TP
 .B "gid_t cp_gid[NGROUPS_MAX + 1]"
 The groups of which the user is a member.  Files whose groups are in
-this set may be considered safe, depending on the 
+this set may be considered safe, depending on the
 .B cp_what
 configuration.  See below.
 .TP
@@ -46,7 +50,7 @@ configuration.  See below.
 The number of gids in the
 .B cp_gid
 array.
-.TP 
+.TP
 .B "int cp_verbose"
 The verbosity level.  Messages are only given to the reporting function
 if their verbosity level is less than or equal to this setting.  As a
@@ -57,7 +61,7 @@ levels 2 and above.  The recommended value is 1.
 .B "unsigned cp_what"
 A bitmask of flags determining what conditions are considered problems,
 and other behaviour.  See below.
-.TP 
+.TP
 .B "void (*cp_report)(...)"
 The reporting function.  See below.
 .TP
@@ -73,7 +77,38 @@ and
 can be set up to reflect the current user and group memberships by
 calling
 .B checkpath_setids
-passing the address of the structure to fill in.
+passing the address of the structure to fill in; this overwrites the
+previous contents of the
+.BR cp_uid ,
+.BR cp_gid ,
+and
+.BR cp_gids
+members.  Alternatively, the functions
+.BR checkpath_setuid ,
+.BR checkpath_setgid ,
+and
+.B checkpath_setgroups
+can be called to do the job in stages.  The
+.B checkpath_setuid
+function simply stores the process's real uid in
+.BR cp_uid .
+The
+.B checkpath_setgid
+and
+.B checkpath_setgroups
+functions store respectively the process's real gid and supplementary
+gids in the
+.B cp_gid
+array; they avoid inserting duplicate entries; they return 0 on success
+or \-1 if the table would overflow; they assume that the table is
+properly set up (minimally, just set
+.BR "cp_gids = 0" ).
+They use a utility function
+.B checkpath_addgid
+to do their work; it takes a pointer to a
+.B struct checkpath
+and a gid, and again returns 0 on success or \-1 if overflow would
+occur.
 .SS "The cp_what flags"
 The
 .B cp_what