Apache Portable Runtime
apr_thread_proc.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_THREAD_PROC_H
00018 #define APR_THREAD_PROC_H
00019 
00020 /**
00021  * @file apr_thread_proc.h
00022  * @brief APR Thread and Process Library
00023  */
00024 
00025 #include "apr.h"
00026 #include "apr_file_io.h"
00027 #include "apr_pools.h"
00028 #include "apr_errno.h"
00029 
00030 #if APR_HAVE_STRUCT_RLIMIT
00031 #include <sys/time.h>
00032 #include <sys/resource.h>
00033 #endif
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif /* __cplusplus */
00038 
00039 /**
00040  * @defgroup apr_thread_proc Threads and Process Functions
00041  * @ingroup APR 
00042  * @{
00043  */
00044 
00045 typedef enum {
00046     APR_SHELLCMD,           /**< use the shell to invoke the program */
00047     APR_PROGRAM,            /**< invoke the program directly, no copied env */
00048     APR_PROGRAM_ENV,        /**< invoke the program, replicating our environment */
00049     APR_PROGRAM_PATH,       /**< find program on PATH, use our environment */
00050     APR_SHELLCMD_ENV        /**< use the shell to invoke the program,
00051                              *   replicating our environment
00052                              */
00053 } apr_cmdtype_e;
00054 
00055 typedef enum {
00056     APR_WAIT,           /**< wait for the specified process to finish */
00057     APR_NOWAIT          /**< do not wait -- just see if it has finished */
00058 } apr_wait_how_e;
00059 
00060 /* I am specifically calling out the values so that the macros below make
00061  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
00062  * I am doing more clear.  If you want to add more reasons to exit, continue
00063  * to use bitmasks.
00064  */
00065 typedef enum {
00066     APR_PROC_EXIT = 1,          /**< process exited normally */
00067     APR_PROC_SIGNAL = 2,        /**< process exited due to a signal */
00068     APR_PROC_SIGNAL_CORE = 4    /**< process exited and dumped a core file */
00069 } apr_exit_why_e;
00070 
00071 /** did we exit the process */
00072 #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
00073 /** did we get a signal */
00074 #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
00075 /** did we get core */
00076 #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
00077 
00078 /** @see apr_procattr_io_set */
00079 #define APR_NO_PIPE          0
00080 /** @see apr_procattr_io_set and apr_file_pipe_create_ex */
00081 #define APR_FULL_BLOCK       1
00082 /** @see apr_procattr_io_set and apr_file_pipe_create_ex */
00083 #define APR_FULL_NONBLOCK    2
00084 /** @see apr_procattr_io_set */
00085 #define APR_PARENT_BLOCK     3
00086 /** @see apr_procattr_io_set */
00087 #define APR_CHILD_BLOCK      4
00088 /** @see apr_procattr_io_set */
00089 #define APR_NO_FILE          8
00090 
00091 /** @see apr_file_pipe_create_ex */
00092 #define APR_READ_BLOCK       3
00093 /** @see apr_file_pipe_create_ex */
00094 #define APR_WRITE_BLOCK      4
00095 
00096 /** @see apr_procattr_io_set 
00097  * @note Win32 only effective with version 1.2.12, portably introduced in 1.3.0
00098  */
00099 #define APR_NO_FILE          8
00100 
00101 /** @see apr_procattr_limit_set */
00102 #define APR_LIMIT_CPU        0
00103 /** @see apr_procattr_limit_set */
00104 #define APR_LIMIT_MEM        1
00105 /** @see apr_procattr_limit_set */
00106 #define APR_LIMIT_NPROC      2
00107 /** @see apr_procattr_limit_set */
00108 #define APR_LIMIT_NOFILE     3
00109 
00110 /**
00111  * @defgroup APR_OC Other Child Flags
00112  * @{
00113  */
00114 #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
00115                                            * unregister still */
00116 #define APR_OC_REASON_UNWRITABLE    1     /**< write_fd is unwritable */
00117 #define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
00118                                            * any necessary cleanup (including
00119                                            * sending a special signal to child)
00120                                            */
00121 #define APR_OC_REASON_UNREGISTER    3     /**< unregister has been called, do
00122                                            * whatever is necessary (including
00123                                            * kill the child) */
00124 #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
00125                                            * us knowing ... buggy os? */
00126 #define APR_OC_REASON_RUNNING       5     /**< a health check is occuring, 
00127                                            * for most maintainence functions
00128                                            * this is a no-op.
00129                                            */
00130 /** @} */
00131 
00132 /** The APR process type */
00133 typedef struct apr_proc_t {
00134     /** The process ID */
00135     pid_t pid;
00136     /** Parent's side of pipe to child's stdin */
00137     apr_file_t *in;
00138     /** Parent's side of pipe to child's stdout */
00139     apr_file_t *out;
00140     /** Parent's side of pipe to child's stdouterr */
00141     apr_file_t *err;
00142 #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
00143     /** Diagnositics/debugging string of the command invoked for 
00144      *  this process [only present if APR_HAS_PROC_INVOKED is true]
00145      * @remark Only enabled on Win32 by default.
00146      * @bug This should either always or never be present in release
00147      * builds - since it breaks binary compatibility.  We may enable
00148      * it always in APR 1.0 yet leave it undefined in most cases.
00149      */
00150     char *invoked;
00151 #endif
00152 #if defined(WIN32) || defined(DOXYGEN)
00153     /** (Win32 only) Creator's handle granting access to the process
00154      * @remark This handle is closed and reset to NULL in every case
00155      * corresponding to a waitpid() on Unix which returns the exit status.
00156      * Therefore Win32 correspond's to Unix's zombie reaping characteristics
00157      * and avoids potential handle leaks.
00158      */
00159     HANDLE hproc;
00160 #endif
00161 } apr_proc_t;
00162 
00163 /**
00164  * The prototype for APR child errfn functions.  (See the description
00165  * of apr_procattr_child_errfn_set() for more information.)
00166  * It is passed the following parameters:
00167  * @param pool Pool associated with the apr_proc_t.  If your child
00168  *             error function needs user data, associate it with this
00169  *             pool.
00170  * @param err APR error code describing the error
00171  * @param description Text description of type of processing which failed
00172  */
00173 typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
00174                                  const char *description);
00175 
00176 /** Opaque Thread structure. */
00177 typedef struct apr_thread_t           apr_thread_t;
00178 
00179 /** Opaque Thread attributes structure. */
00180 typedef struct apr_threadattr_t       apr_threadattr_t;
00181 
00182 /** Opaque Process attributes structure. */
00183 typedef struct apr_procattr_t         apr_procattr_t;
00184 
00185 /** Opaque control variable for one-time atomic variables.  */
00186 typedef struct apr_thread_once_t      apr_thread_once_t;
00187 
00188 /** Opaque thread private address space. */
00189 typedef struct apr_threadkey_t        apr_threadkey_t;
00190 
00191 /** Opaque record of child process. */
00192 typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
00193 
00194 /**
00195  * The prototype for any APR thread worker functions.
00196  */
00197 typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
00198 
00199 typedef enum {
00200     APR_KILL_NEVER,             /**< process is never sent any signals */
00201     APR_KILL_ALWAYS,            /**< process is sent SIGKILL on apr_pool_t cleanup */
00202     APR_KILL_AFTER_TIMEOUT,     /**< SIGTERM, wait 3 seconds, SIGKILL */
00203     APR_JUST_WAIT,              /**< wait forever for the process to complete */
00204     APR_KILL_ONLY_ONCE          /**< send SIGTERM and then wait */
00205 } apr_kill_conditions_e;
00206 
00207 /* Thread Function definitions */
00208 
00209 #if APR_HAS_THREADS
00210 
00211 /**
00212  * Create and initialize a new threadattr variable
00213  * @param new_attr The newly created threadattr.
00214  * @param cont The pool to use
00215  */
00216 APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
00217                                                 apr_pool_t *cont);
00218 
00219 /**
00220  * Set if newly created threads should be created in detached state.
00221  * @param attr The threadattr to affect 
00222  * @param on Non-zero if detached threads should be created.
00223  */
00224 APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
00225                                                     apr_int32_t on);
00226 
00227 /**
00228  * Get the detach state for this threadattr.
00229  * @param attr The threadattr to reference
00230  * @return APR_DETACH if threads are to be detached, or APR_NOTDETACH
00231  * if threads are to be joinable. 
00232  */
00233 APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
00234 
00235 /**
00236  * Set the stack size of newly created threads.
00237  * @param attr The threadattr to affect 
00238  * @param stacksize The stack size in bytes
00239  */
00240 APR_DECLARE(apr_status_t) apr_threadattr_stacksize_set(apr_threadattr_t *attr,
00241                                                        apr_size_t stacksize);
00242 
00243 /**
00244  * Set the stack guard area size of newly created threads.
00245  * @param attr The threadattr to affect 
00246  * @param guardsize The stack guard area size in bytes
00247  * @note Thread library implementations commonly use a "guard area"
00248  * after each thread's stack which is not readable or writable such that
00249  * stack overflows cause a segfault; this consumes e.g. 4K of memory
00250  * and increases memory management overhead.  Setting the guard area
00251  * size to zero hence trades off reliable behaviour on stack overflow
00252  * for performance. */
00253 APR_DECLARE(apr_status_t) apr_threadattr_guardsize_set(apr_threadattr_t *attr,
00254                                                        apr_size_t guardsize);
00255 
00256 /**
00257  * Create a new thread of execution
00258  * @param new_thread The newly created thread handle.
00259  * @param attr The threadattr to use to determine how to create the thread
00260  * @param func The function to start the new thread in
00261  * @param data Any data to be passed to the starting function
00262  * @param cont The pool to use
00263  */
00264 APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
00265                                             apr_threadattr_t *attr, 
00266                                             apr_thread_start_t func, 
00267                                             void *data, apr_pool_t *cont);
00268 
00269 /**
00270  * stop the current thread
00271  * @param thd The thread to stop
00272  * @param retval The return value to pass back to any thread that cares
00273  */
00274 APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
00275                                           apr_status_t retval);
00276 
00277 /**
00278  * block until the desired thread stops executing.
00279  * @param retval The return value from the dead thread.
00280  * @param thd The thread to join
00281  */
00282 APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
00283                                           apr_thread_t *thd); 
00284 
00285 /**
00286  * force the current thread to yield the processor
00287  */
00288 APR_DECLARE(void) apr_thread_yield(void);
00289 
00290 /**
00291  * Initialize the control variable for apr_thread_once.  If this isn't
00292  * called, apr_initialize won't work.
00293  * @param control The control variable to initialize
00294  * @param p The pool to allocate data from.
00295  */
00296 APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
00297                                                apr_pool_t *p);
00298 
00299 /**
00300  * Run the specified function one time, regardless of how many threads
00301  * call it.
00302  * @param control The control variable.  The same variable should
00303  *                be passed in each time the function is tried to be
00304  *                called.  This is how the underlying functions determine
00305  *                if the function has ever been called before.
00306  * @param func The function to call.
00307  */
00308 APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
00309                                           void (*func)(void));
00310 
00311 /**
00312  * detach a thread
00313  * @param thd The thread to detach 
00314  */
00315 APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
00316 
00317 /**
00318  * Return the pool associated with the current thread.
00319  * @param data The user data associated with the thread.
00320  * @param key The key to associate with the data
00321  * @param thread The currently open thread.
00322  */
00323 APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
00324                                              apr_thread_t *thread);
00325 
00326 /**
00327  * Return the pool associated with the current thread.
00328  * @param data The user data to associate with the thread.
00329  * @param key The key to use for associating the data with the thread
00330  * @param cleanup The cleanup routine to use when the thread is destroyed.
00331  * @param thread The currently open thread.
00332  */
00333 APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
00334                                              apr_status_t (*cleanup) (void *),
00335                                              apr_thread_t *thread);
00336 
00337 /**
00338  * Create and initialize a new thread private address space
00339  * @param key The thread private handle.
00340  * @param dest The destructor to use when freeing the private memory.
00341  * @param cont The pool to use
00342  */
00343 APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
00344                                                     void (*dest)(void *),
00345                                                     apr_pool_t *cont);
00346 
00347 /**
00348  * Get a pointer to the thread private memory
00349  * @param new_mem The data stored in private memory 
00350  * @param key The handle for the desired thread private memory 
00351  */
00352 APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
00353                                                  apr_threadkey_t *key);
00354 
00355 /**
00356  * Set the data to be stored in thread private memory
00357  * @param priv The data to be stored in private memory 
00358  * @param key The handle for the desired thread private memory 
00359  */
00360 APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
00361                                                  apr_threadkey_t *key);
00362 
00363 /**
00364  * Free the thread private memory
00365  * @param key The handle for the desired thread private memory 
00366  */
00367 APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
00368 
00369 /**
00370  * Return the pool associated with the current threadkey.
00371  * @param data The user data associated with the threadkey.
00372  * @param key The key associated with the data
00373  * @param threadkey The currently open threadkey.
00374  */
00375 APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
00376                                                 apr_threadkey_t *threadkey);
00377 
00378 /**
00379  * Return the pool associated with the current threadkey.
00380  * @param data The data to set.
00381  * @param key The key to associate with the data.
00382  * @param cleanup The cleanup routine to use when the file is destroyed.
00383  * @param threadkey The currently open threadkey.
00384  */
00385 APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
00386                                                 apr_status_t (*cleanup) (void *),
00387                                                 apr_threadkey_t *threadkey);
00388 
00389 #endif
00390 
00391 /**
00392  * Create and initialize a new procattr variable
00393  * @param new_attr The newly created procattr. 
00394  * @param cont The pool to use
00395  */
00396 APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
00397                                                   apr_pool_t *cont);
00398 
00399 /**
00400  * Determine if any of stdin, stdout, or stderr should be linked to pipes 
00401  * when starting a child process.
00402  * @param attr The procattr we care about. 
00403  * @param in Should stdin be a pipe back to the parent?
00404  * @param out Should stdout be a pipe back to the parent?
00405  * @param err Should stderr be a pipe back to the parent?
00406  * @note If APR_NO_PIPE, there will be no special channel, the child
00407  * inherits the parent's corresponding stdio stream.  If APR_NO_FILE is 
00408  * specified, that corresponding stream is closed in the child (and will
00409  * be INVALID_HANDLE_VALUE when inspected on Win32). This can have ugly 
00410  * side effects, as the next file opened in the child on Unix will fall
00411  * into the stdio stream fd slot!
00412  */
00413 APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
00414                                              apr_int32_t in, apr_int32_t out,
00415                                              apr_int32_t err);
00416 
00417 /**
00418  * Set the child_in and/or parent_in values to existing apr_file_t values.
00419  * @param attr The procattr we care about. 
00420  * @param child_in apr_file_t value to use as child_in. Must be a valid file.
00421  * @param parent_in apr_file_t value to use as parent_in. Must be a valid file.
00422  * @remark  This is NOT a required initializer function. This is
00423  *          useful if you have already opened a pipe (or multiple files)
00424  *          that you wish to use, perhaps persistently across multiple
00425  *          process invocations - such as a log file. You can save some 
00426  *          extra function calls by not creating your own pipe since this
00427  *          creates one in the process space for you.
00428  * @bug Note that calling this function with two NULL files on some platforms
00429  * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor
00430  * is it supported.  @see apr_procattr_io_set instead for simple pipes.
00431  */
00432 APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
00433                                                   apr_file_t *child_in,
00434                                                   apr_file_t *parent_in);
00435 
00436 /**
00437  * Set the child_out and parent_out values to existing apr_file_t values.
00438  * @param attr The procattr we care about. 
00439  * @param child_out apr_file_t value to use as child_out. Must be a valid file.
00440  * @param parent_out apr_file_t value to use as parent_out. Must be a valid file.
00441  * @remark This is NOT a required initializer function. This is
00442  *         useful if you have already opened a pipe (or multiple files)
00443  *         that you wish to use, perhaps persistently across multiple
00444  *         process invocations - such as a log file. 
00445  * @bug Note that calling this function with two NULL files on some platforms
00446  * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor
00447  * is it supported.  @see apr_procattr_io_set instead for simple pipes.
00448  */
00449 APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
00450                                                    apr_file_t *child_out,
00451                                                    apr_file_t *parent_out);
00452 
00453 /**
00454  * Set the child_err and parent_err values to existing apr_file_t values.
00455  * @param attr The procattr we care about. 
00456  * @param child_err apr_file_t value to use as child_err. Must be a valid file.
00457  * @param parent_err apr_file_t value to use as parent_err. Must be a valid file.
00458  * @remark This is NOT a required initializer function. This is
00459  *         useful if you have already opened a pipe (or multiple files)
00460  *         that you wish to use, perhaps persistently across multiple
00461  *         process invocations - such as a log file. 
00462  * @bug Note that calling this function with two NULL files on some platforms
00463  * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor
00464  * is it supported.  @see apr_procattr_io_set instead for simple pipes.
00465  */
00466 APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
00467                                                    apr_file_t *child_err,
00468                                                    apr_file_t *parent_err);
00469 
00470 /**
00471  * Set which directory the child process should start executing in.
00472  * @param attr The procattr we care about. 
00473  * @param dir Which dir to start in.  By default, this is the same dir as
00474  *            the parent currently resides in, when the createprocess call
00475  *            is made. 
00476  */
00477 APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
00478                                               const char *dir);
00479 
00480 /**
00481  * Set what type of command the child process will call.
00482  * @param attr The procattr we care about. 
00483  * @param cmd The type of command.  One of:
00484  * <PRE>
00485  *            APR_SHELLCMD     --  Anything that the shell can handle
00486  *            APR_PROGRAM      --  Executable program   (default) 
00487  *            APR_PROGRAM_ENV  --  Executable program, copy environment
00488  *            APR_PROGRAM_PATH --  Executable program on PATH, copy env
00489  * </PRE>
00490  */
00491 APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
00492                                                   apr_cmdtype_e cmd);
00493 
00494 /**
00495  * Determine if the child should start in detached state.
00496  * @param attr The procattr we care about. 
00497  * @param detach Should the child start in detached state?  Default is no. 
00498  */
00499 APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
00500                                                  apr_int32_t detach);
00501 
00502 #if APR_HAVE_STRUCT_RLIMIT
00503 /**
00504  * Set the Resource Utilization limits when starting a new process.
00505  * @param attr The procattr we care about. 
00506  * @param what Which limit to set, one of:
00507  * <PRE>
00508  *                 APR_LIMIT_CPU
00509  *                 APR_LIMIT_MEM
00510  *                 APR_LIMIT_NPROC
00511  *                 APR_LIMIT_NOFILE
00512  * </PRE>
00513  * @param limit Value to set the limit to.
00514  */
00515 APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
00516                                                 apr_int32_t what,
00517                                                 struct rlimit *limit);
00518 #endif
00519 
00520 /**
00521  * Specify an error function to be called in the child process if APR
00522  * encounters an error in the child prior to running the specified program.
00523  * @param attr The procattr describing the child process to be created.
00524  * @param errfn The function to call in the child process.
00525  * @remark At the present time, it will only be called from apr_proc_create()
00526  *         on platforms where fork() is used.  It will never be called on other
00527  *         platforms, on those platforms apr_proc_create() will return the error
00528  *         in the parent process rather than invoke the callback in the now-forked
00529  *         child process.
00530  */
00531 APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr,
00532                                                        apr_child_errfn_t *errfn);
00533 
00534 /**
00535  * Specify that apr_proc_create() should do whatever it can to report
00536  * failures to the caller of apr_proc_create(), rather than find out in
00537  * the child.
00538  * @param attr The procattr describing the child process to be created.
00539  * @param chk Flag to indicate whether or not extra work should be done
00540  *            to try to report failures to the caller.
00541  * @remark This flag only affects apr_proc_create() on platforms where
00542  *         fork() is used.  This leads to extra overhead in the calling
00543  *         process, but that may help the application handle such
00544  *         errors more gracefully.
00545  */
00546 APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr,
00547                                                        apr_int32_t chk);
00548 
00549 /**
00550  * Determine if the child should start in its own address space or using the 
00551  * current one from its parent
00552  * @param attr The procattr we care about. 
00553  * @param addrspace Should the child start in its own address space?  Default
00554  *                  is no on NetWare and yes on other platforms.
00555  */
00556 APR_DECLARE(apr_status_t) apr_procattr_addrspace_set(apr_procattr_t *attr,
00557                                                        apr_int32_t addrspace);
00558 
00559 /**
00560  * Set the username used for running process
00561  * @param attr The procattr we care about. 
00562  * @param username The username used
00563  * @param password User password if needed. Password is needed on WIN32
00564  *                 or any other platform having
00565  *                 APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.
00566  */
00567 APR_DECLARE(apr_status_t) apr_procattr_user_set(apr_procattr_t *attr,
00568                                                 const char *username,
00569                                                 const char *password);
00570 
00571 /**
00572  * Set the group used for running process
00573  * @param attr The procattr we care about. 
00574  * @param groupname The group name  used
00575  */
00576 APR_DECLARE(apr_status_t) apr_procattr_group_set(apr_procattr_t *attr,
00577                                                  const char *groupname);
00578 
00579 
00580 #if APR_HAS_FORK
00581 /**
00582  * This is currently the only non-portable call in APR.  This executes 
00583  * a standard unix fork.
00584  * @param proc The resulting process handle. 
00585  * @param cont The pool to use. 
00586  * @remark returns APR_INCHILD for the child, and APR_INPARENT for the parent
00587  * or an error.
00588  */
00589 APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
00590 #endif
00591 
00592 /**
00593  * Create a new process and execute a new program within that process.
00594  * @param new_proc The resulting process handle.
00595  * @param progname The program to run 
00596  * @param args the arguments to pass to the new program.  The first 
00597  *             one should be the program name.
00598  * @param env The new environment table for the new process.  This 
00599  *            should be a list of NULL-terminated strings. This argument
00600  *            is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and
00601  *            APR_SHELLCMD_ENV types of commands.
00602  * @param attr the procattr we should use to determine how to create the new
00603  *         process
00604  * @param pool The pool to use.
00605  * @note This function returns without waiting for the new process to terminate;
00606  * use apr_proc_wait for that.
00607  */
00608 APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
00609                                           const char *progname,
00610                                           const char * const *args,
00611                                           const char * const *env, 
00612                                           apr_procattr_t *attr, 
00613                                           apr_pool_t *pool);
00614 
00615 /**
00616  * Wait for a child process to die
00617  * @param proc The process handle that corresponds to the desired child process 
00618  * @param exitcode The returned exit status of the child, if a child process 
00619  *                 dies, or the signal that caused the child to die.
00620  *                 On platforms that don't support obtaining this information, 
00621  *                 the status parameter will be returned as APR_ENOTIMPL.
00622  * @param exitwhy Why the child died, the bitwise or of:
00623  * <PRE>
00624  *            APR_PROC_EXIT         -- process terminated normally
00625  *            APR_PROC_SIGNAL       -- process was killed by a signal
00626  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
00627  *                                     generated a core dump.
00628  * </PRE>
00629  * @param waithow How should we wait.  One of:
00630  * <PRE>
00631  *            APR_WAIT   -- block until the child process dies.
00632  *            APR_NOWAIT -- return immediately regardless of if the 
00633  *                          child is dead or not.
00634  * </PRE>
00635  * @remark The childs status is in the return code to this process.  It is one of:
00636  * <PRE>
00637  *            APR_CHILD_DONE     -- child is no longer running.
00638  *            APR_CHILD_NOTDONE  -- child is still running.
00639  * </PRE>
00640  */
00641 APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
00642                                         int *exitcode, apr_exit_why_e *exitwhy,
00643                                         apr_wait_how_e waithow);
00644 
00645 /**
00646  * Wait for any current child process to die and return information 
00647  * about that child.
00648  * @param proc Pointer to NULL on entry, will be filled out with child's 
00649  *             information 
00650  * @param exitcode The returned exit status of the child, if a child process 
00651  *                 dies, or the signal that caused the child to die.
00652  *                 On platforms that don't support obtaining this information, 
00653  *                 the status parameter will be returned as APR_ENOTIMPL.
00654  * @param exitwhy Why the child died, the bitwise or of:
00655  * <PRE>
00656  *            APR_PROC_EXIT         -- process terminated normally
00657  *            APR_PROC_SIGNAL       -- process was killed by a signal
00658  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
00659  *                                     generated a core dump.
00660  * </PRE>
00661  * @param waithow How should we wait.  One of:
00662  * <PRE>
00663  *            APR_WAIT   -- block until the child process dies.
00664  *            APR_NOWAIT -- return immediately regardless of if the 
00665  *                          child is dead or not.
00666  * </PRE>
00667  * @param p Pool to allocate child information out of.
00668  * @bug Passing proc as a *proc rather than **proc was an odd choice
00669  * for some platforms... this should be revisited in 1.0
00670  */
00671 APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
00672                                                   int *exitcode,
00673                                                   apr_exit_why_e *exitwhy,
00674                                                   apr_wait_how_e waithow,
00675                                                   apr_pool_t *p);
00676 
00677 #define APR_PROC_DETACH_FOREGROUND 0    /**< Do not detach */
00678 #define APR_PROC_DETACH_DAEMONIZE 1     /**< Detach */
00679 
00680 /**
00681  * Detach the process from the controlling terminal.
00682  * @param daemonize set to non-zero if the process should daemonize
00683  *                  and become a background process, else it will
00684  *                  stay in the foreground.
00685  */
00686 APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
00687 
00688 /**
00689  * Register an other_child -- a child associated to its registered 
00690  * maintence callback.  This callback is invoked when the process
00691  * dies, is disconnected or disappears.
00692  * @param proc The child process to register.
00693  * @param maintenance maintenance is a function that is invoked with a 
00694  *                    reason and the data pointer passed here.
00695  * @param data Opaque context data passed to the maintenance function.
00696  * @param write_fd An fd that is probed for writing.  If it is ever unwritable
00697  *                 then the maintenance is invoked with reason 
00698  *                 OC_REASON_UNWRITABLE.
00699  * @param p The pool to use for allocating memory.
00700  * @bug write_fd duplicates the proc->out stream, it's really redundant
00701  * and should be replaced in the APR 1.0 API with a bitflag of which
00702  * proc->in/out/err handles should be health checked.
00703  * @bug no platform currently tests the pipes health.
00704  */
00705 APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 
00706                                            void (*maintenance) (int reason, 
00707                                                                 void *, 
00708                                                                 int status),
00709                                            void *data, apr_file_t *write_fd,
00710                                            apr_pool_t *p);
00711 
00712 /**
00713  * Stop watching the specified other child.  
00714  * @param data The data to pass to the maintenance function.  This is
00715  *             used to find the process to unregister.
00716  * @warning Since this can be called by a maintenance function while we're
00717  *          scanning the other_children list, all scanners should protect 
00718  *          themself by loading ocr->next before calling any maintenance 
00719  *          function.
00720  */
00721 APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
00722 
00723 /**
00724  * Notify the maintenance callback of a registered other child process
00725  * that application has detected an event, such as death.
00726  * @param proc The process to check
00727  * @param reason The reason code to pass to the maintenance function
00728  * @param status The status to pass to the maintenance function
00729  * @remark An example of code using this behavior;
00730  * <pre>
00731  * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
00732  * if (APR_STATUS_IS_CHILD_DONE(rv)) {
00733  * \#if APR_HAS_OTHER_CHILD
00734  *     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
00735  *             == APR_SUCCESS) {
00736  *         ;  (already handled)
00737  *     }
00738  *     else
00739  * \#endif
00740  *         [... handling non-otherchild processes death ...]
00741  * </pre>
00742  */
00743 APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 
00744                                                      int reason,
00745                                                      int status);
00746 
00747 /**
00748  * Test one specific other child processes and invoke the maintenance callback 
00749  * with the appropriate reason code, if still running, or the appropriate reason 
00750  * code if the process is no longer healthy.
00751  * @param ocr The registered other child
00752  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running
00753  */
00754 APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr,
00755                                                int reason);
00756 
00757 /**
00758  * Test all registered other child processes and invoke the maintenance callback 
00759  * with the appropriate reason code, if still running, or the appropriate reason 
00760  * code if the process is no longer healthy.
00761  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes
00762  */
00763 APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason);
00764 
00765 /** 
00766  * Terminate a process.
00767  * @param proc The process to terminate.
00768  * @param sig How to kill the process.
00769  */
00770 APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
00771 
00772 /**
00773  * Register a process to be killed when a pool dies.
00774  * @param a The pool to use to define the processes lifetime 
00775  * @param proc The process to register
00776  * @param how How to kill the process, one of:
00777  * <PRE>
00778  *         APR_KILL_NEVER         -- process is never sent any signals
00779  *         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
00780  *         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
00781  *         APR_JUST_WAIT          -- wait forever for the process to complete
00782  *         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
00783  * </PRE>
00784  */
00785 APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc,
00786                                            apr_kill_conditions_e how);
00787 
00788 #if APR_HAS_THREADS 
00789 
00790 #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
00791 
00792 /**
00793  * Setup the process for a single thread to be used for all signal handling.
00794  * @warning This must be called before any threads are created
00795  */
00796 APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
00797 
00798 /**
00799  * Make the current thread listen for signals.  This thread will loop
00800  * forever, calling a provided function whenever it receives a signal.  That
00801  * functions should return 1 if the signal has been handled, 0 otherwise.
00802  * @param signal_handler The function to call when a signal is received
00803  * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
00804  */
00805 APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
00806 
00807 #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
00808 
00809 /**
00810  * Get the child-pool used by the thread from the thread info.
00811  * @return apr_pool_t the pool
00812  */
00813 APR_POOL_DECLARE_ACCESSOR(thread);
00814 
00815 #endif /* APR_HAS_THREADS */
00816 
00817 /** @} */
00818 
00819 #ifdef __cplusplus
00820 }
00821 #endif
00822 
00823 #endif  /* ! APR_THREAD_PROC_H */
00824 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines