Sub-processes

API to help in launching and monitoring child processes. More...

Data Structures
struct	_subproc_t
	Child process information structure. More...

Typedefs
typedef struct _subproc_t	amxp_subproc_t
	Child process information structure. More...

Functions
int	amxp_subproc_new (amxp_subproc_t **subproc)
	Constructor function, creates a new child process data structure. More...
int	amxp_subproc_delete (amxp_subproc_t **subproc)
	Destructor function, deletes a child process data structure. More...
int	amxp_subproc_open_fd (amxp_subproc_t *subproc, int requested)
	Opens standard file descriptor to the child process. More...
int	amxp_subproc_vstart (amxp_subproc_t *const subproc, char **argv)
	Start a child process. More...
int	amxp_subproc_start (amxp_subproc_t *const subproc, char *cmd,...)
	Start a child process. More...
int	amxp_subproc_astart (amxp_subproc_t *const subproc, amxc_array_t *cmd)
	Start a child process. More...
int	amxp_subproc_kill (const amxp_subproc_t *const subproc, const int sig)
	Sends a Linux signal to the child process. More...
int	amxp_subproc_wait (amxp_subproc_t *subproc, int timeout_msec)
	Waits until the child process has stopped. More...
int	amxp_subproc_vstart_wait (amxp_subproc_t *subproc, int timeout_msec, char **cmd)
	Starts a child process and waits until it exits. More...
int	amxp_subproc_start_wait (amxp_subproc_t *subproc, int timeout_msec, char *cmd,...)
	Starts a child process and waits until it exits. More...
amxp_subproc_t *	amxp_subproc_find (const int pid)
	Retrieve a amxp_subproc_t for a child process using it's process identifier. More...
pid_t	amxp_subproc_get_pid (const amxp_subproc_t *const subproc)
	Get the PID of a child process. More...
amxp_signal_mngr_t *	amxp_subproc_get_sigmngr (const amxp_subproc_t *const subproc)
	Get the Signal managers of the child process. More...
bool	amxp_subproc_is_running (const amxp_subproc_t *const subproc)
	Checks if the child process is running. More...
int	amxp_subproc_ifexited (amxp_subproc_t *subproc)
	Checks if the child process terminated normally. More...
int	amxp_subproc_ifsignaled (amxp_subproc_t *subproc)
	Checks if the child process was stopped because of an uncaught Linux signal. More...
int	amxp_subproc_get_exitstatus (amxp_subproc_t *subproc)
	Gets the exit code of the child process. More...
int	amxp_subproc_get_termsig (amxp_subproc_t *subproc)
	Gets the Linux signal id that caused the child process to stop. More...

Detailed Description

API to help in launching and monitoring child processes.

Typedef Documentation

amxp_subproc_t

typedef struct _subproc_t amxp_subproc_t

Child process information structure.

Function Documentation

amxp_subproc_astart()

int amxp_subproc_astart	(	amxp_subproc_t *const	subproc,
		amxc_array_t *	cmd
	)

Start a child process.

Forks and executes a command. Will monitor the child process and handles SIGCHLD.

The process name and its arguments must be passed as an amxc_array_t, where all items must be char * and the first item (index 0) is the process name.

When an empty item is encountered in the array (item containing a NULL pointer), it is considered as the end of the process argument list.

Example:

amxc_array_t cmd;
amxc_array_init(&cmd, 10);
amxc_array_append_data(&cmd, "dropbear");
amxc_array_append_data(&cmd, "-p");
amxc_array_append_data(&cmd, "10022");
amxc_array_append_data(&cmd, "-F");
amxc_array_append_data(&cmd, "-E");
amxc_array_append_data(&cmd, "-R");
amxp_subproc_astart(subproc, &cmd);
amxc_array_clean(&cmd, NULL);

Parameters

subproc	pointer to the subproc
cmd	the child process

Returns

0 when child process is launched, any other value when an error occurred

