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