Nagios
4.0.8
Dev docs for Nagios core and neb-module hackers
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Macros
Pages
lib
runcmd.h
Go to the documentation of this file.
1
#ifndef LIBNAGIOS_runcmd_h__
2
#define LIBNAGIOS_runcmd_h__
3
#include <signal.h>
4
5
/**
6
* @file runcmd.h
7
* @brief runcmd library function declarations
8
*
9
* A simple interface to executing programs from other programs, using an
10
* optimized and safer popen()-like implementation. It is considered safer in
11
* that no shell needs to be spawned for simple commands, and the environment
12
* passed to the execve()'d program is essentially empty.
13
*
14
* This code is based on popen.c, which in turn was taken from
15
* "Advanced Programming in the UNIX Environment" by W. Richard Stevens.
16
*
17
* Care has been taken to make sure the functions are async-safe. The exception
18
* is runcmd_init() which multithreaded applications or plugins must call in a
19
* non-reentrant manner before calling any other runcmd function.
20
*
21
* @note This is inherited from the nagiosplugins project, although
22
* it might need refactoring for performance later.
23
* @{
24
*/
25
26
/** Return code bitflags for runcmd_cmd2strv() */
27
#define RUNCMD_HAS_REDIR (1 << 0)
/**< I/O redirection */
28
#define RUNCMD_HAS_SUBCOMMAND (1 << 1)
/**< subcommands present */
29
#define RUNCMD_HAS_PAREN (1 << 2)
/**< parentheses present in command */
30
#define RUNCMD_HAS_JOBCONTROL (1 << 3)
/**< job control stuff present */
31
#define RUNCMD_HAS_UBSQ (1 << 4)
/**< unbalanced single quotes */
32
#define RUNCMD_HAS_UBDQ (1 << 5)
/**< unbalanced double quotes */
33
#define RUNCMD_HAS_WILDCARD (1 << 6)
/**< wildcards present */
34
#define RUNCMD_HAS_SHVAR (1 << 7)
/**< shell variables present */
35
36
37
#define RUNCMD_EFD (-1)
/**< Failed to pipe() or open() */
38
#define RUNCMD_EALLOC (-2)
/**< Failed to alloc */
39
#define RUNCMD_ECMD (-3)
/**< Bad command */
40
#define RUNCMD_EFORK (-4)
/**< Failed to fork() */
41
#define RUNCMD_EINVAL (-5)
/**< Invalid parameters */
42
#define RUNCMD_EWAIT (-6)
/**< Failed to wait() */
43
44
/**
45
* Initialize the runcmd library.
46
*
47
* Only multi-threaded programs that might launch the first external
48
* program from multiple threads simultaneously need to bother with
49
* this, and they must ensure this is called at least once in a non-reentrant
50
* manner before calling any other runcmd function.
51
*/
52
extern
void
runcmd_init
(
void
);
53
54
/**
55
* Return pid of a command with a specific file descriptor
56
* @param[in] fd stdout filedescriptor of the child to get pid from
57
* @return pid of the child, or 0 on errors
58
*/
59
extern
pid_t
runcmd_pid
(
int
fd);
60
61
/**
62
* Return explanation of which system call or operation failed
63
* @param code Error code returned by a library function
64
* @return A non-free()'able string explaining where the error occurred
65
*/
66
extern
const
char
*
runcmd_strerror
(
int
code);
67
68
/**
69
* Start a command from a command string
70
* @param[in] cmdstring The command to launch
71
* @param[out] pfd Child's stdout filedescriptor
72
* @param[out] pfderr Child's stderr filedescriptor
73
* @param[in] env Currently ignored for portability
74
* @param[in] iobreg The callback function to register the iobrokers for the read ends of the pipe
75
* @param[in] iobregarg The "arg" value to pass to iobroker_register()
76
*/
77
extern
int
runcmd_open
(
const
char
*cmd,
int
*pfd,
int
*pfderr,
char
**env,
78
void
(*iobreg)(
int
,
int
,
void
*),
void
*iobregarg)
79
__attribute__((__nonnull__(1, 2, 3, 5, 6)));
80
81
/**
82
* Close a command and return its exit status
83
* @note Don't use this. It's a retarded way to reap children suitable
84
* only for launching a one-shot program.
85
*
86
* @param[in] fd The child's stdout filedescriptor
87
* @return exit-status of the child, or -1 in case of errors
88
*/
89
extern
int
runcmd_close
(
int
fd);
90
91
/**
92
* Convert a string to a vector of arguments like a shell would
93
* @note This might have bugs and is only tested to behave similar
94
* to how /bin/sh does things. For csh or other non bash-ish shells
95
* there are no guarantees.
96
* @note The out_argv array has to be large enough to hold all strings
97
* found in the command.
98
* @param[in] str The string to convert to an argument vector
99
* @param[out] out_argc The number of arguments found
100
* @param[out] out_argv The argument vector
101
* @return 0 on (great) success, or a bitmask of failure-codes
102
* representing f.e. unclosed quotes, job control or output redirection.
103
* See the RUNCMD_HAS_* and their ilk to find out about the flag.
104
*/
105
extern
int
runcmd_cmd2strv
(
const
char
*str,
int
*out_argc,
char
**out_argv);
106
107
/** @} */
108
/* INCLUDE_runcmd_h__ */
109
#endif
Generated on Wed Jul 22 2015 17:54:38 for Nagios by
1.8.3.1