TAPI for standard I/O calls

Overview

// typedefs

typedef rpc_ptr rpc_file_p;

// global functions

int rpc_fileno(rcf_rpc_server* rpcs, rpc_file_p f);
rpc_file_p rpc_fopen(rcf_rpc_server* rpcs, const char* path, const char* mode);
rpc_file_p rpc_fdopen(rcf_rpc_server* rpcs, int fd, const char* mode);
int rpc_fclose(rcf_rpc_server* rpcs, rpc_file_p file);
rpc_wait_status rpc_system(rcf_rpc_server* rpcs, const char* cmd);
rpc_wait_status rpc_system_ex(rcf_rpc_server* rpcs, const char* cmd, ...);
rpc_file_p rpc_popen(rcf_rpc_server* rpcs, const char* cmd, const char* mode);
int rpc_pclose(rcf_rpc_server* rpcs, rpc_file_p file);
rpc_wait_status rpc_shell_get_all(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, tarpc_uid_t uid, ...);
rpc_wait_status rpc_shell_get_all2(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, ...);
rpc_wait_status rpc_shell_get_all3(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, ...);
tarpc_pid_t rpc_te_shell_cmd(rcf_rpc_server* rpcs, const char* cmd, tarpc_uid_t uid, int* in_fd, int* out_fd, int* err_fd, ...);
char* rpc_getenv(rcf_rpc_server* rpcs, const char* name);
static int rpc_getenv_int(rcf_rpc_server* rpcs, const char* name, int* val);
int rpc_setenv(rcf_rpc_server* rpcs, const char* name, const char* value, int overwrite);
int rpc_unsetenv(rcf_rpc_server* rpcs, const char* name);

// macros

#define RPC_SHELL_CMDLINE_MAX

Detailed Documentation

Typedefs

typedef rpc_ptr rpc_file_p

‘FILE *’ equivalent

Global Functions

int rpc_fileno(rcf_rpc_server* rpcs, rpc_file_p f)

Query the descriptor of the given file on RPC server side.

See fileno manual page for more information

Parameters:

rpcs	RPC server handle
f	file stream

Returns:

The stream file descriptor, otherwise -1 when error occurred

rpc_file_p rpc_fopen(rcf_rpc_server* rpcs, const char* path, const char* mode)

Open a file on RPC server side and associate it with a stream.

See fopen manual page for more information

Parameters:

rpcs	RPC server handle
path	file name
mode	type of file access

Returns:

Stream associated with the file name, otherwise NULL on error

rpc_file_p rpc_fdopen(rcf_rpc_server* rpcs, int fd, const char* mode)

Open a file on RPC server side and associate it with a stream.

See fdopen manual page for more information

Parameters:

rpcs	RPC server handle
fd	file descriptor
mode	type of file access

Returns:

Stream associated with the file name, otherwise NULL on error

int rpc_fclose(rcf_rpc_server* rpcs, rpc_file_p file)

Close the stream associated with the file.

Parameters:

rpcs	RPC server handle
file	Stream to close

Returns:

Zero on success, otherwise -1.

rpc_wait_status rpc_system(rcf_rpc_server* rpcs, const char* cmd)

Execute shell command on the IPC server. You SHOULD not use this function unless you are sure that shell command will exit normally. If this RPC will timeout, you’ll have no chance to kill the child process, because you do not know its PID.

Parameters:

rpcs	RPC server handle
cmd	the command to be executed

Returns:

status of the process

rpc_wait_status rpc_system_ex(rcf_rpc_server* rpcs, const char* cmd, ...)

Execute shell command on the IPC server. You SHOULD not use this function unless you are sure that shell command will exit normally. If this RPC will timeout, you’ll have no chance to kill the child process, because you do not know its PID.

Parameters:

rpcs	RPC server handle
cmd	format of the command to be executed
…	parameters for the command format

Returns:

status of the process

rpc_file_p rpc_popen(rcf_rpc_server* rpcs, const char* cmd, const char* mode)

