1# zx_process_start
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7process_start - start execution on a process
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_process_start(zx_handle_t handle,
17                             zx_handle_t thread,
18                             zx_vaddr_t entry,
19                             zx_vaddr_t stack,
20                             zx_handle_t arg1,
21                             uintptr_t arg2);
22```
23
24## DESCRIPTION
25
26`zx_process_start()` is similar to [`zx_thread_start()`], but is used for the
27purpose of starting the first thread in a process.
28
29`zx_process_start()` causes a thread to begin execution at the program
30counter specified by *entry* and with the stack pointer set to *stack*.
31The arguments *arg1* and *arg2* are arranged to be in the architecture
32specific registers used for the first two arguments of a function call
33before the thread is started.  All other registers are zero upon start.
34
35The first argument (*arg1*) is a handle, which will be transferred from
36the process of the caller to the process which is being started, and an
37appropriate handle value will be placed in arg1 for the newly started
38thread. If `zx_process_start()` returns an error, *arg1* is closed rather
39than transferred to the process being started.
40
41## RIGHTS
42
43<!-- Updated by update-docs-from-abigen, do not edit. -->
44
45*handle* must be of type **ZX_OBJ_TYPE_PROCESS** and have **ZX_RIGHT_WRITE**.
46
47*thread* must be of type **ZX_OBJ_TYPE_THREAD** and have **ZX_RIGHT_WRITE**.
48
49*arg1* must have **ZX_RIGHT_TRANSFER**.
50
51## RETURN VALUE
52
53`zx_process_start()` returns **ZX_OK** on success.
54In the event of failure, a negative error value is returned.
55
56## ERRORS
57
58**ZX_ERR_BAD_HANDLE**  *process* or *thread* or *arg1* is not a valid handle.
59
60**ZX_ERR_WRONG_TYPE**  *process* is not a process handle or *thread* is
61not a thread handle.
62
63**ZX_ERR_ACCESS_DENIED**  The handle *thread* lacks **ZX_RIGHT_WRITE** or *thread*
64does not belong to *process*, or the handle *process* lacks **ZX_RIGHT_WRITE** or
65*arg1* lacks **ZX_RIGHT_TRANSFER**.
66
67**ZX_ERR_BAD_STATE**  *process* is already running or has exited.
68
69## SEE ALSO
70
71 - [`zx_handle_close()`]
72 - [`zx_handle_duplicate()`]
73 - [`zx_object_wait_async()`]
74 - [`zx_object_wait_many()`]
75 - [`zx_object_wait_one()`]
76 - [`zx_process_create()`]
77 - [`zx_thread_create()`]
78 - [`zx_thread_exit()`]
79 - [`zx_thread_start()`]
80
81<!-- References updated by update-docs-from-abigen, do not edit. -->
82
83[`zx_handle_close()`]: handle_close.md
84[`zx_handle_duplicate()`]: handle_duplicate.md
85[`zx_object_wait_async()`]: object_wait_async.md
86[`zx_object_wait_many()`]: object_wait_many.md
87[`zx_object_wait_one()`]: object_wait_one.md
88[`zx_process_create()`]: process_create.md
89[`zx_thread_create()`]: thread_create.md
90[`zx_thread_exit()`]: thread_exit.md
91[`zx_thread_start()`]: thread_start.md
92