These routines are used for Soletta platform Linux interaction. More...

#include <stdbool.h>
#include <stdint.h>
#include "sol-macros.h"
#include "sol-platform.h"
#include "sol-str-slice.h"

Data Structures
struct	sol_uevent
	Struct that contains information about an uevent. More...

Typedefs
typedef struct sol_uevent	sol_uevent
	Struct that contains information about an uevent. More...

Functions
struct sol_platform_linux_fork_run *	sol_platform_linux_fork_run (void(on_fork)(void data), void(on_child_exit)(void data, uint64_t pid, int status), const void *data)
	Fork a new process and run the given on_fork callback on that process. More...

void	sol_platform_linux_fork_run_exit (int status) SOL_ATTR_NO_RETURN
	Exit from a child process. More...

uint64_t	sol_platform_linux_fork_run_get_pid (const struct sol_platform_linux_fork_run *handle)
	The process identifier of this child. More...

int	sol_platform_linux_fork_run_send_signal (struct sol_platform_linux_fork_run *handle, int sig)
	Send a signal to the child process. More...

int	sol_platform_linux_fork_run_stop (struct sol_platform_linux_fork_run *handle)
	Force the child process to stop running and wait for it. More...

int	sol_platform_linux_mount (const char dev, const char mpoint, const char fstype, void(cb)(void data, const char mpoint, int status), const void *data)
	Mounts a device in a specific location. More...

int	sol_platform_linux_uevent_subscribe (const char action, const char subsystem, void(cb)(void data, struct sol_uevent uevent), const void data)
	Subscribe to monitor linux's uevent events. More...

int	sol_platform_linux_uevent_unsubscribe (const char action, const char subsystem, void(cb)(void data, struct sol_uevent uevent), const void data)
	Unsubscribe `uevent_cb()` for `action` and `subsystem` events monitoring. More...

Detailed Description

These routines are used for Soletta platform Linux interaction.

Typedef Documentation

typedef struct sol_uevent sol_uevent

Struct that contains information about an uevent.

See Also: sol_platform_linux_uevent_subscribe(); sol_platform_linux_uevent_unsubscribe()

Function Documentation

struct sol_platform_linux_fork_run* sol_platform_linux_fork_run	(	void()(void data)	on_fork,
		void()(void data, uint64_t pid, int status)	on_child_exit,
		const void *	data
	)

Fork a new process and run the given on_fork callback on that process.

This call will execute fork(), then wait for children to be ready (internally uses a pipe() to synchronize), reset all signal handlers to their default values and then call on_fork. This user-provided function may then do whatever it wants and when it returns the process will exit with EXIT_SUCCESS. The other way to exit is to call sol_platform_linux_fork_run_exit().

Note: whenever the user wants to exit with a different code or prematurely, never call exit() directly, instead call sol_platform_linux_fork_run_exit() (or _exit()). The reason is that functions registered with atexit() or on_exit() shouldn't be executed in the children processes.

When the child exits, the user-provided on_child_exit is called and after this point the handle returned by sol_platform_linux_fork_run() is invalidated (freed), thus shouldn't be used any further.

The main process may force the child process to stop using sol_platform_linux_fork_run_stop(), that blocking call will send SIGTERM and wait the child to exit using waitpid(), calling on_child_exit before it returns.

Parameters

on_fork	the function to call back after the child process is ready. The given data is the same pointer given as data.
on_child_exit	the function to call back on the main (original) process when the child exits. The given data is the same pointer given as data, `pid` is the process identifier (as returned by sol_platform_linux_fork_run_get_pid()) and the status is the one returned by libc waitpid(), that means the macros such as WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG() and similar from `sys/wait.h` should be used to interpret it.
data	the context data to give to the callbacks on_fork and on_child_exit. It is not modified in any way by sol_platform_linux_fork_run functions.

Returns: the handle to the child process or NULL on errors (and errno is set to the actual reason). The handle may be used to query the process identifier, to stop the process.

See Also: sol_platform_linux_fork_run_stop(); sol_platform_linux_fork_run_get_pid(); sol_platform_linux_fork_run_exit()

void sol_platform_linux_fork_run_exit ( int status )

Exit from a child process.

This function is to be called from inside on_fork to exit the child process using a specific status, such as EXIT_FAILURE or EXIT_SUCCESS.

Children process should never call exit() directly, rather use this function or _exit().

Parameters

status the value to use to exit this process, it will be available to the main process via the on_child_exit status parameter, in that case use the sys/wait.h macros to get the actual value, such as WEXITSTATUS().

uint64_t sol_platform_linux_fork_run_get_pid ( const struct sol_platform_linux_fork_run * handle )

The process identifier of this child.

Parameters

handle a valid (non-NULL and alive) handle returned by sol_platform_linux_fork_run().

Returns: the processes identifier (PID) that can be used with syscalls such as kill(). On errors, UINT64_MAX is returned and errno is set to ENOENT.

int sol_platform_linux_fork_run_send_signal	(	struct sol_platform_linux_fork_run *	handle,
		int	sig
	)

Send a signal to the child process.

This is a helper using sol_platform_linux_fork_run_get_pid() and kill(). It may be useful to send control signals such as SIGUSR1 and SIGUSR2.

Parameters

handle	a valid (non-NULL and alive) handle returned by sol_platform_linux_fork_run().
sig	the signal number, such as `SIGUSR1`.

Returns: 0 on success or -errno on failure.

int sol_platform_linux_fork_run_stop ( struct sol_platform_linux_fork_run * handle )

Force the child process to stop running and wait for it.

This is a blocking function that will kill the child process using SIGTERM, then waiting the process to exit using waitpid().

After the process exit, the on_child_exit is called and the given handle is invalidated (freed) before this function returns.

If the user doesn't want the blocking behavior he may use sol_platform_linux_fork_run_send_signal() using SIGTERM and wait on_child_exit to be called when the process exits.

Parameters

handle a valid (non-NULL and alive) handle returned by sol_platform_linux_fork_run() to be terminated. After this function return, the handle is then invalidated.

Returns: 0 on success or -errno on failure.

See Also: sol_platform_linux_fork_run_send_signal()

int sol_platform_linux_mount	(	const char *	dev,
		const char *	mpoint,
		const char *	fstype,
		void()(void data, const char *mpoint, int status)	cb,
		const void *	data
	)

Mounts a device in a specific location.

Parameters

dev	The device to be mounted
mpoint	The location to mount the device
fstype	The file system type
cb	Callback used to inform that the device was pointed with the proper status.
data	User data to `cb`

Returns: 0 on success or -errno on error.

int sol_platform_linux_uevent_subscribe	(	const char *	action,
		const char *	subsystem,
		void()(void data, struct sol_uevent *uevent)	cb,
		const void *	data
	)

Subscribe to monitor linux's uevent events.

Parameters

action	The action desired to monitor - i.e add, remove etc
subsystem	The subsystem of interest
cb	The callback to be issued after event catch
data	The context pointer to be provided to `cb`

Returns: 0 on success, negative errno otherwise

int sol_platform_linux_uevent_unsubscribe	(	const char *	action,
		const char *	subsystem,
		void()(void data, struct sol_uevent *uevent)	cb,
		const void *	data
	)

Unsubscribe uevent_cb() for action and subsystem events monitoring.

Parameters

action	The action we're monitoring and want to release the callback
subsystem	The subsystem we're monitoring and want to release the callback
cb	The callback itself
data	The context pointer to be provided to `cb`

Returns: 0 on success, negative errno otherwise

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation