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