Process.h

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

Generated on Thu Nov 9 09:42:00 2006 for ACE by doxygen 1.3.6