Definition at line 365 of file amxp_subproc.c.

                                           {
    int retval = -1;
    char** argv = NULL;
    when_null(subproc, exit);
    when_null(cmd, exit);
    when_true(amxc_array_is_empty(cmd), exit);
    when_true(subproc->is_running, exit);
 
    argv = (char**) calloc(amxc_array_capacity(cmd) + 1, sizeof(char*));
    when_null(argv, exit);
 
    for(size_t i = 0; i < amxc_array_capacity(cmd); i++) {
        if(amxc_array_get_data_at(cmd, i) == NULL) {
            break;
        }
        argv[i] = (char*) amxc_array_get_data_at(cmd, i);
    }
 
    retval = amxp_subproc_vstart(subproc, argv);
    free(argv);
 
exit:
    return retval;
}

amxp_subproc_delete()

int amxp_subproc_delete

(

amxp_subproc_t **

subproc

)

Destructor function, deletes a child process data structure.

This function doesn't stop the child process. To stop a child process use amxp_subproc_kill

Parameters

subproc

pointer to the subproc pointer. Will be set to NULL

Returns

0 when successful, otherwise an error code

Definition at line 239 of file amxp_subproc.c.

                                                  {
    int retval = -1;
    when_null(subproc, exit);
    when_null(*subproc, exit);
 
    for(int i = 0; i < AMXP_SUB_PROC_NR_PIPES; i++) {
        if((*subproc)->fd[i][AMXP_SUBPROC_FD_PARENT] >= 0) {
            close((*subproc)->fd[i][AMXP_SUBPROC_FD_PARENT]);
        }
        if((*subproc)->fd[i][AMXP_SUBPROC_FD_CHILD] >= 0) {
            close((*subproc)->fd[i][AMXP_SUBPROC_FD_CHILD]);
        }
    }
 
    amxc_llist_it_take(&(*subproc)->it);
    amxp_sigmngr_delete(&(*subproc)->sigmngr);
    free(*subproc);
    *subproc = NULL;
 
    retval = 0;
exit:
    return retval;
}

amxp_subproc_find()

amxp_subproc_t* amxp_subproc_find

(

const int

pid

)

Retrieve a amxp_subproc_t for a child process using it's process identifier.

Searches in the list of launched and running child processes for a child process with a specific process id and returns the amxp_subproc_t pointer representing the child process.

Parameters

pid	Process id of the child process

Returns

pointer to amxp_subproc_t that represents the child process or NULL when no child process with the give pid is found.

Definition at line 402 of file amxp_subproc.c.

                                                 {
    amxp_subproc_t* subproc = NULL;
    amxc_llist_for_each(it, (&amxp_subprocs)) {
        subproc = amxc_llist_it_get_data(it, amxp_subproc_t, it);
        if(subproc->pid == pid) {
            break;
        }
        subproc = NULL;
    }
 
    return subproc;
}

amxp_subproc_get_exitstatus()

int amxp_subproc_get_exitstatus

(

amxp_subproc_t *

subproc

)

Gets the exit code of the child process.

If the value of WIFEXITED(stat_val) is non-zero, this function evaluates to the low-order 8 bits of the status argument that the child process passed to _exit() or exit(), or the value the child process returned from main().

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

Child process exit code

Definition at line 537 of file amxp_subproc.c.

                                                         {
    int retval = -1;
 
    when_null(subproc, exit);
 
    retval = WEXITSTATUS(subproc->status);
exit:
    return retval;
}

amxp_subproc_get_pid()

pid_t amxp_subproc_get_pid

(

const amxp_subproc_t *const

subproc

)

Get the PID of a child process.

When the provide amxp_subproc_t is not representing a running child process the return pid is 0.

Parameters

subproc

ponter to the amxp_subproc_t structure

Returns

Process id of the child process, or 0 when not running

Definition at line 415 of file amxp_subproc.c.

                                                                {
    return subproc != NULL ? subproc->pid : -1;
}

amxp_subproc_get_sigmngr()

amxp_signal_mngr_t* amxp_subproc_get_sigmngr

(

const amxp_subproc_t *const

subproc

)

Get the Signal managers of the child process.

Using the signal manager callback functions (Slots) can be connected to the child process.

The child process will trigger signal "stop" when it exits. The data of the signal will contain all the Linux system signal information.

See also

Signal/Slots for more information about the Ambiorix signal/slot mechanism (observer)

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

Pointer to the signal manager (amxp_signal_mngr_t)

Definition at line 419 of file amxp_subproc.c.

                                                                                  {
    return subproc != NULL ? subproc->sigmngr : NULL;
}

