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 also possible to specify -1 for either the uid
       or  gid  in  which  case the function will not change the uid or gid and leave it "as is".
       This is useful if you just want the flag  options  to  be  applied  (assuming  the  option
       doesn't require more privileges that you currently have).

       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 may be required  to
       have  CAP_SETPCAP  capability  still  active  before calling this function or capabilities
       cannot be changed.

       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
                     Clear the bounding set regardless to  the  internal  representation  already
                     setup prior to changing the uid/gid.

              CAPNG_CLEAR_AMBIENT
                     Clear ambient capabilities regardless of the internal representation already
                     setup prior to changing the uid/gid.

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 or ambient capabilities 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