1 2.. _misc: 3 4Miscellaneous utilities 5======================= 6 7This section contains miscellaneous functions that don't really belong in any 8other section. 9 10 11Data 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 242API 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:: uv_pid_t uv_os_getpid(void) 364 365 Returns the current process ID. 366 367 .. versionadded:: 1.18.0 368 369.. c:function:: uv_pid_t uv_os_getppid(void) 370 371 Returns the parent process ID. 372 373 .. versionadded:: 1.16.0 374 375.. c:function:: unsigned int uv_available_parallelism(void) 376 377 Returns an estimate of the default amount of parallelism a program should 378 use. Always returns a non-zero value. 379 380 On Linux, inspects the calling thread's CPU affinity mask to determine if 381 it has been pinned to specific CPUs. 382 383 On Windows, the available parallelism may be underreported on systems with 384 more than 64 logical CPUs. 385 386 On other platforms, reports the number of CPUs that the operating system 387 considers to be online. 388 389 .. versionadded:: 1.44.0 390 391.. c:function:: int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count) 392 393 Gets information about the CPUs on the system. The `cpu_infos` array will 394 have `count` elements and needs to be freed with :c:func:`uv_free_cpu_info`. 395 396 Use :c:func:`uv_available_parallelism` if you need to know how many CPUs 397 are available for threads or child processes. 398 399.. c:function:: void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) 400 401 Frees the `cpu_infos` array previously allocated with :c:func:`uv_cpu_info`. 402 403.. c:function:: int uv_cpumask_size(void) 404 405 Returns the maximum size of the mask used for process/thread affinities, 406 or `UV_ENOTSUP` if affinities are not supported on the current platform. 407 408 .. versionadded:: 1.45.0 409 410.. c:function:: int uv_interface_addresses(uv_interface_address_t** addresses, int* count) 411 412 Gets address information about the network interfaces on the system. An 413 array of `count` elements is allocated and returned in `addresses`. It must 414 be freed by the user, calling :c:func:`uv_free_interface_addresses`. 415 416.. c:function:: void uv_free_interface_addresses(uv_interface_address_t* addresses, int count) 417 418 Free an array of :c:type:`uv_interface_address_t` which was returned by 419 :c:func:`uv_interface_addresses`. 420 421.. c:function:: void uv_loadavg(double avg[3]) 422 423 Gets the load average. See: `<https://en.wikipedia.org/wiki/Load_(computing)>`_ 424 425 .. note:: 426 Returns [0,0,0] on Windows (i.e., it's not implemented). 427 428.. c:function:: int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr) 429 430 Convert a string containing an IPv4 addresses to a binary structure. 431 432.. c:function:: int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr) 433 434 Convert a string containing an IPv6 addresses to a binary structure. 435 436.. c:function:: int uv_ip4_name(const struct sockaddr_in* src, char* dst, size_t size) 437 438 Convert a binary structure containing an IPv4 address to a string. 439 440.. c:function:: int uv_ip6_name(const struct sockaddr_in6* src, char* dst, size_t size) 441 442 Convert a binary structure containing an IPv6 address to a string. 443 444.. c:function:: int uv_ip_name(const struct sockaddr *src, char *dst, size_t size) 445 446 Convert a binary structure containing an IPv4 address or an IPv6 address to a string. 447 448.. c:function:: int uv_inet_ntop(int af, const void* src, char* dst, size_t size) 449.. c:function:: int uv_inet_pton(int af, const char* src, void* dst) 450 451 Cross-platform IPv6-capable implementation of :man:`inet_ntop(3)` 452 and :man:`inet_pton(3)`. On success they return 0. In case of error 453 the target `dst` pointer is unmodified. 454 455.. c:macro:: UV_IF_NAMESIZE 456 457 Maximum IPv6 interface identifier name length. Defined as 458 `IFNAMSIZ` on Unix and `IF_NAMESIZE` on Linux and Windows. 459 460 .. versionadded:: 1.16.0 461 462.. c:function:: int uv_if_indextoname(unsigned int ifindex, char* buffer, size_t* size) 463 464 IPv6-capable implementation of :man:`if_indextoname(3)`. When called, 465 `*size` indicates the length of the `buffer`, which is used to store the 466 result. 467 On success, zero is returned, `buffer` contains the interface name, and 468 `*size` represents the string length of the `buffer`, excluding the NUL 469 terminator byte from `*size`. On error, a negative result is 470 returned. If `buffer` is not large enough to hold the result, 471 `UV_ENOBUFS` is returned, and `*size` represents the necessary size in 472 bytes, including the NUL terminator byte into the `*size`. 473 474 On Unix, the returned interface name can be used directly as an 475 interface identifier in scoped IPv6 addresses, e.g. 476 `fe80::abc:def1:2345%en0`. 477 478 On Windows, the returned interface cannot be used as an interface 479 identifier, as Windows uses numerical interface identifiers, e.g. 480 `fe80::abc:def1:2345%5`. 481 482 To get an interface identifier in a cross-platform compatible way, 483 use `uv_if_indextoiid()`. 484 485 Example: 486 487 :: 488 489 char ifname[UV_IF_NAMESIZE]; 490 size_t size = sizeof(ifname); 491 uv_if_indextoname(sin6->sin6_scope_id, ifname, &size); 492 493 .. versionadded:: 1.16.0 494 495.. c:function:: int uv_if_indextoiid(unsigned int ifindex, char* buffer, size_t* size) 496 497 Retrieves a network interface identifier suitable for use in an IPv6 scoped 498 address. On Windows, returns the numeric `ifindex` as a string. On all other 499 platforms, `uv_if_indextoname()` is called. The result is written to 500 `buffer`, with `*size` indicating the length of `buffer`. If `buffer` is not 501 large enough to hold the result, then `UV_ENOBUFS` is returned, and `*size` 502 represents the size, including the NUL byte, required to hold the 503 result. 504 505 See `uv_if_indextoname` for further details. 506 507 .. versionadded:: 1.16.0 508 509.. c:function:: int uv_exepath(char* buffer, size_t* size) 510 511 Gets the executable path. You *must* call `uv_setup_args` before calling 512 this function. 513 514.. c:function:: int uv_cwd(char* buffer, size_t* size) 515 516 Gets the current working directory, and stores it in `buffer`. If the 517 current working directory is too large to fit in `buffer`, this function 518 returns `UV_ENOBUFS`, and sets `size` to the required length, including the 519 null terminator. 520 521 .. versionchanged:: 1.1.0 522 523 On Unix the path no longer ends in a slash. 524 525 .. versionchanged:: 1.9.0 the returned length includes the terminating null 526 byte on `UV_ENOBUFS`, and the buffer is null terminated 527 on success. 528 529 530.. c:function:: int uv_chdir(const char* dir) 531 532 Changes the current working directory. 533 534.. c:function:: int uv_os_homedir(char* buffer, size_t* size) 535 536 Gets the current user's home directory. On Windows, `uv_os_homedir()` first 537 checks the `USERPROFILE` environment variable using 538 `GetEnvironmentVariableW()`. If `USERPROFILE` is not set, 539 `GetUserProfileDirectoryW()` is called. On all other operating systems, 540 `uv_os_homedir()` first checks the `HOME` environment variable using 541 :man:`getenv(3)`. If `HOME` is not set, :man:`getpwuid_r(3)` is called. The 542 user's home directory is stored in `buffer`. When `uv_os_homedir()` is 543 called, `size` indicates the maximum size of `buffer`. On success `size` is set 544 to the string length of `buffer`. On `UV_ENOBUFS` failure `size` is set to the 545 required length for `buffer`, including the null byte. 546 547 .. warning:: 548 `uv_os_homedir()` is not thread safe. 549 550 .. versionadded:: 1.6.0 551 552.. c:function:: int uv_os_tmpdir(char* buffer, size_t* size) 553 554 Gets the temp directory. On Windows, `uv_os_tmpdir()` uses `GetTempPathW()`. 555 On all other operating systems, `uv_os_tmpdir()` uses the first environment 556 variable found in the ordered list `TMPDIR`, `TMP`, `TEMP`, and `TEMPDIR`. 557 If none of these are found, the path `"/tmp"` is used, or, on Android, 558 `"/data/local/tmp"` is used. The temp directory is stored in `buffer`. When 559 `uv_os_tmpdir()` is called, `size` indicates the maximum size of `buffer`. 560 On success `size` is set to the string length of `buffer` (which does not 561 include the terminating null). On `UV_ENOBUFS` failure `size` is set to the 562 required length for `buffer`, including the null byte. 563 564 .. warning:: 565 `uv_os_tmpdir()` is not thread safe. 566 567 .. versionadded:: 1.9.0 568 569.. c:function:: int uv_os_get_passwd(uv_passwd_t* pwd) 570 571 Gets a subset of the password file entry for the current effective uid (not 572 the real uid). The populated data includes the username, euid, gid, shell, 573 and home directory. On non-Windows systems, all data comes from 574 :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no 575 meaning, and shell is `NULL`. After successfully calling this function, the 576 memory allocated to `pwd` needs to be freed with 577 :c:func:`uv_os_free_passwd`. 578 579 .. versionadded:: 1.9.0 580 581.. c:function:: int uv_os_get_passwd2(uv_passwd_t* pwd, uv_uid_t uid) 582 583 Gets a subset of the password file entry for the provided uid. 584 The populated data includes the username, euid, gid, shell, 585 and home directory. On non-Windows systems, all data comes from 586 :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no 587 meaning, and shell is `NULL`. After successfully calling this function, the 588 memory allocated to `pwd` needs to be freed with 589 :c:func:`uv_os_free_passwd`. 590 591 .. versionadded:: 1.45.0 592 593.. c:function:: int uv_os_get_group(uv_group_t* group, uv_uid_t gid) 594 595 Gets a subset of the group file entry for the provided uid. 596 The populated data includes the group name, gid, and members. On non-Windows 597 systems, all data comes from :man:`getgrgid_r(3)`. On Windows, uid and gid 598 are set to -1 and have no meaning. After successfully calling this function, 599 the memory allocated to `group` needs to be freed with 600 :c:func:`uv_os_free_group`. 601 602 .. versionadded:: 1.45.0 603 604.. c:function:: void uv_os_free_group(uv_passwd_t* pwd) 605 606 Frees the memory previously allocated with :c:func:`uv_os_get_group`. 607 608 .. versionadded:: 1.45.0 609 610.. c:function:: void uv_os_free_passwd(uv_passwd_t* pwd) 611 612 Frees the `pwd` memory previously allocated with :c:func:`uv_os_get_passwd`. 613 614 .. versionadded:: 1.9.0 615 616.. c:function:: uint64_t uv_get_free_memory(void) 617 618 Gets the amount of free memory available in the system, as reported by 619 the kernel (in bytes). Returns 0 when unknown. 620 621.. c:function:: uint64_t uv_get_total_memory(void) 622 623 Gets the total amount of physical memory in the system (in bytes). 624 Returns 0 when unknown. 625 626.. c:function:: uint64_t uv_get_constrained_memory(void) 627 628 Gets the total amount of memory available to the process (in bytes) based on 629 limits imposed by the OS. If there is no such constraint, or the constraint 630 is unknown, `0` is returned. If there is a constraining mechanism, but there 631 is no constraint set, `UINT64_MAX` is returned. Note that it is not unusual 632 for this value to be less than or greater than :c:func:`uv_get_total_memory`. 633 634 .. note:: 635 This function currently only returns a non-zero value on Linux, based 636 on cgroups if it is present, and on z/OS based on RLIMIT_MEMLIMIT. 637 638 .. versionadded:: 1.29.0 639 640.. c:function:: uint64_t uv_get_available_memory(void) 641 642 Gets the amount of free memory that is still available to the process (in bytes). 643 This differs from :c:func:`uv_get_free_memory` in that it takes into account any 644 limits imposed by the OS. If there is no such constraint, or the constraint 645 is unknown, the amount returned will be identical to :c:func:`uv_get_free_memory`. 646 647 .. note:: 648 This function currently only returns a value that is different from 649 what :c:func:`uv_get_free_memory` reports on Linux, based 650 on cgroups if it is present. 651 652 .. versionadded:: 1.45.0 653 654.. c:function:: uint64_t uv_hrtime(void) 655 656 Returns the current high-resolution timestamp. This is expressed in 657 nanoseconds. It is relative to an arbitrary time in the past. It is not 658 related to the time of day and therefore not subject to clock drift. The 659 primary use is for measuring performance between intervals. 660 661 .. note:: 662 Not every platform can support nanosecond resolution; however, this value will always 663 be in nanoseconds. 664 665.. c:function:: int uv_clock_gettime(uv_clock_id clock_id, uv_timespec64_t* ts) 666 667 Obtain the current system time from a high-resolution real-time or monotonic 668 clock source. 669 670 The real-time clock counts from the UNIX epoch (1970-01-01) and is subject 671 to time adjustments; it can jump back in time. 672 673 The monotonic clock counts from an arbitrary point in the past and never 674 jumps back in time. 675 676 .. versionadded:: 1.45.0 677 678.. c:function:: void uv_print_all_handles(uv_loop_t* loop, FILE* stream) 679 680 Prints all handles associated with the given `loop` to the given `stream`. 681 682 Example: 683 684 :: 685 686 uv_print_all_handles(uv_default_loop(), stderr); 687 /* 688 [--I] signal 0x1a25ea8 689 [-AI] async 0x1a25cf0 690 [R--] idle 0x1a7a8c8 691 */ 692 693 The format is `[flags] handle-type handle-address`. For `flags`: 694 695 - `R` is printed for a handle that is referenced 696 - `A` is printed for a handle that is active 697 - `I` is printed for a handle that is internal 698 699 .. warning:: 700 This function is meant for ad hoc debugging, there is no API/ABI 701 stability guarantees. 702 703 .. versionadded:: 1.8.0 704 705.. c:function:: void uv_print_active_handles(uv_loop_t* loop, FILE* stream) 706 707 This is the same as :c:func:`uv_print_all_handles` except only active handles 708 are printed. 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:: int uv_os_environ(uv_env_item_t** envitems, int* count) 717 718 Retrieves all environment variables. This function will allocate memory 719 which must be freed by calling :c:func:`uv_os_free_environ`. 720 721 .. warning:: 722 This function is not thread safe. 723 724 .. versionadded:: 1.31.0 725 726.. c:function:: void uv_os_free_environ(uv_env_item_t* envitems, int count); 727 728 Frees the memory allocated for the environment variables by 729 :c:func:`uv_os_environ`. 730 731 .. versionadded:: 1.31.0 732 733.. c:function:: int uv_os_getenv(const char* name, char* buffer, size_t* size) 734 735 Retrieves the environment variable specified by `name`, copies its value 736 into `buffer`, and sets `size` to the string length of the value. When 737 calling this function, `size` must be set to the amount of storage available 738 in `buffer`, including the null terminator. If the environment variable 739 exceeds the storage available in `buffer`, `UV_ENOBUFS` is returned, and 740 `size` is set to the amount of storage required to hold the value. If no 741 matching environment variable exists, `UV_ENOENT` is returned. 742 743 .. warning:: 744 This function is not thread safe. 745 746 .. versionadded:: 1.12.0 747 748.. c:function:: int uv_os_setenv(const char* name, const char* value) 749 750 Creates or updates the environment variable specified by `name` with 751 `value`. 752 753 .. warning:: 754 This function is not thread safe. 755 756 .. versionadded:: 1.12.0 757 758.. c:function:: int uv_os_unsetenv(const char* name) 759 760 Deletes the environment variable specified by `name`. If no such environment 761 variable exists, this function returns successfully. 762 763 .. warning:: 764 This function is not thread safe. 765 766 .. versionadded:: 1.12.0 767 768.. c:function:: int uv_os_gethostname(char* buffer, size_t* size) 769 770 Returns the hostname as a null-terminated string in `buffer`, and sets 771 `size` to the string length of the hostname. When calling this function, 772 `size` must be set to the amount of storage available in `buffer`, including 773 the null terminator. If the hostname exceeds the storage available in 774 `buffer`, `UV_ENOBUFS` is returned, and `size` is set to the amount of 775 storage required to hold the value. 776 777 .. versionadded:: 1.12.0 778 779 .. versionchanged:: 1.26.0 `UV_MAXHOSTNAMESIZE` is available and represents 780 the maximum `buffer` size required to store a 781 hostname and terminating `nul` character. 782 783.. c:function:: int uv_os_getpriority(uv_pid_t pid, int* priority) 784 785 Retrieves the scheduling priority of the process specified by `pid`. The 786 returned value of `priority` is between -20 (high priority) and 19 (low 787 priority). 788 789 .. note:: 790 On Windows, the returned priority will equal one of the `UV_PRIORITY` 791 constants. 792 793 .. versionadded:: 1.23.0 794 795.. c:function:: int uv_os_setpriority(uv_pid_t pid, int priority) 796 797 Sets the scheduling priority of the process specified by `pid`. The 798 `priority` value range is between -20 (high priority) and 19 (low priority). 799 The constants `UV_PRIORITY_LOW`, `UV_PRIORITY_BELOW_NORMAL`, 800 `UV_PRIORITY_NORMAL`, `UV_PRIORITY_ABOVE_NORMAL`, `UV_PRIORITY_HIGH`, and 801 `UV_PRIORITY_HIGHEST` are also provided for convenience. 802 803 .. note:: 804 On Windows, this function utilizes `SetPriorityClass()`. The `priority` 805 argument is mapped to a Windows priority class. When retrieving the 806 process priority, the result will equal one of the `UV_PRIORITY` 807 constants, and not necessarily the exact value of `priority`. 808 809 .. note:: 810 On Windows, setting `PRIORITY_HIGHEST` will only work for elevated user, 811 for others it will be silently reduced to `PRIORITY_HIGH`. 812 813 .. note:: 814 On IBM i PASE, the highest process priority is -10. The constant 815 `UV_PRIORITY_HIGHEST` is -10, `UV_PRIORITY_HIGH` is -7, 816 `UV_PRIORITY_ABOVE_NORMAL` is -4, `UV_PRIORITY_NORMAL` is 0, 817 `UV_PRIORITY_BELOW_NORMAL` is 15 and `UV_PRIORITY_LOW` is 39. 818 819 .. note:: 820 On IBM i PASE, you are not allowed to change your priority unless you 821 have the \*JOBCTL special authority (even to lower it). 822 823 .. versionadded:: 1.23.0 824 825.. c:function:: int uv_os_uname(uv_utsname_t* buffer) 826 827 Retrieves system information in `buffer`. The populated data includes the 828 operating system name, release, version, and machine. On non-Windows 829 systems, `uv_os_uname()` is a thin wrapper around :man:`uname(2)`. Returns 830 zero on success, and a non-zero error value otherwise. 831 832 .. versionadded:: 1.25.0 833 834.. c:function:: int uv_gettimeofday(uv_timeval64_t* tv) 835 836 Cross-platform implementation of :man:`gettimeofday(2)`. The timezone 837 argument to `gettimeofday()` is not supported, as it is considered obsolete. 838 839 .. versionadded:: 1.28.0 840 841.. 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) 842 843 Fill `buf` with exactly `buflen` cryptographically strong random bytes 844 acquired from the system CSPRNG. `flags` is reserved for future extension 845 and must currently be 0. 846 847 Short reads are not possible. When less than `buflen` random bytes are 848 available, a non-zero error value is returned or passed to the callback. 849 850 The synchronous version may block indefinitely when not enough entropy 851 is available. The asynchronous version may not ever finish when the system 852 is low on entropy. 853 854 Sources of entropy: 855 856 - Windows: `RtlGenRandom <https://docs.microsoft.com/en-us/windows/desktop/api/ntsecapi/nf-ntsecapi-rtlgenrandom>_`. 857 - Linux, Android: :man:`getrandom(2)` if available, or :man:`urandom(4)` 858 after reading from `/dev/random` once, or the `KERN_RANDOM` 859 :man:`sysctl(2)`. 860 - FreeBSD: `getrandom(2) <https://www.freebsd.org/cgi/man.cgi?query=getrandom&sektion=2>_`, 861 or `/dev/urandom` after reading from `/dev/random` once. 862 - NetBSD: `KERN_ARND` `sysctl(7) <https://man.netbsd.org/sysctl.7>_` 863 - macOS, OpenBSD: `getentropy(2) <https://man.openbsd.org/getentropy.2>_` 864 if available, or `/dev/urandom` after reading from `/dev/random` once. 865 - AIX: `/dev/random`. 866 - IBM i: `/dev/urandom`. 867 - Other UNIX: `/dev/urandom` after reading from `/dev/random` once. 868 869 :returns: 0 on success, or an error code < 0 on failure. The contents of 870 `buf` is undefined after an error. 871 872 .. note:: 873 When using the synchronous version, both `loop` and `req` parameters 874 are not used and can be set to `NULL`. 875 876 .. versionadded:: 1.33.0 877 878.. c:function:: void uv_sleep(unsigned int msec) 879 880 Causes the calling thread to sleep for `msec` milliseconds. 881 882 .. versionadded:: 1.34.0 883 884String manipulation functions 885----------------------------- 886 887These string utilities are needed internally for dealing with Windows, and are 888exported to allow clients to work uniformly with this data when the libuv API 889is not complete. 890 891.. c:function:: size_t uv_utf16_length_as_wtf8(const uint16_t* utf16, ssize_t utf16_len) 892 893 Get the length of a UTF-16 (or UCS-2) `utf16` value after converting it to 894 WTF-8. If `utf16` is NUL terminated, `utf16_len` can be set to -1, 895 otherwise it must be specified. 896 897 .. versionadded:: 1.47.0 898 899.. c:function:: int uv_utf16_to_wtf8(const uint16_t* utf16, ssize_t utf16_len, char** wtf8_ptr, size_t* wtf8_len_ptr) 900 901 Convert UTF-16 (or UCS-2) data in `utf16` to WTF-8 data in `*wtf8_ptr`. The 902 `utf16_len` count (in characters) gives the length of `utf16`. If `utf16` 903 is NUL terminated, `utf16_len` can be set to -1, otherwise it must be 904 specified. If `wtf8_ptr` is `NULL`, no result will be computed, but the 905 length (equal to `uv_utf16_length_as_wtf8`) will be stored in `wtf8_ptr`. 906 If `*wtf8_ptr` is `NULL`, space for the conversion will be allocated and 907 returned in `wtf8_ptr` and the length will be returned in `wtf8_len_ptr`. 908 Otherwise, the length of `*wtf8_ptr` must be passed in `wtf8_len_ptr`. The 909 `wtf8_ptr` must contain an extra space for an extra NUL after the result. 910 If the result is truncated, `UV_ENOBUFS` will be returned and 911 `wtf8_len_ptr` will be the length of the required `wtf8_ptr` to contain the 912 whole result. 913 914 .. versionadded:: 1.47.0 915 916.. c:function:: ssize_t uv_wtf8_length_as_utf16(const char* wtf8) 917 918 Get the length in characters of a NUL-terminated WTF-8 `wtf8` value 919 after converting it to UTF-16 (or UCS-2), including NUL terminator. 920 921 .. versionadded:: 1.47.0 922 923.. c:function:: void uv_wtf8_to_utf16(const char* utf8, uint16_t* utf16, size_t utf16_len) 924 925 Convert NUL-terminated WTF-8 data in `wtf8` to UTF-16 (or UCS-2) data 926 in `utf16`. The `utf16_len` count (in characters) must include space 927 for the NUL terminator. 928 929 .. versionadded:: 1.47.0 930