amxp_subproc_get_termsig()

int amxp_subproc_get_termsig

(

amxp_subproc_t *

subproc

)

Gets the Linux signal id that caused the child process to stop.

If the value of WIFSIGNALED(stat_val) is non-zero, this function evaluates to the number of the signal that caused the termination of the child process.

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

Signal id that caused the child process to stop

Definition at line 547 of file amxp_subproc.c.

                                                      {
    int retval = -1;
 
    when_null(subproc, exit);
 
    retval = WTERMSIG(subproc->status);
exit:
    return retval;
}

amxp_subproc_ifexited()

int amxp_subproc_ifexited

(

amxp_subproc_t *

subproc

)

Checks if the child process terminated normally.

Evaluates to a non-zero value if status was returned for a child process that terminated normally.

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

non-zero value if status was returned for a child process that terminated normally.

Definition at line 517 of file amxp_subproc.c.

                                                   {
    int retval = -1;
 
    when_null(subproc, exit);
 
    retval = WIFEXITED(subproc->status);
exit:
    return retval;
}

amxp_subproc_ifsignaled()

int amxp_subproc_ifsignaled

(

amxp_subproc_t *

subproc

)

Checks if the child process was stopped because of an uncaught Linux signal.

Evaluates to a non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see <signal.h>).

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught.

Definition at line 527 of file amxp_subproc.c.

                                                     {
    int retval = -1;
 
    when_null(subproc, exit);
 
    retval = WIFSIGNALED(subproc->status);
exit:
    return retval;
}

amxp_subproc_is_running()

bool amxp_subproc_is_running

(

const amxp_subproc_t *const

subproc

)

Checks if the child process is running.

Returns true when the child process is running

Parameters

subproc

pointer to the amxp_subproc_t structure

Returns

true when running, false otherwise

Definition at line 423 of file amxp_subproc.c.

                                                                  {
    return subproc != NULL ? subproc->is_running : false;
}

amxp_subproc_kill()

int amxp_subproc_kill	(	const amxp_subproc_t *const	subproc,
		const int	sig
	)

Sends a Linux signal to the child process.

When the child process is not running this function has no effect.

Note

When stopping a child process make sure that the SIGCHILD is correctly handled. This can be done using amxp_subproc_wait.

Example:

amxp_subproc_kill(subproc, SIGTERM);
amxp_subproc_wait(subproc, 2);

Parameters

subproc	pointer to the subproc
sig	the signal id

Returns

0 when signal is send successful, any other value when an error occurred.

Definition at line 391 of file amxp_subproc.c.

                                                                          {
    int retval = -1;
    when_null(subproc, exit);
    when_true(!subproc->is_running, exit);
 
    retval = kill(subproc->pid, sig);
 
exit:
    return retval;
}

amxp_subproc_new()

int amxp_subproc_new

(

amxp_subproc_t **

subproc

)

Constructor function, creates a new child process data structure.

This function allocates memory, to free the allocated memory use the destruction function amxp_subproc_delete

The *subproc argument must be initialized to NULL before calling this function.

This function doesn't start the child process. To start a child process use amxp_subproc_vstart or amxp_subproc_start.

Parameters

subproc

where to store the subproc pointer

Returns

0 when successful, otherwise an error code

Definition at line 215 of file amxp_subproc.c.

                                               {
    int retval = -1;
    when_null(subproc, exit);
    when_not_null(*subproc, exit);
 
    *subproc = (amxp_subproc_t*) calloc(1, sizeof(amxp_subproc_t));
    when_null(*subproc, exit);
 
    for(int i = 0; i < AMXP_SUB_PROC_NR_PIPES; i++) {
        (*subproc)->fd[i][AMXP_SUBPROC_FD_PARENT] = -1;
        (*subproc)->fd[i][AMXP_SUBPROC_FD_CHILD] = -1;
    }
 
    amxp_sigmngr_new(&(*subproc)->sigmngr);
    amxp_sigmngr_add_signal((*subproc)->sigmngr, "stop");
 
    amxc_llist_append(&amxp_subprocs, &(*subproc)->it);
 
    retval = 0;
 
exit:
    return retval;
}

amxp_subproc_open_fd()

int amxp_subproc_open_fd	(	amxp_subproc_t *	subproc,
		int	requested
	)

