(2023-08-02, commit: 9434b31)

Public definitions/declarations for using the crinit-client shared library. More...

#include <bits/types/FILE.h>
#include <sched.h>
#include <stdarg.h>
#include <stdbool.h>
#include "crinit-sdefs.h"
#include "version.h"

Include dependency graph for crinit-client.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	crinitClientSetErrStream (FILE *errStream)

void	crinitClientSetInfoStream (FILE *infoStream)

int	crinitClientGetVersion (crinitVersion_t *v)

const crinitVersion_t *	crinitClientLibGetVersion (void)

void	crinitClientSetNotifyTaskName (const char *taskName)

void	crinitClientSetSocketPath (const char *sockFile)

int	crinitClientSetVerbose (bool v)

int	sd_notify (int unset_environment, const char *state)

int	sd_notifyf (int unset_environment, const char *format,...)

int	crinitClientTaskAdd (const char configFilePath, bool overwrite, const char forceDeps)

int	crinitClientSeriesAdd (const char *seriesFilePath, bool overwriteTasks)

int	crinitClientTaskEnable (const char *taskName)

int	crinitClientTaskDisable (const char *taskName)

int	crinitClientTaskStop (const char *taskName)

int	crinitClientTaskKill (const char *taskName)

int	crinitClientTaskRestart (const char *taskName)

int	crinitClientTaskGetStatus (crinitTaskState_t s, pid_t pid, const char *taskName)

int	crinitClientGetTaskList (crinitTaskList_t **tl)

void	crinitClientFreeTaskList (crinitTaskList_t *tl)

int	crinitClientShutdown (crinitShutdownCmd_t sCmd)

Detailed Description

Public definitions/declarations for using the crinit-client shared library.

Function Documentation

◆ crinitClientFreeTaskList()

void crinitClientFreeTaskList ( crinitTaskList_t * tl )

Free the list of tasks obtained from crinitClientGetTaskList().

Parameters

tl	The list of tasks.

◆ crinitClientGetTaskList()

int crinitClientGetTaskList ( crinitTaskList_t ** tl )

Request Crinit to report the list of task names from its TaskDB.

The returned object should be freed with crinitClientFreeTaskList().

Parameters

tl	Return pointer for the list of tasks.

Returns: 0 on success, -1 on error

◆ crinitClientGetVersion()

int crinitClientGetVersion ( crinitVersion_t * v )

Queries the version of the crinit daemon.

See also crinitVersion_t. Depending on the build environment, crinitVersion_t::git may be an empty string.

Parameters

v	Return pointer to an crinitVersion_t in which the crinit daemon's version will be written if the query is successful.

Returns: 0 on success, -1 otherwise

◆ crinitClientLibGetVersion()

const crinitVersion_t* crinitClientLibGetVersion ( void )

Returns version information for the crinit-client shared library.

See also crinitVersion_t. Depending on the build environment, crinitVersion_t::git may be an empty string.

Returns: A pointer to an crinitVersion_t constant containing this library's version info.

◆ crinitClientSeriesAdd()

int crinitClientSeriesAdd	(	const char *	seriesFilePath,
		bool	overwriteTasks
	)

Requests Crinit to load tasks and options from a series file.

If successful, the task configurations and options in the series file will be loaded same as if the series file was specified on startup. Already loaded tasks from a prior series file or loaded via crinit-ctl with the same names will be overwritten if and only if overwriteTasks is set to true. Otherwise, task name collisions are an error.

Config options from the newly loaded file generally take precedence over the existing values.

Crinit will spawn no new processes during loading of a series file in order to preserve ordering through dependencies.

Parameters

seriesFilePath	Absolute path to the series file.
overwriteTasks	If true, tasks with the same name already in the TaskDB will be overwritten.

Returns: 0 on success, -1 otherwise

◆ crinitClientSetErrStream()

void crinitClientSetErrStream ( FILE * errStream )

Selects the stream on which to output error messages.