Open a process by creating a pipe, forking, and invoking the shell.

Do not use this function unless you test it - use rpc_te_shell_cmd instead.

Parameters:

rpcs	RPC server handle
cmd	NULL-terminated shell command line
mode	“r” (for reading command output) or “w” (for writing to command standard input)

Returns:

Stream to be used for reading or writing or NULL on error

int rpc_pclose(rcf_rpc_server* rpcs, rpc_file_p file)

Close the stream returned by popen().

Parameters:

rpcs	RPC server handle
file	Stream to close

Returns:

Zero on success, otherwise -1

rpc_wait_status rpc_shell_get_all(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, tarpc_uid_t uid, ...)

Execute shell command on the IPC server and read the output. The routine allocates memory for the output buffer and places null-terminated string to it. pbuf pointer is initialized by NULL if no buffer is allocated.

Parameters:

rpcs	RPC server handle
pbuf	location for the command output buffer
cmd	format of the command to be executed
uid	user id to execute as
…	parameters for command

Returns:

status of the process

rpc_wait_status rpc_shell_get_all2(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, ...)

Execute shell command on the IPC server and read the output. Fail if there was anything on stderr. The routine allocates memory for the output buffer and places null-terminated string to it. pbuf pointer is initialized by NULL if no buffer is allocated. If pbuf is NULL, stdout is not redirected.

Parameters:

rpcs	RPC server handle
pbuf	location for the command output
cmd	format of the command to be executed
…	parameters for command

Returns:

status of the process

rpc_wait_status rpc_shell_get_all3(rcf_rpc_server* rpcs, char** pbuf, const char* cmd, ...)

Execute shell command on the IPC server and read the output and stderr. The routine allocates memory for the output buffers and places null-terminated strings to them. pbuf [0] and pbuf[1] pointers are initialized by NULL if no buffer are allocated. If pbuf is NULL, stdout is not redirected.

Parameters:

rpcs	RPC server handle
pbuf	array of locations for the command output and stderr
cmd	format of the command to be executed
…	parameters for command

Returns:

status of the process

tarpc_pid_t rpc_te_shell_cmd(rcf_rpc_server* rpcs, const char* cmd, tarpc_uid_t uid, int* in_fd, int* out_fd, int* err_fd, ...)

Execute command on the RPC server as a given user and redirect stdin/stdout to pipe(s) if necessary. You MUST use uid parameter instead of “su - user -c”, because su makes one more fork, and you do not know how to kill this grandchild process. You SHOULD destroy this process by calling rpc_ta_kill_death() instead of rpc_kill(RPC_SIGKILL).

Parameters:

rpcs	RPC server handle
cmd	command format to execute
uid	user to run as
in_fd	location to store pipe to stdin or NULL
out_fd	location to store pipe to stdout or NULL
err_fd	location to store pipe to stderr or NULL
…	parameters to command format

Returns:

pid of spawned process or -1 on failure

char* rpc_getenv(rcf_rpc_server* rpcs, const char* name)

Get environment variable.

Parameters:

rpcs	RPC server handle
name	variable name

Returns:

variable value (memory is allocated by the function) or NULL

static int rpc_getenv_int(rcf_rpc_server* rpcs, const char* name, int* val)

Get integer environment variable.

Parameters:

rpcs	RPC server handle
name	Variable name
val	Value location

Returns:

0 on success, otherwise -1

int rpc_setenv(rcf_rpc_server* rpcs, const char* name, const char* value, int overwrite)

Add the variable with specified value to the environment or change value of the existing variable.

Parameters:

rpcs	RPC server handle
name	variable name
value	new value
overwrite	0, value of the existing variable is not changed

Returns:

variable value (memory is allocated by the function) or NULL

int rpc_unsetenv(rcf_rpc_server* rpcs, const char* name)

Remove environment variable.

Parameters:

rpcs	RPC server handle
name	variable name

Returns:

return code

Macros

#define RPC_SHELL_CMDLINE_MAX

Maximum resulting command length for rpc_shell()