/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.apache.tomcat.jni;

Proc
Author:Mladen Turk
Deprecated: The scope of the APR/Native Library will be reduced in Tomcat 10.1.x onwards to only those components required to provide OpenSSL integration with the NIO and NIO2 connectors.
/** Proc * * @author Mladen Turk * * @deprecated The scope of the APR/Native Library will be reduced in Tomcat * 10.1.x onwards to only those components required to provide * OpenSSL integration with the NIO and NIO2 connectors. */
@Deprecated public class Proc { /* * apr_cmdtype_e enum */ public static final int APR_SHELLCM = 0;
use the shell to invoke the program
/** use the shell to invoke the program */
public static final int APR_PROGRAM = 1;
invoke the program directly, no copied env
/** invoke the program directly, no copied env */
public static final int APR_PROGRAM_ENV = 2;
invoke the program, replicating our environment
/** invoke the program, replicating our environment */
public static final int APR_PROGRAM_PATH = 3;
find program on PATH, use our environment
/** find program on PATH, use our environment */
public static final int APR_SHELLCMD_ENV = 4;
use the shell to invoke the program, replicating our environment
/** use the shell to invoke the program, * replicating our environment */
/* * apr_wait_how_e enum */ public static final int APR_WAIT = 0;
wait for the specified process to finish
/** wait for the specified process to finish */
public static final int APR_NOWAIT = 1;
do not wait -- just see if it has finished
/** do not wait -- just see if it has finished */
/* * apr_exit_why_e enum */ public static final int APR_PROC_EXIT = 1;
process exited normally
/** process exited normally */
public static final int APR_PROC_SIGNAL = 2;
process exited due to a signal
/** process exited due to a signal */
public static final int APR_PROC_SIGNAL_CORE = 4;
process exited and dumped a core file
/** process exited and dumped a core file */
public static final int APR_NO_PIPE = 0; public static final int APR_FULL_BLOCK = 1; public static final int APR_FULL_NONBLOCK = 2; public static final int APR_PARENT_BLOCK = 3; public static final int APR_CHILD_BLOCK = 4; public static final int APR_LIMIT_CPU = 0; public static final int APR_LIMIT_MEM = 1; public static final int APR_LIMIT_NPROC = 2; public static final int APR_LIMIT_NOFILE = 3;
child has died, caller must call unregister still
/** child has died, caller must call unregister still */
public static final int APR_OC_REASON_DEATH = 0;
write_fd is unwritable
/** write_fd is unwritable */
public static final int APR_OC_REASON_UNWRITABLE = 1;
a restart is occurring, perform any necessary cleanup (including sending a special signal to child)
/** a restart is occurring, perform any necessary cleanup (including * sending a special signal to child) */
public static final int APR_OC_REASON_RESTART = 2;
unregister has been called, do whatever is necessary (including kill the child)
/** unregister has been called, do whatever is necessary (including * kill the child) */
public static final int APR_OC_REASON_UNREGISTER = 3;
somehow the child exited without us knowing ... buggy os?
/** somehow the child exited without us knowing ... buggy os? */
public static final int APR_OC_REASON_LOST = 4;
a health check is occurring, for most maintenance functions this is a no-op.
/** a health check is occurring, for most maintenance functions * this is a no-op. */
public static final int APR_OC_REASON_RUNNING = 5; /* apr_kill_conditions_e enumeration */
process is never sent any signals
/** process is never sent any signals */
public static final int APR_KILL_NEVER = 0;
process is sent SIGKILL on apr_pool_t cleanup
/** process is sent SIGKILL on apr_pool_t cleanup */
public static final int APR_KILL_ALWAYS = 1;
SIGTERM, wait 3 seconds, SIGKILL
/** SIGTERM, wait 3 seconds, SIGKILL */
public static final int APR_KILL_AFTER_TIMEOUT = 2;
wait forever for the process to complete
/** wait forever for the process to complete */
public static final int APR_JUST_WAIT = 3;
send SIGTERM and then wait
/** send SIGTERM and then wait */
public static final int APR_KILL_ONLY_ONCE = 4; public static final int APR_PROC_DETACH_FOREGROUND = 0;
Do not detach
/** Do not detach */
public static final int APR_PROC_DETACH_DAEMONIZE = 1;
Detach
/** Detach */
/* Maximum number of arguments for create process call */ public static final int MAX_ARGS_SIZE = 1024; /* Maximum number of environment variables for create process call */ public static final int MAX_ENV_SIZE = 1024;
Allocate apr_proc_t structure from pool This is not an apr function.
Params:
  • cont – The pool to use.
Returns:the pointer
/** * Allocate apr_proc_t structure from pool * This is not an apr function. * @param cont The pool to use. * @return the pointer */
public static native long alloc(long cont);
This is currently the only non-portable call in APR. This executes a standard unix fork.
Params:
  • proc – The resulting process handle.
  • cont – The pool to use.
Returns:APR_INCHILD for the child, and APR_INPARENT for the parent or an error.
/** * This is currently the only non-portable call in APR. This executes * a standard unix fork. * @param proc The resulting process handle. * @param cont The pool to use. * @return APR_INCHILD for the child, and APR_INPARENT for the parent * or an error. */
public static native int fork(long [] proc, long cont);
Create a new process and execute a new program within that process. This function returns without waiting for the new process to terminate; use apr_proc_wait for that.
Params:
  • proc – The process handle
  • progname – The program to run
  • args – The arguments to pass to the new program. The first one should be the program name.
  • env – The new environment table for the new process. This should be a list of NULL-terminated strings. This argument is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and APR_SHELLCMD_ENV types of commands.
  • attr – The procattr we should use to determine how to create the new process
  • pool – The pool to use.
Returns:The resulting process handle.
/** * Create a new process and execute a new program within that process. * This function returns without waiting for the new process to terminate; * use apr_proc_wait for that. * @param proc The process handle * @param progname The program to run * @param args The arguments to pass to the new program. The first * one should be the program name. * @param env The new environment table for the new process. This * should be a list of NULL-terminated strings. This argument * is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and * APR_SHELLCMD_ENV types of commands. * @param attr The procattr we should use to determine how to create the new * process * @param pool The pool to use. * @return The resulting process handle. */
public static native int create(long proc, String progname, String [] args, String [] env, long attr, long pool);
Wait for a child process to die
Params:
  • proc – The process handle that corresponds to the desired child process
  • exit – exit[0] The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL. exit[1] Why the child died, the bitwise or of:
    APR_PROC_EXIT         -- process terminated normally
    APR_PROC_SIGNAL       -- process was killed by a signal
    APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
                             generated a core dump.
    