By default, the crinit-client library will output error messages to stderr specifying where a failure occurred. This function can be used to pipe them to a logfile instead or to completely suppress them by piping to /dev/null. The stream can be the same as the one used for crinitClientSetInfoStream().

Parameters

errStream The stream to use.

◆ crinitClientSetInfoStream()

void crinitClientSetInfoStream ( FILE * infoStream )

Selects the stream on which to output (debug) information messages.

By default, the crinit-client library will output debug information messages to stdout if activated by crinitClientSetVerbose(). This function can be used to pipe them to a logfile instead. The stream can be the same as the one used for crinitClientSetInfoStream().

Parameters

infoStream The stream to use.

◆ crinitClientSetNotifyTaskName()

void crinitClientSetNotifyTaskName ( const char * taskName )

Sets the task name reported to Crinit by sd_notify().

The default is set via the environment variable specified by CRINIT_ENV_NOTIFY_NAME if it is present.

Parameters

taskName The task name to use.

◆ crinitClientSetSocketPath()

void crinitClientSetSocketPath ( const char * sockFile )

Sets the path to Crinit's AF_UNIX communication socket.

The default is set by CRINIT_SOCKFILE.

Parameters

sockFile Path to the socket file.

◆ crinitClientSetVerbose()

int crinitClientSetVerbose ( bool v )

Turns debug output on or off.

The default is no debug output.

Parameters

v	If there should be debug output (YES==true).

◆ crinitClientShutdown()

int crinitClientShutdown ( crinitShutdownCmd_t sCmd )

Request Crinit to initiate an immediate shutdown or reboot.

Calling process must have the CAP_SYS_BOOT capability or Crinit will refuse with "Permission denied." Before issuing the shutdown or reboot syscall, Crinit will send SIGCONT+SIGTERM to all processes, wait a grace period (which can be set in the main series config file as SHUTDOWN_GRACE_PERIOD_US = <microseconds>), send SIGKILL to remaining processes, detach or read-only-remount all filesystems, and finally call sync().

Parameters

sCmd	The shutdown command to be performed, either CRINIT_SHD_POWEROFF (for poweroff) or CRINIT_SHD_POWEROFF (for reboot).

Returns: 0 on success, -1 on error

◆ crinitClientTaskAdd()

int crinitClientTaskAdd	(	const char *	configFilePath,
		bool	overwrite,
		const char *	forceDeps
	)

Requests Crinit to add a task from a given task config.

If successful, the given task configuration will be parsed and added to the TaskDB. Task execution takes place once all dependencies have been fulfilled, as with pre-loaded tasks.

Using forceDeps, it is possible to specify a DEPENDS value which overrides the one in the configuration file. An empty string will cause the task to be started immediately. Specifying @ctl:enable will let the task wait for crinitClientTaskEnable(). If the dependencies from the task config file should be used, forceDeps must be NULL or "@unchanged".

Note, that Crinit does not keep track of already fulfilled dependencies, i.e. in order to not be blocked forever a task configuration must only contain dependencies which will be fulfilled in the future.

Parameters

configFilePath	Absolute path to the task configuration file.
overwrite	If an existing task with the same name should be overwritten (==true). Otherwise Crinit would return an error in this case.
forceDeps	String to override the value of DEPENDS in the config file, can be "" for no dependencies (immediate start), an arbitrary list of dependencies, or `NULL`/`"@unchanged"` to keep the dependencies in the config.

Returns: 0 on success, -1 otherwise

◆ crinitClientTaskDisable()

int crinitClientTaskDisable ( const char * taskName )

Requests Crinit to add the dependency "@ctl:enable" to a specific task.

This can be used in tandem with crinitClientTaskEnable() to implement starting on command.

Note, that this function can also be used to prevent tasks with the RESPAWN option set to YES from respawning, temporarily or permanently.

Parameters

taskName The name of the task.

Returns: 0 on success, -1 on error

◆ crinitClientTaskEnable()

int crinitClientTaskEnable ( const char * taskName )

Requests Crinit to remove the dependency "@ctl:enable" from a specific task.

