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