Viewing file:  Spawn.h (6.18 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
/*
* Phusion Passenger - https://www.phusionpassenger.com/
* Copyright (c) 2010-2018 Phusion Holding B.V.
*
* "Passenger", "Phusion Passenger" and "Union Station" are registered
* trademarks of Phusion Holding B.V.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef _PASSENGER_PROCESS_MANAGEMENT_SPAWN_H_
#define _PASSENGER_PROCESS_MANAGEMENT_SPAWN_H_
#include <sys/types.h>
#include <boost/function.hpp>
#include <string>
#include <StaticString.h>
namespace Passenger {
using namespace std;
struct SubprocessInfo {
/**
* The PID of the subprocess. This is set to -1 on
* object creation. If fork fails or is interrupted,
* then this field is unmodified.
*
* Attention: if you called `runCommand()` with `wait = true`,
* or if you called `runCommandAndCaptureOutput()`,
* then when that function returns, this PID no longer
* exists.
*/
pid_t pid;
/**
* The status of the subprocess, as returned by waitpid().
* This is set to -1 on object creation.
*
* Only if `runCommand()` is done waiting for the subprocess
* will this field be set. So if you call `runCommand()` with
* `wait = false` then this field will never be modified.
*
* When unable to waitpid() the subprocess because of
* an ECHILD or ESRCH, then this field is set to -2.
*/
int status;
SubprocessInfo()
: pid(-1),
status(-1)
{ }
};
struct SubprocessOutput {
/**
* The read subprocess output data.
*/
string data;
/**
* Whether the entire file has been read. If false, then it
* means there is more data than specified through the `maxSize`
* parameter.
*/
bool eof;
SubprocessOutput()
: eof(false)
{ }
};
// See ProcessManagement/Utils.h for definition
void printExecError(const char **command, int errcode);
/**
* Like system(), but properly resets the signal handler mask,
* disables malloc debugging and closes file descriptors > 2.
*
* This is like `runCommand()` but runs something through the shell.
*
* @throws SystemException
* @throws boost::thread_interrupted
*/
int runShellCommand(const StaticString &command);
/**
* Run a command and (if so configured) wait for it. You can see this function
* as a more flexible version of system(): it accepts a command array
* instead of a shell command string, and you can choose whether to wait
* for the subprocess or not.
*
* In addition, this function also properly resets the signal handler mask,
* disables malloc debugging and closes file descriptors > 2.
*
* Information about the subprocess is stored inside `info`. See the comments
* for the `SubprocessInfo` structure to learn more about it.
*
* If this function encounters an error or is interrupted, then it ensures
* that as much information as possible about the current state of things
* is stored in `info` so that the caller can clean things up appropriately.
*
* @param command The argument array to pass to execvp(). Must be null-terminated.
* @param info
* @param wait Whether to wait for the subprocess before returning.
* @param killSubprocessOnInterruption Whether to automatically kill the subprocess
* when this function is interrupted.
* @param afterFork A function object to be called right after forking.
* @throws SystemException
* @throws boost::thread_interrupted
*/
void runCommand(const char **command, SubprocessInfo &info,
bool wait = true, bool killSubprocessOnInterruption = true,
const boost::function<void ()> &afterFork = boost::function<void ()>(),
const boost::function<void (const char **command, int errcode)> &onExecFail = printExecError);
/**
* Run a command, wait for it, and capture its stdout output.
* This function does not care whether the command fails.
*
* In addition (like `runCommand()`), this function also properly
* resets the signal handler mask, disables malloc debugging and
* closes file descriptors > 2.
*
* If something goes wrong or when interrupted while capturing the
* output, then `output` contains the output captured so far.
*
* Information about the subprocess is stored inside `info`. See the comments
* for the `SubprocessInfo` structure to learn more about it.
*
* If this function encounters an error or is interrupted, then it ensures
* that as much information as possible about the current state of things
* is stored in `info` so that the caller can clean things up appropriately.
*
* @param command The argument array to pass to execvp(). Must be null-terminated.
* @param info
* @param maxSize The maximum number of output bytes to read.
* @param killSubprocessOnInterruption Whether to automatically kill the subprocess
* when this function is interrupted.
* @param afterFork A function object to be called right after forking.
* @param onExecFail A function object to be called if exec fails.
* @throws SystemException
* @throws boost::thread_interrupted
*/
void runCommandAndCaptureOutput(const char **command, SubprocessInfo &info,
SubprocessOutput &output, size_t maxSize, bool killSubprocessOnInterruption = true,
const boost::function<void ()> &afterFork = boost::function<void ()>(),
const boost::function<void (const char **command, int errcode)> &onExecFail = printExecError);
} // namespace Passenger
#endif /* _PASSENGER_PROCESS_MANAGEMENT_SPAWN_H_ */
|