This can be used in tandem with crinitClientTaskDisable() or config files which already contain the above dependency to implement starting on command.

Parameters

taskName The name of the task.

Returns: 0 on success, -1 on error

◆ crinitClientTaskGetStatus()

int crinitClientTaskGetStatus	(	crinitTaskState_t *	s,
		pid_t *	pid,
		const char *	taskName
	)

Request Crinit to report the current state and PID of a task from its TaskDB.

Parameters

s	Return pointer for the task's state.
pid	Return pointer for the task's PID.
taskName	The name of the task.

Returns: 0 on success, -1 on error

◆ crinitClientTaskKill()

int crinitClientTaskKill ( const char * taskName )

Request Crinit to send SIGKILL to a task process.

Will only send a signal if a corresponding PID has been saved in the TaskDB, either through sd_notify() or the Process Dispatcher during process start.

Parameters

taskName The name of the task.

Returns: 0 on success, -1 on error

◆ crinitClientTaskRestart()

int crinitClientTaskRestart ( const char * taskName )

Request Crinit to reset the state of a task within the TaskDB.

State will be reset to 0 it is currently CRINIT_TASK_STATE_DONE or CRINIT_TASK_STATE_FAILED. If the task has no unfulfilled dependencies, this will cause an immediate restart.

Note, that the semantics are different than with e.g. systemctl restart. To get equivalent behaviour, i.e. restart a task that is currently running, a possibility is a call to crinitClientTaskStop() followed by a call to this function.

Parameters

taskName The name of the task.

Returns: 0 on success, -1 on error

◆ crinitClientTaskStop()

int crinitClientTaskStop ( const char * taskName )

Request Crinit to send SIGTERM to a task process.

Will only send a signal if a corresponding PID has been saved in the TaskDB, either through sd_notify() or the Process Dispatcher during process start.

Parameters

taskName The name of the task.

Returns: 0 on success, -1 on error

◆ sd_notify()

int sd_notify	(	int	unset_environment,
		const char *	state
	)

Notifies Crinit of task state changes.

Partially implements the SD_NOTIFY interface of systemd. Specifically, the commands READY and MAINPID are supported. Others are currently unimplemented and will be ignored. The unset_environment argument is also unimplemented, i.e. the environment will not be unset. If unset_environment is not 0, a warning will be printed.

READY=1 lets Crinit know the task is currently running. MAINPID=[pid] tells Crinit its PID. Delimiting character is a newline.

Example: "READY=1\nMAINPID=42" will update the task's state to CRINIT_TASK_STATE_RUNNING and its PID to 42.

For more information regarding the use cases of this interface, refer to the official SD_NOTIFY documentation.

Parameters

unset_environment	Unimplemented, should be set to 0.
state	SD_NOTIFY string. A newline-separated list of commands, as in the above example.

Returns: 0 on success, -1 otherwise

◆ sd_notifyf()

int sd_notifyf	(	int	unset_environment,
		const char *	format,
			...
	)

Notifies Crinit of task state changes.

Like sd_notify() but uses printf-style formatting for the input string.

(2023-08-02, commit: 9434b31)

Functions

Detailed Description

Function Documentation

◆ crinitClientFreeTaskList()

◆ crinitClientGetTaskList()

◆ crinitClientGetVersion()

◆ crinitClientLibGetVersion()

◆ crinitClientSeriesAdd()

◆ crinitClientSetErrStream()

◆ crinitClientSetInfoStream()

◆ crinitClientSetNotifyTaskName()

◆ crinitClientSetSocketPath()

◆ crinitClientSetVerbose()

◆ crinitClientShutdown()

◆ crinitClientTaskAdd()

◆ crinitClientTaskDisable()

◆ crinitClientTaskEnable()

◆ crinitClientTaskGetStatus()

◆ crinitClientTaskKill()

◆ crinitClientTaskRestart()

◆ crinitClientTaskStop()

◆ sd_notify()

◆ sd_notifyf()