Break checkpath_setids into separate functions which work properly even

[checkpath] / checkpath.3

diff --git a/checkpath.3 b/checkpath.3
index 8c2b5ac..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
@@ -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