capng_change_id(3) — Linux manual page


CAPNG_CHANGE_ID(3)              Libcap-ng API             CAPNG_CHANGE_ID(3)

NAME         top

       capng_change_id - change the credentials retaining capabilities

SYNOPSIS         top

       #include <cap-ng.h>

       int capng_change_id(int uid, int gid, capng_flags_t flag);

DESCRIPTION         top

       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.

       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:

                     Simply change uid and retain specified capabilities and
                     that's all.

                     After changing id, remove any supplement groups that
                     may still be in effect from the old uid.

                     After changing id, initialize any supplement groups
                     that may come with the new account. If given with
                     CAPNG_DROP_SUPP_GRP it will have no effect.

                     After changing the uid and gid, clear the bounding set
                     regardless to the internal representation already

RETURN VALUE         top

       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, -10 means initializing supplemental
       groups failed.

       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.

SEE ALSO         top

       capng_update(3), capng_apply(3), prctl(2), capabilities(7)

AUTHOR         top

       Steve Grubb

COLOPHON         top

       This page is part of the libcap-ng (capabilities commands and library
       (NG)) project.  Information about the project can be found at 
       ⟨⟩.  It is not known how to
       report bugs for this man page; if you know, please send a mail to  This page was obtained from the tarball libcap-
       ng-0.7.9.tar.gz fetched from
       ⟨⟩ on
       2020-08-13.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

Red Hat                           Feb 2013                CAPNG_CHANGE_ID(3)