Opens standard file descriptor to the child process.

It is possible to read the child stdout or stderr to monitor it's output or to write to the child stdin file descriptor.

Parameters

subproc	pointer to the subproc
requested	must be one of STDIN_FILENO, STDOUT_FILENO or STDERR_FILENO

Returns

The opened file descriptor or -1 when an error occurred

Definition at line 263 of file amxp_subproc.c.

                                                                 {
    int retval = -1;
    when_null(subproc, exit);
    when_true(requested < STDIN_FILENO ||
              requested > STDERR_FILENO, exit)
 
    if(subproc->fd[requested][AMXP_SUBPROC_FD_PARENT] < 0) {
        if(pipe2(subproc->fd[requested], O_NONBLOCK | O_CLOEXEC) < 0) {
            return -1;
        }
        if(requested == STDIN_FILENO) {
            int swap = subproc->fd[STDIN_FILENO][0];
            subproc->fd[STDIN_FILENO][0] = subproc->fd[STDIN_FILENO][1];
            subproc->fd[STDIN_FILENO][1] = swap;
        }
        retval = subproc->fd[requested][AMXP_SUBPROC_FD_PARENT];
    } else {
        retval = subproc->fd[requested][AMXP_SUBPROC_FD_PARENT];
    }
 
exit:
    return retval;
}

amxp_subproc_start()

int amxp_subproc_start	(	amxp_subproc_t *const	subproc,
		char *	cmd,
			...
	)

Start a child process.

Forks and executes a command. Will monitor the child process and handles SIGCHLD.

The process name and it's arguments must be passed as individual arguments to this function. The last argument must be a NULL pointer.

Example:

amxp_subproc_start(subproc, (char*)"dropbear", "-p", "10022", "-F", "-E", "-R", NULL);

Parameters

subproc	pointer to the subproc
cmd	the child process

Returns

0 when child process is launched, any other value when an error occurred

Definition at line 330 of file amxp_subproc.c.

                            {
    int retval = -1;
    va_list ap;
    int argc = 0;
    char** argv = NULL;
    when_null(subproc, exit);
    when_null(cmd, exit);
    when_true(subproc->is_running, exit);
 
    va_start(ap, cmd);
    while(va_arg(ap, char*)) {
        argc++;
    }
    va_end(ap);
 
    argv = (char**) calloc(argc + 2, sizeof(char*));
    when_null(argv, exit);
 
    va_start(ap, cmd);
    // By convention, the first argument is always the executable name
    argv[0] = cmd;
    for(int i = 1; i <= argc; i++) {
        argv[i] = va_arg(ap, char*);
    }
    va_end(ap);
 
    retval = amxp_subproc_vstart(subproc, argv);
    free(argv);
 
exit:
    return retval;
}

amxp_subproc_start_wait()

int amxp_subproc_start_wait	(	amxp_subproc_t *	subproc,
		int	timeout_msec,
		char *	cmd,
			...
	)

Starts a child process and waits until it exits.

This function is blocking and will return either when the child process has exited or when a timeout occurs.

When the child process was not able to start an error is returned

This function calls amxp_subproc_vstart_wait to launch the child process and to wait until the child exits.

Parameters

subproc	pointer to the subproc
timeout_msec	time out in milli seconds
cmd	the command used to launch the child process

Returns

-1 - an error occurred 0 child launched and exited 1 timeout reached, child is still running

Definition at line 480 of file amxp_subproc.c.

                                                                                       {
    int retval = -1;
 
    va_list ap;
    int argc = 0;
    char** argv = NULL;
 
    when_null(subproc, exit);
    when_null(cmd, exit);
 
    va_start(ap, cmd);
    while(va_arg(ap, char*)) {
        argc++;
    }
    va_end(ap);
 
    argv = (char**) calloc(argc + 2, sizeof(char*));
    when_null(argv, exit);
 
    va_start(ap, cmd);
    // By convention, the first argument is always the executable name
    argv[0] = cmd;
    for(int i = 1; i <= argc; i++) {
        argv[i] = va_arg(ap, char*);
    }
    va_end(ap);
 
    retval = amxp_subproc_vstart_wait(subproc, timeout_msec, argv);
    when_failed(retval, exit_free);
 
    retval = 0;
exit_free:
    free(argv);
exit:
    return retval;
}

