Asynchronous exec. More...

#include <freeradius-devel/server/request.h>
#include <freeradius-devel/util/pair.h>
#include <freeradius-devel/util/talloc.h>
#include <sys/types.h>

Include dependency graph for exec.h:

Go to the source code of this file.

Data Structures
struct	fr_exec_state_t

Macros
#define	EXEC_TIMEOUT 10
	Default wait time for exec calls (in seconds). More...

Enumerations
enum	fr_exec_fail_t { FR_EXEC_FAIL_NONE = 0 , FR_EXEC_FAIL_TOO_MUCH_DATA , FR_EXEC_FAIL_TIMEOUT }

Low level interface
These functions are used both by fr_exec_oneshot function, and any code which needs a lower level interface for execing external programs. In the case of fr_exec_fork_wait, the caller is responsible for installing I/O handlers, cleaning up file descriptors returned, and reaping the process.
int	fr_exec_fork_nowait (fr_event_list_t el, char argv_in, char *env_in, bool env_inherit, bool debug)
	Execute a program without waiting for the program to finish. More...

int	fr_exec_fork_wait (pid_t pid_p, int stdin_fd, int stdout_fd, int stderr_fd, char argv_in, char env_usr, bool env_inherit, bool debug)
	Execute a program assuming that the caller waits for it to finish. More...

char **	fr_exec_pair_to_env (request_t request, fr_pair_list_t env_pairs, bool env_escape)
	Convert env_pairs into an array of environmental variables using thread local buffers. More...

int	fr_exec_value_box_list_to_argv (TALLOC_CTX ctx, char *argv_p, fr_value_box_list_t const in)
	Flatten a list into individual "char *" argv-style array. More...

High level interface
These functions allow easy processing of oneshot exec calls.
int	fr_exec_oneshot (TALLOC_CTX ctx, fr_exec_state_t exec, request_t request, fr_value_box_list_t args, fr_pair_list_t env_pairs, bool env_escape, bool env_inherit, bool need_stdin, bool store_stdout, TALLOC_CTX stdout_ctx, fr_time_delta_t timeout)
	Call an child program, optionally reading it's output. More...

void	fr_exec_oneshot_cleanup (fr_exec_state_t *exec, int signal)
	Cleans up an exec'd process on error. More...

int	fr_exec_oneshot_nowait (request_t request, fr_value_box_list_t args, fr_pair_list_t *env_pairs, bool env_escape, bool env_inherit)
	Similar to fr_exec_oneshot, but does not attempt to parse output. More...

Detailed Description

Asynchronous exec.

Id: 7f5335e8e504121f52f0f1d4909d63700993ebb8

Copyright: 2014 The FreeRADIUS server project

Definition in file exec.h.

Data Structure Documentation

◆ fr_exec_state_t

struct fr_exec_state_t

Definition at line 53 of file exec.h.

Collaboration diagram for fr_exec_state_t:

Data Fields
fr_pair_list_t *	env_pairs	input VPs. These are inserted into the environment of the child as environmental variables.
fr_event_timer_t const *	ev	for timing out the child
fr_event_pid_t const *	ev_pid	for cleaning up the process
fr_exec_fail_t	failed	what kind of failure
pid_t	pid	child PID
request_t *	request	request this exec is related to
int	status	return code of the program
int	stderr_fd	for producing error messages.
char	stderr_prefix[sizeof("pid -9223372036854775808 (stderr)")]
log_fd_event_ctx_t	stderr_uctx	Config for the stderr logger.
int	stdin_fd	for writing to the child.
bool	stdin_used	use stdin fd?
fr_sbuff_t	stdout_buff	Expandable buffer to store process output.
TALLOC_CTX *	stdout_ctx	ctx to allocate output buffers
int	stdout_fd	for reading from the child.
char	stdout_prefix[sizeof("pid -9223372036854775808 (stdout)")]
fr_sbuff_uctx_talloc_t	stdout_tctx	sbuff talloc ctx data.
log_fd_event_ctx_t	stdout_uctx	Config for the stdout logger.
bool	stdout_used	use stdout fd?

Macro Definition Documentation

◆ EXEC_TIMEOUT

#define EXEC_TIMEOUT 10

Default wait time for exec calls (in seconds).

Definition at line 32 of file exec.h.

Enumeration Type Documentation

◆ fr_exec_fail_t

enum fr_exec_fail_t

Enumerator
FR_EXEC_FAIL_NONE
FR_EXEC_FAIL_TOO_MUCH_DATA
FR_EXEC_FAIL_TIMEOUT

Definition at line 47 of file exec.h.

Function Documentation

◆ fr_exec_fork_nowait()

int fr_exec_fork_nowait	(	fr_event_list_t *	el,
		char **	argv_in,
		char **	env_in,
		bool	env_inherit,
		bool	debug
	)

Execute a program without waiting for the program to finish.

Parameters

[in]	el	event list to insert reaper child into.
[in]	argv_in	arg[0] is the path to the program, arg[...] are arguments to pass to the program.
[in]	env_in	any additional environmental variables to pass to the program.
[in]	env_inherit	Inherit the environment from the current process. This will be merged with any variables from env_pairs.
[in]	debug	If true, STDERR will be left open and pointing to the stderr descriptor of the parent.

Returns

<0 on error. Error retrievable fr_strerror().
0 on success

Todo:

maybe take an fr_dcursor_t instead of env_pairs? That would allow finer-grained control over the attributes to put into the environment.

Definition at line 461 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_fork_wait()

int fr_exec_fork_wait	(	pid_t *	pid_p,
		int *	stdin_fd,
		int *	stdout_fd,
		int *	stderr_fd,
		char **	argv_in,
		char **	env_in,
		bool	env_inherit,
		bool	debug
	)

