GssService: libgsystemservice Reference Manual

## GssService GssService — System service base class |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | gss_service_add_option_group ()
void | gss_service_run ()
void | gss_service_exit ()
GDBusConnection * | gss_service_get_dbus_connection ()
int | gss_service_get_exit_signal ()
guint | gss_service_get_inactivity_timeout ()
void | gss_service_set_inactivity_timeout ()
GDebugController * | gss_service_get_debug_controller ()
void | gss_service_hold ()
void | gss_service_release ()
int | gss_service_error_to_exit_status ()

## Types and Values

| GssService
struct | GssServiceClass
enum | GssServiceError

## Includes

    #include <libgsystemservice/service.h>

## Description

A skeleton implementation of a system service, which exposes itself on the bus with a well-known name.

It follows the implementation recommendations in `man 7 daemon`.

Since 0.2.0, it registers a D-Bus object at `/org/freedesktop/Debugging` which exposes controls for debugging the service. Requests to these controls from peers must be authorized. The default policy is to check against polkit using the action ID set as “debug-controller-action-id”, if set.

If “debug-controller-action-id” is not set, requests to the debug object will be accepted unconditionally if the service is running on the D-Bus session bus, and rejected unconditionally if the service is running on the system bus.

## Functions

### gss_service_add_option_group ()

    void
    gss_service_add_option_group (GssService *self,
                                  GOptionGroup *group);

Add an option group to the command line options. The options in this group will be listed in the help output, and their values will be set when `gss_service_run()` is called.

This is effectively a wrapper around `g_option_context_add_group()`, so see the documentation for that for more information.

#### Parameters

self | a GssService |
group | an option group to add. | [transfer none]

Since: 0.1.0

### gss_service_run ()

    void
    gss_service_run (GssService *self,
                     int argc,
                     char **argv,
                     GError **error);

Run the service, and return when the process should exit. If it should exit with an error status, `error` is set; otherwise it should exit with exit code zero (success).

This handles UNIX signals and command line parsing. If you wish to schedule some work to happen asynchronously while `gss_service_run()` is running in your ``main()`` function, use `g_idle_add()`. This function, like the rest of the library, is not thread-safe.

#### Parameters

self | a GssService |
argc | number of arguments in `argv` |
argv | argument array. | [array length=argc]
error | return location for a GError |

Since: 0.1.0

### gss_service_exit ()

    void
    gss_service_exit (GssService *self,
                      const GError *error,
                      int signum);

Cause the service to exit from `gss_service_run()`. If `error` is non-`NULL`, the service will exit with the given error; otherwise it will exit successfully. If this is called multiple times, all errors except the first will be ignored, so it may be safely used for error handling in shutdown code.

It is a programmer error to call this before `startup_async()` has been called on your service.

#### Parameters

self | a GssService |
error | error which caused the process to exit, or `NULL` for a successful exit. | [nullable]
signum | signal which caused the process to exit, or 0 for a successful exit |

Since: 0.1.0

### gss_service_get_dbus_connection ()

    GDBusConnection *
    gss_service_get_dbus_connection (GssService *self);

Get the GDBusConnection used to export the service’s well-known name, as specified in “bus-type”.

#### Parameters

self | a GssService |

#### Returns

D-Bus connection.

[transfer none]

Since: 0.1.0

### gss_service_get_exit_signal ()

    int
    gss_service_get_exit_signal (GssService *self);

Get the number of the signal which caused the GssService to exit.

#### Parameters

self | a GssService |

#### Returns

exit signal number, or 0 if unset

Since: 0.1.0

### gss_service_get_inactivity_timeout ()

    guint
    gss_service_get_inactivity_timeout (GssService *self);

Get the value of “inactivity-timeout”.

#### Parameters

self | a GssService |

#### Returns

inactivity timeout, in milliseconds, or zero if inactivity is ignored

Since: 0.1.0

### gss_service_set_inactivity_timeout ()

    void
    gss_service_set_inactivity_timeout (GssService *self,
                                        guint timeout_ms);

Set the value of “inactivity-timeout”.

