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:: uv_file 50 51 Cross platform representation of a file handle. 52 53.. c:type:: uv_os_sock_t 54 55 Cross platform representation of a socket handle. 56 57.. c:type:: uv_os_fd_t 58 59 Abstract representation of a file descriptor. On Unix systems this is a 60 `typedef` of `int` and on Windows a `HANDLE`. 61 62.. c:type:: uv_pid_t 63 64 Cross platform representation of a `pid_t`. 65 66 .. versionadded:: 1.16.0 67 68.. c:type:: uv_rusage_t 69 70 Data type for resource usage results. 71 72 :: 73 74 typedef struct { 75 uv_timeval_t ru_utime; /* user CPU time used */ 76 uv_timeval_t ru_stime; /* system CPU time used */ 77 uint64_t ru_maxrss; /* maximum resident set size */ 78 uint64_t ru_ixrss; /* integral shared memory size (X) */ 79 uint64_t ru_idrss; /* integral unshared data size (X) */ 80 uint64_t ru_isrss; /* integral unshared stack size (X) */ 81 uint64_t ru_minflt; /* page reclaims (soft page faults) (X) */ 82 uint64_t ru_majflt; /* page faults (hard page faults) */ 83 uint64_t ru_nswap; /* swaps (X) */ 84 uint64_t ru_inblock; /* block input operations */ 85 uint64_t ru_oublock; /* block output operations */ 86 uint64_t ru_msgsnd; /* IPC messages sent (X) */ 87 uint64_t ru_msgrcv; /* IPC messages received (X) */ 88 uint64_t ru_nsignals; /* signals received (X) */ 89 uint64_t ru_nvcsw; /* voluntary context switches (X) */ 90 uint64_t ru_nivcsw; /* involuntary context switches (X) */ 91 } uv_rusage_t; 92 93 Members marked with `(X)` are unsupported on Windows. 94 See :man:`getrusage(2)` for supported fields on Unix 95 96.. c:type:: uv_cpu_info_t 97 98 Data type for CPU information. 99 100 :: 101 102 typedef struct uv_cpu_info_s { 103 char* model; 104 int speed; 105 struct uv_cpu_times_s { 106 uint64_t user; 107 uint64_t nice; 108 uint64_t sys; 109 uint64_t idle; 110 uint64_t irq; 111 } cpu_times; 112 } uv_cpu_info_t; 113 114.. c:type:: uv_interface_address_t 115 116 Data type for interface addresses. 117 118 :: 119 120 typedef struct uv_interface_address_s { 121 char* name; 122 char phys_addr[6]; 123 int is_internal; 124 union { 125 struct sockaddr_in address4; 126 struct sockaddr_in6 address6; 127 } address; 128 union { 129 struct sockaddr_in netmask4; 130 struct sockaddr_in6 netmask6; 131 } netmask; 132 } uv_interface_address_t; 133 134.. c:type:: uv_passwd_t 135 136 Data type for password file information. 137 138 :: 139 140 typedef struct uv_passwd_s { 141 char* username; 142 long uid; 143 long gid; 144 char* shell; 145 char* homedir; 146 } uv_passwd_t; 147 148 149API 150--- 151 152.. c:function:: uv_handle_type uv_guess_handle(uv_file file) 153 154 Used to detect what type of stream should be used with a given file 155 descriptor. Usually this will be used during initialization to guess the 156 type of the stdio streams. 157 158 For :man:`isatty(3)` equivalent functionality use this function and test 159 for ``UV_TTY``. 160 161.. 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) 162 163 .. versionadded:: 1.6.0 164 165 Override the use of the standard library's :man:`malloc(3)`, 166 :man:`calloc(3)`, :man:`realloc(3)`, :man:`free(3)`, memory allocation 167 functions. 168 169 This function must be called before any other libuv function is called or 170 after all resources have been freed and thus libuv doesn't reference 171 any allocated memory chunk. 172 173 On success, it returns 0, if any of the function pointers is NULL it 174 returns UV_EINVAL. 175 176 .. warning:: There is no protection against changing the allocator multiple 177 times. If the user changes it they are responsible for making 178 sure the allocator is changed while no memory was allocated with 179 the previous allocator, or that they are compatible. 180 181.. c:function:: uv_buf_t uv_buf_init(char* base, unsigned int len) 182 183 Constructor for :c:type:`uv_buf_t`. 184 185 Due to platform differences the user cannot rely on the ordering of the 186 `base` and `len` members of the uv_buf_t struct. The user is responsible for 187 freeing `base` after the uv_buf_t is done. Return struct passed by value. 188 189.. c:function:: char** uv_setup_args(int argc, char** argv) 190 191 Store the program arguments. Required for getting / setting the process title. 192 193.. c:function:: int uv_get_process_title(char* buffer, size_t size) 194 195 Gets the title of the current process. You *must* call `uv_setup_args` 196 before calling this function. If `buffer` is `NULL` or `size` is zero, 197 `UV_EINVAL` is returned. If `size` cannot accommodate the process title and 198 terminating `NULL` character, the function returns `UV_ENOBUFS`. 199 200 .. versionchanged:: 1.18.1 now thread-safe on all supported platforms. 201 202.. c:function:: int uv_set_process_title(const char* title) 203 204 Sets the current process title. You *must* call `uv_setup_args` before 205 calling this function. On platforms with a fixed size buffer for the process 206 title the contents of `title` will be copied to the buffer and truncated if 207 larger than the available space. Other platforms will return `UV_ENOMEM` if 208 they cannot allocate enough space to duplicate the contents of `title`. 209 210 .. versionchanged:: 1.18.1 now thread-safe on all supported platforms. 211 212.. c:function:: int uv_resident_set_memory(size_t* rss) 213 214 Gets the resident set size (RSS) for the current process. 215 216.. c:function:: int uv_uptime(double* uptime) 217 218 Gets the current system uptime. 219 220.. c:function:: int uv_getrusage(uv_rusage_t* rusage) 221 222 Gets the resource usage measures for the current process. 223 224 .. note:: 225 On Windows not all fields are set, the unsupported fields are filled with zeroes. 226 See :c:type:`uv_rusage_t` for more details. 227 228.. c:function:: uv_pid_t uv_os_getpid(void) 229 230 Returns the current process ID. 231 232 .. versionadded:: 1.18.0 233 234.. c:function:: uv_pid_t uv_os_getppid(void) 235 236 Returns the parent process ID. 237 238 .. versionadded:: 1.16.0 239 240.. c:function:: int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count) 241 242 Gets information about the CPUs on the system. The `cpu_infos` array will 243 have `count` elements and needs to be freed with :c:func:`uv_free_cpu_info`. 244 245.. c:function:: void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) 246 247 Frees the `cpu_infos` array previously allocated with :c:func:`uv_cpu_info`. 248 249.. c:function:: int uv_interface_addresses(uv_interface_address_t** addresses, int* count) 250 251 Gets address information about the network interfaces on the system. An 252 array of `count` elements is allocated and returned in `addresses`. It must 253 be freed by the user, calling :c:func:`uv_free_interface_addresses`. 254 255.. c:function:: void uv_free_interface_addresses(uv_interface_address_t* addresses, int count) 256 257 Free an array of :c:type:`uv_interface_address_t` which was returned by 258 :c:func:`uv_interface_addresses`. 259 260.. c:function:: void uv_loadavg(double avg[3]) 261 262 Gets the load average. See: `<http://en.wikipedia.org/wiki/Load_(computing)>`_ 263 264 .. note:: 265 Returns [0,0,0] on Windows (i.e., it's not implemented). 266 267.. c:function:: int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr) 268 269 Convert a string containing an IPv4 addresses to a binary structure. 270 271.. c:function:: int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr) 272 273 Convert a string containing an IPv6 addresses to a binary structure. 274 275.. c:function:: int uv_ip4_name(const struct sockaddr_in* src, char* dst, size_t size) 276 277 Convert a binary structure containing an IPv4 address to a string. 278 279.. c:function:: int uv_ip6_name(const struct sockaddr_in6* src, char* dst, size_t size) 280 281 Convert a binary structure containing an IPv6 address to a string. 282 283.. c:function:: int uv_inet_ntop(int af, const void* src, char* dst, size_t size) 284.. c:function:: int uv_inet_pton(int af, const char* src, void* dst) 285 286 Cross-platform IPv6-capable implementation of :man:`inet_ntop(3)` 287 and :man:`inet_pton(3)`. On success they return 0. In case of error 288 the target `dst` pointer is unmodified. 289 290.. c:macro:: UV_IF_NAMESIZE 291 292 Maximum IPv6 interface identifier name length. Defined as 293 `IFNAMSIZ` on Unix and `IF_NAMESIZE` on Linux and Windows. 294 295 .. versionadded:: 1.16.0 296 297.. c:function:: int uv_if_indextoname(unsigned int ifindex, char* buffer, size_t* size) 298 299 IPv6-capable implementation of :man:`if_indextoname(3)`. When called, 300 `*size` indicates the length of the `buffer`, which is used to store the 301 result. 302 On success, zero is returned, `buffer` contains the interface name, and 303 `*size` represents the string length of the `buffer`, excluding the NUL 304 terminator byte from `*size`. On error, a negative result is 305 returned. If `buffer` is not large enough to hold the result, 306 `UV_ENOBUFS` is returned, and `*size` represents the necessary size in 307 bytes, including the NUL terminator byte into the `*size`. 308 309 On Unix, the returned interface name can be used directly as an 310 interface identifier in scoped IPv6 addresses, e.g. 311 `fe80::abc:def1:2345%en0`. 312 313 On Windows, the returned interface cannot be used as an interface 314 identifier, as Windows uses numerical interface identifiers, e.g. 315 `fe80::abc:def1:2345%5`. 316 317 To get an interface identifier in a cross-platform compatible way, 318 use `uv_if_indextoiid()`. 319 320 Example: 321 322 :: 323 324 char ifname[UV_IF_NAMESIZE]; 325 size_t size = sizeof(ifname); 326 uv_if_indextoname(sin6->sin6_scope_id, ifname, &size); 327 328 .. versionadded:: 1.16.0 329 330.. c:function:: int uv_if_indextoiid(unsigned int ifindex, char* buffer, size_t* size) 331 332 Retrieves a network interface identifier suitable for use in an IPv6 scoped 333 address. On Windows, returns the numeric `ifindex` as a string. On all other 334 platforms, `uv_if_indextoname()` is called. The result is written to 335 `buffer`, with `*size` indicating the length of `buffer`. If `buffer` is not 336 large enough to hold the result, then `UV_ENOBUFS` is returned, and `*size` 337 represents the size, including the NUL byte, required to hold the 338 result. 339 340 See `uv_if_indextoname` for further details. 341 342 .. versionadded:: 1.16.0 343 344.. c:function:: int uv_exepath(char* buffer, size_t* size) 345 346 Gets the executable path. 347 348.. c:function:: int uv_cwd(char* buffer, size_t* size) 349 350 Gets the current working directory, and stores it in `buffer`. If the 351 current working directory is too large to fit in `buffer`, this function 352 returns `UV_ENOBUFS`, and sets `size` to the required length, including the 353 null terminator. 354 355 .. versionchanged:: 1.1.0 356 357 On Unix the path no longer ends in a slash. 358 359 .. versionchanged:: 1.9.0 the returned length includes the terminating null 360 byte on `UV_ENOBUFS`, and the buffer is null terminated 361 on success. 362 363 364.. c:function:: int uv_chdir(const char* dir) 365 366 Changes the current working directory. 367 368.. c:function:: int uv_os_homedir(char* buffer, size_t* size) 369 370 Gets the current user's home directory. On Windows, `uv_os_homedir()` first 371 checks the `USERPROFILE` environment variable using 372 `GetEnvironmentVariableW()`. If `USERPROFILE` is not set, 373 `GetUserProfileDirectoryW()` is called. On all other operating systems, 374 `uv_os_homedir()` first checks the `HOME` environment variable using 375 :man:`getenv(3)`. If `HOME` is not set, :man:`getpwuid_r(3)` is called. The 376 user's home directory is stored in `buffer`. When `uv_os_homedir()` is 377 called, `size` indicates the maximum size of `buffer`. On success `size` is set 378 to the string length of `buffer`. On `UV_ENOBUFS` failure `size` is set to the 379 required length for `buffer`, including the null byte. 380 381 .. warning:: 382 `uv_os_homedir()` is not thread safe. 383 384 .. versionadded:: 1.6.0 385 386.. c:function:: int uv_os_tmpdir(char* buffer, size_t* size) 387 388 Gets the temp directory. On Windows, `uv_os_tmpdir()` uses `GetTempPathW()`. 389 On all other operating systems, `uv_os_tmpdir()` uses the first environment 390 variable found in the ordered list `TMPDIR`, `TMP`, `TEMP`, and `TEMPDIR`. 391 If none of these are found, the path `"/tmp"` is used, or, on Android, 392 `"/data/local/tmp"` is used. The temp directory is stored in `buffer`. When 393 `uv_os_tmpdir()` is called, `size` indicates the maximum size of `buffer`. 394 On success `size` is set to the string length of `buffer` (which does not 395 include the terminating null). On `UV_ENOBUFS` failure `size` is set to the 396 required length for `buffer`, including the null byte. 397 398 .. warning:: 399 `uv_os_tmpdir()` is not thread safe. 400 401 .. versionadded:: 1.9.0 402 403.. c:function:: int uv_os_get_passwd(uv_passwd_t* pwd) 404 405 Gets a subset of the password file entry for the current effective uid (not 406 the real uid). The populated data includes the username, euid, gid, shell, 407 and home directory. On non-Windows systems, all data comes from 408 :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no 409 meaning, and shell is `NULL`. After successfully calling this function, the 410 memory allocated to `pwd` needs to be freed with 411 :c:func:`uv_os_free_passwd`. 412 413 .. versionadded:: 1.9.0 414 415.. c:function:: void uv_os_free_passwd(uv_passwd_t* pwd) 416 417 Frees the `pwd` memory previously allocated with :c:func:`uv_os_get_passwd`. 418 419 .. versionadded:: 1.9.0 420 421.. uint64_t uv_get_free_memory(void) 422.. c:function:: uint64_t uv_get_total_memory(void) 423 424 Gets memory information (in bytes). 425 426.. c:function:: uint64_t uv_hrtime(void) 427 428 Returns the current high-resolution real time. This is expressed in 429 nanoseconds. It is relative to an arbitrary time in the past. It is not 430 related to the time of day and therefore not subject to clock drift. The 431 primary use is for measuring performance between intervals. 432 433 .. note:: 434 Not every platform can support nanosecond resolution; however, this value will always 435 be in nanoseconds. 436 437.. c:function:: void uv_print_all_handles(uv_loop_t* loop, FILE* stream) 438 439 Prints all handles associated with the given `loop` to the given `stream`. 440 441 Example: 442 443 :: 444 445 uv_print_all_handles(uv_default_loop(), stderr); 446 /* 447 [--I] signal 0x1a25ea8 448 [-AI] async 0x1a25cf0 449 [R--] idle 0x1a7a8c8 450 */ 451 452 The format is `[flags] handle-type handle-address`. For `flags`: 453 454 - `R` is printed for a handle that is referenced 455 - `A` is printed for a handle that is active 456 - `I` is printed for a handle that is internal 457 458 .. warning:: 459 This function is meant for ad hoc debugging, there is no API/ABI 460 stability guarantees. 461 462 .. versionadded:: 1.8.0 463 464.. c:function:: void uv_print_active_handles(uv_loop_t* loop, FILE* stream) 465 466 This is the same as :c:func:`uv_print_all_handles` except only active handles 467 are printed. 468 469 .. warning:: 470 This function is meant for ad hoc debugging, there is no API/ABI 471 stability guarantees. 472 473 .. versionadded:: 1.8.0 474 475.. c:function:: int uv_os_getenv(const char* name, char* buffer, size_t* size) 476 477 Retrieves the environment variable specified by `name`, copies its value 478 into `buffer`, and sets `size` to the string length of the value. When 479 calling this function, `size` must be set to the amount of storage available 480 in `buffer`, including the null terminator. If the environment variable 481 exceeds the storage available in `buffer`, `UV_ENOBUFS` is returned, and 482 `size` is set to the amount of storage required to hold the value. If no 483 matching environment variable exists, `UV_ENOENT` is returned. 484 485 .. warning:: 486 This function is not thread safe. 487 488 .. versionadded:: 1.12.0 489 490.. c:function:: int uv_os_setenv(const char* name, const char* value) 491 492 Creates or updates the environment variable specified by `name` with 493 `value`. 494 495 .. warning:: 496 This function is not thread safe. 497 498 .. versionadded:: 1.12.0 499 500.. c:function:: int uv_os_unsetenv(const char* name) 501 502 Deletes the environment variable specified by `name`. If no such environment 503 variable exists, this function returns successfully. 504 505 .. warning:: 506 This function is not thread safe. 507 508 .. versionadded:: 1.12.0 509 510.. c:function:: int uv_os_gethostname(char* buffer, size_t* size) 511 512 Returns the hostname as a null-terminated string in `buffer`, and sets 513 `size` to the string length of the hostname. When calling this function, 514 `size` must be set to the amount of storage available in `buffer`, including 515 the null terminator. If the hostname exceeds the storage available in 516 `buffer`, `UV_ENOBUFS` is returned, and `size` is set to the amount of 517 storage required to hold the value. 518 519 .. versionadded:: 1.12.0 520