# capng_change_id

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


* * *