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 already 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 component is invoked,  some  global  variables
       are  initialised,  requested  mutual  exclusion  semaphores  are  initialised  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  (exept  "statgrab")  are
       destroyed etc.  sg_shutdown() is protected 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 appropriate 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/⟩