Nagios  4.4.3
Dev docs for Nagios core and neb-module hackers
runcmd.h
Go to the documentation of this file.
1 #ifndef NDO_LIBNAGIOS_RUNCMD_H_INCLUDED
2 #define NDO_LIBNAGIOS_RUNCMD_H_INCLUDED
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] cmd 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 
80 /**
81  * Close a command and return its exit status
82  * @note Don't use this. It's a retarded way to reap children suitable
83  * only for launching a one-shot program.
84  *
85  * @param[in] fd The child's stdout filedescriptor
86  * @return exit-status of the child, or -1 in case of errors
87  */
88 extern int runcmd_close(int fd);
89 
90 /**
91  * Convert a string to a vector of arguments like a shell would
92  * @note This might have bugs and is only tested to behave similar
93  * to how /bin/sh does things. For csh or other non bash-ish shells
94  * there are no guarantees.
95  * @note The out_argv array has to be large enough to hold all strings
96  * found in the command.
97  * @param[in] str The string to convert to an argument vector
98  * @param[out] out_argc The number of arguments found
99  * @param[out] out_argv The argument vector
100  * @return 0 on (great) success, or a bitmask of failure-codes
101  * representing f.e. unclosed quotes, job control or output redirection.
102  * See the RUNCMD_HAS_* and their ilk to find out about the flag.
103  */
104 extern int runcmd_cmd2strv(const char *str, int *out_argc, char **out_argv);
105 
106 /**
107  * If you're using libnagios to execute a remote command, the
108  * static pid_t pids is not freed after runcmd_open
109  * You can call this function when you're sure pids is no longer
110  * in use, to keep down memory leaks
111  */
112 extern void runcmd_free_pids(void);
113 
114 /** @} */
115 /* INCLUDE_runcmd_h__ */
116 #endif
runcmd_close
int runcmd_close(int fd)
Close a command and return its exit status.
runcmd_init
void runcmd_init(void)
Initialize the runcmd library.
runcmd_cmd2strv
int runcmd_cmd2strv(const char *str, int *out_argc, char **out_argv)
Convert a string to a vector of arguments like a shell would.
runcmd_strerror
const char * runcmd_strerror(int code)
Return explanation of which system call or operation failed.
runcmd_pid
pid_t runcmd_pid(int fd)
Return pid of a command with a specific file descriptor.
runcmd_free_pids
void runcmd_free_pids(void)
If you're using libnagios to execute a remote command, the static pid_t pids is not freed after runcm...
runcmd_open
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.