blob: c86b13c2b501f892299cb91327a58f2002dffb1b [file] [log] [blame]
/*
* Copyright (C) Tildeslash Ltd. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* In addition, as a special exception, the copyright holders give
* permission to link the code of portions of this program with the
* OpenSSL library under certain conditions as described in each
* individual source file, and distribute linked combinations
* including the two.
*
* You must obey the GNU Affero General Public License in all respects
* for all of the code used other than OpenSSL.
*/
#ifndef PROCESS_INCLUDED
#define PROCESS_INCLUDED
#include <sys/types.h>
#include "io/InputStream.h"
#include "io/OutputStream.h"
/**
* A <b>Process</b> represent an operating system process. A new Process
* object is created via Command_execute().
*
* The sub-process represented by this Process does not have its own terminal
* or console. All its standard I/O (i.e. stdin, stdout, stderr) operations
* will be redirected to the parent process where they can be accessed using
* the streams obtained using the methods Process_getOutputStream(),
* Process_getInputStream(), and Process_getErrorStream(). Your program can
* then use these streams to feed input to and get output from the sub-process.
*
* The sub-process continues executing until it stops or until either
* Process_free() is called or it is terminated with either Process_terminate()
* or Process_kill().
*
* <h4>Environment</h4>
* The Process does <em>not</em> inherit the environment from the calling
* process and has only a spartan PATH set by default; defined by
* Command_Path. Clients should call Command_setEnv() to set environment
* variables as needed <em>before</em> calling Command_execute()
*
* @see Command.h
* @see http://www.mmonit.com/
* @file
*/
#define T Process_T
typedef struct T *T;
/**
* Destroy a Process object and free allocated resources. Clients
* should call this method when they are done with the Process object.
* This method will kill the sub-process represented by this Process
* object if it is still running and close down stdio to the sub-process.
* @param P a Process object reference
*/
void Process_free(T *P);
/** @name Properties */
//@{
/**
* Returns the user id of the sub-process
* @param P A Process object
* @return The user id the sub-process
*/
uid_t Process_getUid(T P);
/**
* Returns the group id of the sub-process
* @param P A Process object
* @return The group id the sub-process
*/
gid_t Process_getGid(T P);
/**
* Returns the Process timeout.
* @param P A Process object
* @return The number of seconds this Process has until exit before
* the <code>onTimeout</code> handler is called if it is defined for
* the Command. 0 means that there is no timeout.
*/
int Process_getTimeout(T P);
/**
* Returns the working directory of the Process
* @param P A Process object
* @return The Process working directory
*/
const char *Process_getDir(T P);
/**
* Returns the Process's identification number
* @param P A Process object
* @return The process identification number of the sub-process
*/
pid_t Process_getPid(T P);
/**
* Causes the current thread to wait, if necessary, until the sub-process
* represented by this Process object has terminated. This method returns
* immediately if the sub-process has already terminated. If the sub-process
* has not yet terminated, the calling thread will be blocked until the
* sub-process exits. By convention, the value 0 indicates normal termination.
* @param P A Process object
* @return The exit status of the sub-process or -1 if an error occur.
* Investigate errno for a description of the error
*/
int Process_waitFor(T P);
/**
* Returns the Process exit status. If the sub-process is still running, this
* method returns -1, otherwise the sub-process exit status. By convention,
* the value 0 indicates normal termination.
* @param P A Process object
* @return The exit status of the sub-process or -1 if the sub-process is still
* running.
*/
int Process_exitStatus(T P);
/**
* Returns true if the sub-process is running otherwise false
* @param P A Process object
* @return True if Process is running otherwise false
*/
int Process_isRunning(T P);
/**
* Returns the output stream connected to the normal input of the sub-process.
* Output to the stream is piped into the standard input of the process
* represented by this Process object.
* @param P A Process object
* @return The output stream connected to the normal input of the sub-process.
*/
OutputStream_T Process_getOutputStream(T P);
/**
* Returns the input stream connected to the normal output of the sub-process.
* The stream obtains data piped from the standard output of the process
* represented by this Process object.
* @param P A Process object
* @return The input stream connected to the normal output of the sub-process.
*/
InputStream_T Process_getInputStream(T P);
/**
* Returns the input stream connected to the error output of the sub-process.
* The stream obtains data piped from the error output of the process
* represented by this Process object.
* @param P A Process object
* @return The input stream connected to the error output of the sub-process.
*/
InputStream_T Process_getErrorStream(T P);
//@}
/**
* Destroy the sub-process. The sub-process is destroyed by sending
* it a termination signal (SIGTERM)
* @param P A Process object
*/
void Process_terminate(T P);
/**
* Kill the sub-process. The sub-process is destroyed by sending
* it a termination signal (SIGKILL). While SIGTERM may be blocked
* by a process, SIGKILL can not be blocked and will kill the process
* @param P A Process object
*/
void Process_kill(T P);
#undef T
#endif