|
160
|
1
|
|
|
2 .. _misc:
|
|
|
3
|
|
|
4 Miscellaneous utilities
|
|
|
5 =======================
|
|
|
6
|
|
|
7 This section contains miscellaneous functions that don't really belong in any
|
|
|
8 other section.
|
|
|
9
|
|
|
10
|
|
|
11 Data types
|
|
|
12 ----------
|
|
|
13
|
|
|
14 .. c:type:: uv_buf_t
|
|
|
15
|
|
|
16 Buffer data type.
|
|
|
17
|
|
|
18 .. c:member:: char* uv_buf_t.base
|
|
|
19
|
|
|
20 Pointer to the base of the buffer.
|
|
|
21
|
|
|
22 .. c:member:: size_t uv_buf_t.len
|
|
|
23
|
|
|
24 Total bytes in the buffer.
|
|
|
25
|
|
|
26 .. note::
|
|
|
27 On Windows this field is ULONG.
|
|
|
28
|
|
|
29 .. c:type:: void* (*uv_malloc_func)(size_t size)
|
|
|
30
|
|
|
31 Replacement function for :man:`malloc(3)`.
|
|
|
32 See :c:func:`uv_replace_allocator`.
|
|
|
33
|
|
|
34 .. c:type:: void* (*uv_realloc_func)(void* ptr, size_t size)
|
|
|
35
|
|
|
36 Replacement function for :man:`realloc(3)`.
|
|
|
37 See :c:func:`uv_replace_allocator`.
|
|
|
38
|
|
|
39 .. c:type:: void* (*uv_calloc_func)(size_t count, size_t size)
|
|
|
40
|
|
|
41 Replacement function for :man:`calloc(3)`.
|
|
|
42 See :c:func:`uv_replace_allocator`.
|
|
|
43
|
|
|
44 .. c:type:: void (*uv_free_func)(void* ptr)
|
|
|
45
|
|
|
46 Replacement function for :man:`free(3)`.
|
|
|
47 See :c:func:`uv_replace_allocator`.
|
|
|
48
|
|
|
49 .. c:type:: void (*uv_random_cb)(uv_random_t* req, int status, void* buf, size_t buflen)
|
|
|
50
|
|
|
51 Callback passed to :c:func:`uv_random`. `status` is non-zero in case of
|
|
|
52 error. The `buf` pointer is the same pointer that was passed to
|
|
|
53 :c:func:`uv_random`.
|
|
|
54
|
|
|
55 .. c:type:: uv_file
|
|
|
56
|
|
|
57 Cross platform representation of a file handle.
|
|
|
58
|
|
|
59 .. c:type:: uv_os_sock_t
|
|
|
60
|
|
|
61 Cross platform representation of a socket handle.
|
|
|
62
|
|
|
63 .. c:type:: uv_os_fd_t
|
|
|
64
|
|
|
65 Abstract representation of a file descriptor. On Unix systems this is a
|
|
|
66 `typedef` of `int` and on Windows a `HANDLE`.
|
|
|
67
|
|
|
68 .. c:type:: uv_pid_t
|
|
|
69
|
|
|
70 Cross platform representation of a `pid_t`.
|
|
|
71
|
|
|
72 .. versionadded:: 1.16.0
|
|
|
73
|
|
|
74 .. c:type:: uv_timeval_t
|
|
|
75
|
|
|
76 Y2K38-unsafe data type for storing times with microsecond resolution.
|
|
|
77 Will be replaced with :c:type:`uv_timeval64_t` in libuv v2.0.
|
|
|
78
|
|
|
79 ::
|
|
|
80
|
|
|
81 typedef struct {
|
|
|
82 long tv_sec;
|
|
|
83 long tv_usec;
|
|
|
84 } uv_timeval_t;
|
|
|
85
|
|
|
86 .. c:type:: uv_timeval64_t
|
|
|
87
|
|
|
88 Y2K38-safe data type for storing times with microsecond resolution.
|
|
|
89
|
|
|
90 ::
|
|
|
91
|
|
|
92 typedef struct {
|
|
|
93 int64_t tv_sec;
|
|
|
94 int32_t tv_usec;
|
|
|
95 } uv_timeval64_t;
|
|
|
96
|
|
|
97 .. c:type:: uv_timespec64_t
|
|
|
98
|
|
|
99 Y2K38-safe data type for storing times with nanosecond resolution.
|
|
|
100
|
|
|
101 ::
|
|
|
102
|
|
|
103 typedef struct {
|
|
|
104 int64_t tv_sec;
|
|
|
105 int32_t tv_nsec;
|
|
|
106 } uv_timespec64_t;
|
|
|
107
|
|
|
108 .. c:enum:: uv_clock_id
|
|
|
109
|
|
|
110 Clock source for :c:func:`uv_clock_gettime`.
|
|
|
111
|
|
|
112 ::
|
|
|
113
|
|
|
114 typedef enum {
|
|
|
115 UV_CLOCK_MONOTONIC,
|
|
|
116 UV_CLOCK_REALTIME
|
|
|
117 } uv_clock_id;
|
|
|
118
|
|
|
119 .. c:type:: uv_rusage_t
|
|
|
120
|
|
|
121 Data type for resource usage results.
|
|
|
122
|
|
|
123 ::
|
|
|
124
|
|
|
125 typedef struct {
|
|
|
126 uv_timeval_t ru_utime; /* user CPU time used */
|
|
|
127 uv_timeval_t ru_stime; /* system CPU time used */
|
|
|
128 uint64_t ru_maxrss; /* maximum resident set size */
|
|
|
129 uint64_t ru_ixrss; /* integral shared memory size (X) */
|
|
|
130 uint64_t ru_idrss; /* integral unshared data size (X) */
|
|
|
131 uint64_t ru_isrss; /* integral unshared stack size (X) */
|
|
|
132 uint64_t ru_minflt; /* page reclaims (soft page faults) (X) */
|
|
|
133 uint64_t ru_majflt; /* page faults (hard page faults) */
|
|
|
134 uint64_t ru_nswap; /* swaps (X) */
|
|
|
135 uint64_t ru_inblock; /* block input operations */
|
|
|
136 uint64_t ru_oublock; /* block output operations */
|
|
|
137 uint64_t ru_msgsnd; /* IPC messages sent (X) */
|
|
|
138 uint64_t ru_msgrcv; /* IPC messages received (X) */
|
|
|
139 uint64_t ru_nsignals; /* signals received (X) */
|
|
|
140 uint64_t ru_nvcsw; /* voluntary context switches (X) */
|
|
|
141 uint64_t ru_nivcsw; /* involuntary context switches (X) */
|
|
|
142 } uv_rusage_t;
|
|
|
143
|
|
|
144 Members marked with `(X)` are unsupported on Windows.
|
|
|
145 See :man:`getrusage(2)` for supported fields on UNIX-like platforms.
|
|
|
146
|
|
|
147 The maximum resident set size is reported in kilobytes, the unit most
|
|
|
148 platforms use natively.
|
|
|
149
|
|
|
150 .. c:type:: uv_cpu_info_t
|
|
|
151
|
|
|
152 Data type for CPU information.
|
|
|
153
|
|
|
154 ::
|
|
|
155
|
|
|
156 typedef struct uv_cpu_info_s {
|
|
|
157 char* model;
|
|
|
158 int speed;
|
|
|
159 struct uv_cpu_times_s {
|
|
|
160 uint64_t user; /* milliseconds */
|
|
|
161 uint64_t nice; /* milliseconds */
|
|
|
162 uint64_t sys; /* milliseconds */
|
|
|
163 uint64_t idle; /* milliseconds */
|
|
|
164 uint64_t irq; /* milliseconds */
|
|
|
165 } cpu_times;
|
|
|
166 } uv_cpu_info_t;
|
|
|
167
|
|
|
168 .. c:type:: uv_interface_address_t
|
|
|
169
|
|
|
170 Data type for interface addresses.
|
|
|
171
|
|
|
172 ::
|
|
|
173
|
|
|
174 typedef struct uv_interface_address_s {
|
|
|
175 char* name;
|
|
|
176 char phys_addr[6];
|
|
|
177 int is_internal;
|
|
|
178 union {
|
|
|
179 struct sockaddr_in address4;
|
|
|
180 struct sockaddr_in6 address6;
|
|
|
181 } address;
|
|
|
182 union {
|
|
|
183 struct sockaddr_in netmask4;
|
|
|
184 struct sockaddr_in6 netmask6;
|
|
|
185 } netmask;
|
|
|
186 } uv_interface_address_t;
|
|
|
187
|
|
|
188 .. c:type:: uv_passwd_t
|
|
|
189
|
|
|
190 Data type for password file information.
|
|
|
191
|
|
|
192 ::
|
|
|
193
|
|
|
194 typedef struct uv_passwd_s {
|
|
|
195 char* username;
|
|
|
196 long uid;
|
|
|
197 long gid;
|
|
|
198 char* shell;
|
|
|
199 char* homedir;
|
|
|
200 } uv_passwd_t;
|
|
|
201
|
|
|
202 .. c:type:: uv_group_t
|
|
|
203
|
|
|
204 Data type for group file information.
|
|
|
205
|
|
|
206 ::
|
|
|
207
|
|
|
208 typedef struct uv_group_s {
|
|
|
209 char* groupname;
|
|
|
210 unsigned long gid;
|
|
|
211 char** members;
|
|
|
212 } uv_group_t;
|
|
|
213
|
|
|
214 .. c:type:: uv_utsname_t
|
|
|
215
|
|
|
216 Data type for operating system name and version information.
|
|
|
217
|
|
|
218 ::
|
|
|
219
|
|
|
220 typedef struct uv_utsname_s {
|
|
|
221 char sysname[256];
|
|
|
222 char release[256];
|
|
|
223 char version[256];
|
|
|
224 char machine[256];
|
|
|
225 } uv_utsname_t;
|
|
|
226
|
|
|
227 .. c:type:: uv_env_item_t
|
|
|
228
|
|
|
229 Data type for environment variable storage.
|
|
|
230
|
|
|
231 ::
|
|
|
232
|
|
|
233 typedef struct uv_env_item_s {
|
|
|
234 char* name;
|
|
|
235 char* value;
|
|
|
236 } uv_env_item_t;
|
|
|
237
|
|
|
238 .. c:type:: uv_random_t
|
|
|
239
|
|
|
240 Random data request type.
|
|
|
241
|
|
|
242 API
|
|
|
243 ---
|
|
|
244
|
|
|
245 .. c:function:: uv_handle_type uv_guess_handle(uv_file file)
|
|
|
246
|
|
|
247 Used to detect what type of stream should be used with a given file
|
|
|
248 descriptor. Usually this will be used during initialization to guess the
|
|
|
249 type of the stdio streams.
|
|
|
250
|
|
|
251 For :man:`isatty(3)` equivalent functionality use this function and test
|
|
|
252 for `UV_TTY`.
|
|
|
253
|
|
|
254 .. c:function:: int uv_replace_allocator(uv_malloc_func malloc_func, uv_realloc_func realloc_func, uv_calloc_func calloc_func, uv_free_func free_func)
|
|
|
255
|
|
|
256 .. versionadded:: 1.6.0
|
|
|
257
|
|
|
258 Override the use of the standard library's :man:`malloc(3)`,
|
|
|
259 :man:`calloc(3)`, :man:`realloc(3)`, :man:`free(3)`, memory allocation
|
|
|
260 functions.
|
|
|
261
|
|
|
262 This function must be called before any other libuv function is called or
|
|
|
263 after all resources have been freed and thus libuv doesn't reference
|
|
|
264 any allocated memory chunk.
|
|
|
265
|
|
|
266 On success, it returns 0, if any of the function pointers is `NULL` it
|
|
|
267 returns `UV_EINVAL`.
|
|
|
268
|
|
|
269 .. warning:: There is no protection against changing the allocator multiple
|
|
|
270 times. If the user changes it they are responsible for making
|
|
|
271 sure the allocator is changed while no memory was allocated with
|
|
|
272 the previous allocator, or that they are compatible.
|
|
|
273
|
|
|
274 .. warning:: Allocator must be thread-safe.
|
|
|
275
|
|
|
276 .. c:function:: void uv_library_shutdown(void);
|
|
|
277
|
|
|
278 .. versionadded:: 1.38.0
|
|
|
279
|
|
|
280 Release any global state that libuv is holding onto. Libuv will normally
|
|
|
281 do so automatically when it is unloaded but it can be instructed to perform
|
|
|
282 cleanup manually.
|
|
|
283
|
|
|
284 .. warning:: Only call :c:func:`uv_library_shutdown()` once.
|
|
|
285
|
|
|
286 .. warning:: Don't call :c:func:`uv_library_shutdown()` when there are
|
|
|
287 still event loops or I/O requests active.
|
|
|
288
|
|
|
289 .. warning:: Don't call libuv functions after calling
|
|
|
290 :c:func:`uv_library_shutdown()`.
|
|
|
291
|
|
|
292 .. c:function:: uv_buf_t uv_buf_init(char* base, unsigned int len)
|
|
|
293
|
|
|
294 Constructor for :c:type:`uv_buf_t`.
|
|
|
295
|
|
|
296 Due to platform differences the user cannot rely on the ordering of the
|
|
|
297 `base` and `len` members of the uv_buf_t struct. The user is responsible for
|
|
|
298 freeing `base` after the uv_buf_t is done. Return struct passed by value.
|
|
|
299
|
|
|
300 .. c:function:: char** uv_setup_args(int argc, char** argv)
|
|
|
301
|
|
|
302 Store the program arguments. Required for getting / setting the process title
|
|
|
303 or the executable path. Libuv may take ownership of the memory that `argv`
|
|
|
304 points to. This function should be called exactly once, at program start-up.
|
|
|
305
|
|
|
306 Example:
|
|
|
307
|
|
|
308 ::
|
|
|
309
|
|
|
310 argv = uv_setup_args(argc, argv); /* May return a copy of argv. */
|
|
|
311
|
|
|
312
|
|
|
313 .. c:function:: int uv_get_process_title(char* buffer, size_t size)
|
|
|
314
|
|
|
315 Gets the title of the current process. You *must* call `uv_setup_args`
|
|
|
316 before calling this function on Unix and AIX systems. If `uv_setup_args`
|
|
|
317 has not been called on systems that require it, then `UV_ENOBUFS` is
|
|
|
318 returned. If `buffer` is `NULL` or `size` is zero, `UV_EINVAL` is returned.
|
|
|
319 If `size` cannot accommodate the process title and terminating `nul`
|
|
|
320 character, the function returns `UV_ENOBUFS`.
|
|
|
321
|
|
|
322 .. note::
|
|
|
323 On BSD systems, `uv_setup_args` is needed for getting the initial process
|
|
|
324 title. The process title returned will be an empty string until either
|
|
|
325 `uv_setup_args` or `uv_set_process_title` is called.
|
|
|
326
|
|
|
327 .. versionchanged:: 1.18.1 now thread-safe on all supported platforms.
|
|
|
328
|
|
|
329 .. versionchanged:: 1.39.0 now returns an error if `uv_setup_args` is needed
|
|
|
330 but hasn't been called.
|
|
|
331
|
|
|
332 .. c:function:: int uv_set_process_title(const char* title)
|
|
|
333
|
|
|
334 Sets the current process title. You *must* call `uv_setup_args` before
|
|
|
335 calling this function on Unix and AIX systems. If `uv_setup_args` has not
|
|
|
336 been called on systems that require it, then `UV_ENOBUFS` is returned. On
|
|
|
337 platforms with a fixed size buffer for the process title the contents of
|
|
|
338 `title` will be copied to the buffer and truncated if larger than the
|
|
|
339 available space. Other platforms will return `UV_ENOMEM` if they cannot
|
|
|
340 allocate enough space to duplicate the contents of `title`.
|
|
|
341
|
|
|
342 .. versionchanged:: 1.18.1 now thread-safe on all supported platforms.
|
|
|
343
|
|
|
344 .. versionchanged:: 1.39.0 now returns an error if `uv_setup_args` is needed
|
|
|
345 but hasn't been called.
|
|
|
346
|
|
|
347 .. c:function:: int uv_resident_set_memory(size_t* rss)
|
|
|
348
|
|
|
349 Gets the resident set size (RSS) for the current process.
|
|
|
350
|
|
|
351 .. c:function:: int uv_uptime(double* uptime)
|
|
|
352
|
|
|
353 Gets the current system uptime. Depending on the system full or fractional seconds are returned.
|
|
|
354
|
|
|
355 .. c:function:: int uv_getrusage(uv_rusage_t* rusage)
|
|
|
356
|
|
|
357 Gets the resource usage measures for the current process.
|
|
|
358
|
|
|
359 .. note::
|
|
|
360 On Windows not all fields are set, the unsupported fields are filled with zeroes.
|
|
|
361 See :c:type:`uv_rusage_t` for more details.
|
|
|
362
|
|
|
363 .. c:function:: int uv_getrusage_thread(uv_rusage_t* rusage)
|
|
|
364
|
|
|
365 Gets the resource usage measures for the calling thread.
|
|
|
366
|
|
|
367 .. versionadded:: 1.50.0
|
|
|
368
|
|
|
369 .. note::
|
|
|
370 Not supported on all platforms. May return `UV_ENOTSUP`.
|
|
|
371 On macOS and Windows not all fields are set, the unsupported fields are filled with zeroes.
|
|
|
372 See :c:type:`uv_rusage_t` for more details.
|
|
|
373
|
|
|
374 .. c:function:: uv_pid_t uv_os_getpid(void)
|
|
|
375
|
|
|
376 Returns the current process ID.
|
|
|
377
|
|
|
378 .. versionadded:: 1.18.0
|
|
|
379
|
|
|
380 .. c:function:: uv_pid_t uv_os_getppid(void)
|
|
|
381
|
|
|
382 Returns the parent process ID.
|
|
|
383
|
|
|
384 .. versionadded:: 1.16.0
|
|
|
385
|
|
|
386 .. c:function:: unsigned int uv_available_parallelism(void)
|
|
|
387
|
|
|
388 Returns an estimate of the default amount of parallelism a program should
|
|
|
389 use. Always returns a non-zero value.
|
|
|
390
|
|
|
391 On Linux, inspects the calling thread's CPU affinity mask to determine if
|
|
|
392 it has been pinned to specific CPUs.
|
|
|
393
|
|
|
394 On Windows, the available parallelism may be underreported on systems with
|
|
|
395 more than 64 logical CPUs.
|
|
|
396
|
|
|
397 On other platforms, reports the number of CPUs that the operating system
|
|
|
398 considers to be online.
|
|
|
399
|
|
|
400 .. versionadded:: 1.44.0
|
|
|
401
|
|
|
402 .. c:function:: int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count)
|
|
|
403
|
|
|
404 Gets information about the CPUs on the system. The `cpu_infos` array will
|
|
|
405 have `count` elements and needs to be freed with :c:func:`uv_free_cpu_info`.
|
|
|
406
|
|
|
407 Use :c:func:`uv_available_parallelism` if you need to know how many CPUs
|
|
|
408 are available for threads or child processes.
|
|
|
409
|
|
|
410 .. c:function:: void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count)
|
|
|
411
|
|
|
412 Frees the `cpu_infos` array previously allocated with :c:func:`uv_cpu_info`.
|
|
|
413
|
|
|
414 .. c:function:: int uv_cpumask_size(void)
|
|
|
415
|
|
|
416 Returns the maximum size of the mask used for process/thread affinities,
|
|
|
417 or `UV_ENOTSUP` if affinities are not supported on the current platform.
|
|
|
418
|
|
|
419 .. versionadded:: 1.45.0
|
|
|
420
|
|
|
421 .. c:function:: int uv_interface_addresses(uv_interface_address_t** addresses, int* count)
|
|
|
422
|
|
|
423 Gets address information about the network interfaces on the system. An
|
|
|
424 array of `count` elements is allocated and returned in `addresses`. It must
|
|
|
425 be freed by the user, calling :c:func:`uv_free_interface_addresses`.
|
|
|
426
|
|
|
427 .. c:function:: void uv_free_interface_addresses(uv_interface_address_t* addresses, int count)
|
|
|
428
|
|
|
429 Free an array of :c:type:`uv_interface_address_t` which was returned by
|
|
|
430 :c:func:`uv_interface_addresses`.
|
|
|
431
|
|
|
432 .. c:function:: void uv_loadavg(double avg[3])
|
|
|
433
|
|
|
434 Gets the load average. See: `<https://en.wikipedia.org/wiki/Load_(computing)>`_
|
|
|
435
|
|
|
436 .. note::
|
|
|
437 Returns [0,0,0] on Windows (i.e., it's not implemented).
|
|
|
438
|
|
|
439 .. c:function:: int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr)
|
|
|
440
|
|
|
441 Convert a string containing an IPv4 addresses to a binary structure.
|
|
|
442
|
|
|
443 .. c:function:: int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr)
|
|
|
444
|
|
|
445 Convert a string containing an IPv6 addresses to a binary structure.
|
|
|
446
|
|
|
447 .. c:function:: int uv_ip4_name(const struct sockaddr_in* src, char* dst, size_t size)
|
|
|
448
|
|
|
449 Convert a binary structure containing an IPv4 address to a string.
|
|
|
450
|
|
|
451 .. c:function:: int uv_ip6_name(const struct sockaddr_in6* src, char* dst, size_t size)
|
|
|
452
|
|
|
453 Convert a binary structure containing an IPv6 address to a string.
|
|
|
454
|
|
|
455 .. c:function:: int uv_ip_name(const struct sockaddr *src, char *dst, size_t size)
|
|
|
456
|
|
|
457 Convert a binary structure containing an IPv4 address or an IPv6 address to a string.
|
|
|
458
|
|
|
459 .. c:function:: int uv_inet_ntop(int af, const void* src, char* dst, size_t size)
|
|
|
460 .. c:function:: int uv_inet_pton(int af, const char* src, void* dst)
|
|
|
461
|
|
|
462 Cross-platform IPv6-capable implementation of :man:`inet_ntop(3)`
|
|
|
463 and :man:`inet_pton(3)`. On success they return 0. In case of error
|
|
|
464 the target `dst` pointer is unmodified.
|
|
|
465
|
|
|
466 .. c:macro:: UV_IF_NAMESIZE
|
|
|
467
|
|
|
468 Maximum IPv6 interface identifier name length. Defined as
|
|
|
469 `IFNAMSIZ` on Unix and `IF_NAMESIZE` on Linux and Windows.
|
|
|
470
|
|
|
471 .. versionadded:: 1.16.0
|
|
|
472
|
|
|
473 .. c:function:: int uv_if_indextoname(unsigned int ifindex, char* buffer, size_t* size)
|
|
|
474
|
|
|
475 IPv6-capable implementation of :man:`if_indextoname(3)`. When called,
|
|
|
476 `*size` indicates the length of the `buffer`, which is used to store the
|
|
|
477 result.
|
|
|
478 On success, zero is returned, `buffer` contains the interface name, and
|
|
|
479 `*size` represents the string length of the `buffer`, excluding the NUL
|
|
|
480 terminator byte from `*size`. On error, a negative result is
|
|
|
481 returned. If `buffer` is not large enough to hold the result,
|
|
|
482 `UV_ENOBUFS` is returned, and `*size` represents the necessary size in
|
|
|
483 bytes, including the NUL terminator byte into the `*size`.
|
|
|
484
|
|
|
485 On Unix, the returned interface name can be used directly as an
|
|
|
486 interface identifier in scoped IPv6 addresses, e.g.
|
|
|
487 `fe80::abc:def1:2345%en0`.
|
|
|
488
|
|
|
489 On Windows, the returned interface cannot be used as an interface
|
|
|
490 identifier, as Windows uses numerical interface identifiers, e.g.
|
|
|
491 `fe80::abc:def1:2345%5`.
|
|
|
492
|
|
|
493 To get an interface identifier in a cross-platform compatible way,
|
|
|
494 use `uv_if_indextoiid()`.
|
|
|
495
|
|
|
496 Example:
|
|
|
497
|
|
|
498 ::
|
|
|
499
|
|
|
500 char ifname[UV_IF_NAMESIZE];
|
|
|
501 size_t size = sizeof(ifname);
|
|
|
502 uv_if_indextoname(sin6->sin6_scope_id, ifname, &size);
|
|
|
503
|
|
|
504 .. versionadded:: 1.16.0
|
|
|
505
|
|
|
506 .. c:function:: int uv_if_indextoiid(unsigned int ifindex, char* buffer, size_t* size)
|
|
|
507
|
|
|
508 Retrieves a network interface identifier suitable for use in an IPv6 scoped
|
|
|
509 address. On Windows, returns the numeric `ifindex` as a string. On all other
|
|
|
510 platforms, `uv_if_indextoname()` is called. The result is written to
|
|
|
511 `buffer`, with `*size` indicating the length of `buffer`. If `buffer` is not
|
|
|
512 large enough to hold the result, then `UV_ENOBUFS` is returned, and `*size`
|
|
|
513 represents the size, including the NUL byte, required to hold the
|
|
|
514 result.
|
|
|
515
|
|
|
516 See `uv_if_indextoname` for further details.
|
|
|
517
|
|
|
518 .. versionadded:: 1.16.0
|
|
|
519
|
|
|
520 .. c:function:: int uv_exepath(char* buffer, size_t* size)
|
|
|
521
|
|
|
522 Gets the executable path. You *must* call `uv_setup_args` before calling
|
|
|
523 this function.
|
|
|
524
|
|
|
525 .. c:function:: int uv_cwd(char* buffer, size_t* size)
|
|
|
526
|
|
|
527 Gets the current working directory, and stores it in `buffer`. If the
|
|
|
528 current working directory is too large to fit in `buffer`, this function
|
|
|
529 returns `UV_ENOBUFS`, and sets `size` to the required length, including the
|
|
|
530 null terminator.
|
|
|
531
|
|
|
532 .. versionchanged:: 1.1.0
|
|
|
533
|
|
|
534 On Unix the path no longer ends in a slash.
|
|
|
535
|
|
|
536 .. versionchanged:: 1.9.0 the returned length includes the terminating null
|
|
|
537 byte on `UV_ENOBUFS`, and the buffer is null terminated
|
|
|
538 on success.
|
|
|
539
|
|
|
540
|
|
|
541 .. c:function:: int uv_chdir(const char* dir)
|
|
|
542
|
|
|
543 Changes the current working directory.
|
|
|
544
|
|
|
545 .. c:function:: int uv_os_homedir(char* buffer, size_t* size)
|
|
|
546
|
|
|
547 Gets the current user's home directory. On Windows, `uv_os_homedir()` first
|
|
|
548 checks the `USERPROFILE` environment variable using
|
|
|
549 `GetEnvironmentVariableW()`. If `USERPROFILE` is not set,
|
|
|
550 `GetUserProfileDirectoryW()` is called. On all other operating systems,
|
|
|
551 `uv_os_homedir()` first checks the `HOME` environment variable using
|
|
|
552 :man:`getenv(3)`. If `HOME` is not set, :man:`getpwuid_r(3)` is called. The
|
|
|
553 user's home directory is stored in `buffer`. When `uv_os_homedir()` is
|
|
|
554 called, `size` indicates the maximum size of `buffer`. On success `size` is set
|
|
|
555 to the string length of `buffer`. On `UV_ENOBUFS` failure `size` is set to the
|
|
|
556 required length for `buffer`, including the null byte.
|
|
|
557
|
|
|
558 .. warning::
|
|
|
559 `uv_os_homedir()` is not thread safe.
|
|
|
560
|
|
|
561 .. versionadded:: 1.6.0
|
|
|
562
|
|
|
563 .. c:function:: int uv_os_tmpdir(char* buffer, size_t* size)
|
|
|
564
|
|
|
565 Gets the temp directory. On Windows, `uv_os_tmpdir()` uses `GetTempPathW()`.
|
|
|
566 On all other operating systems, `uv_os_tmpdir()` uses the first environment
|
|
|
567 variable found in the ordered list `TMPDIR`, `TMP`, `TEMP`, and `TEMPDIR`.
|
|
|
568 If none of these are found, the path `"/tmp"` is used, or, on Android,
|
|
|
569 `"/data/local/tmp"` is used. The temp directory is stored in `buffer`. When
|
|
|
570 `uv_os_tmpdir()` is called, `size` indicates the maximum size of `buffer`.
|
|
|
571 On success `size` is set to the string length of `buffer` (which does not
|
|
|
572 include the terminating null). On `UV_ENOBUFS` failure `size` is set to the
|
|
|
573 required length for `buffer`, including the null byte.
|
|
|
574
|
|
|
575 .. warning::
|
|
|
576 `uv_os_tmpdir()` is not thread safe.
|
|
|
577
|
|
|
578 .. versionadded:: 1.9.0
|
|
|
579
|
|
|
580 .. c:function:: int uv_os_get_passwd(uv_passwd_t* pwd)
|
|
|
581
|
|
|
582 Gets a subset of the password file entry for the current effective uid (not
|
|
|
583 the real uid). The populated data includes the username, euid, gid, shell,
|
|
|
584 and home directory. On non-Windows systems, all data comes from
|
|
|
585 :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no
|
|
|
586 meaning, and shell is `NULL`. After successfully calling this function, the
|
|
|
587 memory allocated to `pwd` needs to be freed with
|
|
|
588 :c:func:`uv_os_free_passwd`.
|
|
|
589
|
|
|
590 .. versionadded:: 1.9.0
|
|
|
591
|
|
|
592 .. c:function:: int uv_os_get_passwd2(uv_passwd_t* pwd, uv_uid_t uid)
|
|
|
593
|
|
|
594 Gets a subset of the password file entry for the provided uid.
|
|
|
595 The populated data includes the username, euid, gid, shell,
|
|
|
596 and home directory. On non-Windows systems, all data comes from
|
|
|
597 :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no
|
|
|
598 meaning, and shell is `NULL`. After successfully calling this function, the
|
|
|
599 memory allocated to `pwd` needs to be freed with
|
|
|
600 :c:func:`uv_os_free_passwd`.
|
|
|
601
|
|
|
602 .. versionadded:: 1.45.0
|
|
|
603
|
|
|
604 .. c:function:: int uv_os_get_group(uv_group_t* group, uv_uid_t gid)
|
|
|
605
|
|
|
606 Gets a subset of the group file entry for the provided uid.
|
|
|
607 The populated data includes the group name, gid, and members. On non-Windows
|
|
|
608 systems, all data comes from :man:`getgrgid_r(3)`. On Windows, uid and gid
|
|
|
609 are set to -1 and have no meaning. After successfully calling this function,
|
|
|
610 the memory allocated to `group` needs to be freed with
|
|
|
611 :c:func:`uv_os_free_group`.
|
|
|
612
|
|
|
613 .. versionadded:: 1.45.0
|
|
|
614
|
|
|
615 .. c:function:: void uv_os_free_group(uv_passwd_t* pwd)
|
|
|
616
|
|
|
617 Frees the memory previously allocated with :c:func:`uv_os_get_group`.
|
|
|
618
|
|
|
619 .. versionadded:: 1.45.0
|
|
|
620
|
|
|
621 .. c:function:: void uv_os_free_passwd(uv_passwd_t* pwd)
|
|
|
622
|
|
|
623 Frees the `pwd` memory previously allocated with :c:func:`uv_os_get_passwd`.
|
|
|
624
|
|
|
625 .. versionadded:: 1.9.0
|
|
|
626
|
|
|
627 .. c:function:: uint64_t uv_get_free_memory(void)
|
|
|
628
|
|
|
629 Gets the amount of free memory available in the system, as reported by
|
|
|
630 the kernel (in bytes). Returns 0 when unknown.
|
|
|
631
|
|
|
632 .. c:function:: uint64_t uv_get_total_memory(void)
|
|
|
633
|
|
|
634 Gets the total amount of physical memory in the system (in bytes).
|
|
|
635 Returns 0 when unknown.
|
|
|
636
|
|
|
637 .. c:function:: uint64_t uv_get_constrained_memory(void)
|
|
|
638
|
|
|
639 Gets the total amount of memory available to the process (in bytes) based on
|
|
|
640 limits imposed by the OS. If there is no such constraint, or the constraint
|
|
|
641 is unknown, `0` is returned. If there is a constraining mechanism, but there
|
|
|
642 is no constraint set, `UINT64_MAX` is returned. Note that it is not unusual
|
|
|
643 for this value to be less than or greater than :c:func:`uv_get_total_memory`.
|
|
|
644
|
|
|
645 .. note::
|
|
|
646 This function currently only returns a non-zero value on Linux, based
|
|
|
647 on cgroups if it is present, and on z/OS based on RLIMIT_MEMLIMIT.
|
|
|
648
|
|
|
649 .. versionadded:: 1.29.0
|
|
|
650
|
|
|
651 .. c:function:: uint64_t uv_get_available_memory(void)
|
|
|
652
|
|
|
653 Gets the amount of free memory that is still available to the process (in bytes).
|
|
|
654 This differs from :c:func:`uv_get_free_memory` in that it takes into account any
|
|
|
655 limits imposed by the OS. If there is no such constraint, or the constraint
|
|
|
656 is unknown, the amount returned will be identical to :c:func:`uv_get_free_memory`.
|
|
|
657
|
|
|
658 .. note::
|
|
|
659 This function currently only returns a value that is different from
|
|
|
660 what :c:func:`uv_get_free_memory` reports on Linux, based
|
|
|
661 on cgroups if it is present.
|
|
|
662
|
|
|
663 .. versionadded:: 1.45.0
|
|
|
664
|
|
|
665 .. c:function:: uint64_t uv_hrtime(void)
|
|
|
666
|
|
|
667 Returns the current high-resolution timestamp. This is expressed in
|
|
|
668 nanoseconds. It is relative to an arbitrary time in the past. It is not
|
|
|
669 related to the time of day and therefore not subject to clock drift. The
|
|
|
670 primary use is for measuring performance between intervals.
|
|
|
671
|
|
|
672 .. note::
|
|
|
673 Not every platform can support nanosecond resolution; however, this value will always
|
|
|
674 be in nanoseconds.
|
|
|
675
|
|
|
676 .. c:function:: int uv_clock_gettime(uv_clock_id clock_id, uv_timespec64_t* ts)
|
|
|
677
|
|
|
678 Obtain the current system time from a high-resolution real-time or monotonic
|
|
|
679 clock source.
|
|
|
680
|
|
|
681 The real-time clock counts from the UNIX epoch (1970-01-01) and is subject
|
|
|
682 to time adjustments; it can jump back in time.
|
|
|
683
|
|
|
684 The monotonic clock counts from an arbitrary point in the past and never
|
|
|
685 jumps back in time.
|
|
|
686
|
|
|
687 .. versionadded:: 1.45.0
|
|
|
688
|
|
|
689 .. c:function:: void uv_print_all_handles(uv_loop_t* loop, FILE* stream)
|
|
|
690
|
|
|
691 Prints all handles associated with the given `loop` to the given `stream`.
|
|
|
692
|
|
|
693 Example:
|
|
|
694
|
|
|
695 ::
|
|
|
696
|
|
|
697 uv_print_all_handles(uv_default_loop(), stderr);
|
|
|
698 /*
|
|
|
699 [--I] signal 0x1a25ea8
|
|
|
700 [-AI] async 0x1a25cf0
|
|
|
701 [R--] idle 0x1a7a8c8
|
|
|
702 */
|
|
|
703
|
|
|
704 The format is `[flags] handle-type handle-address`. For `flags`:
|
|
|
705
|
|
|
706 - `R` is printed for a handle that is referenced
|
|
|
707 - `A` is printed for a handle that is active
|
|
|
708 - `I` is printed for a handle that is internal
|
|
|
709
|
|
|
710 .. warning::
|
|
|
711 This function is meant for ad hoc debugging, there is no API/ABI
|
|
|
712 stability guarantees.
|
|
|
713
|
|
|
714 .. versionadded:: 1.8.0
|
|
|
715
|
|
|
716 .. c:function:: void uv_print_active_handles(uv_loop_t* loop, FILE* stream)
|
|
|
717
|
|
|
718 This is the same as :c:func:`uv_print_all_handles` except only active handles
|
|
|
719 are printed.
|
|
|
720
|
|
|
721 .. warning::
|
|
|
722 This function is meant for ad hoc debugging, there is no API/ABI
|
|
|
723 stability guarantees.
|
|
|
724
|
|
|
725 .. versionadded:: 1.8.0
|
|
|
726
|
|
|
727 .. c:function:: int uv_os_environ(uv_env_item_t** envitems, int* count)
|
|
|
728
|
|
|
729 Retrieves all environment variables. This function will allocate memory
|
|
|
730 which must be freed by calling :c:func:`uv_os_free_environ`.
|
|
|
731
|
|
|
732 .. warning::
|
|
|
733 This function is not thread safe.
|
|
|
734
|
|
|
735 .. versionadded:: 1.31.0
|
|
|
736
|
|
|
737 .. c:function:: void uv_os_free_environ(uv_env_item_t* envitems, int count);
|
|
|
738
|
|
|
739 Frees the memory allocated for the environment variables by
|
|
|
740 :c:func:`uv_os_environ`.
|
|
|
741
|
|
|
742 .. versionadded:: 1.31.0
|
|
|
743
|
|
|
744 .. c:function:: int uv_os_getenv(const char* name, char* buffer, size_t* size)
|
|
|
745
|
|
|
746 Retrieves the environment variable specified by `name`, copies its value
|
|
|
747 into `buffer`, and sets `size` to the string length of the value. When
|
|
|
748 calling this function, `size` must be set to the amount of storage available
|
|
|
749 in `buffer`, including the null terminator. If the environment variable
|
|
|
750 exceeds the storage available in `buffer`, `UV_ENOBUFS` is returned, and
|
|
|
751 `size` is set to the amount of storage required to hold the value. If no
|
|
|
752 matching environment variable exists, `UV_ENOENT` is returned.
|
|
|
753
|
|
|
754 .. warning::
|
|
|
755 This function is not thread safe.
|
|
|
756
|
|
|
757 .. versionadded:: 1.12.0
|
|
|
758
|
|
|
759 .. c:function:: int uv_os_setenv(const char* name, const char* value)
|
|
|
760
|
|
|
761 Creates or updates the environment variable specified by `name` with
|
|
|
762 `value`.
|
|
|
763
|
|
|
764 .. warning::
|
|
|
765 This function is not thread safe.
|
|
|
766
|
|
|
767 .. versionadded:: 1.12.0
|
|
|
768
|
|
|
769 .. c:function:: int uv_os_unsetenv(const char* name)
|
|
|
770
|
|
|
771 Deletes the environment variable specified by `name`. If no such environment
|
|
|
772 variable exists, this function returns successfully.
|
|
|
773
|
|
|
774 .. warning::
|
|
|
775 This function is not thread safe.
|
|
|
776
|
|
|
777 .. versionadded:: 1.12.0
|
|
|
778
|
|
|
779 .. c:function:: int uv_os_gethostname(char* buffer, size_t* size)
|
|
|
780
|
|
|
781 Returns the hostname as a null-terminated string in `buffer`, and sets
|
|
|
782 `size` to the string length of the hostname. When calling this function,
|
|
|
783 `size` must be set to the amount of storage available in `buffer`, including
|
|
|
784 the null terminator. If the hostname exceeds the storage available in
|
|
|
785 `buffer`, `UV_ENOBUFS` is returned, and `size` is set to the amount of
|
|
|
786 storage required to hold the value.
|
|
|
787
|
|
|
788 .. versionadded:: 1.12.0
|
|
|
789
|
|
|
790 .. versionchanged:: 1.26.0 `UV_MAXHOSTNAMESIZE` is available and represents
|
|
|
791 the maximum `buffer` size required to store a
|
|
|
792 hostname and terminating `nul` character.
|
|
|
793
|
|
|
794 .. c:function:: int uv_os_getpriority(uv_pid_t pid, int* priority)
|
|
|
795
|
|
|
796 Retrieves the scheduling priority of the process specified by `pid`. The
|
|
|
797 returned value of `priority` is between -20 (high priority) and 19 (low
|
|
|
798 priority).
|
|
|
799
|
|
|
800 .. note::
|
|
|
801 On Windows, the returned priority will equal one of the `UV_PRIORITY`
|
|
|
802 constants.
|
|
|
803
|
|
|
804 .. versionadded:: 1.23.0
|
|
|
805
|
|
|
806 .. c:function:: int uv_os_setpriority(uv_pid_t pid, int priority)
|
|
|
807
|
|
|
808 Sets the scheduling priority of the process specified by `pid`. The
|
|
|
809 `priority` value range is between -20 (high priority) and 19 (low priority).
|
|
|
810 The constants `UV_PRIORITY_LOW`, `UV_PRIORITY_BELOW_NORMAL`,
|
|
|
811 `UV_PRIORITY_NORMAL`, `UV_PRIORITY_ABOVE_NORMAL`, `UV_PRIORITY_HIGH`, and
|
|
|
812 `UV_PRIORITY_HIGHEST` are also provided for convenience.
|
|
|
813
|
|
|
814 .. note::
|
|
|
815 On Windows, this function utilizes `SetPriorityClass()`. The `priority`
|
|
|
816 argument is mapped to a Windows priority class. When retrieving the
|
|
|
817 process priority, the result will equal one of the `UV_PRIORITY`
|
|
|
818 constants, and not necessarily the exact value of `priority`.
|
|
|
819
|
|
|
820 .. note::
|
|
|
821 On Windows, setting `PRIORITY_HIGHEST` will only work for elevated user,
|
|
|
822 for others it will be silently reduced to `PRIORITY_HIGH`.
|
|
|
823
|
|
|
824 .. note::
|
|
|
825 On IBM i PASE, the highest process priority is -10. The constant
|
|
|
826 `UV_PRIORITY_HIGHEST` is -10, `UV_PRIORITY_HIGH` is -7,
|
|
|
827 `UV_PRIORITY_ABOVE_NORMAL` is -4, `UV_PRIORITY_NORMAL` is 0,
|
|
|
828 `UV_PRIORITY_BELOW_NORMAL` is 15 and `UV_PRIORITY_LOW` is 39.
|
|
|
829
|
|
|
830 .. note::
|
|
|
831 On IBM i PASE, you are not allowed to change your priority unless you
|
|
|
832 have the \*JOBCTL special authority (even to lower it).
|
|
|
833
|
|
|
834 .. versionadded:: 1.23.0
|
|
|
835
|
|
|
836 .. c:function:: int uv_os_uname(uv_utsname_t* buffer)
|
|
|
837
|
|
|
838 Retrieves system information in `buffer`. The populated data includes the
|
|
|
839 operating system name, release, version, and machine. On non-Windows
|
|
|
840 systems, `uv_os_uname()` is a thin wrapper around :man:`uname(2)`. Returns
|
|
|
841 zero on success, and a non-zero error value otherwise.
|
|
|
842
|
|
|
843 .. versionadded:: 1.25.0
|
|
|
844
|
|
|
845 .. c:function:: int uv_gettimeofday(uv_timeval64_t* tv)
|
|
|
846
|
|
|
847 Cross-platform implementation of :man:`gettimeofday(2)`. The timezone
|
|
|
848 argument to `gettimeofday()` is not supported, as it is considered obsolete.
|
|
|
849
|
|
|
850 .. versionadded:: 1.28.0
|
|
|
851
|
|
|
852 .. c:function:: int uv_random(uv_loop_t* loop, uv_random_t* req, void* buf, size_t buflen, unsigned int flags, uv_random_cb cb)
|
|
|
853
|
|
|
854 Fill `buf` with exactly `buflen` cryptographically strong random bytes
|
|
|
855 acquired from the system CSPRNG. `flags` is reserved for future extension
|
|
|
856 and must currently be 0.
|
|
|
857
|
|
|
858 Short reads are not possible. When less than `buflen` random bytes are
|
|
|
859 available, a non-zero error value is returned or passed to the callback.
|
|
|
860
|
|
|
861 The synchronous version may block indefinitely when not enough entropy
|
|
|
862 is available. The asynchronous version may not ever finish when the system
|
|
|
863 is low on entropy.
|
|
|
864
|
|
|
865 Sources of entropy:
|
|
|
866
|
|
|
867 - Windows: `RtlGenRandom <https://docs.microsoft.com/en-us/windows/desktop/api/ntsecapi/nf-ntsecapi-rtlgenrandom>_`.
|
|
|
868 - Linux, Android: :man:`getrandom(2)` if available, or :man:`urandom(4)`
|
|
|
869 after reading from `/dev/random` once, or the `KERN_RANDOM`
|
|
|
870 :man:`sysctl(2)`.
|
|
|
871 - FreeBSD: `getrandom(2) <https://www.freebsd.org/cgi/man.cgi?query=getrandom&sektion=2>_`,
|
|
|
872 or `/dev/urandom` after reading from `/dev/random` once.
|
|
|
873 - NetBSD: `KERN_ARND` `sysctl(7) <https://man.netbsd.org/sysctl.7>_`
|
|
|
874 - macOS, OpenBSD: `getentropy(2) <https://man.openbsd.org/getentropy.2>_`
|
|
|
875 if available, or `/dev/urandom` after reading from `/dev/random` once.
|
|
|
876 - AIX: `/dev/random`.
|
|
|
877 - IBM i: `/dev/urandom`.
|
|
|
878 - Other UNIX: `/dev/urandom` after reading from `/dev/random` once.
|
|
|
879
|
|
|
880 :returns: 0 on success, or an error code < 0 on failure. The contents of
|
|
|
881 `buf` is undefined after an error.
|
|
|
882
|
|
|
883 .. note::
|
|
|
884 When using the synchronous version, both `loop` and `req` parameters
|
|
|
885 are not used and can be set to `NULL`.
|
|
|
886
|
|
|
887 .. versionadded:: 1.33.0
|
|
|
888
|
|
|
889 .. c:function:: void uv_sleep(unsigned int msec)
|
|
|
890
|
|
|
891 Causes the calling thread to sleep for `msec` milliseconds.
|
|
|
892
|
|
|
893 .. versionadded:: 1.34.0
|
|
|
894
|
|
|
895 String manipulation functions
|
|
|
896 -----------------------------
|
|
|
897
|
|
|
898 These string utilities are needed internally for dealing with Windows, and are
|
|
|
899 exported to allow clients to work uniformly with this data when the libuv API
|
|
|
900 is not complete.
|
|
|
901
|
|
|
902 .. c:function:: size_t uv_utf16_length_as_wtf8(const uint16_t* utf16, ssize_t utf16_len)
|
|
|
903
|
|
|
904 Get the length of a UTF-16 (or UCS-2) `utf16` value after converting it to
|
|
|
905 WTF-8. If `utf16` is NUL terminated, `utf16_len` can be set to -1,
|
|
|
906 otherwise it must be specified.
|
|
|
907
|
|
|
908 .. versionadded:: 1.47.0
|
|
|
909
|
|
|
910 .. c:function:: int uv_utf16_to_wtf8(const uint16_t* utf16, ssize_t utf16_len, char** wtf8_ptr, size_t* wtf8_len_ptr)
|
|
|
911
|
|
|
912 Convert UTF-16 (or UCS-2) data in `utf16` to WTF-8 data in `*wtf8_ptr`. The
|
|
|
913 `utf16_len` count (in characters) gives the length of `utf16`. If `utf16`
|
|
|
914 is NUL terminated, `utf16_len` can be set to -1, otherwise it must be
|
|
|
915 specified. If `wtf8_ptr` is `NULL`, no result will be computed, but the
|
|
|
916 length (equal to `uv_utf16_length_as_wtf8`) will be stored in `wtf8_ptr`.
|
|
|
917 If `*wtf8_ptr` is `NULL`, space for the conversion will be allocated and
|
|
|
918 returned in `wtf8_ptr` and the length will be returned in `wtf8_len_ptr`.
|
|
|
919 Otherwise, the length of `*wtf8_ptr` must be passed in `wtf8_len_ptr`. The
|
|
|
920 `wtf8_ptr` must contain an extra space for an extra NUL after the result.
|
|
|
921 If the result is truncated, `UV_ENOBUFS` will be returned and
|
|
|
922 `wtf8_len_ptr` will be the length of the required `wtf8_ptr` to contain the
|
|
|
923 whole result.
|
|
|
924
|
|
|
925 .. versionadded:: 1.47.0
|
|
|
926
|
|
|
927 .. c:function:: ssize_t uv_wtf8_length_as_utf16(const char* wtf8)
|
|
|
928
|
|
|
929 Get the length in characters of a NUL-terminated WTF-8 `wtf8` value
|
|
|
930 after converting it to UTF-16 (or UCS-2), including NUL terminator.
|
|
|
931
|
|
|
932 .. versionadded:: 1.47.0
|
|
|
933
|
|
|
934 .. c:function:: void uv_wtf8_to_utf16(const char* utf8, uint16_t* utf16, size_t utf16_len)
|
|
|
935
|
|
|
936 Convert NUL-terminated WTF-8 data in `wtf8` to UTF-16 (or UCS-2) data
|
|
|
937 in `utf16`. The `utf16_len` count (in characters) must include space
|
|
|
938 for the NUL terminator.
|
|
|
939
|
|
|
940 .. versionadded:: 1.47.0
|
