Nagios  4.0.3
Dev docs for Nagios core and neb-module hackers
 All Data Structures Files Functions Variables Typedefs Macros Pages
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  * @note This is inherited from the nagiosplugins project, although
10  * I (AE) wrote the original code, and it might need refactoring
11  * for performance later.
12  * @{
13  */
14 
15 /** Return code bitflags for runcmd_cmd2strv() */
16 #define RUNCMD_HAS_REDIR (1 << 0) /**< I/O redirection */
17 #define RUNCMD_HAS_SUBCOMMAND (1 << 1) /**< subcommands present */
18 #define RUNCMD_HAS_PAREN (1 << 2) /**< parentheses present in command */
19 #define RUNCMD_HAS_JOBCONTROL (1 << 3) /**< job control stuff present */
20 #define RUNCMD_HAS_UBSQ (1 << 4) /**< unbalanced single quotes */
21 #define RUNCMD_HAS_UBDQ (1 << 5) /**< unbalanced double quotes */
22 #define RUNCMD_HAS_WILDCARD (1 << 6) /**< wildcards present */
23 #define RUNCMD_HAS_SHVAR (1 << 7) /**< shell variables present */
24 
25 
26 #define RUNCMD_EFD (-1) /**< Failed to pipe() or open() */
27 #define RUNCMD_EALLOC (-2) /**< Failed to alloc */
28 #define RUNCMD_ECMD (-3) /**< Bad command */
29 #define RUNCMD_EFORK (-4) /**< Failed to fork() */
30 #define RUNCMD_EINVAL (-5) /**< Invalid parameters */
31 #define RUNCMD_EWAIT (-6) /**< Failed to wait() */
32 
33 /**
34  * Initialize the runcmd library.
35  *
36  * Only multi-threaded programs that might launch the first external
37  * program from multiple threads simultaneously need to bother with
38  * this.
39  */
40 extern void runcmd_init(void);
41 
42 /**
43  * Return pid of a command with a specific file descriptor
44  * @param[in] fd stdout filedescriptor of the child to get pid from
45  * @return pid of the child, or 0 on errors
46  */
47 extern pid_t runcmd_pid(int fd);
48 
49 /**
50  * Return explanation of which system call or operation failed
51  * @param code Error code returned by a library function
52  * @return A non-free()'able string explaining where the error occurred
53  */
54 extern const char *runcmd_strerror(int code);
55 
56 /**
57  * Start a command from a command string
58  * @param[in] cmdstring The command to launch
59  * @param[out] pfd Child's stdout filedescriptor
60  * @param[out] pfderr Child's stderr filedescriptor
61  * @param[in] env Currently ignored for portability
62  * @param[in] iobreg The callback function to register the iobrokers for the read ends of the pipe
63  * @param[in] iobregarg The "arg" value to pass to iobroker_register()
64  */
65 extern int runcmd_open(const char *cmd, int *pfd, int *pfderr, char **env,
66  void (*iobreg)(int, int, void *), void *iobregarg)
67  __attribute__((__nonnull__(1, 2, 3, 5, 6)));
68 
69 /**
70  * Close a command and return its exit status
71  * @note Don't use this. It's a retarded way to reap children suitable
72  * only for launching a one-shot program.
73  *
74  * @param[in] fd The child's stdout filedescriptor
75  * @return exit-status of the child, or -1 in case of errors
76  */
77 extern int runcmd_close(int fd);
78 
79 /**
80  * Convert a string to a vector of arguments like a shell would
81  * @note This might have bugs and is only tested to behave similar
82  * to how /bin/sh does things. For csh or other non bash-ish shells
83  * there are no guarantees.
84  * @note The out_argv array has to be large enough to hold all strings
85  * found in the command.
86  * @param[in] str The string to convert to an argument vector
87  * @param[out] out_argc The number of arguments found
88  * @param[out] out_argv The argument vector
89  * @return 0 on (great) success, or a bitmask of failure-codes
90  * representing f.e. unclosed quotes, job control or output redirection.
91  * See the RUNCMD_HAS_* and their ilk to find out about the flag.
92  */
93 extern int runcmd_cmd2strv(const char *str, int *out_argc, char **out_argv);
94 
95 #endif /* INCLUDE_runcmd_h__ */
96 /** @} */
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.
const char * runcmd_strerror(int code)
Return explanation of which system call or operation failed.
int int runcmd_close(int fd)
Close a command and return its exit status.
void runcmd_init(void)
Initialize the runcmd library.
int runcmd_cmd2strv(const char *str, int *out_argc, char **out_argv)
Convert a string to a vector of arguments like a shell would.
pid_t runcmd_pid(int fd)
Return pid of a command with a specific file descriptor.