contrib/apr/include/apr_thread_proc.h

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