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