NAME

       capng_change_id - change the credentials retaining capabilities

SYNOPSIS

       #include <cap-ng.h>

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

DESCRIPTION

       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:

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

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

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

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

RETURN VALUE

       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

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

AUTHOR

       Steve Grubb

Red Hat                                             Feb 2013                                  CAPNG_CHANGE_ID(3)