process_builder/lib.rs
1// Copyright 2019 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//! Native process creation and program loading library.
6//!
7//! # Restrictions
8//!
9//! Most Fuchsia processes are not able to use this library.
10//!
11//! This library uses the [zx_process_create] syscall to create a new process in a job. Use of that
12//! syscall requires that the job of the process using the syscall (not the job that the process is
13//! being created in) be allowed to create processes. In concrete terms, the process using this
14//! library must be in a job whose [ZX_POL_NEW_PROCESS job policy is
15//! ZX_POL_ACTION_ALLOW][zx_job_set_policy].
16//!
17//! Most processes on Fuchsia run in jobs where this job policy is set to DENY and thus will not
18//! be able to use this library. Those processes should instead use the [fuchsia.process.Launcher]
19//! FIDL service, which is itself implemented using this library. [fdio::spawn()],
20//! [fdio::spawn_vmo()], and [fdio::spawn_etc()] provide simple interfaces to this service.
21//!
22//! # Example
23//!
24//! ```
25//! let process_name = CString::new("my_process")?;
26//! let job = /* job to create new process in */;
27//! let executable = /* VMO with execute rights containing ELF executable */;
28//! let pkg_directory = /* fidl::endpoints::ClientEnd for fuchsia.io.Directory */;
29//! let out_directory = /* server end of zx::Channel */;
30//! let other_handle = /* some arbitrary zx::Handle */;
31//!
32//! let builder = ProcessBuilder::new(&process_name, &job, executable)?;
33//! builder.add_arguments(vec![process_name, CString::new("arg0")?]);
34//! builder.add_environment_variables(vec![CString::new("VAR=VALUE")?]);
35//! builder.add_namespace_entries(vec![NamespaceEntry{
36//! path: CString::new("/pkg")?,
37//! directory: package_directory,
38//! }])?;
39//! builder.add_handles(vec![
40//! StartupHandle{
41//! handle: out_directory.into_handle(),
42//! info: HandleInfo::new(HandleType::DirectoryRequest, 0),
43//! },
44//! StartupHandle{
45//! handle: other_handle,
46//! info: HandleInfo::new(HandleType::User0, 1),
47//! },
48//! ])?;
49//!
50//! let built_process: BuiltProcess = builder.build()?;
51//! let process: zx::Process = builder.start()?;
52//! ```
53//!
54//! [zx_process_create]: https://fuchsia.dev/fuchsia-src/reference/syscalls/process_create.md
55//! [zx_job_set_policy]: https://fuchsia.dev/fuchsia-src/reference/syscalls/job_set_policy.md
56//! [fuchsia.process.Launcher]: https://fuchsia.googlesource.com/fuchsia/+/HEAD/zircon/system/fidl/fuchsia-process/launcher.fidl
57
58pub use self::process_args::*;
59pub use self::process_builder::*;
60
61pub mod elf_load;
62pub mod elf_parse;
63
64mod process_args;
65mod process_builder;
66mod util;