1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_THREAD_PROC_H 18#define APR_THREAD_PROC_H 19 20/** 21 * @file apr_thread_proc.h 22 * @brief APR Thread and Process Library 23 */ 24 25#include "apr.h" 26#include "apr_file_io.h" 27#include "apr_pools.h" 28#include "apr_errno.h" 29 30#if APR_HAVE_STRUCT_RLIMIT 31#include <sys/time.h> 32#include <sys/resource.h> 33#endif 34 35#ifdef __cplusplus 36extern "C" { 37#endif /* __cplusplus */ 38 39/** 40 * @defgroup apr_thread_proc Threads and Process Functions 41 * @ingroup APR 42 * @{ 43 */ 44 45typedef enum { 46 APR_SHELLCMD, /**< use the shell to invoke the program */ 47 APR_PROGRAM, /**< invoke the program directly, no copied env */ 48 APR_PROGRAM_ENV, /**< invoke the program, replicating our environment */ 49 APR_PROGRAM_PATH, /**< find program on PATH, use our environment */ 50 APR_SHELLCMD_ENV /**< use the shell to invoke the program, 51 * replicating our environment 52 */ 53} apr_cmdtype_e; 54 55typedef enum { 56 APR_WAIT, /**< wait for the specified process to finish */ 57 APR_NOWAIT /**< do not wait -- just see if it has finished */ 58} apr_wait_how_e; 59 60/* I am specifically calling out the values so that the macros below make 61 * more sense. Yes, I know I don't need to, but I am hoping this makes what 62 * I am doing more clear. If you want to add more reasons to exit, continue 63 * to use bitmasks. 64 */ 65typedef enum { 66 APR_PROC_EXIT = 1, /**< process exited normally */ 67 APR_PROC_SIGNAL = 2, /**< process exited due to a signal */ 68 APR_PROC_SIGNAL_CORE = 4 /**< process exited and dumped a core file */ 69} apr_exit_why_e; 70 71/** did we exit the process */ 72#define APR_PROC_CHECK_EXIT(x) (x & APR_PROC_EXIT) 73/** did we get a signal */ 74#define APR_PROC_CHECK_SIGNALED(x) (x & APR_PROC_SIGNAL) 75/** did we get core */ 76#define APR_PROC_CHECK_CORE_DUMP(x) (x & APR_PROC_SIGNAL_CORE) 77 78/** @see apr_procattr_io_set */ 79#define APR_NO_PIPE 0 80/** @see apr_procattr_io_set and apr_file_pipe_create_ex */ 81#define APR_FULL_BLOCK 1 82/** @see apr_procattr_io_set and apr_file_pipe_create_ex */ 83#define APR_FULL_NONBLOCK 2 84/** @see apr_procattr_io_set */ 85#define APR_PARENT_BLOCK 3 86/** @see apr_procattr_io_set */ 87#define APR_CHILD_BLOCK 4 88/** @see apr_procattr_io_set */ 89#define APR_NO_FILE 8 90 91/** @see apr_file_pipe_create_ex */ 92#define APR_READ_BLOCK 3 93/** @see apr_file_pipe_create_ex */ 94#define APR_WRITE_BLOCK 4 95 96/** @see apr_procattr_io_set 97 * @note Win32 only effective with version 1.2.12, portably introduced in 1.3.0 98 */ 99#define APR_NO_FILE 8 100 101/** @see apr_procattr_limit_set */ 102#define APR_LIMIT_CPU 0 103/** @see apr_procattr_limit_set */ 104#define APR_LIMIT_MEM 1 105/** @see apr_procattr_limit_set */ 106#define APR_LIMIT_NPROC 2 107/** @see apr_procattr_limit_set */ 108#define APR_LIMIT_NOFILE 3 109 110/** 111 * @defgroup APR_OC Other Child Flags 112 * @{ 113 */ 114#define APR_OC_REASON_DEATH 0 /**< child has died, caller must call 115 * unregister still */ 116#define APR_OC_REASON_UNWRITABLE 1 /**< write_fd is unwritable */ 117#define APR_OC_REASON_RESTART 2 /**< a restart is occuring, perform 118 * any necessary cleanup (including 119 * sending a special signal to child) 120 */ 121#define APR_OC_REASON_UNREGISTER 3 /**< unregister has been called, do 122 * whatever is necessary (including 123 * kill the child) */ 124#define APR_OC_REASON_LOST 4 /**< somehow the child exited without 125 * us knowing ... buggy os? */ 126#define APR_OC_REASON_RUNNING 5 /**< a health check is occuring, 127 * for most maintainence functions 128 * this is a no-op. 129 */ 130/** @} */ 131 132/** The APR process type */ 133typedef struct apr_proc_t { 134 /** The process ID */ 135 pid_t pid; 136 /** Parent's side of pipe to child's stdin */ 137 apr_file_t *in; 138 /** Parent's side of pipe to child's stdout */ 139 apr_file_t *out; 140 /** Parent's side of pipe to child's stdouterr */ 141 apr_file_t *err; 142#if APR_HAS_PROC_INVOKED || defined(DOXYGEN) 143 /** Diagnositics/debugging string of the command invoked for 144 * this process [only present if APR_HAS_PROC_INVOKED is true] 145 * @remark Only enabled on Win32 by default. 146 * @bug This should either always or never be present in release 147 * builds - since it breaks binary compatibility. We may enable 148 * it always in APR 1.0 yet leave it undefined in most cases. 149 */ 150 char *invoked; 151#endif 152#if defined(WIN32) || defined(DOXYGEN) 153 /** (Win32 only) Creator's handle granting access to the process 154 * @remark This handle is closed and reset to NULL in every case 155 * corresponding to a waitpid() on Unix which returns the exit status. 156 * Therefore Win32 correspond's to Unix's zombie reaping characteristics 157 * and avoids potential handle leaks. 158 */ 159 HANDLE hproc; 160#endif 161} apr_proc_t; 162 163/** 164 * The prototype for APR child errfn functions. (See the description 165 * of apr_procattr_child_errfn_set() for more information.) 166 * It is passed the following parameters: 167 * @param pool Pool associated with the apr_proc_t. If your child 168 * error function needs user data, associate it with this 169 * pool. 170 * @param err APR error code describing the error 171 * @param description Text description of type of processing which failed 172 */ 173typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err, 174 const char *description); 175 176/** Opaque Thread structure. */ 177typedef struct apr_thread_t apr_thread_t; 178 179/** Opaque Thread attributes structure. */ 180typedef struct apr_threadattr_t apr_threadattr_t; 181 182/** Opaque Process attributes structure. */ 183typedef struct apr_procattr_t apr_procattr_t; 184 185/** Opaque control variable for one-time atomic variables. */ 186typedef struct apr_thread_once_t apr_thread_once_t; 187 188/** Opaque thread private address space. */ 189typedef struct apr_threadkey_t apr_threadkey_t; 190 191/** Opaque record of child process. */ 192typedef struct apr_other_child_rec_t apr_other_child_rec_t; 193 194/** 195 * The prototype for any APR thread worker functions. 196 */ 197typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*); 198 199typedef enum { 200 APR_KILL_NEVER, /**< process is never sent any signals */ 201 APR_KILL_ALWAYS, /**< process is sent SIGKILL on apr_pool_t cleanup */ 202 APR_KILL_AFTER_TIMEOUT, /**< SIGTERM, wait 3 seconds, SIGKILL */ 203 APR_JUST_WAIT, /**< wait forever for the process to complete */ 204 APR_KILL_ONLY_ONCE /**< send SIGTERM and then wait */ 205} apr_kill_conditions_e; 206 207/* Thread Function definitions */ 208 209#if APR_HAS_THREADS 210 211/** 212 * Create and initialize a new threadattr variable 213 * @param new_attr The newly created threadattr. 214 * @param cont The pool to use 215 */ 216APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 217 apr_pool_t *cont); 218 219/** 220 * Set if newly created threads should be created in detached state. 221 * @param attr The threadattr to affect 222 * @param on Non-zero if detached threads should be created. 223 */ 224APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 225 apr_int32_t on); 226 227/** 228 * Get the detach state for this threadattr. 229 * @param attr The threadattr to reference 230 * @return APR_DETACH if threads are to be detached, or APR_NOTDETACH 231 * if threads are to be joinable. 232 */ 233APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr); 234 235/** 236 * Set the stack size of newly created threads. 237 * @param attr The threadattr to affect 238 * @param stacksize The stack size in bytes 239 */ 240APR_DECLARE(apr_status_t) apr_threadattr_stacksize_set(apr_threadattr_t *attr, 241 apr_size_t stacksize); 242 243/** 244 * Set the stack guard area size of newly created threads. 245 * @param attr The threadattr to affect 246 * @param guardsize The stack guard area size in bytes 247 * @note Thread library implementations commonly use a "guard area" 248 * after each thread's stack which is not readable or writable such that 249 * stack overflows cause a segfault; this consumes e.g. 4K of memory 250 * and increases memory management overhead. Setting the guard area 251 * size to zero hence trades off reliable behaviour on stack overflow 252 * for performance. */ 253APR_DECLARE(apr_status_t) apr_threadattr_guardsize_set(apr_threadattr_t *attr, 254 apr_size_t guardsize); 255 256/** 257 * Create a new thread of execution 258 * @param new_thread The newly created thread handle. 259 * @param attr The threadattr to use to determine how to create the thread 260 * @param func The function to start the new thread in 261 * @param data Any data to be passed to the starting function 262 * @param cont The pool to use 263 */ 264APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 265 apr_threadattr_t *attr, 266 apr_thread_start_t func, 267 void *data, apr_pool_t *cont); 268 269/** 270 * stop the current thread 271 * @param thd The thread to stop 272 * @param retval The return value to pass back to any thread that cares 273 */ 274APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 275 apr_status_t retval); 276 277/** 278 * block until the desired thread stops executing. 279 * @param retval The return value from the dead thread. 280 * @param thd The thread to join 281 */ 282APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 283 apr_thread_t *thd); 284 285/** 286 * force the current thread to yield the processor 287 */ 288APR_DECLARE(void) apr_thread_yield(void); 289 290/** 291 * Initialize the control variable for apr_thread_once. If this isn't 292 * called, apr_initialize won't work. 293 * @param control The control variable to initialize 294 * @param p The pool to allocate data from. 295 */ 296APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control, 297 apr_pool_t *p); 298 299/** 300 * Run the specified function one time, regardless of how many threads 301 * call it. 302 * @param control The control variable. The same variable should 303 * be passed in each time the function is tried to be 304 * called. This is how the underlying functions determine 305 * if the function has ever been called before. 306 * @param func The function to call. 307 */ 308APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control, 309 void (*func)(void)); 310 311/** 312 * detach a thread 313 * @param thd The thread to detach 314 */ 315APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd); 316 317/** 318 * Return the pool associated with the current thread. 319 * @param data The user data associated with the thread. 320 * @param key The key to associate with the data 321 * @param thread The currently open thread. 322 */ 323APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key, 324 apr_thread_t *thread); 325 326/** 327 * Return the pool associated with the current thread. 328 * @param data The user data to associate with the thread. 329 * @param key The key to use for associating the data with the thread 330 * @param cleanup The cleanup routine to use when the thread is destroyed. 331 * @param thread The currently open thread. 332 */ 333APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key, 334 apr_status_t (*cleanup) (void *), 335 apr_thread_t *thread); 336 337/** 338 * Create and initialize a new thread private address space 339 * @param key The thread private handle. 340 * @param dest The destructor to use when freeing the private memory. 341 * @param cont The pool to use 342 */ 343APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 344 void (*dest)(void *), 345 apr_pool_t *cont); 346 347/** 348 * Get a pointer to the thread private memory 349 * @param new_mem The data stored in private memory 350 * @param key The handle for the desired thread private memory 351 */ 352APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 353 apr_threadkey_t *key); 354 355/** 356 * Set the data to be stored in thread private memory 357 * @param priv The data to be stored in private memory 358 * @param key The handle for the desired thread private memory 359 */ 360APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 361 apr_threadkey_t *key); 362 363/** 364 * Free the thread private memory 365 * @param key The handle for the desired thread private memory 366 */ 367APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key); 368 369/** 370 * Return the pool associated with the current threadkey. 371 * @param data The user data associated with the threadkey. 372 * @param key The key associated with the data 373 * @param threadkey The currently open threadkey. 374 */ 375APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key, 376 apr_threadkey_t *threadkey); 377 378/** 379 * Return the pool associated with the current threadkey. 380 * @param data The data to set. 381 * @param key The key to associate with the data. 382 * @param cleanup The cleanup routine to use when the file is destroyed. 383 * @param threadkey The currently open threadkey. 384 */ 385APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key, 386 apr_status_t (*cleanup) (void *), 387 apr_threadkey_t *threadkey); 388 389#endif 390 391/** 392 * Create and initialize a new procattr variable 393 * @param new_attr The newly created procattr. 394 * @param cont The pool to use 395 */ 396APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr, 397 apr_pool_t *cont); 398 399/** 400 * Determine if any of stdin, stdout, or stderr should be linked to pipes 401 * when starting a child process. 402 * @param attr The procattr we care about. 403 * @param in Should stdin be a pipe back to the parent? 404 * @param out Should stdout be a pipe back to the parent? 405 * @param err Should stderr be a pipe back to the parent? 406 * @note If APR_NO_PIPE, there will be no special channel, the child 407 * inherits the parent's corresponding stdio stream. If APR_NO_FILE is 408 * specified, that corresponding stream is closed in the child (and will 409 * be INVALID_HANDLE_VALUE when inspected on Win32). This can have ugly 410 * side effects, as the next file opened in the child on Unix will fall 411 * into the stdio stream fd slot! 412 */ 413APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 414 apr_int32_t in, apr_int32_t out, 415 apr_int32_t err); 416 417/** 418 * Set the child_in and/or parent_in values to existing apr_file_t values. 419 * @param attr The procattr we care about. 420 * @param child_in apr_file_t value to use as child_in. Must be a valid file. 421 * @param parent_in apr_file_t value to use as parent_in. Must be a valid file. 422 * @remark This is NOT a required initializer function. This is 423 * useful if you have already opened a pipe (or multiple files) 424 * that you wish to use, perhaps persistently across multiple 425 * process invocations - such as a log file. You can save some 426 * extra function calls by not creating your own pipe since this 427 * creates one in the process space for you. 428 * @bug Note that calling this function with two NULL files on some platforms 429 * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor 430 * is it supported. @see apr_procattr_io_set instead for simple pipes. 431 */ 432APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr, 433 apr_file_t *child_in, 434 apr_file_t *parent_in); 435 436/** 437 * Set the child_out and parent_out values to existing apr_file_t values. 438 * @param attr The procattr we care about. 439 * @param child_out apr_file_t value to use as child_out. Must be a valid file. 440 * @param parent_out apr_file_t value to use as parent_out. Must be a valid file. 441 * @remark This is NOT a required initializer function. This is 442 * useful if you have already opened a pipe (or multiple files) 443 * that you wish to use, perhaps persistently across multiple 444 * process invocations - such as a log file. 445 * @bug Note that calling this function with two NULL files on some platforms 446 * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor 447 * is it supported. @see apr_procattr_io_set instead for simple pipes. 448 */ 449APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr, 450 apr_file_t *child_out, 451 apr_file_t *parent_out); 452 453/** 454 * Set the child_err and parent_err values to existing apr_file_t values. 455 * @param attr The procattr we care about. 456 * @param child_err apr_file_t value to use as child_err. Must be a valid file. 457 * @param parent_err apr_file_t value to use as parent_err. Must be a valid file. 458 * @remark This is NOT a required initializer function. This is 459 * useful if you have already opened a pipe (or multiple files) 460 * that you wish to use, perhaps persistently across multiple 461 * process invocations - such as a log file. 462 * @bug Note that calling this function with two NULL files on some platforms 463 * creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor 464 * is it supported. @see apr_procattr_io_set instead for simple pipes. 465 */ 466APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr, 467 apr_file_t *child_err, 468 apr_file_t *parent_err); 469 470/** 471 * Set which directory the child process should start executing in. 472 * @param attr The procattr we care about. 473 * @param dir Which dir to start in. By default, this is the same dir as 474 * the parent currently resides in, when the createprocess call 475 * is made. 476 */ 477APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 478 const char *dir); 479 480/** 481 * Set what type of command the child process will call. 482 * @param attr The procattr we care about. 483 * @param cmd The type of command. One of: 484 * <PRE> 485 * APR_SHELLCMD -- Anything that the shell can handle 486 * APR_PROGRAM -- Executable program (default) 487 * APR_PROGRAM_ENV -- Executable program, copy environment 488 * APR_PROGRAM_PATH -- Executable program on PATH, copy env 489 * </PRE> 490 */ 491APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr, 492 apr_cmdtype_e cmd); 493 494/** 495 * Determine if the child should start in detached state. 496 * @param attr The procattr we care about. 497 * @param detach Should the child start in detached state? Default is no. 498 */ 499APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 500 apr_int32_t detach); 501 502#if APR_HAVE_STRUCT_RLIMIT 503/** 504 * Set the Resource Utilization limits when starting a new process. 505 * @param attr The procattr we care about. 506 * @param what Which limit to set, one of: 507 * <PRE> 508 * APR_LIMIT_CPU 509 * APR_LIMIT_MEM 510 * APR_LIMIT_NPROC 511 * APR_LIMIT_NOFILE 512 * </PRE> 513 * @param limit Value to set the limit to. 514 */ 515APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 516 apr_int32_t what, 517 struct rlimit *limit); 518#endif 519 520/** 521 * Specify an error function to be called in the child process if APR 522 * encounters an error in the child prior to running the specified program. 523 * @param attr The procattr describing the child process to be created. 524 * @param errfn The function to call in the child process. 525 * @remark At the present time, it will only be called from apr_proc_create() 526 * on platforms where fork() is used. It will never be called on other 527 * platforms, on those platforms apr_proc_create() will return the error 528 * in the parent process rather than invoke the callback in the now-forked 529 * child process. 530 */ 531APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr, 532 apr_child_errfn_t *errfn); 533 534/** 535 * Specify that apr_proc_create() should do whatever it can to report 536 * failures to the caller of apr_proc_create(), rather than find out in 537 * the child. 538 * @param attr The procattr describing the child process to be created. 539 * @param chk Flag to indicate whether or not extra work should be done 540 * to try to report failures to the caller. 541 * @remark This flag only affects apr_proc_create() on platforms where 542 * fork() is used. This leads to extra overhead in the calling 543 * process, but that may help the application handle such 544 * errors more gracefully. 545 */ 546APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr, 547 apr_int32_t chk); 548 549/** 550 * Determine if the child should start in its own address space or using the 551 * current one from its parent 552 * @param attr The procattr we care about. 553 * @param addrspace Should the child start in its own address space? Default 554 * is no on NetWare and yes on other platforms. 555 */ 556APR_DECLARE(apr_status_t) apr_procattr_addrspace_set(apr_procattr_t *attr, 557 apr_int32_t addrspace); 558 559/** 560 * Set the username used for running process 561 * @param attr The procattr we care about. 562 * @param username The username used 563 * @param password User password if needed. Password is needed on WIN32 564 * or any other platform having 565 * APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set. 566 */ 567APR_DECLARE(apr_status_t) apr_procattr_user_set(apr_procattr_t *attr, 568 const char *username, 569 const char *password); 570 571/** 572 * Set the group used for running process 573 * @param attr The procattr we care about. 574 * @param groupname The group name used 575 */ 576APR_DECLARE(apr_status_t) apr_procattr_group_set(apr_procattr_t *attr, 577 const char *groupname); 578 579 580#if APR_HAS_FORK 581/** 582 * This is currently the only non-portable call in APR. This executes 583 * a standard unix fork. 584 * @param proc The resulting process handle. 585 * @param cont The pool to use. 586 * @remark returns APR_INCHILD for the child, and APR_INPARENT for the parent 587 * or an error. 588 */ 589APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont); 590#endif 591 592/** 593 * Create a new process and execute a new program within that process. 594 * @param new_proc The resulting process handle. 595 * @param progname The program to run 596 * @param args the arguments to pass to the new program. The first 597 * one should be the program name. 598 * @param env The new environment table for the new process. This 599 * should be a list of NULL-terminated strings. This argument 600 * is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and 601 * APR_SHELLCMD_ENV types of commands. 602 * @param attr the procattr we should use to determine how to create the new 603 * process 604 * @param pool The pool to use. 605 * @note This function returns without waiting for the new process to terminate; 606 * use apr_proc_wait for that. 607 */ 608APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc, 609 const char *progname, 610 const char * const *args, 611 const char * const *env, 612 apr_procattr_t *attr, 613 apr_pool_t *pool); 614 615/** 616 * Wait for a child process to die 617 * @param proc The process handle that corresponds to the desired child process 618 * @param exitcode The returned exit status of the child, if a child process 619 * dies, or the signal that caused the child to die. 620 * On platforms that don't support obtaining this information, 621 * the status parameter will be returned as APR_ENOTIMPL. 622 * @param exitwhy Why the child died, the bitwise or of: 623 * <PRE> 624 * APR_PROC_EXIT -- process terminated normally 625 * APR_PROC_SIGNAL -- process was killed by a signal 626 * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and 627 * generated a core dump. 628 * </PRE> 629 * @param waithow How should we wait. One of: 630 * <PRE> 631 * APR_WAIT -- block until the child process dies. 632 * APR_NOWAIT -- return immediately regardless of if the 633 * child is dead or not. 634 * </PRE> 635 * @remark The childs status is in the return code to this process. It is one of: 636 * <PRE> 637 * APR_CHILD_DONE -- child is no longer running. 638 * APR_CHILD_NOTDONE -- child is still running. 639 * </PRE> 640 */ 641APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc, 642 int *exitcode, apr_exit_why_e *exitwhy, 643 apr_wait_how_e waithow); 644 645/** 646 * Wait for any current child process to die and return information 647 * about that child. 648 * @param proc Pointer to NULL on entry, will be filled out with child's 649 * information 650 * @param exitcode The returned exit status of the child, if a child process 651 * dies, or the signal that caused the child to die. 652 * On platforms that don't support obtaining this information, 653 * the status parameter will be returned as APR_ENOTIMPL. 654 * @param exitwhy Why the child died, the bitwise or of: 655 * <PRE> 656 * APR_PROC_EXIT -- process terminated normally 657 * APR_PROC_SIGNAL -- process was killed by a signal 658 * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and 659 * generated a core dump. 660 * </PRE> 661 * @param waithow How should we wait. One of: 662 * <PRE> 663 * APR_WAIT -- block until the child process dies. 664 * APR_NOWAIT -- return immediately regardless of if the 665 * child is dead or not. 666 * </PRE> 667 * @param p Pool to allocate child information out of. 668 * @bug Passing proc as a *proc rather than **proc was an odd choice 669 * for some platforms... this should be revisited in 1.0 670 */ 671APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc, 672 int *exitcode, 673 apr_exit_why_e *exitwhy, 674 apr_wait_how_e waithow, 675 apr_pool_t *p); 676 677#define APR_PROC_DETACH_FOREGROUND 0 /**< Do not detach */ 678#define APR_PROC_DETACH_DAEMONIZE 1 /**< Detach */ 679 680/** 681 * Detach the process from the controlling terminal. 682 * @param daemonize set to non-zero if the process should daemonize 683 * and become a background process, else it will 684 * stay in the foreground. 685 */ 686APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize); 687 688/** 689 * Register an other_child -- a child associated to its registered 690 * maintence callback. This callback is invoked when the process 691 * dies, is disconnected or disappears. 692 * @param proc The child process to register. 693 * @param maintenance maintenance is a function that is invoked with a 694 * reason and the data pointer passed here. 695 * @param data Opaque context data passed to the maintenance function. 696 * @param write_fd An fd that is probed for writing. If it is ever unwritable 697 * then the maintenance is invoked with reason 698 * OC_REASON_UNWRITABLE. 699 * @param p The pool to use for allocating memory. 700 * @bug write_fd duplicates the proc->out stream, it's really redundant 701 * and should be replaced in the APR 1.0 API with a bitflag of which 702 * proc->in/out/err handles should be health checked. 703 * @bug no platform currently tests the pipes health. 704 */ 705APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 706 void (*maintenance) (int reason, 707 void *, 708 int status), 709 void *data, apr_file_t *write_fd, 710 apr_pool_t *p); 711 712/** 713 * Stop watching the specified other child. 714 * @param data The data to pass to the maintenance function. This is 715 * used to find the process to unregister. 716 * @warning Since this can be called by a maintenance function while we're 717 * scanning the other_children list, all scanners should protect 718 * themself by loading ocr->next before calling any maintenance 719 * function. 720 */ 721APR_DECLARE(void) apr_proc_other_child_unregister(void *data); 722 723/** 724 * Notify the maintenance callback of a registered other child process 725 * that application has detected an event, such as death. 726 * @param proc The process to check 727 * @param reason The reason code to pass to the maintenance function 728 * @param status The status to pass to the maintenance function 729 * @remark An example of code using this behavior; 730 * <pre> 731 * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p); 732 * if (APR_STATUS_IS_CHILD_DONE(rv)) { 733 * \#if APR_HAS_OTHER_CHILD 734 * if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status) 735 * == APR_SUCCESS) { 736 * ; (already handled) 737 * } 738 * else 739 * \#endif 740 * [... handling non-otherchild processes death ...] 741 * </pre> 742 */ 743APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 744 int reason, 745 int status); 746 747/** 748 * Test one specific other child processes and invoke the maintenance callback 749 * with the appropriate reason code, if still running, or the appropriate reason 750 * code if the process is no longer healthy. 751 * @param ocr The registered other child 752 * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running 753 */ 754APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr, 755 int reason); 756 757/** 758 * Test all registered other child processes and invoke the maintenance callback 759 * with the appropriate reason code, if still running, or the appropriate reason 760 * code if the process is no longer healthy. 761 * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes 762 */ 763APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason); 764 765/** 766 * Terminate a process. 767 * @param proc The process to terminate. 768 * @param sig How to kill the process. 769 */ 770APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig); 771 772/** 773 * Register a process to be killed when a pool dies. 774 * @param a The pool to use to define the processes lifetime 775 * @param proc The process to register 776 * @param how How to kill the process, one of: 777 * <PRE> 778 * APR_KILL_NEVER -- process is never sent any signals 779 * APR_KILL_ALWAYS -- process is sent SIGKILL on apr_pool_t cleanup 780 * APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL 781 * APR_JUST_WAIT -- wait forever for the process to complete 782 * APR_KILL_ONLY_ONCE -- send SIGTERM and then wait 783 * </PRE> 784 */ 785APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc, 786 apr_kill_conditions_e how); 787 788#if APR_HAS_THREADS 789 790#if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) 791 792/** 793 * Setup the process for a single thread to be used for all signal handling. 794 * @warning This must be called before any threads are created 795 */ 796APR_DECLARE(apr_status_t) apr_setup_signal_thread(void); 797 798/** 799 * Make the current thread listen for signals. This thread will loop 800 * forever, calling a provided function whenever it receives a signal. That 801 * functions should return 1 if the signal has been handled, 0 otherwise. 802 * @param signal_handler The function to call when a signal is received 803 * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum)) 804 */ 805APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum)); 806 807#endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */ 808 809/** 810 * Get the child-pool used by the thread from the thread info. 811 * @return apr_pool_t the pool 812 */ 813APR_POOL_DECLARE_ACCESSOR(thread); 814 815#endif /* APR_HAS_THREADS */ 816 817/** @} */ 818 819#ifdef __cplusplus 820} 821#endif 822 823#endif /* ! APR_THREAD_PROC_H */ 824 825