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) __attribute__((__nonnull__(1
 Start a command from a command string.
int 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.

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.

Define Documentation

#define RUNCMD_HAS_REDIR   (1 << 0)

Return code bitflags for runcmd_cmd2strv().

I/O redirection


Function Documentation

int int runcmd_close ( int  fd  ) 

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] fd The child's stdout filedescriptor
Returns:
exit-status of the child, or -1 in case of errors
int runcmd_cmd2strv ( const char *  str,
int *  out_argc,
char **  out_argv 
)

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] str The string to convert to an argument vector
[out] out_argc The number of arguments found
[out] out_argv The 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.
void runcmd_init ( void   ) 

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.

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

Start a command from a command string.

Parameters:
[in] cmdstring The command to launch
[out] pfd Child's stdout filedescriptor
[out] pfderr Child's stderr filedescriptor
[in] env Currently ignored for portability
[in] iobreg The callback function to register the iobrokers for the read ends of the pipe
[in] iobregarg The "arg" value to pass to iobroker_register()
pid_t runcmd_pid ( int  fd  ) 

Return pid of a command with a specific file descriptor.

Parameters:
[in] fd stdout filedescriptor of the child to get pid from
Returns:
pid of the child, or 0 on errors
const char* runcmd_strerror ( int  code  ) 

Return explanation of which system call or operation failed.

Parameters:
code Error code returned by a library function
Returns:
A non-free()'able string explaining where the error occurred
 All Data Structures Files Functions Variables Typedefs Defines

Generated on 16 Apr 2015 for Nagios by  doxygen 1.6.1