amxp_subproc_vstart()

int amxp_subproc_vstart	(	amxp_subproc_t *const	subproc,
		char **	argv
	)

Start a child process.

Forks and executes a command. Will monitor the child process and handles SIGCHLD.

The process name and it's arguments must be passed as an array of strings, the last item in the array must be a NULL pointer.

Example:

const char* cmd[] = { "dropbear", "-p", "10022", "-F", "-E", "-R", NULL };
amxp_subproc_vstart(subproc, (char **) cmd);

Parameters

subproc	pointer to the subproc
argv	the child process and its arguments

Returns

0 when child process is launched, any other value when an error occurred

Definition at line 288 of file amxp_subproc.c.

                                     {
    int retval = -1;
    pid_t pid = 0;
    sigset_t original_mask;
    sigset_t block_mask;
 
    when_null(subproc, exit);
    when_null(argv, exit);
    when_null(*argv, exit);
    when_true(subproc->is_running, exit);
 
    sigfillset(&block_mask);
    sigprocmask(SIG_SETMASK, &block_mask, &original_mask);
 
    pid = fork();
    if(pid > 0) {
        waitpid(pid, NULL, WNOHANG);
        sigprocmask(SIG_SETMASK, &original_mask, NULL);
        amxp_syssig_enable(SIGCHLD, true);
        amxp_slot_connect(NULL,
                          strsignal(SIGCHLD),
                          NULL,
                          amxp_subproc_sigchild,
                          NULL);
        subproc->pid = pid;
        subproc->is_running = true;
        subproc->status = 0;
        retval = 0;
        goto exit;
    } else if(pid == -1) {
        goto exit;
    }
 
    amxp_subproc_exec_child(subproc, argv);
 
    retval = 0;
 
exit:
    return retval;
}

amxp_subproc_vstart_wait()

int amxp_subproc_vstart_wait	(	amxp_subproc_t *	subproc,
		int	timeout_msec,
		char **	cmd
	)

Starts a child process and waits until it exits.

This function is blocking and will return either when the child process has exited or when a timeout occurs.

When the child process was not able to start an error is returned

This function first launches the child process by calling amxp_subproc_vstart and then waits until it exits using amxp_subproc_wait.

Parameters

subproc	pointer to the subproc
timeout_msec	time out in milli seconds
cmd	the command used to launch the child process

Returns

-1 - an error occurred 0 child launched and exited 1 timeout reached, child is still running

Definition at line 466 of file amxp_subproc.c.

                                                                                    {
    int retval = -1;
 
    retval = amxp_subproc_vstart(subproc, cmd);
    when_failed(retval, exit);
 
    retval = amxp_subproc_wait(subproc, timeout_msec);
    when_failed(retval, exit);
 
    retval = 0;
exit:
    return retval;
}

amxp_subproc_wait()

int amxp_subproc_wait	(	amxp_subproc_t *	subproc,
		int	timeout_msec
	)

Waits until the child process has stopped.

This function is blocking and will return either when the child process has stopped or when a timeout occurs.

Parameters

subproc	pointer to the subproc
timeout_msec	time out in milli-seconds

Returns

-1 - an error occurred 0 child exited 1 timeout reached, child is still running

Definition at line 428 of file amxp_subproc.c.

                                                                 {
    int retval = -1;
    int err;
    struct pollfd pollfd;
    struct timespec start;
    int remaining_timeout_msec = timeout_msec;
 
    when_null(subproc, exit);
 
    pollfd.fd = amxp_syssig_get_fd();
    pollfd.events = POLLIN;
 
    err = clock_gettime(CLOCK_REALTIME, &start);
    when_failed(err, exit);
 
    while(amxp_subproc_is_running(subproc)) {
        err = poll(&pollfd, 1, remaining_timeout_msec);
        if(err == 0) {
            retval = 1;
            goto exit;
        } else if(err > 0) {
            amxp_syssig_read();
            if(!amxp_subproc_is_running(subproc)) {
                break;
            }
        }
 
        if(remaining_timeout_msec > 0) {
            remaining_timeout_msec = amxp_recalculate_timeout(&start, timeout_msec);
        }
    }
 
    retval = 0;
 
exit:
    return retval;
}