ncbiexec.hpp

ncbi源码

    /// - The letter "P" as suffix refers to the fact that the PATH
    ///   environment variable is used to find file to execute - on a Unix
    ///   platform this feature works in functions without letter "P" in
    ///   function name. 
    /// - The letter "E" as suffix refers to the fact that environment pointer,
    ///   envp, is passed as an array of pointers to environment settings to 
    ///   the new process. The NULL environment pointer indicates that the new 
    ///   process will inherit the parents process's environment.
    ///
    /// NOTE: At least one argument must be present. This argument is always, 
    /// by convention, the name of the file being spawned (argument with 
    /// number 0).
    /// @param mode
    ///   Mode for running the process.
    /// @param cmdline
    ///   Command-line string.
    /// @param argv
    ///   Argument vector.
    /// @param ...
    ///   NULL, const char* envp[]
    /// @return 
    ///   On success, return:
    ///     - exit code      - in eWait mode.
    ///     - process handle - in eNoWait and eDetach modes.
    ///     - nothing        - in eOverlay mode.   
    ///    Throw an exception if command failed to execute.
    /// @sa
    ///   SpawnL(), SpawnLE(), SpawnLP(), SpawnV(), SpawnVE(), SpawnVP(), 
    ///   SpawnVPE().
    static int SpawnLPE(EMode mode, const char *cmdname,
                        const char *argv, ... /*, NULL, const char *envp[] */);

    /// Spawn a new process with variable number of command-line arguments. 
    ///
    /// In the SpawnV() version, the command-line arguments are a variable
    /// number. The array of pointers to arguments must have a length of 1 or
    /// more and you must assign parameters for the new process beginning
    /// from 1.
    ///
    /// Meaning of the suffix "V" in method name:
    /// - The letter "V" as suffix refers to the fact that the number of
    /// command-line arguments are variable.
    ///
    /// NOTE: At least one argument must be present. This argument is always, 
    /// by convention, the name of the file being spawned (argument with 
    /// number 0).
    /// @param mode
    ///   Mode for running the process.
    /// @param cmdline
    ///   Command-line string.
    /// @param argv
    ///   Argument vector.
    /// @return 
    ///   On success, return:
    ///     - exit code      - in eWait mode.
    ///     - process handle - in eNoWait and eDetach modes.
    ///     - nothing        - in eOverlay mode.   
    ///   Throw an exception if command failed to execute.
    /// @sa
    ///   SpawnL(), SpawnLE(), SpawnLP(), SpawnLPE(), SpawnVE(), SpawnVP(), 
    ///   SpawnVPE().
    static int SpawnV(EMode mode, const char *cmdname,
                      const char *const *argv);

    /// Spawn a new process with variable number of command-line arguments
    /// and specified environment settings.
    ///
    /// In the SpawnVE() version, the command-line arguments are a variable
    /// number. The array of pointers to arguments must have a length of 1 or
    /// more and you must assign parameters for the new process beginning from
    /// 1.  The individual environment parameter settings are known in advance
    /// and passed explicitly.
    ///
    /// Meaning of the suffix "VE" in method name:
    /// - The letter "V" as suffix refers to the fact that the number of
    ///   command-line arguments are variable.
    /// - The letter "E" as suffix refers to the fact that environment pointer,
    ///   envp, is passed as an array of pointers to environment settings to 
    ///   the new process. The NULL environment pointer indicates that the new 
    ///   process will inherit the parents process's environment.
    ///
    /// NOTE: At least one argument must be present. This argument is always, 
    /// by convention, the name of the file being spawned (argument with 
    /// number 0).
    /// @param mode
    ///   Mode for running the process.
    /// @param cmdline
    ///   Command-line string.
    /// @param argv
    ///   Argument vector.
    /// @return 
    ///   On success, return:
    ///     - exit code      - in eWait mode.
    ///     - process handle - in eNoWait and eDetach modes.
    ///     - nothing        - in eOverlay mode.   
    ///   Throw an exception if command failed to execute.
    /// @sa
    ///   SpawnL(), SpawnLE(), SpawnLP(), SpawnLPE(), SpawnV(), SpawnVP(), 
    ///   SpawnVPE().
    static int SpawnVE(EMode mode, const char *cmdname,
                       const char *const *argv, const char *const *envp);

    /// Spawn a new process with variable number of command-line arguments and
    /// find file to execute from the PATH environment variable.
    ///
    /// In the SpawnVP() version, the command-line arguments are a variable
    /// number. The array of pointers to arguments must have a length of 1 or
    /// more and you must assign parameters for the new process beginning from
    /// 1. The PATH environment variable is used to find the file to execute.
    ///
    /// Meaning of the suffix "VP" in method name:
    /// - The letter "V" as suffix refers to the fact that the number of
    ///   command-line arguments are variable.
    /// - The letter "P" as suffix refers to the fact that the PATH
    ///   environment variable is used to find file to execute - on a Unix
    ///   platform this feature works in functions without letter "P" in
    ///   function name. 
    ///
    /// NOTE: At least one argument must be present. This argument is always, 
    /// by convention, the name of the file being spawned (argument with 
    /// number 0).
    /// @param mode
    ///   Mode for running the process.
    /// @param cmdline
    ///   Command-line string.
    /// @param argv
    ///   Argument vector.
    /// @param ...
    ///   NULL, const char* envp[]
    /// @return 
    ///   On success, return:
    ///     - exit code      - in eWait mode.
    ///     - process handle - in eNoWait and eDetach modes.
    ///     - nothing        - in eOverlay mode.   
    ///   Throw an exception if command failed to execute.
    /// @sa
    ///   SpawnL(), SpawnLE(), SpawnLP(), SpawnLPE(), SpawnV(), SpawnVE(), 
    ///   SpawnVPE().
    static int SpawnVP(EMode mode, const char *cmdname,
                       const char *const *argv);

    /// Spawn a new process with variable number of command-line arguments
    /// and specified environment settings, and find the file to execute
    /// from the PATH environment variable.
    ///
    /// In the SpawnVPE() version, the command-line arguments are a variable
    /// number. The array of pointers to arguments must have a length of 1 or
    /// more and you must assign parameters for the new process beginning from
    /// 1. The PATH environment variable is used to find the file to execute,
    /// and the environment is passed via an environment vector pointer.
    ///
    /// Meaning of the suffix "VPE" in method name:
    /// - The letter "V" as suffix refers to the fact that the number of
    ///   command-line arguments are variable.
    /// - The letter "P" as suffix refers to the fact that the PATH
    ///   environment variable is used to find file to execute - on a Unix
    ///   platform this feature works in functions without letter "P" in
    ///   function name. 
    /// - The letter "E" as suffix refers to the fact that environment pointer,
    ///   envp, is passed as an array of pointers to environment settings to 
    ///   the new process. The NULL environment pointer indicates that the new 
    ///   process will inherit the parents process's environment.
    ///
    /// NOTE: At least one argument must be present. This argument is always, 
    /// by convention, the name of the file being spawned (argument with 
    /// number 0).
    /// @param mode
    ///   Mode for running the process.
    /// @param cmdline
    ///   Command-line string.
    /// @param argv
    ///   Argument vector.
    /// @return 
    ///   On success, return:
    ///     - exit code      - in eWait mode.
    ///     - process handle - in eNoWait and eDetach modes.
    ///     - nothing        - in eOverlay mode.   
    ///   Throw an exception if command failed to execute.
    /// @sa
    ///   SpawnL(), SpawnLE(), SpawnLP(), SpawnLPE(), SpawnV(), SpawnVE(),
    ///   SpawnVP(), 
    static int SpawnVPE(EMode mode, const char *cmdname,
                        const char *const *argv, const char *const *envp);

    /// Wait until child process terminates.
    ///
    /// Wait until the child process with "handle" terminates, and return
    /// immeditately if the specifed child process has already terminated.
    /// @param handle
    ///   Wait on child process with identifier "handle", returned by one 
    ///   of the Spawn* function in eNoWait and eDetach modes.
    /// @param timeout
    ///   Time-out interval. By default it is infinite.
    /// @return
    ///   - Exit code of child process, if no errors.
    ///   - (-1), if error has occurred.
    static int Wait(int handle, unsigned long timeout = kMax_ULong);
};