#### Parameters

self | a GssService |
timeout_ms | inactivity timeout (in ms), or zero for no timeout |

Since: 0.1.0

### gss_service_get_debug_controller ()

    GDebugController *
    gss_service_get_debug_controller (GssService *self);

Get the value of “debug-controller”.

#### Parameters

self | a GssService |

#### Returns

the service’s debug controller, or `NULL` if none is available.

[transfer none][nullable]

Since: 0.2.0

### gss_service_hold ()

    void
    gss_service_hold (GssService *self);

Increase the hold count of the service, and hence prevent it from automatically exiting after the “inactivity-timeout” period expires with no activity.

Call `gss_service_release()` to decrement the hold count. Calls to these two methods must be paired; it is a programmer error not to.

#### Parameters

self | a GssService |

Since: 0.1.0

### gss_service_release ()

    void
    gss_service_release (GssService *self);

Decrease the hold count of the service, and hence potentially (if the hold count reaches zero) allow it to automatically exit after the “inactivity-timeout” period expires with no activity.

Call `gss_service_hold()` to increment the hold count. Calls to these two methods must be paired; it is a programmer error not to.

#### Parameters

self | a GssService |

Since: 0.1.0

### gss_service_error_to_exit_status ()

    int
    gss_service_error_to_exit_status (GssServiceError error);

Converts `error` to a standard exit status.

This uses an appropriate exit status from `sysexits.h`) if possible.

The exit status is always guaranteed to be non-zero.

#### Parameters

error | an error code |

#### Returns

exit status for `error`

Since: 0.3.0

## Types and Values

### GssService

    typedef struct _GssService GssService;

A skeleton implementation of a system service, which exposes itself on the bus with a well-known name.

It follows the implementation recommendations in `man 7 daemon`.

Since: 0.1.0

### struct GssServiceClass

    struct GssServiceClass {
      GObjectClass parent_class;

      GOptionEntry *(*get_main_option_entries) (GssService *service);

      void (*startup_async)  (GssService          *service,
                              GCancellable        *cancellable,
                              GAsyncReadyCallback  callback,
                              gpointer             user_data);
      void (*startup_finish) (GssService          *service,
                              GAsyncResult        *result,
                              GError             **error);
      void (*shutdown)       (GssService          *service);
    };

Class structure for a GssService implementation.

All services must implement `startup_async` , `startup_finish` and `shutdown` , which are called by `gss_service_run()` to start up and shut down the service.

If your service needs to support additional command line options in the main group, implement `get_main_option_entries` ; otherwise leave it unimplemented.

#### Members

`get_main_option_entries` () | Get a `NULL`-terminated array of GOptionEntrys to add to the main option group for the service. If implemented, this must return a non-`NULL` value. | [nullable]
`startup_async` () | Asynchronous service startup implementation. This should start performing the startup for the service, when called by `gss_service_run()`. `startup_finish` will be called to complete the startup, and a GMainContext will be iterated between the two. This method must be implemented. If `gss_service_exit()` is called during `startup_async()`, the exit return value (success or error) will be returned from `gss_service_run()`. | [not nullable]
`startup_finish` () | Finish asynchronous startup started with `startup_async` . This method must be implemented. | [not nullable]
`shutdown` () | Synchronous service shutdown implementation. This should perform all shutdown for the service, and is called from `gss_service_run()` once the service shutdown is triggered. This method must be implemented. | [not nullable]

Since: 0.1.0

### enum GssServiceError

Errors from running a service.

#### Members

GSS_SERVICE_ERROR_SIGNALLED | Process was signalled with `SIGINT` or `SIGTERM`. |
GSS_SERVICE_ERROR_INVALID_OPTIONS | Invalid command line options. |
GSS_SERVICE_ERROR_NAME_UNAVAILABLE | Bus or well-known name unavailable. |
GSS_SERVICE_ERROR_INVALID_ENVIRONMENT | Runtime environment is insecure or otherwise invalid for running the daemon. |
GSS_SERVICE_ERROR_TIMEOUT | Inactivity timeout reached. |

Since: 0.1.0