blob: 3abfdd899eb7158048d442ece5c1b1ba15ff97b3 [file] [log] [blame]
Nick Kralevich1d1011a2012-09-06 10:14:03 -07001.TH "CAPNG_CHANGE_ID" "3" "June 2009" "Red Hat" "Libcap-ng API"
2.SH NAME
3capng_change_id \- change the credentials retaining capabilities
4.SH "SYNOPSIS"
5.B #include <cap-ng.h>
6.sp
7int capng_change_id(int uid, int gid, capng_flags_t flag);
8
9.SH "DESCRIPTION"
10
11This function will change uid and gid to the ones given while retaining the capabilities previously specified in capng_update. It is not necessary and perhaps better if capng_apply has not been called prior to this function so that all necessary privileges are still intact. The caller is required to have CAP_SETPCAP capability still active before calling this function.
12
13This function also takes a flag parameter that helps to tailor the exact actions performed by the function to secure the environment. The option may be or'ed together. The legal values are:
14
15.RS
16.TP
17.B CAPNG_NO_FLAG
18Simply change uid and retain specified capabilities and that's all.
19.TP
20.B CAPNG_DROP_SUPP_GRP
21After changing id, remove and supplement groups that may come with the account.
22.TP
23.B CAPNG_CLEAR_BOUNDING
24After changing the uid and gid, clear the bounding set regardless to the internal representation already setup.
25
26.RE
27.SH "RETURN VALUE"
28
29This returns 0 on success and a negative number on failure. -1 means capng has not been initted properly, -2 means a failure requesting to keep capabilities across the uid change, -3 means that applying the intermediate capabilities failed, -4 means changing gid failed, -5 means dropping supplemental groups failed, -6 means changing the uid failed, -7 means dropping the ability to retain caps across a uid change failed, -8 means clearing the bounding set failed, -9 means dropping CAP_SETPCAP failed.
30
31Note: the only safe action to do upon failure of this function is to probably exit. This is because you are likely in a situation with partial permissions and not what you intended.
32
33.SH "SEE ALSO"
34
35.BR capng_update (3),
36.BR capng_apply (3),
37.BR prctl (2),
38.BR capabilities (7)
39
40.SH AUTHOR
41Steve Grubb