Execute a program assuming that the caller waits for it to finish.

The caller takes responsibility for calling waitpid() on the returned PID.

The caller takes responsibility for reading from the returned FD, and closing it.

Parameters

[out]	pid_p	The PID of the child
[out]	stdin_fd	The stdin FD of the child.
[out]	stdout_fd	The stdout FD of the child.
[out]	stderr_fd	The stderr FD of the child.
[in]	argv_in	arg[0] is the path to the program, arg[...] are arguments to pass to the program.
[in]	env_in	Environmental variables to pass to the program.
[in]	env_inherit	Inherit the environment from the current process. This will be merged with any variables from env_pairs.
[in]	debug	If true, STDERR will be left open and pointing to the stderr descriptor of the parent, if no stderr_fd pointer is provided.

Returns

<0 on error. Error retrievable fr_strerror().
0 on success.

Todo:

maybe take an fr_dcursor_t instead of env_pairs? That would allow finer-grained control over the attributes to put into the environment.

Definition at line 528 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_oneshot()

int fr_exec_oneshot	(	TALLOC_CTX *	ctx,
		fr_exec_state_t *	exec,
		request_t *	request,
		fr_value_box_list_t *	args,
		fr_pair_list_t *	env_pairs,
		bool	env_escape,
		bool	env_inherit,
		bool	need_stdin,
		bool	store_stdout,
		TALLOC_CTX *	stdout_ctx,
		fr_time_delta_t	timeout
	)

Call an child program, optionally reading it's output.

Note: If the caller set need_stdin = true, it is the caller's responsibility to close exec->std_in and remove it from any event loops if this function returns 0 (success).

Parameters

[in]	ctx	to allocate events in.
[in,out]	exec	structure holding the state of the external call.
[in]	request	currently being processed, may be NULL.
[in]	args	to call as a fr_value_box_list_t. Program will be the first box and arguments in the subsequent boxes.
[in]	env_pairs	list of pairs to be presented as environment variables to the child.
[in]	env_escape	Wrap string values in double quotes, and apply doublequote escaping to all environmental variable values.
[in]	env_inherit	Inherit the environment from the current process. This will be merged with any variables from env_pairs.
[in]	need_stdin	If true, allocate a pipe that will allow us to send data to the process.
[in]	store_stdout	if true keep a copy of stdout in addition to logging it if RDEBUG_ENABLED2.
[in]	stdout_ctx	ctx to alloc stdout data in.
[in]	timeout	to wait for child to complete.

Returns

0 on success
-1 on failure

Definition at line 984 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_oneshot_cleanup()

void fr_exec_oneshot_cleanup	(	fr_exec_state_t *	exec,
		int	signal
	)

Cleans up an exec'd process on error.

This function is intended to be called at any point after a successful fr_exec_oneshot call in order to release resources and cleanup zombie processes.

Parameters

[in]	exec	state to cleanup.
[in]	signal	If non-zero, and we think the process is still running, send it a signal to cause it to exit. The PID reaper we insert here will cleanup its state so it doesn't become a zombie.

Definition at line 666 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_oneshot_nowait()

int fr_exec_oneshot_nowait	(	request_t *	request,
		fr_value_box_list_t *	args,
		fr_pair_list_t *	env_pairs,
		bool	env_escape,
		bool	env_inherit
	)

Similar to fr_exec_oneshot, but does not attempt to parse output.

Parameters

[in]	request	currently being processed, may be NULL.
[in]	args	to call as a fr_value_box_list_t. Program will be the first box and arguments in the subsequent boxes.
[in]	env_pairs	list of pairs to be presented as environment variables to the child.
[in]	env_escape	Wrap string values in double quotes, and apply doublequote escaping to all environmental variable values.
[in]	env_inherit	Inherit the environment from the current process. This will be merged with any variables from env_pairs.

Returns

0 on success.
-1 on error.

Definition at line 623 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_pair_to_env()

char** fr_exec_pair_to_env	(	request_t *	request,
		fr_pair_list_t *	env_pairs,
		bool	env_escape
	)

Convert env_pairs into an array of environmental variables using thread local buffers.

Parameters

[in]	request	Will be searched for control.Exec-Export pairs.
[in]	env_pairs	env_pairs to put into into the environment. May be NULL.
[in]	env_escape	Wrap string values in double quotes, and apply doublequote escaping to all environmental variable values.

Returns

An array of environmental variable definitions, valid until the next call to fr_exec_pair_to_env within the same thread.
NULL on error. Error retrievable fr_strerror().

Definition at line 258 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_exec_value_box_list_to_argv()

int fr_exec_value_box_list_to_argv	(	TALLOC_CTX *	ctx,
		char ***	argv_p,
		fr_value_box_list_t const *	in
	)

Flatten a list into individual "char *" argv-style array.

Parameters

[in]	ctx	to allocate boxes in.
[out]	argv_p	where output strings go
[in]	in	boxes to flatten

Returns

>= 0 number of array elements in argv
<0 on error

Definition at line 50 of file exec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Enumerations

Low level interface

High level interface

Detailed Description

Data Structure Documentation

◆ fr_exec_state_t

Macro Definition Documentation

◆ EXEC_TIMEOUT

Enumeration Type Documentation

◆ fr_exec_fail_t

Function Documentation

◆ fr_exec_fork_nowait()

◆ fr_exec_fork_wait()

◆ fr_exec_oneshot()

◆ fr_exec_oneshot_cleanup()

◆ fr_exec_oneshot_nowait()

◆ fr_exec_pair_to_env()

◆ fr_exec_value_box_list_to_argv()