Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Process.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Process.h
00006  *
00007  *  $Id: Process.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Tim Harrison <harrison@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_PROCESS_H
00014 #define ACE_PROCESS_H
00015 #include "ace/pre.h"
00016 
00017 #include "ace/OS.h"
00018 #include "ace/Handle_Set.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 /**
00025  * @class ACE_Process_Options
00026  *
00027  * @brief Process Options
00028  *
00029  * This class controls the options passed to <CreateProcess> (or <fork>
00030  * and <exec>).
00031  * Notice that on Windows CE, creating a process merely means
00032  * instantiating a new process.  You can't set the handles (since
00033  * there's no stdin, stdout and stderr,) specify process/thread
00034  * options, set environment,...  So, basically, this class only
00035  * set the command line and nothing else.
00036  * Notice that on UNIX platforms, if the <setenv> is used, the
00037  * <spawn> is using the <execve> system call. It means that the
00038  * <command_line> should include a full path to the program file
00039  * (<execve> does not search the PATH).  If <setenv> is not used
00040  * then, the <spawn> is using the <execvp> which searches for the
00041  * program file in the PATH variable.
00042  */
00043 class ACE_Export ACE_Process_Options
00044 {
00045 public:
00046   enum
00047   {
00048     DEFAULT_COMMAND_LINE_BUF_LEN = 1024,
00049     // UNIX process creation flags.
00050 #if defined (ACE_WIN32)
00051     NO_EXEC = 0
00052 #else
00053     NO_EXEC = 1
00054 #endif /* ACE_WIN32 */
00055   };
00056 
00057 protected:
00058   // = Default settings not part of public Interface.
00059   //
00060   // @@todo These sizes should be taken from the appropriate
00061   // POSIX/system header files and/or defined dynamically.
00062   enum
00063   {
00064     MAX_COMMAND_LINE_OPTIONS = 128,
00065     ENVIRONMENT_BUFFER = 16 * 1024, // 16K
00066     MAX_ENVIRONMENT_ARGS = 512 //
00067   };
00068 
00069 public:
00070   /**
00071    * If <inherit_environment> == 1, the new process will inherit the
00072    * environment of the current process.  <command_line_buf_len> is the
00073    * max strlen for command-line arguments.
00074    */
00075   ACE_Process_Options (int inherit_environment = 1,
00076                        int command_line_buf_len = DEFAULT_COMMAND_LINE_BUF_LEN,
00077                        int env_buf_len = ENVIRONMENT_BUFFER,
00078                        int max_env_args = MAX_ENVIRONMENT_ARGS);
00079 
00080   /// Destructor.
00081   ~ACE_Process_Options (void);
00082 
00083   // = Methods to set process creation options portably.
00084 
00085   /**
00086    * Set the standard handles of the new process to the respective
00087    * handles.  If you want to affect a subset of the handles, make
00088    * sure to set the others to ACE_INVALID_HANDLE.  Returns 0 on
00089    * success, -1 on failure.
00090    */
00091   int set_handles (ACE_HANDLE std_in,
00092                    ACE_HANDLE std_out = ACE_INVALID_HANDLE,
00093                    ACE_HANDLE std_err = ACE_INVALID_HANDLE);
00094 
00095   /// Felease the standard handles previously set with set_handles;
00096   void release_handles (void);
00097 
00098   /// <format> must be of the form "VARIABLE=VALUE".  There can not be
00099   /// any spaces between VARIABLE and the equal sign.
00100   int setenv (const ACE_TCHAR *format,
00101               ...);
00102 
00103   /**
00104    * Set a single environment variable, <variable_name>.  Since
00105    * different platforms separate each environment variable
00106    * differently, you must call this method once for each variable.
00107    * <format> can be any printf format string.  So options->setenv
00108    * ("FOO","one + two = %s", "three") will result in "FOO=one + two =
00109    * three".
00110    */
00111   int setenv (const ACE_TCHAR *variable_name,
00112               const ACE_TCHAR *format,
00113               ...);
00114 
00115   /// Same as above with argv format.  <envp> must be null terminated.
00116   int setenv (ACE_TCHAR *envp[]);
00117 
00118   /// Set the working directory for the process.  strlen of <wd> must
00119   /// be <= MAXPATHLEN.
00120   void working_directory (const char *wd);
00121 
00122 #if defined (ACE_HAS_WCHAR)
00123   /// wchar_t version of working_directory
00124   void working_directory (const wchar_t *wd);
00125 #endif /* ACE_HAS_WCHAR */
00126 
00127   /**
00128    * Set the command-line arguments.  <format> can use any printf
00129    * formats.  The first token in <format> should be the path to the
00130    * application.  This can either be a full path, relative path, or
00131    * just an executable name.  If an executable name is used, we rely
00132    * on the platform's support for searching paths.  Since we need a
00133    * path to run a process, this method *must* be called!  Returns 0
00134    * on success, -1 on failure.
00135    */
00136   int command_line (const ACE_TCHAR *format, ...);
00137 
00138 #if defined (ACE_HAS_WCHAR) && !defined (ACE_HAS_WINCE)
00139   /// Anti-TChar version of command_line ()
00140   int command_line (const ACE_ANTI_TCHAR *format, ...);
00141 #endif /* ACE_HAS_WCHAR && !ACE_HAS_WINCE */
00142 
00143   /// Same as above in argv format.  <argv> must be null terminated.
00144   int command_line (const ACE_TCHAR * const argv[]);
00145 
00146   // = Set/get the pathname used to name the process.
00147   /**
00148    * Specify the full path or relative path, or just the executable
00149    * name for the process. If this is set, then <name> will be used to
00150    * create the process instead of argv[0] set in the command
00151    * line. This is here so that you can supply something other than
00152    * executable name as argv[0].
00153    */
00154   void process_name (const ACE_TCHAR *name);
00155 
00156   /// Return the process_name.  If the <process_name(name)> set
00157   /// method is not called, this method will return argv[0].
00158   const ACE_TCHAR *process_name (void);
00159 
00160   // = Set/get creation flags.
00161   /// Get the creation flags.
00162   u_long creation_flags (void) const;
00163 
00164   /// Set the creation flags.
00165   void creation_flags (u_long);
00166 
00167   // = <ACE_Process> uses these operations to retrieve option values.
00168 
00169   /// Current working directory.  Returns "" if nothing has been set.
00170   ACE_TCHAR *working_directory (void);
00171 
00172   /// Buffer of command-line options.  Returns a pointer to a buffer that
00173   /// contains the list of command line options.  Prior to a call to
00174   /// command_line_argv(), this is a single string of space separated
00175   /// arguments independent of which form of command_line() was used to
00176   /// create it.  After a call to command_line_argv(), this is a list of
00177   /// strings each terminated by '\0'.  [Note: spawn() will call
00178   /// command_line_argv().]  The total length of all these strings is the
00179   /// same as the single string in the prior case and can be obtained by
00180   /// providing max_len. @arg max_len, if non-zero, provides a location
00181   /// into which the total length of the command line buffer is returned.
00182   ACE_TCHAR *command_line_buf (int *max_len = 0);
00183 
00184   /**
00185    * argv-style command-line options.  Parses and modifies the string
00186    * created from <command_line_>.  All spaces not in quotes ("" or
00187    * '') are replaced with null (\0) bytes.  An argv array is built
00188    * and returned with each entry pointing to the start of
00189    * null-terminated string.  Returns { 0 } if nothing has been set.
00190    */
00191   ACE_TCHAR * const *command_line_argv (void);
00192 
00193   /**
00194    * Null-terminated buffer of null terminated strings.  Each string
00195    * is an environment assignment "VARIABLE=value".  This buffer
00196    * should end with two null characters.
00197    */
00198   ACE_TCHAR *env_buf (void);
00199 
00200   // = Get/set process group.
00201   /// Get the process group.  On UNIX, these methods are used by the
00202   /// <ACE_Process_Manager> to manage groups of processes.
00203   pid_t getgroup (void) const;
00204 
00205   /// Set the process group.  On UNIX, these methods are used by the
00206   /// <ACE_Process_Manager> to manage groups of processes.
00207   pid_t setgroup (pid_t pgrp);
00208 
00209   /// Default is TRUE.
00210   /// Allows disabling of handle inheritence.
00211   int handle_inheritence (void);
00212   void handle_inheritence (int);
00213 
00214   /// Cause the specified handle to be passed to a child process
00215   /// when it runs a new program image.
00216   /**
00217    * The specified handle value will be included in the spawned
00218    * process's command line as @arg +H @arg handle, if a new
00219    * program is spawned (always on Win32; else if NO_EXEC is not
00220    * set in creation flags).  The passed handle value will be
00221    * duplicated if on Win32 less capable than NT.
00222    * @return 0 if success, -1 if failure.
00223    */
00224   int pass_handle (ACE_HANDLE);
00225 
00226   /// Get a copy of the handles the ACE_Process_Options duplicated
00227   /// for the spawned process.
00228   /**
00229    * Any handles created through duplication of those passed into
00230    * @arg pass_handle are returned in @arg set.
00231    * @return 0 if there were no handles to return; 1 if there were.
00232    */
00233   int dup_handles (ACE_Handle_Set &set) const;
00234 
00235   /// Get a copy of the handles passed to the spawned process. This
00236   /// will be the set of handles previously passed to @arg pass_handle().
00237   /**
00238    * Any handles previously passed to @arg pass_handle are returned
00239    * in @arg set.
00240    * @return 0 if there were no handles to return; 1 if there were.
00241    */
00242   int passed_handles (ACE_Handle_Set &set) const;
00243 
00244   /// Set value for avoid_zombies (has no real effect except on *nix).
00245   void avoid_zombies (int);
00246 
00247   /// Get current value for avoid_zombies.
00248   int avoid_zombies (void);
00249 
00250 #if defined (ACE_WIN32)
00251   // = Non-portable accessors for when you "just have to use them."
00252 
00253   /// Used for setting and getting.
00254   ACE_TEXT_STARTUPINFO *startup_info (void);
00255 
00256   /// Get the process_attributes.  Returns NULL if
00257   /// set_process_attributes has not been set.
00258   LPSECURITY_ATTRIBUTES get_process_attributes (void) const;
00259 
00260   /// If this is called, a non-null process attributes is sent to
00261   /// CreateProcess.
00262   LPSECURITY_ATTRIBUTES set_process_attributes (void);
00263 
00264   /// Get the thread_attributes.  Returns NULL if set_thread_attributes
00265   /// has not been set.
00266   LPSECURITY_ATTRIBUTES get_thread_attributes (void) const;
00267 
00268   /// If this is called, a non-null thread attributes is sent to
00269   /// CreateProcess.
00270   LPSECURITY_ATTRIBUTES set_thread_attributes (void);
00271 
00272 #else /* All things not WIN32 */
00273 
00274   /// argv-style array of environment settings.
00275   ACE_TCHAR *const *env_argv (void);
00276 
00277   // = Accessors for the standard handles.
00278   ACE_HANDLE get_stdin (void) const;
00279   ACE_HANDLE get_stdout (void) const;
00280   ACE_HANDLE get_stderr (void) const;
00281 
00282   // = Set/get real & effective user & group id associated with user.
00283   int setreugid (const ACE_TCHAR* user);
00284   void setruid (uid_t id);
00285   void seteuid (uid_t id);
00286   void setrgid (uid_t id);
00287   void setegid (uid_t id);
00288   uid_t getruid (void) const;
00289   uid_t geteuid (void) const;
00290   uid_t getrgid (void) const;
00291   uid_t getegid (void) const;
00292 
00293   /**
00294    * Get the inherit_environment flag.
00295    */
00296   int inherit_environment (void) const;
00297 
00298   /**
00299    * Set the inherit_environment flag.
00300    */
00301   void inherit_environment (int nv);
00302 #endif /* ACE_WIN32 */
00303 protected:
00304 
00305 #if !defined (ACE_HAS_WINCE)
00306   /// Add <assignment> to environment_buf_ and adjust
00307   /// environment_argv_.  <len> is the strlen of <assignment>.
00308   int setenv_i (ACE_TCHAR *assignment, size_t len);
00309 
00310   /// Whether the child process inherits the current process
00311   /// environment.
00312   int inherit_environment_;
00313 #endif /* !ACE_HAS_WINCE */
00314 
00315   /// Default 0.
00316   u_long creation_flags_;
00317 
00318   /// Avoid zombies for spawned processes.
00319   int avoid_zombies_;
00320 
00321 #if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)
00322   /// Helper function to grab win32 environment and stick it in
00323   /// environment_buf_ using this->setenv_i.
00324   void inherit_environment (void);
00325 
00326   /// Ensures once only call to inherit environment.
00327   int environment_inherited_;
00328 
00329   ACE_TEXT_STARTUPINFO startup_info_;
00330 
00331   /// Default TRUE.
00332   BOOL handle_inheritence_;
00333 
00334   /// Pointer to security_buf1_.
00335   LPSECURITY_ATTRIBUTES process_attributes_;
00336 
00337   /// Pointer to security_buf2_.
00338   LPSECURITY_ATTRIBUTES thread_attributes_;
00339 
00340   /// Data for process_attributes_.
00341   SECURITY_ATTRIBUTES security_buf1_;
00342 
00343   /// Data for thread_attributes_.
00344   SECURITY_ATTRIBUTES security_buf2_;
00345 
00346 #else /* !ACE_WIN32 */
00347   ACE_HANDLE stdin_;
00348   ACE_HANDLE stdout_;
00349   ACE_HANDLE stderr_;
00350 
00351   // = Real & effective user & group id's.
00352   //   These should be set to -1 to leave unchanged (default).
00353   uid_t ruid_;
00354   uid_t euid_;
00355   uid_t rgid_;
00356   uid_t egid_;
00357 #endif /* ACE_WIN32 */
00358 
00359 #if !defined (ACE_HAS_WINCE)
00360   /// Is 1 if stdhandles was called.
00361   int set_handles_called_;
00362 
00363   /// Pointer into environment_buf_.  This should point to the next
00364   /// free spot.
00365   size_t environment_buf_index_;
00366 
00367   /// Pointer to environment_argv_.
00368   int environment_argv_index_;
00369 
00370   /// Pointer to buffer of the environment settings.
00371   ACE_TCHAR *environment_buf_;
00372 
00373   /// Size of the environment buffer. Configurable
00374   size_t environment_buf_len_;
00375 
00376   /// Pointers into environment_buf_.
00377   ACE_TCHAR **environment_argv_;
00378 
00379   /// Maximum number of environment variables. Configurable
00380   int max_environment_args_;
00381 
00382   /// Maximum index of environment_argv_ buffer
00383   int max_environ_argv_index_;
00384 
00385   /// The current working directory.
00386   ACE_TCHAR working_directory_[MAXPATHLEN + 1];
00387 #endif /* !ACE_HAS_WINCE */
00388 
00389   /// Ensures command_line_argv is only calculated once.
00390   int command_line_argv_calculated_;
00391 
00392   /// Pointer to buffer of command-line arguments.  E.g., "-f foo -b bar".
00393   ACE_TCHAR *command_line_buf_;
00394 
00395   /// Max length of command_line_buf_
00396   int command_line_buf_len_;
00397 
00398   /// Argv-style command-line arguments.
00399   ACE_TCHAR *command_line_argv_[MAX_COMMAND_LINE_OPTIONS];
00400 
00401   /// Process-group on Unix; unused on Win32.
00402   pid_t process_group_;
00403 
00404   /// Set of handles that were passed in pass_handle ().
00405   ACE_Handle_Set handles_passed_;
00406 
00407   /// Results of duplicating handles passed in pass_handle ().
00408   ACE_Handle_Set dup_handles_;
00409 
00410   /// Pathname for the process. Relative path or absolute path or just
00411   /// the program name.
00412   ACE_TCHAR process_name_[MAXPATHLEN + 1];
00413 };
00414 
00415 //class ACE_Process_Manager;
00416 
00417 /**
00418  * @class ACE_Process
00419  *
00420  * @brief Process
00421  *
00422  * A Portable encapsulation for creating new processes.
00423  * Notice that on UNIX platforms, if the <setenv> is used, the
00424  * <spawn> is using the <execve> system call. It means that the
00425  * <command_line> should include a full path to the program file
00426  * (<execve> does not search the PATH).  If <setenv> is not used
00427  * then, the <spawn> is using the <execvp> which searches for the
00428  * program file in the PATH variable.
00429  */
00430 class ACE_Export ACE_Process
00431 {
00432 public:
00433   friend class ACE_Process_Manager;
00434 
00435   /// Default construction.  Must use <ACE_Process::spawn> to start.
00436   ACE_Process (void);
00437 
00438   /// Destructor.
00439   virtual ~ACE_Process (void);
00440 
00441   /**
00442    * Called just before <ACE_OS::fork> in the <spawn>.  If this
00443    * returns non-zero, the <spawn> is aborted (and returns
00444    * ACE_INVALID_PID).  The default simply returns zero.
00445    */
00446   virtual int prepare (ACE_Process_Options &options);
00447 
00448   /**
00449    * Launch a new process as described by <options>.  Returns the
00450    * process id of the newly spawned child on success or -1 on
00451    * failure.
00452    */
00453   virtual pid_t spawn (ACE_Process_Options &options);
00454 
00455   /// Called just after <ACE_OS::fork> in the parent's context, if the
00456   /// <fork> succeeds.  The default is to do nothing.
00457   virtual void parent (pid_t child);
00458 
00459   /**
00460    * Called just after <ACE_OS::fork> in the child's context.  The
00461    * default does nothing.  This function is *not* called on Win32
00462    * because the process-creation scheme does not allow it.
00463    */
00464   virtual void child (pid_t parent);
00465 
00466   /// Called by a <Process_Manager> that is removing this Process from
00467   /// its table of managed Processes.  Default is to do nothing.
00468   virtual void unmanage (void);
00469 
00470   /**
00471    * Wait for the process we've created to exit.  If <status> != 0, it
00472    * points to an integer where the function store the exit status of
00473    * child process to.  If <wait_options> == <WNOHANG> then return 0
00474    * and don't block if the child process hasn't exited yet.  A return
00475    * value of -1 represents the <wait> operation failed, otherwise,
00476    * the child process id is returned.
00477    */
00478   pid_t wait (ACE_exitcode *status = 0,
00479               int wait_options = 0);
00480 
00481   /**
00482    * Timed wait for the process we've created to exit.  A return value
00483    * of -1 indicates that the something failed; 0 indicates that a
00484    * timeout occurred.  Otherwise, the child's process id is returned.
00485    * If <status> != 0, it points to an integer where the function
00486    * stores the child's exit status.
00487    *
00488    * NOTE: on UNIX platforms this function uses <ualarm>, i.e., it
00489    * overwrites any existing alarm.  In addition, it steals all
00490    * <SIGCHLD>s during the timeout period, which will break another
00491    * <ACE_Process_Manager> in the same process that's expecting
00492    * <SIGCHLD> to kick off process reaping.
00493    */
00494   pid_t wait (const ACE_Time_Value &tv,
00495               ACE_exitcode *status = 0);
00496 
00497   /// Send the process a signal.  This is only portable to operating
00498   /// systems that support signals, such as UNIX/POSIX.
00499   int kill (int signum = SIGINT);
00500 
00501   /**
00502    * Terminate the process abruptly using <ACE::terminate_process>.
00503    * This call doesn't give the process a chance to cleanup, so use it
00504    * with caution...
00505    */
00506   int terminate (void);
00507 
00508   /// Return the process id of the new child process.
00509   pid_t getpid (void) const;
00510 
00511   /// Return the handle of the process, if it has one.
00512   ACE_HANDLE gethandle (void) const;
00513 
00514   /// Return 1 if running; 0 otherwise.
00515   int running (void) const;
00516 
00517   /// Return the Process' exit code.  This method returns the raw
00518   /// exit status returned from system APIs (such as <wait> or
00519   /// <waitpid>).  This value is system dependent.
00520   ACE_exitcode exit_code (void) const;
00521 
00522   /// Return the Process' return value.  This method returns the
00523   /// actual return value that a child process returns or <exit>s.
00524   int return_value (void) const;
00525 
00526   /// Close all the handles in the set obtained from the
00527   /// @arg ACE_Process_Options::dup_handles object used to spawn
00528   /// the process.
00529   void close_dup_handles (void);
00530 
00531   /// Close all the handles in the set obtained from the
00532   /// @arg ACE_Process_Options::passed_handles object used to spawn
00533   /// the process.
00534   void close_passed_handles (void);
00535 
00536 #if defined (ACE_WIN32)
00537   PROCESS_INFORMATION process_info (void);
00538 #endif /* ACE_WIN32 */
00539 
00540 protected:
00541   /// Set this process' <exit_code_>.  ACE_Process_Manager uses this
00542   /// method to set the <exit_code_> after successfully waiting for
00543   /// this proecess to exit.
00544   void exit_code (ACE_exitcode code);
00545 
00546 #if defined (ACE_WIN32)
00547   PROCESS_INFORMATION process_info_;
00548 #else /* ACE_WIN32 */
00549   /// Process id of the child.
00550   pid_t child_id_;
00551 #endif /* ACE_WIN32 */
00552   ACE_exitcode exit_code_;
00553 
00554   /// Set of handles that were passed to the child process.
00555   ACE_Handle_Set handles_passed_;
00556   /// Handle duplicates made for the child process.
00557   ACE_Handle_Set dup_handles_;
00558 };
00559 
00560 
00561 /**
00562  * @class ACE_Managed_Process
00563  *
00564  * @brief A process easily managed by ACE_Process_Manager.
00565  *
00566  * @arg ACE_Managed_Process is just an @arg ACE_Process with an
00567  * @arg unmanage method that deletes the instance.
00568  * This class is only valid for use as a dynamically-allocated object!
00569  */
00570 class ACE_Export ACE_Managed_Process : public ACE_Process
00571 {
00572 public:
00573   ACE_Managed_Process ();
00574 
00575   /// Cleanup by deleting <this>.
00576   virtual void unmanage (void);
00577 
00578 private:
00579   /// Make sure that we're allocated dynamically!
00580   virtual ~ACE_Managed_Process (void);
00581 
00582   /// Keep G++ happy...
00583   friend class ace_dewarn_gplusplus;
00584 };
00585 
00586 #include "ace/SString.h"
00587 
00588 #if defined (__ACE_INLINE__)
00589 #include "ace/Process.i"
00590 #endif /* __ACE_INLINE__ */
00591 
00592 #include "ace/post.h"
00593 #endif /* ACE_PROCESS_H */

Generated on Mon Jun 16 11:20:54 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002