NAME

       sg_init, sg_snapshot, sg_shutdown, sg_drop_privileges - initialise libstatgrab

SYNOPSIS

       #include <statgrab.h>

       void sg_log_init (const char *properties_pfx, const char *env_name, const char *argv0);

       sg_error sg_init (int ignore_init_errors);

       sg_error sg_snapshot (void);

       sg_error sg_shutdown (void);

       sg_error sg_drop_privileges (void);

DESCRIPTION

       sg_init()  either  initialises  the statgrab library and sets the initialisation counter to 1, if not al‐
       ready done, or increases the initialisation counter.  If called for the first time (in  fact:  if  called
       when the initialisation counter is 0), the constructor (initialisation routine) of each registered compo‐
       nent  is  invoked,  some global variables are initialised, requested mutual exclusion semaphores are ini‐
       tialised and so on.  sg_init() is protected by the mutex named "statgrab".

       sg_log_init() allows some application-individual logging configuration. It's intended for  projects  with
       several  applications  or  commands  which might have different appenders.  Mind that sg_log_init must be
       called before sg_init, but after your application initialized logging framework.

       sg_snapshot() is Win32 only and will probably disappear.

       sg_shutdown() decrements the initialisation counter. If the counter reaches zero, components' destructors
       are called, mutual exclusion semaphores (except "statgrab") are destroyed etc.  sg_shutdown() is protect‐
       ed by the mutex named "statgrab".

       sg_drop_privileges() drops elevated privileges.

RETURN VALUES

       All functions return a statgrab error code. Either SG_ERROR_NONE when everything was ok or the  appropri‐
       ate error code from an constructor/destructor.

EXAMPLE

       Typical initialization/deinitialization sequence when using with log4cplus:

       static void *l4cplus_initializer;

       static void
       cleanup_logging(void)
       {
              log4cplus_deinitialize(l4cplus_initializer);
       }

       int
       main(int argc, char const *argv[])
       {
           l4cplus_initializer = log4cplus_initialize();
           atexit((void (*)(void))cleanup_logging);

           sg_log_init("saidar", "SAIDAR_LOG_PROPERTIES", argv[0]);
           sg_init(1);
           if(sg_drop_privileges() != 0) {
            die("Failed to drop setuid/setgid privileges");
           }

           do_something();

           sg_shutdown();

           return 0;
       }

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩

libstatgrab                                        2019-10-03                                         sg_init(3)