Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
runcmd.h File Reference

runcmd library function declarations More...

#include <signal.h>

Go to the source code of this file.

#define RUNCMD_HAS_REDIR   (1 << 0)
 Return code bitflags for runcmd_cmd2strv()
 
#define RUNCMD_HAS_SUBCOMMAND   (1 << 1)
 subcommands present
 
#define RUNCMD_HAS_PAREN   (1 << 2)
 parentheses present in command
 
#define RUNCMD_HAS_JOBCONTROL   (1 << 3)
 job control stuff present
 
#define RUNCMD_HAS_UBSQ   (1 << 4)
 unbalanced single quotes
 
#define RUNCMD_HAS_UBDQ   (1 << 5)
 unbalanced double quotes
 
#define RUNCMD_HAS_WILDCARD   (1 << 6)
 wildcards present
 
#define RUNCMD_HAS_SHVAR   (1 << 7)
 shell variables present
 
#define RUNCMD_EFD   (-1)
 Failed to pipe() or open()
 
#define RUNCMD_EALLOC   (-2)
 Failed to alloc.
 
#define RUNCMD_ECMD   (-3)
 Bad command.
 
#define RUNCMD_EFORK   (-4)
 Failed to fork()
 
#define RUNCMD_EINVAL   (-5)
 Invalid parameters.
 
#define RUNCMD_EWAIT   (-6)
 Failed to wait()
 
void runcmd_init (void)
 Initialize the runcmd library.
 
pid_t runcmd_pid (int fd)
 Return pid of a command with a specific file descriptor.
 
const char * runcmd_strerror (int code)
 Return explanation of which system call or operation failed.
 
int runcmd_open (const char *cmd, int *pfd, int *pfderr, char **env, void(*iobreg)(int, int, void *), void *iobregarg)
 Start a command from a command string.
 
int runcmd_close (int fd)
 Close a command and return its exit status.
 
int runcmd_cmd2strv (const char *str, int *out_argc, char **out_argv)
 Convert a string to a vector of arguments like a shell would.
 
void runcmd_free_pids (void)
 If you're using libnagios to execute a remote command, the static pid_t pids is not freed after runcmd_open You can call this function when you're sure pids is no longer in use, to keep down memory leaks.
 

Detailed Description

runcmd library function declarations

A simple interface to executing programs from other programs, using an optimized and safer popen()-like implementation. It is considered safer in that no shell needs to be spawned for simple commands, and the environment passed to the execve()'d program is essentially empty.

This code is based on popen.c, which in turn was taken from "Advanced Programming in the UNIX Environment" by W. Richard Stevens.

Care has been taken to make sure the functions are async-safe. The exception is runcmd_init() which multithreaded applications or plugins must call in a non-reentrant manner before calling any other runcmd function.

Note
This is inherited from the nagiosplugins project, although it might need refactoring for performance later.

Macro Definition Documentation

◆ RUNCMD_HAS_REDIR

#define RUNCMD_HAS_REDIR   (1 << 0)

Return code bitflags for runcmd_cmd2strv()

I/O redirection

Function Documentation

◆ runcmd_close()

int runcmd_close ( int fd)
extern

Close a command and return its exit status.

Note
Don't use this. It's a retarded way to reap children suitable only for launching a one-shot program.
Parameters
[in]fdThe child's stdout filedescriptor
Returns
exit-status of the child, or -1 in case of errors

◆ runcmd_cmd2strv()

int runcmd_cmd2strv ( const char * str,
int * out_argc,
char ** out_argv )
extern

Convert a string to a vector of arguments like a shell would.

Note
This might have bugs and is only tested to behave similar to how /bin/sh does things. For csh or other non bash-ish shells there are no guarantees.
The out_argv array has to be large enough to hold all strings found in the command.
Parameters
[in]strThe string to convert to an argument vector
[out]out_argcThe number of arguments found
[out]out_argvThe argument vector
Returns
0 on (great) success, or a bitmask of failure-codes representing f.e. unclosed quotes, job control or output redirection. See the RUNCMD_HAS_* and their ilk to find out about the flag.

◆ runcmd_init()

void runcmd_init ( void )
extern

Initialize the runcmd library.

Only multi-threaded programs that might launch the first external program from multiple threads simultaneously need to bother with this, and they must ensure this is called at least once in a non-reentrant manner before calling any other runcmd function.

◆ runcmd_open()

int runcmd_open ( const char * cmd,
int * pfd,
int * pfderr,
char ** env,
void(* iobreg )(int, int, void *),
void * iobregarg )
extern

Start a command from a command string.

Parameters
[in]cmdThe command to launch
[out]pfdChild's stdout filedescriptor
[out]pfderrChild's stderr filedescriptor
[in]envCurrently ignored for portability
[in]iobregThe callback function to register the iobrokers for the read ends of the pipe
[in]iobregargThe "arg" value to pass to iobroker_register()

◆ runcmd_pid()

pid_t runcmd_pid ( int fd)
extern

Return pid of a command with a specific file descriptor.

Parameters
[in]fdstdout filedescriptor of the child to get pid from
Returns
pid of the child, or 0 on errors

◆ runcmd_strerror()

const char * runcmd_strerror ( int code)
extern

Return explanation of which system call or operation failed.

Parameters
codeError code returned by a library function
Returns
A non-free()'able string explaining where the error occurred