1# zx_object_get_property
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7object_get_property - Ask for various properties of various kernel objects.
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_object_get_property(zx_handle_t handle,
17                                   uint32_t property,
18                                   void* value,
19                                   size_t value_size);
20```
21
22## DESCRIPTION
23
24`zx_object_get_property()` requests the value of a kernel object's property.
25Getting a property requires **ZX_RIGHT_GET_PROPERTY** rights on the handle.
26
27The *handle* parameter indicates the target kernel object. Different properties
28only work on certain types of kernel objects, as described below.
29
30The *property* parameter indicates which property to get/set. Property values
31have the prefix **ZX_PROP_**, and are described below.
32
33The *value* parameter holds the property value, and must be a pointer to a
34buffer of *value_size* bytes. Different properties expect different value
35types/sizes as described below.
36
37## PROPERTIES
38
39Property values have the prefix **ZX_PROP_**, and are defined in
40
41```
42#include <zircon/syscalls/object.h>
43```
44
45### ZX_PROP_NAME
46
47*handle* type: **(Most types)**
48
49*value* type: `char[ZX_MAX_NAME_LEN]`
50
51Allowed operations: **get**, **set**
52
53The name of the object, as a NUL-terminated string.
54
55### ZX_PROP_REGISTER_FS and ZX_PROP_REGISTER_GS
56
57*handle* type: **Thread**
58
59*value* type: `uintptr_t`
60
61Allowed operations: **set**
62
63The value of the x86 FS or GS segment register. `value` must be a
64canonical address, and must be a userspace address.
65
66Only defined for x86-64.
67
68### ZX_PROP_PROCESS_DEBUG_ADDR
69
70*handle* type: **Process**
71
72*value* type: `uintptr_t`
73
74Allowed operations: **get**, **set**
75
76The value of ld.so's `_dl_debug_addr`. This can be used by debuggers to
77interrogate the state of the dynamic loader.
78
79If this value is set to `ZX_PROCESS_DEBUG_ADDR_BREAK_ON_SET` on process
80creation, the loader will manually issue a debug breakpoint when the property
81has been set to its correct value. This gives an opportunity to read or modify
82the initial state of the program.
83
84### ZX_PROP_PROCESS_VDSO_BASE_ADDRESS
85
86*handle* type: **Process**
87
88*value* type: `uintptr_t`
89
90Allowed operations: **get**
91
92The base address of the vDSO mapping, or zero.
93
94### ZX_PROP_JOB_IMPORTANCE
95
96*handle* type: **Job**
97
98*value* type: `zx_job_importance_t`
99
100Allowed operations: **get**, **set**
101
102A hint about how important a job is; used to rank jobs for the out-of-memory
103(OOM) killer.
104
105Additional errors:
106
107*   **ZX_ERR_OUT_OF_RANGE**: If the importance value is not valid
108
109### ZX_PROP_SOCKET_RX_THRESHOLD
110
111*handle* type: **Socket**
112
113*value* type: `size_t`
114
115Allowed operations: **get**, **set**
116
117The size of the read threshold of a socket, in bytes. Setting this will
118assert ZX_SOCKET_READ_THRESHOLD if the amount of data that can be read
119is greater than or equal to the threshold. Setting this property to zero
120will result in the deasserting of ZX_SOCKET_READ_THRESHOLD.
121
122### ZX_PROP_SOCKET_TX_THRESHOLD
123
124*handle* type: **Socket**
125
126*value* type: `size_t`
127
128Allowed operations: **get**, **set**
129
130The size of the write threshold of a socket, in bytes. Setting this will
131assert ZX_SOCKET_WRITE_THRESHOLD if the amount of space available for writing
132is greater than or equal to the threshold. Setting this property to zero
133will result in the deasserting of ZX_SOCKET_WRITE_THRESHOLD. Setting the
134write threshold after the peer has closed is an error, and results in a
135ZX_ERR_PEER_CLOSED error being returned.
136
137### ZX_PROP_JOB_KILL_ON_OOM
138
139*handle* type: **Job**
140
141*value* type: `size_t`
142
143Allowed operations: **set**
144
145The value of 1 means the Job and its children will be terminated if the
146system finds itself in a system-wide low memory situation. Called with 0
147(which is the default) opts out the job from being terminated in this
148scenario.
149
150## RIGHTS
151
152<!-- Updated by update-docs-from-abigen, do not edit. -->
153
154*handle* must have **ZX_RIGHT_GET_PROPERTY**.
155
156If *property* is **ZX_PROP_PROCESS_DEBUG_ADDR**, *handle* must be of type **ZX_OBJ_TYPE_PROCESS**.
157
158If *property* is **ZX_PROP_PROCESS_VDSO_BASE_ADDRESS**, *handle* must be of type **ZX_OBJ_TYPE_PROCESS**.
159
160If *property* is **ZX_PROP_SOCKET_RX_THRESHOLD**, *handle* must be of type **ZX_OBJ_TYPE_SOCKET**.
161
162If *property* is **ZX_PROP_SOCKET_TX_THRESHOLD**, *handle* must be of type **ZX_OBJ_TYPE_SOCKET**.
163
164## RETURN VALUE
165
166`zx_object_get_property()` returns **ZX_OK** on success. In the event of
167failure, a negative error value is returned.
168
169## ERRORS
170
171**ZX_ERR_BAD_HANDLE**: *handle* is not a valid handle
172
173**ZX_ERR_WRONG_TYPE**: *handle* is not an appropriate type for *property*
174
175**ZX_ERR_ACCESS_DENIED**: *handle* does not have the necessary rights for the
176operation
177
178**ZX_ERR_INVALID_ARGS**: *value* is an invalid pointer
179
180**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
181There is no good way for userspace to handle this (unlikely) error.
182In a future build this error will no longer occur.
183
184**ZX_ERR_BUFFER_TOO_SMALL**: *value_size* is too small for *property*
185
186**ZX_ERR_NOT_SUPPORTED**: *property* does not exist
187
188## SEE ALSO
189
190
191[object_set_property](object_set_property.md)
192