  • waithow – How should we wait. One of:
    APR_WAIT   -- block until the child process dies.
    APR_NOWAIT -- return immediately regardless of if the
                  child is dead or not.
    
Returns:The childs status is in the return code to this process. It is one of:
APR_CHILD_DONE     -- child is no longer running.
APR_CHILD_NOTDONE  -- child is still running.
/** * Wait for a child process to die * @param proc The process handle that corresponds to the desired child process * @param exit exit[0] The returned exit status of the child, if a child process * dies, or the signal that caused the child to die. * On platforms that don't support obtaining this information, * the status parameter will be returned as APR_ENOTIMPL. * exit[1] Why the child died, the bitwise or of: * <PRE> * APR_PROC_EXIT -- process terminated normally * APR_PROC_SIGNAL -- process was killed by a signal * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and * generated a core dump. * </PRE> * @param waithow How should we wait. One of: * <PRE> * APR_WAIT -- block until the child process dies. * APR_NOWAIT -- return immediately regardless of if the * child is dead or not. * </PRE> * @return The childs status is in the return code to this process. It is one of: * <PRE> * APR_CHILD_DONE -- child is no longer running. * APR_CHILD_NOTDONE -- child is still running. * </PRE> */
public static native int wait(long proc, int [] exit, int waithow);
Wait for any current child process to die and return information about that child.
Params:
  • proc – Pointer to NULL on entry, will be filled out with child's information
  • exit – exit[0] The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL. exit[1] Why the child died, the bitwise or of:
    APR_PROC_EXIT         -- process terminated normally
    APR_PROC_SIGNAL       -- process was killed by a signal
    APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
                             generated a core dump.
    
  • waithow – How should we wait. One of:
    APR_WAIT   -- block until the child process dies.
    APR_NOWAIT -- return immediately regardless of if the
                  child is dead or not.
    
  • pool – Pool to allocate child information out of.
Returns:the operation status
/** * Wait for any current child process to die and return information * about that child. * @param proc Pointer to NULL on entry, will be filled out with child's * information * @param exit exit[0] The returned exit status of the child, if a child process * dies, or the signal that caused the child to die. * On platforms that don't support obtaining this information, * the status parameter will be returned as APR_ENOTIMPL. * exit[1] Why the child died, the bitwise or of: * <PRE> * APR_PROC_EXIT -- process terminated normally * APR_PROC_SIGNAL -- process was killed by a signal * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and * generated a core dump. * </PRE> * @param waithow How should we wait. One of: * <PRE> * APR_WAIT -- block until the child process dies. * APR_NOWAIT -- return immediately regardless of if the * child is dead or not. * </PRE> * @param pool Pool to allocate child information out of. * @return the operation status */
public static native int waitAllProcs(long proc, int [] exit, int waithow, long pool);
Detach the process from the controlling terminal.
Params:
  • daemonize – set to non-zero if the process should daemonize and become a background process, else it will stay in the foreground.
Returns:the operation status
/** * Detach the process from the controlling terminal. * @param daemonize set to non-zero if the process should daemonize * and become a background process, else it will * stay in the foreground. * @return the operation status */
public static native int detach(int daemonize);
Terminate a process.
Params:
  • proc – The process to terminate.
  • sig – How to kill the process.
Returns:the operation status
/** * Terminate a process. * @param proc The process to terminate. * @param sig How to kill the process. * @return the operation status */
public static native int kill(long proc, int sig); }