TAPI for signal and signal sets remote calls

Overview

// typedefs

typedef struct rpc_struct_sigaction rpc_struct_sigaction;

// structs

struct rpc_struct_sigaction;

// global functions

char* rpc_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler);
char* rpc_bsd_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler);
char* rpc_sysv_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler);
char* rpc___sysv_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler);
int rpc_kill(rcf_rpc_server* rpcs, tarpc_pid_t pid, rpc_signum signum);
int rpc_pthread_kill(rcf_rpc_server* rpcs, tarpc_pthread_t tid, rpc_signum signum);
int rpc_tgkill(rcf_rpc_server* rpcs, tarpc_int tgid, tarpc_int tid, rpc_signum sig);
tarpc_pid_t rpc_waitpid(rcf_rpc_server* rpcs, tarpc_pid_t pid, rpc_wait_status* status, rpc_waitpid_opts options);
void rpc_sigaction_init(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa);
void rpc_sigaction_release(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa);
static void rpc_sigaction_reinit(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa);
int rpc_sigaction(rcf_rpc_server* rpcs, rpc_signum signum, const struct rpc_struct_sigaction* act, struct rpc_struct_sigaction* oldact);
int rpc_sigaltstack(rcf_rpc_server* rpcs, tarpc_stack_t* ss, tarpc_stack_t* oss);
rpc_sigset_p rpc_sigset_new(rcf_rpc_server* rpcs);
void rpc_sigset_delete(rcf_rpc_server* rpcs, rpc_sigset_p set);
rpc_sigset_p rpc_sigreceived(rcf_rpc_server* rpcs);
int rpc_siginfo_received(rcf_rpc_server* rpcs, tarpc_siginfo_t* siginfo);
int rpc_sigset_cmp(rcf_rpc_server* rpcs, const rpc_sigset_p first_set, const rpc_sigset_p second_set);
int rpc_sigprocmask(rcf_rpc_server* rpcs, rpc_sighow how, const rpc_sigset_p set, rpc_sigset_p oldset);
int rpc_sigemptyset(rcf_rpc_server* rpcs, rpc_sigset_p set);
int rpc_sigfillset(rcf_rpc_server* rpcs, rpc_sigset_p set);
int rpc_sigaddset(rcf_rpc_server* rpcs, rpc_sigset_p set, rpc_signum signum);
int rpc_sigdelset(rcf_rpc_server* rpcs, rpc_sigset_p set, rpc_signum signum);
int rpc_sigismember(rcf_rpc_server* rpcs, const rpc_sigset_p set, rpc_signum signum);
int rpc_sigpending(rcf_rpc_server* rpcs, rpc_sigset_p set);
int rpc_sigsuspend(rcf_rpc_server* rpcs, const rpc_sigset_p set);
int rpc_ta_kill_death(rcf_rpc_server* rpcs, tarpc_pid_t pid);
int rpc_ta_kill_and_wait(rcf_rpc_server* rpcs, tarpc_pid_t pid, rpc_signum sig, unsigned int timeout_s);
int rpc_siginterrupt(rcf_rpc_server* rpcs, rpc_signum signum, int flag);
void rpc_signal_registrar_cleanup(rcf_rpc_server* rpcs);

// macros

#define DEFINE_RPC_STRUCT_SIGACTION(sa_)
#define RCF_RPC_MAX_FUNC_NAME
#define __RPC_STRUCT_SIGACTION_INITIALIZER

Detailed Documentation

Typedefs

typedef struct rpc_struct_sigaction rpc_struct_sigaction

Store information of the action taken by the process when a specific signal is receipt

Global Functions

char* rpc_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler)

Establish an action to be taken when a given signal signum occurs on RPC server.

return Pointer to the signal handler function.

Parameters:

rpcs	RPC server handle
signum	Signal whose behavior is controlled
handler	Signal handler

char* rpc_bsd_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler)

Establish an action to be taken when a given signal signum occurs on RPC server.

return Pointer to the signal handler function.

Parameters:

rpcs	RPC server handle
signum	Signal whose behavior is controlled
handler	Signal handler

char* rpc_sysv_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler)

Establish an action to be taken when a given signal signum occurs on RPC server.

return Pointer to the signal handler function.

Parameters:

rpcs	RPC server handle
signum	Signal whose behavior is controlled
handler	Signal handler

char* rpc___sysv_signal(rcf_rpc_server* rpcs, rpc_signum signum, const char* handler)

