.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
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
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
.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
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
.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
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