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