With help of __sysv_signal() establish an action to be taken when a given signal signum occurs on RPC server.

return Pointer to the previous signal handler name (should be released by caller).

Parameters:

rpcs	RPC server handle
signum	Signal whose behavior is controlled
handler	Signal handler

int rpc_kill(rcf_rpc_server* rpcs, tarpc_pid_t pid, rpc_signum signum)

Send signal with number signum to process or process group whose pid’s pid.

Parameters:

rpcs	RPC server handle
pid	Process or process group PID
signum	Number of signal to be sent

Returns:

0 on success or -1 on failure

int rpc_pthread_kill(rcf_rpc_server* rpcs, tarpc_pthread_t tid, rpc_signum signum)

Send signal with number signum to thread whose tid’s tid.

Parameters:

rpcs	RPC server handle
tid	Thread ID
signum	Number of signal to be sent

Returns:

0 on success or -1 on failure

int rpc_tgkill(rcf_rpc_server* rpcs, tarpc_int tgid, tarpc_int tid, rpc_signum sig)

Send signal with number signum to thread whose tid is tid and tgid is tgid. This is linux-specific system call.

Parameters:

rpcs	RPC server handle
tgid	Thread GID
tid	Thread ID
sig	Number of signal to be sent

Returns:

0 on success or -1 on failure

tarpc_pid_t rpc_waitpid(rcf_rpc_server* rpcs, tarpc_pid_t pid, rpc_wait_status* status, rpc_waitpid_opts options)

Wait for termination of process pid or process group whose pid’s pid.

Parameters:

rpcs	RPC server handle
pid	Process or process group PID
status	Status of the process
options	Options how to wait for process

Returns:

PID of the process exited, or zero if none is exited, or -1 on error.

void rpc_sigaction_init(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa)

Initialise rpc_struct_sigaction structure.

Function jumps to cleanup in case of failure.

Parameters:

rpcs	RPC server handle
sa	Pointer to a rpc_struct_sigaction structure to be initialised

void rpc_sigaction_release(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa)

Release rpc_struct_sigaction structure.

Function jumps to cleanup in case of failure.

Parameters:

rpcs	RPC server handle
sa	Pointer to a rpc_struct_sigaction structure to be released

static void rpc_sigaction_reinit(rcf_rpc_server* rpcs, struct rpc_struct_sigaction* sa)

Relese and initialise rpc_struct_sigaction structure. The function can be useful for subsequent calls of rpc_sigaction() wich reuse the same structure in argument oldact.

Function jumps to cleanup in case of failure.

Parameters:

rpcs	RPC server handle
sa	Pointer to a rpc_struct_sigaction structure to be reinitialised

int rpc_sigaction(rcf_rpc_server* rpcs, rpc_signum signum, const struct rpc_struct_sigaction* act, struct rpc_struct_sigaction* oldact)

Allow the calling process to examin or specify the action to be associated with a given signal.

Parameters:

rpcs	RPC server handle
signum	Signal number
act	Pointer to a rpc_struct_sigaction structure storing information of action to be associated with the signal or NULL
oldact	Pointer to previously associated with the signal action or NULL. Note! RPC pointer can be allocated to keep pointer, so `oldact` (if not NULL) must be released using function `rpc_sigaction_release()`.

Returns:

0 on success or -1 on failure

int rpc_sigaltstack(rcf_rpc_server* rpcs, tarpc_stack_t* ss, tarpc_stack_t* oss)

Set and/or get signal stack context.

Parameters:

rpcs	RPC server handle
ss	New aternate signal stack or NULL
oss	Pointer where to save information about current alternate signal stack or NULL

Returns:

0 on success or -1 on failure

rpc_sigset_p rpc_sigset_new(rcf_rpc_server* rpcs)

Allocate new signal set on RPC server side.

Parameters:

rpcs	RPC server handle

Returns:

Handle of allocated signal set or NULL.

void rpc_sigset_delete(rcf_rpc_server* rpcs, rpc_sigset_p set)

Free allocated using rpc_sigset_new() signal set.

Parameters:

rpcs	RPC server handle
set	Signal set handler

rpc_sigset_p rpc_sigreceived(rcf_rpc_server* rpcs)

Get rpcs of set of signals received by special signal handler ‘signal_registrar’.

Parameters:

rpcs	RPC server handle

Returns:

Handle of the signal set (unique for RPC server, i.e. for each thread).

