Nick Kralevich | 1d1011a | 2012-09-06 10:14:03 -0700 | [diff] [blame] | 1 | .TH "CAPNG_CHANGE_ID" "3" "June 2009" "Red Hat" "Libcap-ng API" |
| 2 | .SH NAME |
| 3 | capng_change_id \- change the credentials retaining capabilities |
| 4 | .SH "SYNOPSIS" |
| 5 | .B #include <cap-ng.h> |
| 6 | .sp |
| 7 | int capng_change_id(int uid, int gid, capng_flags_t flag); |
| 8 | |
| 9 | .SH "DESCRIPTION" |
| 10 | |
| 11 | This 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 | |
| 13 | This 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 |
| 18 | Simply change uid and retain specified capabilities and that's all. |
| 19 | .TP |
| 20 | .B CAPNG_DROP_SUPP_GRP |
| 21 | After changing id, remove and supplement groups that may come with the account. |
| 22 | .TP |
| 23 | .B CAPNG_CLEAR_BOUNDING |
| 24 | After changing the uid and gid, clear the bounding set regardless to the internal representation already setup. |
| 25 | |
| 26 | .RE |
| 27 | .SH "RETURN VALUE" |
| 28 | |
| 29 | This 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 | |
| 31 | Note: 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 |
| 41 | Steve Grubb |