Zygote.java revision 04aaaf18dac85eee31b3451226daf586a455feb7 
1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * 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
17package dalvik.system;
18
19/**
20 * Provides access to the Dalvik "zygote" feature, which allows a VM instance to
21 * be partially initialized and then fork()'d from the partially initialized
22 * state.
23 *
24 * @deprecated this is an internal Dalvik class that is not appropriate for
25 *      general use. It will be removed from the public API in a future release.
26 */
27public class Zygote {
28    /*
29     * Bit values for "debugFlags" argument.  The definitions are duplicated
30     * in the native code.
31     */
32    /** enable debugging over JDWP */
33    public static final int DEBUG_ENABLE_DEBUGGER   = 1;
34    /** enable JNI checks */
35    public static final int DEBUG_ENABLE_CHECKJNI   = 1 << 1;
36    /** enable Java programming language "assert" statements */
37    public static final int DEBUG_ENABLE_ASSERT     = 1 << 2;
38
39    private Zygote() {}
40
41    /**
42     * Forks a new Zygote instance, but does not leave the zygote mode.
43     * The current VM must have been started with the -Xzygote flag. The
44     * new child is expected to eventually call forkAndSpecialize()
45     *
46     * @return 0 if this is the child, pid of the child
47     * if this is the parent, or -1 on error
48     */
49    native public static int fork();
50
51    /**
52     * Forks a new VM instance.  The current VM must have been started
53     * with the -Xzygote flag. <b>NOTE: new instance keeps all
54     * root capabilities. The new process is expected to call capset()</b>.
55     *
56     * @param uid the UNIX uid that the new process should setuid() to after
57     * fork()ing and and before spawning any threads.
58     * @param gid the UNIX gid that the new process should setgid() to after
59     * fork()ing and and before spawning any threads.
60     * @param gids null-ok; a list of UNIX gids that the new process should
61     * setgroups() to after fork and before spawning any threads.
62     * @param debugFlags bit flags that enable debugging features.
63     * @param rlimits null-ok an array of rlimit tuples, with the second
64     * dimension having a length of 3 and representing
65     * (resource, rlim_cur, rlim_max). These are set via the posix
66     * setrlimit(2) call.
67     *
68     * @return 0 if this is the child, pid of the child
69     * if this is the parent, or -1 on error.
70     */
71    native public static int forkAndSpecialize(int uid, int gid, int[] gids,
72            int debugFlags, int[][] rlimits);
73
74    /**
75     * Forks a new VM instance.
76     * @deprecated use {@link Zygote#forkAndSpecialize(int, int, int[], int, int[][])}
77     */
78    @Deprecated
79    public static int forkAndSpecialize(int uid, int gid, int[] gids,
80            boolean enableDebugger, int[][] rlimits) {
81        int debugFlags = enableDebugger ? DEBUG_ENABLE_DEBUGGER : 0;
82        return forkAndSpecialize(uid, gid, gids, debugFlags, rlimits);
83    }
84
85    /**
86     * Special method to start the system server process. In addition to the
87     * common actions performed in forkAndSpecialize, the pid of the child
88     * process is recorded such that the death of the child process will cause
89     * zygote to exit.
90     *
91     * @param uid the UNIX uid that the new process should setuid() to after
92     * fork()ing and and before spawning any threads.
93     * @param gid the UNIX gid that the new process should setgid() to after
94     * fork()ing and and before spawning any threads.
95     * @param gids null-ok; a list of UNIX gids that the new process should
96     * setgroups() to after fork and before spawning any threads.
97     * @param debugFlags bit flags that enable debugging features.
98     * @param rlimits null-ok an array of rlimit tuples, with the second
99     * dimension having a length of 3 and representing
100     * (resource, rlim_cur, rlim_max). These are set via the posix
101     * setrlimit(2) call.
102     *
103     * @return 0 if this is the child, pid of the child
104     * if this is the parent, or -1 on error.
105     */
106    native public static int forkSystemServer(int uid, int gid,
107            int[] gids, int debugFlags, int[][] rlimits);
108
109    /**
110     * Special method to start the system server process.
111     * @deprecated use {@link Zygote#forkSystemServer(int, int, int[], int, int[][])}
112     */
113    @Deprecated
114    public static int forkSystemServer(int uid, int gid, int[] gids,
115            boolean enableDebugger, int[][] rlimits) {
116        int debugFlags = enableDebugger ? DEBUG_ENABLE_DEBUGGER : 0;
117        return forkAndSpecialize(uid, gid, gids, debugFlags, rlimits);
118    }
119}
120
121