END_NCBI_SCOPE


/* @} */


/*
 * ===========================================================================
 * $Log: ncbiexec.hpp,v $
 * Revision 1000.1  2004/04/21 14:34:43  gouriano
 * PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.13
 *
 * Revision 1.13  2004/04/01 14:14:01  lavr
 * Spell "occurred", "occurrence", and "occurring"
 *
 * Revision 1.12  2003/09/25 17:59:12  ivanov
 * Comment changes
 *
 * Revision 1.11  2003/09/25 17:19:05  ucko
 * CExec::Wait: add an optional timeout argument per the new (forwarding)
 * implementation.
 *
 * Revision 1.10  2003/09/16 17:48:03  ucko
 * Remove redundant "const"s from arguments passed by value.
 *
 * Revision 1.9  2003/09/16 15:22:31  ivanov
 * Minor comments changes
 *
 * Revision 1.8  2003/07/30 11:08:44  siyan
 * Documentation changes.
 *
 * Revision 1.7  2003/03/31 16:40:07  siyan
 * Added doxygen support
 *
 * Revision 1.6  2003/02/24 19:54:52  gouriano
 * use template-based exceptions instead of errno and parse exceptions
 *
 * Revision 1.5  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.4  2002/07/11 14:17:54  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.3  2002/06/10 18:55:27  ivanov
 * Added comment note about arguments with spaces inside
 *
 * Revision 1.2  2002/05/31 20:48:39  ivanov
 * Clean up code
 *
 * Revision 1.1  2002/05/30 16:30:45  ivanov
 * Initial revision
 *
 * ===========================================================================
 */

#endif  /* CORELIB__NCBIEXEC__HPP */