int rpc_siginfo_received(rcf_rpc_server* rpcs, tarpc_siginfo_t* siginfo)

Get sininfo_t structure lastly received by special signal handler ‘signal_registrar_siginfo’.

Parameters:

rpcs	RPC server handle
siginfo	Where to save siginfo_t structure

Returns:

0 or error code

int rpc_sigset_cmp(rcf_rpc_server* rpcs, const rpc_sigset_p first_set, const rpc_sigset_p second_set)

Compare two signal masks.

Parameters:

rpcs	RPC server handle
first_set	The first signal mask
second_set	The second signal mask

Returns:

-1, 0 or 1 as a result of comparison

int rpc_sigprocmask(rcf_rpc_server* rpcs, rpc_sighow how, const rpc_sigset_p set, rpc_sigset_p oldset)

Examin or change list of currently blocked signal on RPC server side.

Parameters:

rpcs	RPC server handle
how	indicates the type of change and can take following valye: RPC_SIG_BLOCK add set to currently blocked signal RPC_SIG_UNBLOCK unblock signal specified on set RPC_SIG_SETMASK replace the currently blocked set of signal by the one specified by set
set	pointer to a new set of signals
oldset	pointer to the old set of signals or NUL

Returns:

0 on success or -1 on failure

int rpc_sigemptyset(rcf_rpc_server* rpcs, rpc_sigset_p set)

Initialize the signal set pointed by set, so that all signals are excluded.

Parameters:

rpcs	RPC server handle
set	pointer to signal set.

Returns:

0 on success or -1 on failure

int rpc_sigfillset(rcf_rpc_server* rpcs, rpc_sigset_p set)

Initialize the signal set pointed by set, so that all signals are included.

Parameters:

rpcs	RPC server handle.
set	pointer to signal set.

Returns:

0 on success or -1 on failure

int rpc_sigaddset(rcf_rpc_server* rpcs, rpc_sigset_p set, rpc_signum signum)

Add a given signum signal to a signal set on RPC server side.

Parameters:

rpcs	RPC server handle
set	set to which signal is added.
signum	number of signal to be added.

Returns:

0 on success or -1 on failure

int rpc_sigdelset(rcf_rpc_server* rpcs, rpc_sigset_p set, rpc_signum signum)

Delete a given signum signal from the signal set on RPC server side.

Parameters:

rpcs	RPC server handle
set	set from which signal is deleted.
signum	number of signal to be deleted.

Returns:

0 on success or -1 on failure

int rpc_sigismember(rcf_rpc_server* rpcs, const rpc_sigset_p set, rpc_signum signum)

Check membership of signal with number signum, in the signal set on RPC server side.

Parameters:

rpcs	RPC server handle
set	signal set
signum	signal number

Returns:

1 signal is a member of the set 0 signal is not a member of the set -1 on failure

int rpc_sigpending(rcf_rpc_server* rpcs, rpc_sigset_p set)

Return the set of signal blocked by the signal mask on RPC server side and waiting to be delivered.

Parameters:

rpcs	RPC server handle
set	pointer to the set of pending signals

Returns:

0 on success or -1 on failure

int rpc_sigsuspend(rcf_rpc_server* rpcs, const rpc_sigset_p set)

Replace the current signal mask on RPC server side by the set pointed by set and then suspend the process on server side until signal is received.

Parameters:

rpcs	RPC server handle
set	pointer to new set replacing the current one.

Returns:

Always -1 with errno normally set to RPC_EINTR (to be fixed)

int rpc_ta_kill_death(rcf_rpc_server* rpcs, tarpc_pid_t pid)

Kill a child process.

Parameters:

rpcs	RPC server handle
pid	PID of the child to be killed

Returns:

0 if child was exited or killed successfully or -1 there is no such child.

Macros

#define DEFINE_RPC_STRUCT_SIGACTION(sa_)

Declare initialized rpc_struct_sigaction structure.

#define RCF_RPC_MAX_FUNC_NAME

Maximum length of function name

#define __RPC_STRUCT_SIGACTION_INITIALIZER

Initializer of rpc_struct_sigaction structure.

rpcs	RPC server handle
pid	PID of the child process to be killed
sig	Signal to be sent to child process
timeout_s	Time to wait for process to change state
0	Successful result
-1	Failed to kill the child process, of `rpcs` is `NULL`
-2	Timed out to wait for changed state of the child process