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 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 */
 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 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  */
 216 APR_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  */
 224 APR_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  */
 233 APR_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  */
 240 APR_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. */
 253 APR_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  */
 264 APR_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  */
 274 APR_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  */
 282 APR_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  */
 288 APR_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  */
 296 APR_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  */
 308 APR_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  */
 315 APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
 316
 317 /**
 318  * Return user data 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  */
 323 APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
 324                                              apr_thread_t *thread);
 325
 326 /**
 327  * Set user data 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  */
 333 APR_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  */
 343 APR_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  */
 352 APR_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  */
 360 APR_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  */
 367 APR_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  */
 375 APR_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  */
 385 APR_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  */
 396 APR_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  */
 413 APR_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  */
 432 APR_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  */
 449 APR_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  */
 466 APR_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  */
 477 APR_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  */
 491 APR_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  */
 499 APR_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  */
 515 APR_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  */
 531 APR_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  */
 546 APR_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  */
 556 APR_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  */
 567 APR_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  */
 576 APR_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  */
 589 APR_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  */
 608 APR_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  */
 641 APR_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  */
 671 APR_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  */
 686 APR_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  */
 705 APR_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  */
 721 APR_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  */
 743 APR_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  */
 754 APR_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  */
 763 APR_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  */
 770 APR_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  */
 785 APR_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  */
 796 APR_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  */
 805 APR_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  */
 813 APR_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