1 // Copyright 2018 The Fuchsia Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #pragma once 6 7 #include <zircon/compiler.h> 8 #include <zircon/types.h> 9 10 #include <stdbool.h> 11 #include <stddef.h> 12 #include <stdint.h> 13 14 __BEGIN_CDECLS 15 16 // The |fdio_spawn| and |fdio_spawn_etc| functions allow some or all of the 17 // environment of the running process to be shared with the process being 18 // spawned. 19 20 // Provides the spawned process with the job in which the process was created. 21 // 22 // The spawned process receives the job using the |PA_JOB_DEFAULT| process 23 // argument. 24 #define FDIO_SPAWN_CLONE_JOB ((uint32_t)0x0001u) 25 26 // Provides the spawned process with the shared library loader resolved via 27 // fuchsia.process.Resolver (if resolved), or that which is used by this 28 // process. 29 // 30 // The shared library loader is passed as |PA_LDSVC_LOADER|. 31 #define FDIO_SPAWN_DEFAULT_LDSVC ((uint32_t)0x0002u) 32 // FDIO_SPAWN_CLONE_LDSVC is the same as FDIO_SPAWN_DEFAULT_LDSVC. 33 // TODO(ZX-3031): this name is deprecated. 34 #define FDIO_SPAWN_CLONE_LDSVC ((uint32_t)0x0002u) 35 36 // Clones the filesystem namespace into the spawned process. 37 #define FDIO_SPAWN_CLONE_NAMESPACE ((uint32_t)0x0004u) 38 39 // Clones file descriptors 0, 1, and 2 into the spawned process. 40 // 41 // Skips any of these file descriptors that are closed without generating an 42 // error. 43 #define FDIO_SPAWN_CLONE_STDIO ((uint32_t)0x0008u) 44 45 // Clones the environment into the spawned process. 46 #define FDIO_SPAWN_CLONE_ENVIRON ((uint32_t)0x0010u) 47 48 // Clones all of the above into the spawned process. 49 #define FDIO_SPAWN_CLONE_ALL ((uint32_t)0xFFFFu) 50 51 // Spawn a process in the given job. 52 // 53 // The program for the process is loaded from the given |path| and passed |argv|. 54 // The aspects of this process' environment indicated by |flags| are shared with 55 // the process. If the target program begins with |#!resolve | then the binary is 56 // resolved by url via |fuchsia.process.Resolver|. 57 // 58 // The |argv| array must be terminated with a null pointer. 59 // 60 // If |job| is |ZX_HANDLE_INVALID|, then the process is spawned in 61 // |zx_job_default()|. Does not take ownership of |job|. 62 // 63 // Upon success, |process_out| will be a handle to the process. 64 zx_status_t fdio_spawn(zx_handle_t job, 65 uint32_t flags, 66 const char* path, 67 const char* const* argv, 68 zx_handle_t* process_out); 69 70 // The |fdio_spawn_etc| function allows the running process to control the file 71 // descriptor table in the process being spawned. 72 73 // Duplicate a descriptor |local_fd| into |target_fd| in the spawned process. 74 // 75 // Uses the |fd| entry in the |fdio_spawn_action_t| union. 76 #define FDIO_SPAWN_ACTION_CLONE_FD ((uint32_t)0x0001u) 77 78 // Transfer local descriptor |local_fd| into |target_fd| in the spawned process. 79 // 80 // This action will fail if |local_fd| is not a valid |local_fd|, if |local_fd| 81 // has been duplicated, if |local_fd| is being used in an io operation, or if 82 // |local_fd| does not support this operation. 83 // 84 // From the point of view of the calling process, the |local_fd| will appear to 85 // have been closed, regardless of whether the |fdio_spawn_etc| call succeeds. 86 // 87 // Uses the |fd| entry in the |fdio_spawn_action_t| union. 88 #define FDIO_SPAWN_ACTION_TRANSFER_FD ((uint32_t)0x0002u) 89 90 // Add the given entry to the namespace of the spawned process. 91 // 92 // If |FDIO_SPAWN_CLONE_NAMESPACE| is specified via |flags|, the namespace entry 93 // is added to the cloned namespace from the calling process. 94 // 95 // The given handle will be closed regardless of whether the |fdio_spawn_etc| 96 // call succeeds. 97 // 98 // Uses the |ns| entry in the |fdio_spawn_action_t| union. 99 #define FDIO_SPAWN_ACTION_ADD_NS_ENTRY ((uint32_t)0x0003u) 100 101 // Add the given handle to the process arguments of the spawned process. 102 // 103 // The given handle will be closed regardless of whether the |fdio_spawn_etc| 104 // call succeeds. 105 // 106 // Uses the |h| entry in the |fdio_spawn_action_t| union. 107 #define FDIO_SPAWN_ACTION_ADD_HANDLE ((uint32_t)0x0004u) 108 109 // Sets the name of the spawned process to the given name. 110 // 111 // Overrides the default of use the first argument to name the process. 112 // 113 // Uses the |name| entry in the |fdio_spawn_action_t| union. 114 #define FDIO_SPAWN_ACTION_SET_NAME ((uint32_t)0x0005u) 115 116 // Instructs |fdio_spawn_etc| which actions to take. 117 typedef struct fdio_spawn_action fdio_spawn_action_t; 118 struct fdio_spawn_action { 119 // The action to take. 120 // 121 // See |FDIO_SPAWN_ACTION_*| above. If |action| is invalid, the action will 122 // be ignored (rather than generate an error). 123 uint32_t action; 124 union { 125 struct { 126 // The file descriptor in this process to clone or transfer. 127 int local_fd; 128 129 // The file descriptor in the spawned process that will receive the 130 // clone or transfer. 131 int target_fd; 132 } fd; 133 struct { 134 // The prefix in which to install the given handle in the namespace 135 // of the spawned process. 136 const char* prefix; 137 138 // The handle to install with the given prefix in the namespace of 139 // the spawned process. 140 zx_handle_t handle; 141 } ns; 142 struct { 143 // The process argument identifier of the handle to pass to the 144 // spawned process. 145 uint32_t id; 146 147 // The handle to pass to the process on startup. 148 zx_handle_t handle; 149 } h; 150 struct { 151 // The name to assign to the spawned process. 152 const char* data; 153 } name; 154 }; 155 }; 156 157 // The maximum size for error messages from |fdio_spawn_etc|. 158 // 159 // Including the null terminator. 160 #define FDIO_SPAWN_ERR_MSG_MAX_LENGTH ((size_t)1024u) 161 162 // Spawn a process in the given job. 163 // 164 // The binary for the process is loaded from the given |path| and passed |argv|. 165 // The aspects of this process' environment indicated by |clone| are shared with 166 // the process. 167 // 168 // The spawned process is also given |environ| as its environment and the given 169 // |actions| are applied when creating the process. 170 // 171 // The |argv| array must be terminated with a null pointer. 172 // 173 // If non-null, the |environ| array must be terminated with a null pointer. 174 // 175 // If non-null, the |err_msg_out| buffer must have space for 176 // |FDIO_SPAWN_ERR_MSG_MAX_LENGTH| bytes. 177 // 178 // If both |FDIO_SPAWN_CLONE_ENVIRON| and |environ| are specified, then the 179 // spawned process is given |environ| as its environment. If both 180 // |FDIO_SPAWN_CLONE_STDIO| and |actions| that target any of fds 0, 1, and 2 are 181 // specified, then the actions that target those fds will control their 182 // semantics in the spawned process. 183 // 184 // If |job| is |ZX_HANDLE_INVALID|, then the process is spawned in 185 // |zx_job_default()|. Does not take ownership of |job|. 186 // 187 // Upon success, |process_out| will be a handle to the process. Upon failure, if 188 // |err_msg_out| is not null, an error message will be we written to 189 // |err_msg_out|, including a null terminator. 190 zx_status_t fdio_spawn_etc(zx_handle_t job, 191 uint32_t flags, 192 const char* path, 193 const char* const* argv, 194 const char* const* environ, 195 size_t action_count, 196 const fdio_spawn_action_t* actions, 197 zx_handle_t* process_out, 198 char err_msg_out[FDIO_SPAWN_ERR_MSG_MAX_LENGTH]); 199 200 // Spawn a process using the given executable in the given job. 201 // 202 // See |fdio_spawn_etc| for details. Rather than loading the binary for the 203 // process from a path, this function receives the binary as the contents of a 204 // vmo. 205 // 206 // Always consumes |executable_vmo|. 207 zx_status_t fdio_spawn_vmo(zx_handle_t job, 208 uint32_t flags, 209 zx_handle_t executable_vmo, 210 const char* const* argv, 211 const char* const* environ, 212 size_t action_count, 213 const fdio_spawn_action_t* actions, 214 zx_handle_t* process_out, 215 char err_msg_out[FDIO_SPAWN_ERR_MSG_MAX_LENGTH]); 216 217 __END_CDECLS 218