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