1 /* Copyright Joyent, Inc. and other Node contributors. All rights reserved. 2 * 3 * Permission is hereby granted, free of charge, to any person obtaining a copy 4 * of this software and associated documentation files (the "Software"), to 5 * deal in the Software without restriction, including without limitation the 6 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 7 * sell copies of the Software, and to permit persons to whom the Software is 8 * furnished to do so, subject to the following conditions: 9 * 10 * The above copyright notice and this permission notice shall be included in 11 * all copies or substantial portions of the Software. 12 * 13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 18 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 19 * IN THE SOFTWARE. 20 */ 21 22 /* See http://nikhilm.github.com/uvbook/ for an introduction. */ 23 24 #ifndef UV_H 25 #define UV_H 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #ifdef _WIN32 31 /* Windows - set up dll import/export decorators. */ 32 # if defined(BUILDING_UV_SHARED) 33 /* Building shared library. */ 34 # define UV_EXTERN __declspec(dllexport) 35 # elif defined(USING_UV_SHARED) 36 /* Using shared library. */ 37 # define UV_EXTERN __declspec(dllimport) 38 # else 39 /* Building static library. */ 40 # define UV_EXTERN /* nothing */ 41 # endif 42 #elif __GNUC__ >= 4 43 # define UV_EXTERN __attribute__((visibility("default"))) 44 #else 45 # define UV_EXTERN /* nothing */ 46 #endif 47 48 #include "uv-errno.h" 49 #include <stddef.h> 50 51 #if defined(_MSC_VER) && _MSC_VER < 1600 52 # include "stdint-msvc2008.h" 53 #else 54 # include <stdint.h> 55 #endif 56 57 #if defined(_WIN32) 58 # include "uv-win.h" 59 #else 60 # include "uv-unix.h" 61 #endif 62 63 /* Expand this list if necessary. */ 64 #define UV_ERRNO_MAP(XX) \ 65 XX(E2BIG, "argument list too long") \ 66 XX(EACCES, "permission denied") \ 67 XX(EADDRINUSE, "address already in use") \ 68 XX(EADDRNOTAVAIL, "address not available") \ 69 XX(EAFNOSUPPORT, "address family not supported") \ 70 XX(EAGAIN, "resource temporarily unavailable") \ 71 XX(EAI_ADDRFAMILY, "address family not supported") \ 72 XX(EAI_AGAIN, "temporary failure") \ 73 XX(EAI_BADFLAGS, "bad ai_flags value") \ 74 XX(EAI_BADHINTS, "invalid value for hints") \ 75 XX(EAI_CANCELED, "request canceled") \ 76 XX(EAI_FAIL, "permanent failure") \ 77 XX(EAI_FAMILY, "ai_family not supported") \ 78 XX(EAI_MEMORY, "out of memory") \ 79 XX(EAI_NODATA, "no address") \ 80 XX(EAI_NONAME, "unknown node or service") \ 81 XX(EAI_OVERFLOW, "argument buffer overflow") \ 82 XX(EAI_PROTOCOL, "resolved protocol is unknown") \ 83 XX(EAI_SERVICE, "service not available for socket type") \ 84 XX(EAI_SOCKTYPE, "socket type not supported") \ 85 XX(EAI_SYSTEM, "system error") \ 86 XX(EALREADY, "connection already in progress") \ 87 XX(EBADF, "bad file descriptor") \ 88 XX(EBUSY, "resource busy or locked") \ 89 XX(ECANCELED, "operation canceled") \ 90 XX(ECHARSET, "invalid Unicode character") \ 91 XX(ECONNABORTED, "software caused connection abort") \ 92 XX(ECONNREFUSED, "connection refused") \ 93 XX(ECONNRESET, "connection reset by peer") \ 94 XX(EDESTADDRREQ, "destination address required") \ 95 XX(EEXIST, "file already exists") \ 96 XX(EFAULT, "bad address in system call argument") \ 97 XX(EHOSTUNREACH, "host is unreachable") \ 98 XX(EINTR, "interrupted system call") \ 99 XX(EINVAL, "invalid argument") \ 100 XX(EIO, "i/o error") \ 101 XX(EISCONN, "socket is already connected") \ 102 XX(EISDIR, "illegal operation on a directory") \ 103 XX(ELOOP, "too many symbolic links encountered") \ 104 XX(EMFILE, "too many open files") \ 105 XX(EMSGSIZE, "message too long") \ 106 XX(ENAMETOOLONG, "name too long") \ 107 XX(ENETDOWN, "network is down") \ 108 XX(ENETUNREACH, "network is unreachable") \ 109 XX(ENFILE, "file table overflow") \ 110 XX(ENOBUFS, "no buffer space available") \ 111 XX(ENODEV, "no such device") \ 112 XX(ENOENT, "no such file or directory") \ 113 XX(ENOMEM, "not enough memory") \ 114 XX(ENONET, "machine is not on the network") \ 115 XX(ENOSPC, "no space left on device") \ 116 XX(ENOSYS, "function not implemented") \ 117 XX(ENOTCONN, "socket is not connected") \ 118 XX(ENOTDIR, "not a directory") \ 119 XX(ENOTEMPTY, "directory not empty") \ 120 XX(ENOTSOCK, "socket operation on non-socket") \ 121 XX(ENOTSUP, "operation not supported on socket") \ 122 XX(EPERM, "operation not permitted") \ 123 XX(EPIPE, "broken pipe") \ 124 XX(EPROTO, "protocol error") \ 125 XX(EPROTONOSUPPORT, "protocol not supported") \ 126 XX(EPROTOTYPE, "protocol wrong type for socket") \ 127 XX(EROFS, "read-only file system") \ 128 XX(ESHUTDOWN, "cannot send after transport endpoint shutdown") \ 129 XX(ESPIPE, "invalid seek") \ 130 XX(ESRCH, "no such process") \ 131 XX(ETIMEDOUT, "connection timed out") \ 132 XX(EXDEV, "cross-device link not permitted") \ 133 XX(UNKNOWN, "unknown error") \ 134 XX(EOF, "end of file") \ 135 136 #define UV_HANDLE_TYPE_MAP(XX) \ 137 XX(ASYNC, async) \ 138 XX(CHECK, check) \ 139 XX(FS_EVENT, fs_event) \ 140 XX(FS_POLL, fs_poll) \ 141 XX(HANDLE, handle) \ 142 XX(IDLE, idle) \ 143 XX(NAMED_PIPE, pipe) \ 144 XX(POLL, poll) \ 145 XX(PREPARE, prepare) \ 146 XX(PROCESS, process) \ 147 XX(STREAM, stream) \ 148 XX(TCP, tcp) \ 149 XX(TIMER, timer) \ 150 XX(TTY, tty) \ 151 XX(UDP, udp) \ 152 XX(SIGNAL, signal) \ 153 XX(IOCP, iocp) \ 154 155 #define UV_REQ_TYPE_MAP(XX) \ 156 XX(REQ, req) \ 157 XX(CONNECT, connect) \ 158 XX(WRITE, write) \ 159 XX(SHUTDOWN, shutdown) \ 160 XX(UDP_SEND, udp_send) \ 161 XX(FS, fs) \ 162 XX(WORK, work) \ 163 XX(GETADDRINFO, getaddrinfo) \ 164 165 typedef enum { 166 #define XX(code, _) UV_ ## code = UV__ ## code, 167 UV_ERRNO_MAP(XX) 168 #undef XX 169 UV_ERRNO_MAX = UV__EOF - 1 170 } uv_errno_t; 171 172 typedef enum { 173 UV_UNKNOWN_HANDLE = 0, 174 #define XX(uc, lc) UV_##uc, 175 UV_HANDLE_TYPE_MAP(XX) 176 #undef XX 177 UV_FILE, 178 UV_HANDLE_TYPE_MAX 179 } uv_handle_type; 180 181 typedef enum { 182 UV_UNKNOWN_REQ = 0, 183 #define XX(uc, lc) UV_##uc, 184 UV_REQ_TYPE_MAP(XX) 185 #undef XX 186 UV_REQ_TYPE_PRIVATE 187 UV_REQ_TYPE_MAX 188 } uv_req_type; 189 190 191 /* Handle types. */ 192 typedef struct uv_loop_s uv_loop_t; 193 typedef struct uv_handle_s uv_handle_t; 194 typedef struct uv_stream_s uv_stream_t; 195 typedef struct uv_tcp_s uv_tcp_t; 196 typedef struct uv_udp_s uv_udp_t; 197 typedef struct uv_pipe_s uv_pipe_t; 198 typedef struct uv_tty_s uv_tty_t; 199 typedef struct uv_poll_s uv_poll_t; 200 typedef struct uv_iocp_s uv_iocp_t; 201 typedef struct uv_timer_s uv_timer_t; 202 typedef struct uv_prepare_s uv_prepare_t; 203 typedef struct uv_check_s uv_check_t; 204 typedef struct uv_idle_s uv_idle_t; 205 typedef struct uv_async_s uv_async_t; 206 typedef struct uv_process_s uv_process_t; 207 typedef struct uv_fs_event_s uv_fs_event_t; 208 typedef struct uv_fs_poll_s uv_fs_poll_t; 209 typedef struct uv_signal_s uv_signal_t; 210 211 /* Request types. */ 212 typedef struct uv_req_s uv_req_t; 213 typedef struct uv_getaddrinfo_s uv_getaddrinfo_t; 214 typedef struct uv_shutdown_s uv_shutdown_t; 215 typedef struct uv_write_s uv_write_t; 216 typedef struct uv_connect_s uv_connect_t; 217 typedef struct uv_udp_send_s uv_udp_send_t; 218 typedef struct uv_fs_s uv_fs_t; 219 typedef struct uv_work_s uv_work_t; 220 221 /* None of the above. */ 222 typedef struct uv_cpu_info_s uv_cpu_info_t; 223 typedef struct uv_interface_address_s uv_interface_address_t; 224 225 226 typedef enum { 227 UV_RUN_DEFAULT = 0, 228 UV_RUN_ONCE, 229 UV_RUN_NOWAIT 230 } uv_run_mode; 231 232 233 /* 234 * Returns the libuv version packed into a single integer. 8 bits are used for 235 * each component, with the patch number stored in the 8 least significant 236 * bits. E.g. for libuv 1.2.3 this would return 0x010203. 237 */ 238 UV_EXTERN unsigned int uv_version(void); 239 240 /* 241 * Returns the libuv version number as a string. For non-release versions 242 * "-pre" is appended, so the version number could be "1.2.3-pre". 243 */ 244 UV_EXTERN const char* uv_version_string(void); 245 246 247 /* 248 * This function must be called before any other functions in libuv. 249 * 250 * All functions besides uv_run() are non-blocking. 251 * 252 * All callbacks in libuv are made asynchronously. That is they are never 253 * made by the function that takes them as a parameter. 254 */ 255 UV_EXTERN uv_loop_t* uv_loop_new(void); 256 UV_EXTERN void uv_loop_delete(uv_loop_t*); 257 258 /* 259 * Returns the default loop. 260 */ 261 UV_EXTERN uv_loop_t* uv_default_loop(void); 262 263 /* 264 * This function runs the event loop. It will act differently depending on the 265 * specified mode: 266 * - UV_RUN_DEFAULT: Runs the event loop until the reference count drops to 267 * zero. Always returns zero. 268 * - UV_RUN_ONCE: Poll for new events once. Note that this function blocks if 269 * there are no pending events. Returns zero when done (no active handles 270 * or requests left), or non-zero if more events are expected (meaning you 271 * should run the event loop again sometime in the future). 272 * - UV_RUN_NOWAIT: Poll for new events once but don't block if there are no 273 * pending events. 274 */ 275 UV_EXTERN int uv_run(uv_loop_t*, uv_run_mode mode); 276 277 /* 278 * This function checks whether the reference count, the number of active 279 * handles or requests left in the event loop, is non-zero. 280 */ 281 UV_EXTERN int uv_loop_alive(const uv_loop_t* loop); 282 283 /* 284 * This function will stop the event loop by forcing uv_run to end 285 * as soon as possible, but not sooner than the next loop iteration. 286 * If this function was called before blocking for i/o, the loop won't 287 * block for i/o on this iteration. 288 */ 289 UV_EXTERN void uv_stop(uv_loop_t*); 290 291 /* 292 * Manually modify the event loop's reference count. Useful if the user wants 293 * to have a handle or timeout that doesn't keep the loop alive. 294 */ 295 UV_EXTERN void uv_ref(uv_handle_t*); 296 UV_EXTERN void uv_unref(uv_handle_t*); 297 UV_EXTERN int uv_has_ref(const uv_handle_t*); 298 299 /* 300 * Update the event loop's concept of "now". Libuv caches the current time 301 * at the start of the event loop tick in order to reduce the number of 302 * time-related system calls. 303 * 304 * You won't normally need to call this function unless you have callbacks 305 * that block the event loop for longer periods of time, where "longer" is 306 * somewhat subjective but probably on the order of a millisecond or more. 307 */ 308 UV_EXTERN void uv_update_time(uv_loop_t*); 309 310 /* 311 * Return the current timestamp in milliseconds. The timestamp is cached at 312 * the start of the event loop tick, see |uv_update_time()| for details and 313 * rationale. 314 * 315 * The timestamp increases monotonically from some arbitrary point in time. 316 * Don't make assumptions about the starting point, you will only get 317 * disappointed. 318 * 319 * Use uv_hrtime() if you need sub-millisecond granularity. 320 */ 321 UV_EXTERN uint64_t uv_now(uv_loop_t*); 322 323 /* 324 * Get backend file descriptor. Only kqueue, epoll and event ports are 325 * supported. 326 * 327 * This can be used in conjunction with `uv_run(loop, UV_RUN_NOWAIT)` to 328 * poll in one thread and run the event loop's event callbacks in another. 329 * 330 * Useful for embedding libuv's event loop in another event loop. 331 * See test/test-embed.c for an example. 332 * 333 * Note that embedding a kqueue fd in another kqueue pollset doesn't work on 334 * all platforms. It's not an error to add the fd but it never generates 335 * events. 336 */ 337 UV_EXTERN int uv_backend_fd(const uv_loop_t*); 338 339 /* 340 * Get the poll timeout. The return value is in milliseconds, or -1 for no 341 * timeout. 342 */ 343 UV_EXTERN int uv_backend_timeout(const uv_loop_t*); 344 345 346 /* 347 * Should prepare a buffer that libuv can use to read data into. 348 * 349 * `suggested_size` is a hint. Returning a buffer that is smaller is perfectly 350 * okay as long as `buf.len > 0`. 351 * 352 * If you return a buffer with `buf.len == 0`, libuv skips the read and calls 353 * your read or recv callback with nread=UV_ENOBUFS. 354 * 355 * Note that returning a zero-length buffer does not stop the handle, call 356 * uv_read_stop() or uv_udp_recv_stop() for that. 357 */ 358 typedef void (*uv_alloc_cb)(uv_handle_t* handle, 359 size_t suggested_size, 360 uv_buf_t* buf); 361 362 /* 363 * `nread` is > 0 if there is data available, 0 if libuv is done reading for 364 * now, or < 0 on error. 365 * 366 * The callee is responsible for closing the stream when an error happens. 367 * Trying to read from the stream again is undefined. 368 * 369 * The callee is responsible for freeing the buffer, libuv does not reuse it. 370 * The buffer may be a null buffer (where buf->base=NULL and buf->len=0) on 371 * EOF or error. 372 */ 373 typedef void (*uv_read_cb)(uv_stream_t* stream, 374 ssize_t nread, 375 const uv_buf_t* buf); 376 377 /* 378 * Just like the uv_read_cb except that if the pending parameter is true 379 * then you can use uv_accept() to pull the new handle into the process. 380 * If no handle is pending then pending will be UV_UNKNOWN_HANDLE. 381 */ 382 typedef void (*uv_read2_cb)(uv_pipe_t* pipe, 383 ssize_t nread, 384 const uv_buf_t* buf, 385 uv_handle_type pending); 386 387 typedef void (*uv_write_cb)(uv_write_t* req, int status); 388 typedef void (*uv_connect_cb)(uv_connect_t* req, int status); 389 typedef void (*uv_shutdown_cb)(uv_shutdown_t* req, int status); 390 typedef void (*uv_connection_cb)(uv_stream_t* server, int status); 391 typedef void (*uv_close_cb)(uv_handle_t* handle); 392 typedef void (*uv_iocp_cb)(uv_iocp_t* handle); 393 typedef void (*uv_poll_cb)(uv_poll_t* handle, int status, int events); 394 typedef void (*uv_timer_cb)(uv_timer_t* handle, int status); 395 /* TODO: do these really need a status argument? */ 396 typedef void (*uv_async_cb)(uv_async_t* handle, int status); 397 typedef void (*uv_prepare_cb)(uv_prepare_t* handle, int status); 398 typedef void (*uv_check_cb)(uv_check_t* handle, int status); 399 typedef void (*uv_idle_cb)(uv_idle_t* handle, int status); 400 typedef void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal); 401 typedef void (*uv_walk_cb)(uv_handle_t* handle, void* arg); 402 typedef void (*uv_fs_cb)(uv_fs_t* req); 403 typedef void (*uv_work_cb)(uv_work_t* req); 404 typedef void (*uv_after_work_cb)(uv_work_t* req, int status); 405 typedef void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t* req, 406 int status, 407 struct addrinfo* res); 408 409 typedef struct { 410 long tv_sec; 411 long tv_nsec; 412 } uv_timespec_t; 413 414 415 typedef struct { 416 uint64_t st_dev; 417 uint64_t st_mode; 418 uint64_t st_nlink; 419 uint64_t st_uid; 420 uint64_t st_gid; 421 uint64_t st_rdev; 422 uint64_t st_ino; 423 uint64_t st_size; 424 uint64_t st_blksize; 425 uint64_t st_blocks; 426 uint64_t st_flags; 427 uint64_t st_gen; 428 uv_timespec_t st_atim; 429 uv_timespec_t st_mtim; 430 uv_timespec_t st_ctim; 431 uv_timespec_t st_birthtim; 432 } uv_stat_t; 433 434 435 /* 436 * This will be called repeatedly after the uv_fs_event_t is initialized. 437 * If uv_fs_event_t was initialized with a directory the filename parameter 438 * will be a relative path to a file contained in the directory. 439 * The events parameter is an ORed mask of enum uv_fs_event elements. 440 */ 441 typedef void (*uv_fs_event_cb)(uv_fs_event_t* handle, const char* filename, 442 int events, int status); 443 444 typedef void (*uv_fs_poll_cb)(uv_fs_poll_t* handle, 445 int status, 446 const uv_stat_t* prev, 447 const uv_stat_t* curr); 448 449 typedef void (*uv_signal_cb)(uv_signal_t* handle, int signum); 450 451 452 typedef enum { 453 UV_LEAVE_GROUP = 0, 454 UV_JOIN_GROUP 455 } uv_membership; 456 457 458 /* 459 * Most functions return 0 on success or an error code < 0 on failure. 460 */ 461 UV_EXTERN const char* uv_strerror(int err); 462 UV_EXTERN const char* uv_err_name(int err); 463 464 465 #define UV_REQ_FIELDS \ 466 /* public */ \ 467 void* data; \ 468 /* read-only */ \ 469 uv_req_type type; \ 470 /* private */ \ 471 void* active_queue[2]; \ 472 UV_REQ_PRIVATE_FIELDS \ 473 474 /* Abstract base class of all requests. */ 475 struct uv_req_s { 476 UV_REQ_FIELDS 477 }; 478 479 480 /* Platform-specific request types */ 481 UV_PRIVATE_REQ_TYPES 482 483 484 /* 485 * uv_shutdown_t is a subclass of uv_req_t 486 * 487 * Shutdown the outgoing (write) side of a duplex stream. It waits for 488 * pending write requests to complete. The handle should refer to a 489 * initialized stream. req should be an uninitialized shutdown request 490 * struct. The cb is called after shutdown is complete. 491 */ 492 UV_EXTERN int uv_shutdown(uv_shutdown_t* req, uv_stream_t* handle, 493 uv_shutdown_cb cb); 494 495 struct uv_shutdown_s { 496 UV_REQ_FIELDS 497 uv_stream_t* handle; 498 uv_shutdown_cb cb; 499 UV_SHUTDOWN_PRIVATE_FIELDS 500 }; 501 502 503 #define UV_HANDLE_FIELDS \ 504 /* public */ \ 505 uv_close_cb close_cb; \ 506 void* data; \ 507 /* read-only */ \ 508 uv_loop_t* loop; \ 509 uv_handle_type type; \ 510 /* private */ \ 511 void* handle_queue[2]; \ 512 UV_HANDLE_PRIVATE_FIELDS \ 513 514 /* The abstract base class of all handles. */ 515 struct uv_handle_s { 516 UV_HANDLE_FIELDS 517 }; 518 519 /* 520 * Returns size of various handle types, useful for FFI 521 * bindings to allocate correct memory without copying struct 522 * definitions 523 */ 524 UV_EXTERN size_t uv_handle_size(uv_handle_type type); 525 526 /* 527 * Returns size of request types, useful for dynamic lookup with FFI 528 */ 529 UV_EXTERN size_t uv_req_size(uv_req_type type); 530 531 /* 532 * Returns non-zero if the handle is active, zero if it's inactive. 533 * 534 * What "active" means depends on the type of handle: 535 * 536 * - A uv_async_t handle is always active and cannot be deactivated, except 537 * by closing it with uv_close(). 538 * 539 * - A uv_pipe_t, uv_tcp_t, uv_udp_t, etc. handle - basically any handle that 540 * deals with I/O - is active when it is doing something that involves I/O, 541 * like reading, writing, connecting, accepting new connections, etc. 542 * 543 * - A uv_check_t, uv_idle_t, uv_timer_t, etc. handle is active when it has 544 * been started with a call to uv_check_start(), uv_idle_start(), etc. 545 * 546 * Rule of thumb: if a handle of type uv_foo_t has a uv_foo_start() 547 * function, then it's active from the moment that function is called. 548 * Likewise, uv_foo_stop() deactivates the handle again. 549 * 550 */ 551 UV_EXTERN int uv_is_active(const uv_handle_t* handle); 552 553 /* 554 * Walk the list of open handles. 555 */ 556 UV_EXTERN void uv_walk(uv_loop_t* loop, uv_walk_cb walk_cb, void* arg); 557 558 559 /* 560 * Request handle to be closed. close_cb will be called asynchronously after 561 * this call. This MUST be called on each handle before memory is released. 562 * 563 * Note that handles that wrap file descriptors are closed immediately but 564 * close_cb will still be deferred to the next iteration of the event loop. 565 * It gives you a chance to free up any resources associated with the handle. 566 * 567 * In-progress requests, like uv_connect_t or uv_write_t, are cancelled and 568 * have their callbacks called asynchronously with status=UV_ECANCELED. 569 */ 570 UV_EXTERN void uv_close(uv_handle_t* handle, uv_close_cb close_cb); 571 572 573 /* 574 * Constructor for uv_buf_t. 575 * Due to platform differences the user cannot rely on the ordering of the 576 * base and len members of the uv_buf_t struct. The user is responsible for 577 * freeing base after the uv_buf_t is done. Return struct passed by value. 578 */ 579 UV_EXTERN uv_buf_t uv_buf_init(char* base, unsigned int len); 580 581 582 #define UV_STREAM_FIELDS \ 583 /* number of bytes queued for writing */ \ 584 size_t write_queue_size; \ 585 uv_alloc_cb alloc_cb; \ 586 uv_read_cb read_cb; \ 587 uv_read2_cb read2_cb; \ 588 /* private */ \ 589 UV_STREAM_PRIVATE_FIELDS 590 591 /* 592 * uv_stream_t is a subclass of uv_handle_t 593 * 594 * uv_stream is an abstract class. 595 * 596 * uv_stream_t is the parent class of uv_tcp_t, uv_pipe_t, uv_tty_t, and 597 * soon uv_file_t. 598 */ 599 struct uv_stream_s { 600 UV_HANDLE_FIELDS 601 UV_STREAM_FIELDS 602 }; 603 604 UV_EXTERN int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb); 605 606 /* 607 * This call is used in conjunction with uv_listen() to accept incoming 608 * connections. Call uv_accept after receiving a uv_connection_cb to accept 609 * the connection. Before calling uv_accept use uv_*_init() must be 610 * called on the client. Non-zero return value indicates an error. 611 * 612 * When the uv_connection_cb is called it is guaranteed that uv_accept will 613 * complete successfully the first time. If you attempt to use it more than 614 * once, it may fail. It is suggested to only call uv_accept once per 615 * uv_connection_cb call. 616 */ 617 UV_EXTERN int uv_accept(uv_stream_t* server, uv_stream_t* client); 618 619 /* 620 * Read data from an incoming stream. The callback will be made several 621 * times until there is no more data to read or uv_read_stop is called. 622 * When we've reached EOF nread will be set to UV_EOF. 623 * 624 * When nread < 0, the buf parameter might not point to a valid buffer; 625 * in that case buf.len and buf.base are both set to 0. 626 * 627 * Note that nread might also be 0, which does *not* indicate an error or 628 * eof; it happens when libuv requested a buffer through the alloc callback 629 * but then decided that it didn't need that buffer. 630 */ 631 UV_EXTERN int uv_read_start(uv_stream_t*, uv_alloc_cb alloc_cb, 632 uv_read_cb read_cb); 633 634 UV_EXTERN int uv_read_stop(uv_stream_t*); 635 636 /* 637 * Extended read methods for receiving handles over a pipe. The pipe must be 638 * initialized with ipc == 1. 639 */ 640 UV_EXTERN int uv_read2_start(uv_stream_t*, uv_alloc_cb alloc_cb, 641 uv_read2_cb read_cb); 642 643 644 /* 645 * Write data to stream. Buffers are written in order. Example: 646 * 647 * uv_buf_t a[] = { 648 * { .base = "1", .len = 1 }, 649 * { .base = "2", .len = 1 } 650 * }; 651 * 652 * uv_buf_t b[] = { 653 * { .base = "3", .len = 1 }, 654 * { .base = "4", .len = 1 } 655 * }; 656 * 657 * uv_write_t req1; 658 * uv_write_t req2; 659 * 660 * // writes "1234" 661 * uv_write(&req1, stream, a, 2); 662 * uv_write(&req2, stream, b, 2); 663 * 664 */ 665 UV_EXTERN int uv_write(uv_write_t* req, 666 uv_stream_t* handle, 667 const uv_buf_t bufs[], 668 unsigned int nbufs, 669 uv_write_cb cb); 670 671 /* 672 * Extended write function for sending handles over a pipe. The pipe must be 673 * initialized with ipc == 1. 674 * send_handle must be a TCP socket or pipe, which is a server or a connection 675 * (listening or connected state). Bound sockets or pipes will be assumed to 676 * be servers. 677 */ 678 UV_EXTERN int uv_write2(uv_write_t* req, 679 uv_stream_t* handle, 680 const uv_buf_t bufs[], 681 unsigned int nbufs, 682 uv_stream_t* send_handle, 683 uv_write_cb cb); 684 685 /* 686 * Same as `uv_write()`, but won't queue write request if it can't be completed 687 * immediately. 688 * Will return either: 689 * - positive number of bytes written 690 * - zero - if queued write is needed 691 * - negative error code 692 */ 693 UV_EXTERN int uv_try_write(uv_stream_t* handle, 694 const uv_buf_t bufs[], 695 unsigned int nbufs); 696 697 /* uv_write_t is a subclass of uv_req_t */ 698 struct uv_write_s { 699 UV_REQ_FIELDS 700 uv_write_cb cb; 701 uv_stream_t* send_handle; 702 uv_stream_t* handle; 703 UV_WRITE_PRIVATE_FIELDS 704 }; 705 706 707 /* 708 * Used to determine whether a stream is readable or writable. 709 */ 710 UV_EXTERN int uv_is_readable(const uv_stream_t* handle); 711 UV_EXTERN int uv_is_writable(const uv_stream_t* handle); 712 713 714 /* 715 * Enable or disable blocking mode for a stream. 716 * 717 * When blocking mode is enabled all writes complete synchronously. The 718 * interface remains unchanged otherwise, e.g. completion or failure of the 719 * operation will still be reported through a callback which is made 720 * asychronously. 721 * 722 * Relying too much on this API is not recommended. It is likely to change 723 * significantly in the future. 724 * 725 * On windows this currently works only for uv_pipe_t instances. On unix it 726 * works for tcp, pipe and tty instances. Be aware that changing the blocking 727 * mode on unix sets or clears the O_NONBLOCK bit. If you are sharing a handle 728 * with another process, the other process is affected by the change too, 729 * which can lead to unexpected results. 730 * 731 * Also libuv currently makes no ordering guarantee when the blocking mode 732 * is changed after write requests have already been submitted. Therefore it is 733 * recommended to set the blocking mode immediately after opening or creating 734 * the stream. 735 */ 736 UV_EXTERN int uv_stream_set_blocking(uv_stream_t* handle, int blocking); 737 738 739 /* 740 * Used to determine whether a stream is closing or closed. 741 * 742 * N.B. is only valid between the initialization of the handle 743 * and the arrival of the close callback, and cannot be used 744 * to validate the handle. 745 */ 746 UV_EXTERN int uv_is_closing(const uv_handle_t* handle); 747 748 749 /* 750 * uv_tcp_t is a subclass of uv_stream_t 751 * 752 * Represents a TCP stream or TCP server. 753 */ 754 struct uv_tcp_s { 755 UV_HANDLE_FIELDS 756 UV_STREAM_FIELDS 757 UV_TCP_PRIVATE_FIELDS 758 }; 759 760 UV_EXTERN int uv_tcp_init(uv_loop_t*, uv_tcp_t* handle); 761 762 /* 763 * Opens an existing file descriptor or SOCKET as a tcp handle. 764 */ 765 UV_EXTERN int uv_tcp_open(uv_tcp_t* handle, uv_os_sock_t sock); 766 767 /* Enable/disable Nagle's algorithm. */ 768 UV_EXTERN int uv_tcp_nodelay(uv_tcp_t* handle, int enable); 769 770 /* 771 * Enable/disable TCP keep-alive. 772 * 773 * `delay` is the initial delay in seconds, ignored when `enable` is zero. 774 */ 775 UV_EXTERN int uv_tcp_keepalive(uv_tcp_t* handle, 776 int enable, 777 unsigned int delay); 778 779 /* 780 * Enable/disable simultaneous asynchronous accept requests that are 781 * queued by the operating system when listening for new tcp connections. 782 * This setting is used to tune a tcp server for the desired performance. 783 * Having simultaneous accepts can significantly improve the rate of 784 * accepting connections (which is why it is enabled by default) but 785 * may lead to uneven load distribution in multi-process setups. 786 */ 787 UV_EXTERN int uv_tcp_simultaneous_accepts(uv_tcp_t* handle, int enable); 788 789 enum uv_tcp_flags { 790 /* Used with uv_tcp_bind, when an IPv6 address is used */ 791 UV_TCP_IPV6ONLY = 1 792 }; 793 794 /* 795 * Bind the handle to an address and port. `addr` should point to an 796 * initialized struct sockaddr_in or struct sockaddr_in6. 797 * 798 * When the port is already taken, you can expect to see an UV_EADDRINUSE 799 * error from either uv_tcp_bind(), uv_listen() or uv_tcp_connect(). 800 * 801 * That is, a successful call to uv_tcp_bind() does not guarantee that 802 * the call to uv_listen() or uv_tcp_connect() will succeed as well. 803 */ 804 UV_EXTERN int uv_tcp_bind(uv_tcp_t* handle, 805 const struct sockaddr* addr, 806 unsigned int flags); 807 UV_EXTERN int uv_tcp_getsockname(uv_tcp_t* handle, struct sockaddr* name, 808 int* namelen); 809 UV_EXTERN int uv_tcp_getpeername(uv_tcp_t* handle, struct sockaddr* name, 810 int* namelen); 811 812 /* 813 * Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle 814 * and an uninitialized uv_connect_t*. `addr` should point to an initialized 815 * struct sockaddr_in or struct sockaddr_in6. 816 * 817 * The callback is made when the connection has been established or when a 818 * connection error happened. 819 */ 820 UV_EXTERN int uv_tcp_connect(uv_connect_t* req, 821 uv_tcp_t* handle, 822 const struct sockaddr* addr, 823 uv_connect_cb cb); 824 825 /* uv_connect_t is a subclass of uv_req_t */ 826 struct uv_connect_s { 827 UV_REQ_FIELDS 828 uv_connect_cb cb; 829 uv_stream_t* handle; 830 UV_CONNECT_PRIVATE_FIELDS 831 }; 832 833 834 /* 835 * UDP support. 836 */ 837 838 enum uv_udp_flags { 839 /* Disables dual stack mode. */ 840 UV_UDP_IPV6ONLY = 1, 841 /* 842 * Indicates message was truncated because read buffer was too small. The 843 * remainder was discarded by the OS. Used in uv_udp_recv_cb. 844 */ 845 UV_UDP_PARTIAL = 2 846 }; 847 848 /* 849 * Called after a uv_udp_send() or uv_udp_send6(). status 0 indicates 850 * success otherwise error. 851 */ 852 typedef void (*uv_udp_send_cb)(uv_udp_send_t* req, int status); 853 854 /* 855 * Callback that is invoked when a new UDP datagram is received. 856 * 857 * handle UDP handle. 858 * nread Number of bytes that have been received. 859 * 0 if there is no more data to read. You may 860 * discard or repurpose the read buffer. 861 * < 0 if a transmission error was detected. 862 * buf uv_buf_t with the received data. 863 * addr struct sockaddr_in or struct sockaddr_in6. 864 * Valid for the duration of the callback only. 865 * flags One or more OR'ed UV_UDP_* constants. 866 * Right now only UV_UDP_PARTIAL is used. 867 */ 868 typedef void (*uv_udp_recv_cb)(uv_udp_t* handle, 869 ssize_t nread, 870 const uv_buf_t* buf, 871 const struct sockaddr* addr, 872 unsigned flags); 873 874 /* uv_udp_t is a subclass of uv_handle_t */ 875 struct uv_udp_s { 876 UV_HANDLE_FIELDS 877 UV_UDP_PRIVATE_FIELDS 878 }; 879 880 /* uv_udp_send_t is a subclass of uv_req_t */ 881 struct uv_udp_send_s { 882 UV_REQ_FIELDS 883 uv_udp_t* handle; 884 uv_udp_send_cb cb; 885 UV_UDP_SEND_PRIVATE_FIELDS 886 }; 887 888 /* 889 * Initialize a new UDP handle. The actual socket is created lazily. 890 * Returns 0 on success. 891 */ 892 UV_EXTERN int uv_udp_init(uv_loop_t*, uv_udp_t* handle); 893 894 /* 895 * Opens an existing file descriptor or SOCKET as a udp handle. 896 * 897 * Unix only: 898 * The only requirement of the sock argument is that it follows the 899 * datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(), 900 * etc.). In other words, other datagram-type sockets like raw sockets or 901 * netlink sockets can also be passed to this function. 902 * 903 * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other 904 * UNIX platforms, it sets the SO_REUSEADDR flag. What that means is that 905 * multiple threads or processes can bind to the same address without error 906 * (provided they all set the flag) but only the last one to bind will receive 907 * any traffic, in effect "stealing" the port from the previous listener. 908 * This behavior is something of an anomaly and may be replaced by an explicit 909 * opt-in mechanism in future versions of libuv. 910 */ 911 UV_EXTERN int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock); 912 913 /* 914 * Bind to a IPv4 address and port. 915 * 916 * Arguments: 917 * handle UDP handle. Should have been initialized with `uv_udp_init`. 918 * addr struct sockaddr_in or struct sockaddr_in6 with the address and 919 * port to bind to. 920 * flags Unused. 921 * 922 * Returns: 923 * 0 on success, or an error code < 0 on failure. 924 * 925 * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other 926 * UNIX platforms, it sets the SO_REUSEADDR flag. What that means is that 927 * multiple threads or processes can bind to the same address without error 928 * (provided they all set the flag) but only the last one to bind will receive 929 * any traffic, in effect "stealing" the port from the previous listener. 930 * This behavior is something of an anomaly and may be replaced by an explicit 931 * opt-in mechanism in future versions of libuv. 932 */ 933 UV_EXTERN int uv_udp_bind(uv_udp_t* handle, 934 const struct sockaddr* addr, 935 unsigned int flags); 936 937 UV_EXTERN int uv_udp_getsockname(uv_udp_t* handle, struct sockaddr* name, 938 int* namelen); 939 940 /* 941 * Set membership for a multicast address 942 * 943 * Arguments: 944 * handle UDP handle. Should have been initialized with 945 * `uv_udp_init`. 946 * multicast_addr multicast address to set membership for 947 * interface_addr interface address 948 * membership Should be UV_JOIN_GROUP or UV_LEAVE_GROUP 949 * 950 * Returns: 951 * 0 on success, or an error code < 0 on failure. 952 */ 953 UV_EXTERN int uv_udp_set_membership(uv_udp_t* handle, 954 const char* multicast_addr, const char* interface_addr, 955 uv_membership membership); 956 957 /* 958 * Set IP multicast loop flag. Makes multicast packets loop back to 959 * local sockets. 960 * 961 * Arguments: 962 * handle UDP handle. Should have been initialized with 963 * `uv_udp_init`. 964 * on 1 for on, 0 for off 965 * 966 * Returns: 967 * 0 on success, or an error code < 0 on failure. 968 */ 969 UV_EXTERN int uv_udp_set_multicast_loop(uv_udp_t* handle, int on); 970 971 /* 972 * Set the multicast ttl 973 * 974 * Arguments: 975 * handle UDP handle. Should have been initialized with 976 * `uv_udp_init`. 977 * ttl 1 through 255 978 * 979 * Returns: 980 * 0 on success, or an error code < 0 on failure. 981 */ 982 UV_EXTERN int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl); 983 984 /* 985 * Set broadcast on or off 986 * 987 * Arguments: 988 * handle UDP handle. Should have been initialized with 989 * `uv_udp_init`. 990 * on 1 for on, 0 for off 991 * 992 * Returns: 993 * 0 on success, or an error code < 0 on failure. 994 */ 995 UV_EXTERN int uv_udp_set_broadcast(uv_udp_t* handle, int on); 996 997 /* 998 * Set the time to live 999 * 1000 * Arguments: 1001 * handle UDP handle. Should have been initialized with 1002 * `uv_udp_init`. 1003 * ttl 1 through 255 1004 * 1005 * Returns: 1006 * 0 on success, or an error code < 0 on failure. 1007 */ 1008 UV_EXTERN int uv_udp_set_ttl(uv_udp_t* handle, int ttl); 1009 1010 /* 1011 * Send data. If the socket has not previously been bound with `uv_udp_bind` 1012 * or `uv_udp_bind6`, it is bound to 0.0.0.0 (the "all interfaces" address) 1013 * and a random port number. 1014 * 1015 * Arguments: 1016 * req UDP request handle. Need not be initialized. 1017 * handle UDP handle. Should have been initialized with `uv_udp_init`. 1018 * bufs List of buffers to send. 1019 * nbufs Number of buffers in `bufs`. 1020 * addr Address of the remote peer. See `uv_ip4_addr`. 1021 * send_cb Callback to invoke when the data has been sent out. 1022 * 1023 * Returns: 1024 * 0 on success, or an error code < 0 on failure. 1025 */ 1026 UV_EXTERN int uv_udp_send(uv_udp_send_t* req, 1027 uv_udp_t* handle, 1028 const uv_buf_t bufs[], 1029 unsigned int nbufs, 1030 const struct sockaddr* addr, 1031 uv_udp_send_cb send_cb); 1032 1033 /* 1034 * Receive data. If the socket has not previously been bound with `uv_udp_bind` 1035 * or `uv_udp_bind6`, it is bound to 0.0.0.0 (the "all interfaces" address) 1036 * and a random port number. 1037 * 1038 * Arguments: 1039 * handle UDP handle. Should have been initialized with `uv_udp_init`. 1040 * alloc_cb Callback to invoke when temporary storage is needed. 1041 * recv_cb Callback to invoke with received data. 1042 * 1043 * Returns: 1044 * 0 on success, or an error code < 0 on failure. 1045 */ 1046 UV_EXTERN int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, 1047 uv_udp_recv_cb recv_cb); 1048 1049 /* 1050 * Stop listening for incoming datagrams. 1051 * 1052 * Arguments: 1053 * handle UDP handle. Should have been initialized with `uv_udp_init`. 1054 * 1055 * Returns: 1056 * 0 on success, or an error code < 0 on failure. 1057 */ 1058 UV_EXTERN int uv_udp_recv_stop(uv_udp_t* handle); 1059 1060 1061 /* 1062 * uv_tty_t is a subclass of uv_stream_t 1063 * 1064 * Representing a stream for the console. 1065 */ 1066 struct uv_tty_s { 1067 UV_HANDLE_FIELDS 1068 UV_STREAM_FIELDS 1069 UV_TTY_PRIVATE_FIELDS 1070 }; 1071 1072 /* 1073 * Initialize a new TTY stream with the given file descriptor. Usually the 1074 * file descriptor will be 1075 * 0 = stdin 1076 * 1 = stdout 1077 * 2 = stderr 1078 * The last argument, readable, specifies if you plan on calling 1079 * uv_read_start with this stream. stdin is readable, stdout is not. 1080 * 1081 * TTY streams which are not readable have blocking writes. 1082 */ 1083 UV_EXTERN int uv_tty_init(uv_loop_t*, uv_tty_t*, uv_file fd, int readable); 1084 1085 /* 1086 * Set mode. 0 for normal, 1 for raw. 1087 */ 1088 UV_EXTERN int uv_tty_set_mode(uv_tty_t*, int mode); 1089 1090 /* 1091 * To be called when the program exits. Resets TTY settings to default 1092 * values for the next process to take over. 1093 * 1094 * This function is async signal-safe on UNIX platforms but can fail with error 1095 * code UV_EBUSY if you call it when execution is inside uv_tty_set_mode(). 1096 */ 1097 UV_EXTERN int uv_tty_reset_mode(void); 1098 1099 /* 1100 * Gets the current Window size. On success zero is returned. 1101 */ 1102 UV_EXTERN int uv_tty_get_winsize(uv_tty_t*, int* width, int* height); 1103 1104 /* 1105 * Used to detect what type of stream should be used with a given file 1106 * descriptor. Usually this will be used during initialization to guess the 1107 * type of the stdio streams. 1108 * For isatty() functionality use this function and test for UV_TTY. 1109 */ 1110 UV_EXTERN uv_handle_type uv_guess_handle(uv_file file); 1111 1112 /* 1113 * uv_pipe_t is a subclass of uv_stream_t 1114 * 1115 * Representing a pipe stream or pipe server. On Windows this is a Named 1116 * Pipe. On Unix this is a UNIX domain socket. 1117 */ 1118 struct uv_pipe_s { 1119 UV_HANDLE_FIELDS 1120 UV_STREAM_FIELDS 1121 int ipc; /* non-zero if this pipe is used for passing handles */ 1122 UV_PIPE_PRIVATE_FIELDS 1123 }; 1124 1125 /* 1126 * Initialize a pipe. The last argument is a boolean to indicate if 1127 * this pipe will be used for handle passing between processes. 1128 */ 1129 UV_EXTERN int uv_pipe_init(uv_loop_t*, uv_pipe_t* handle, int ipc); 1130 1131 /* 1132 * Opens an existing file descriptor or HANDLE as a pipe. 1133 */ 1134 UV_EXTERN int uv_pipe_open(uv_pipe_t*, uv_file file); 1135 1136 /* 1137 * Bind the pipe to a file path (UNIX) or a name (Windows.) 1138 * 1139 * Paths on UNIX get truncated to `sizeof(sockaddr_un.sun_path)` bytes, 1140 * typically between 92 and 108 bytes. 1141 */ 1142 UV_EXTERN int uv_pipe_bind(uv_pipe_t* handle, const char* name); 1143 1144 /* 1145 * Connect to the UNIX domain socket or the named pipe. 1146 * 1147 * Paths on UNIX get truncated to `sizeof(sockaddr_un.sun_path)` bytes, 1148 * typically between 92 and 108 bytes. 1149 */ 1150 UV_EXTERN void uv_pipe_connect(uv_connect_t* req, uv_pipe_t* handle, 1151 const char* name, uv_connect_cb cb); 1152 1153 /* 1154 * This setting applies to Windows only. 1155 * Set the number of pending pipe instance handles when the pipe server 1156 * is waiting for connections. 1157 */ 1158 UV_EXTERN void uv_pipe_pending_instances(uv_pipe_t* handle, int count); 1159 1160 1161 /* 1162 * uv_poll_t is a subclass of uv_handle_t. 1163 * 1164 * The uv_poll watcher is used to watch file descriptors for readability and 1165 * writability, similar to the purpose of poll(2). 1166 * 1167 * The purpose of uv_poll is to enable integrating external libraries that 1168 * rely on the event loop to signal it about the socket status changes, like 1169 * c-ares or libssh2. Using uv_poll_t for any other other purpose is not 1170 * recommended; uv_tcp_t, uv_udp_t, etc. provide an implementation that is 1171 * much faster and more scalable than what can be achieved with uv_poll_t, 1172 * especially on Windows. 1173 * 1174 * It is possible that uv_poll occasionally signals that a file descriptor is 1175 * readable or writable even when it isn't. The user should therefore always 1176 * be prepared to handle EAGAIN or equivalent when it attempts to read from or 1177 * write to the fd. 1178 * 1179 * It is not okay to have multiple active uv_poll watchers for the same socket. 1180 * This can cause libuv to busyloop or otherwise malfunction. 1181 * 1182 * The user should not close a file descriptor while it is being polled by an 1183 * active uv_poll watcher. This can cause the poll watcher to report an error, 1184 * but it might also start polling another socket. However the fd can be safely 1185 * closed immediately after a call to uv_poll_stop() or uv_close(). 1186 * 1187 * On windows only sockets can be polled with uv_poll. On unix any file 1188 * descriptor that would be accepted by poll(2) can be used with uv_poll. 1189 */ 1190 struct uv_poll_s { 1191 UV_HANDLE_FIELDS 1192 uv_poll_cb poll_cb; 1193 UV_POLL_PRIVATE_FIELDS 1194 }; 1195 1196 enum uv_poll_event { 1197 UV_READABLE = 1, 1198 UV_WRITABLE = 2 1199 }; 1200 1201 /* Initialize the poll watcher using a file descriptor. */ 1202 UV_EXTERN int uv_poll_init(uv_loop_t* loop, uv_poll_t* handle, int fd); 1203 1204 /* Initialize the poll watcher using a socket descriptor. On unix this is */ 1205 /* identical to uv_poll_init. On windows it takes a SOCKET handle. */ 1206 UV_EXTERN int uv_poll_init_socket(uv_loop_t* loop, uv_poll_t* handle, 1207 uv_os_sock_t socket); 1208 1209 /* 1210 * Starts polling the file descriptor. `events` is a bitmask consisting made up 1211 * of UV_READABLE and UV_WRITABLE. As soon as an event is detected the callback 1212 * will be called with `status` set to 0, and the detected events set en the 1213 * `events` field. 1214 * 1215 * If an error happens while polling status, `status` < 0 and corresponds 1216 * with one of the UV_E* error codes. The user should not close the socket 1217 * while uv_poll is active. If the user does that anyway, the callback *may* 1218 * be called reporting an error status, but this is not guaranteed. 1219 * 1220 * Calling uv_poll_start on an uv_poll watcher that is already active is fine. 1221 * Doing so will update the events mask that is being watched for. 1222 */ 1223 UV_EXTERN int uv_poll_start(uv_poll_t* handle, int events, uv_poll_cb cb); 1224 1225 /* Stops polling the file descriptor. */ 1226 UV_EXTERN int uv_poll_stop(uv_poll_t* handle); 1227 1228 1229 /* 1230 * uv_iocp_t is a subclass of uv_handle_t. 1231 * 1232 * The uv_iocp allows asynchronous file operations in Windows to be waited 1233 * on manually. 1234 * 1235 * The purpose of uv_iocp is for interacting with "weird" file handles such 1236 * as devices where the reads and writes to the handle must be made in a 1237 * specific way (for example you must read a certain number of bytes). 1238 * Since it is not feasible for libuv to predict every possible device or 1239 * file handle which you may wish to read from or write to, uv_iocp allows 1240 * you to associate an OVERLAPPED file handle, then call ReadFile() or 1241 * WriteFile() yourself with your own parameters and then be called back on 1242 * completion. 1243 * 1244 * On non-windows systems, uv_iocp is meaningless and always fails. 1245 */ 1246 struct uv_iocp_s { 1247 UV_HANDLE_FIELDS 1248 uv_iocp_cb iocp_cb; 1249 1250 /* 1251 * This is set to a pointer to the internal OVERLAPPED structure 1252 * needed for ReadFile() and WriteFile(). 1253 */ 1254 void* overlapped; 1255 1256 UV_IOCP_PRIVATE_FIELDS 1257 }; 1258 1259 /* 1260 * Associates a callback with this IOCP handle. 1261 * When an IO operation completes, this callback will be invoked. 1262 */ 1263 UV_EXTERN int uv_iocp_start(uv_loop_t* loop, 1264 uv_iocp_t* handle, 1265 uv_os_file_t fd, 1266 uv_iocp_cb cb); 1267 1268 /* Stops listening for IOCP events on this handle. */ 1269 UV_EXTERN int uv_iocp_stop(uv_iocp_t* handle); 1270 1271 /* 1272 * uv_prepare_t is a subclass of uv_handle_t. 1273 * 1274 * Every active prepare handle gets its callback called exactly once per loop 1275 * iteration, just before the system blocks to wait for completed i/o. 1276 */ 1277 struct uv_prepare_s { 1278 UV_HANDLE_FIELDS 1279 UV_PREPARE_PRIVATE_FIELDS 1280 }; 1281 1282 UV_EXTERN int uv_prepare_init(uv_loop_t*, uv_prepare_t* prepare); 1283 1284 UV_EXTERN int uv_prepare_start(uv_prepare_t* prepare, uv_prepare_cb cb); 1285 1286 UV_EXTERN int uv_prepare_stop(uv_prepare_t* prepare); 1287 1288 1289 /* 1290 * uv_check_t is a subclass of uv_handle_t. 1291 * 1292 * Every active check handle gets its callback called exactly once per loop 1293 * iteration, just after the system returns from blocking. 1294 */ 1295 struct uv_check_s { 1296 UV_HANDLE_FIELDS 1297 UV_CHECK_PRIVATE_FIELDS 1298 }; 1299 1300 UV_EXTERN int uv_check_init(uv_loop_t*, uv_check_t* check); 1301 1302 UV_EXTERN int uv_check_start(uv_check_t* check, uv_check_cb cb); 1303 1304 UV_EXTERN int uv_check_stop(uv_check_t* check); 1305 1306 1307 /* 1308 * uv_idle_t is a subclass of uv_handle_t. 1309 * 1310 * Every active idle handle gets its callback called repeatedly until it is 1311 * stopped. This happens after all other types of callbacks are processed. 1312 * When there are multiple "idle" handles active, their callbacks are called 1313 * in turn. 1314 */ 1315 struct uv_idle_s { 1316 UV_HANDLE_FIELDS 1317 UV_IDLE_PRIVATE_FIELDS 1318 }; 1319 1320 UV_EXTERN int uv_idle_init(uv_loop_t*, uv_idle_t* idle); 1321 1322 UV_EXTERN int uv_idle_start(uv_idle_t* idle, uv_idle_cb cb); 1323 1324 UV_EXTERN int uv_idle_stop(uv_idle_t* idle); 1325 1326 1327 /* 1328 * uv_async_t is a subclass of uv_handle_t. 1329 * 1330 * uv_async_send wakes up the event loop and calls the async handle's callback. 1331 * There is no guarantee that every uv_async_send call leads to exactly one 1332 * invocation of the callback; the only guarantee is that the callback function 1333 * is called at least once after the call to async_send. Unlike all other 1334 * libuv functions, uv_async_send can be called from another thread. 1335 */ 1336 struct uv_async_s { 1337 UV_HANDLE_FIELDS 1338 UV_ASYNC_PRIVATE_FIELDS 1339 }; 1340 1341 /* 1342 * Initialize the uv_async_t handle. A NULL callback is allowed. 1343 * 1344 * Note that uv_async_init(), unlike other libuv functions, immediately 1345 * starts the handle. To stop the handle again, close it with uv_close(). 1346 */ 1347 UV_EXTERN int uv_async_init(uv_loop_t*, uv_async_t* async, 1348 uv_async_cb async_cb); 1349 1350 /* 1351 * This can be called from other threads to wake up a libuv thread. 1352 * 1353 * libuv is single threaded at the moment. 1354 */ 1355 UV_EXTERN int uv_async_send(uv_async_t* async); 1356 1357 1358 /* 1359 * uv_timer_t is a subclass of uv_handle_t. 1360 * 1361 * Used to get woken up at a specified time in the future. 1362 */ 1363 struct uv_timer_s { 1364 UV_HANDLE_FIELDS 1365 UV_TIMER_PRIVATE_FIELDS 1366 }; 1367 1368 UV_EXTERN int uv_timer_init(uv_loop_t*, uv_timer_t* handle); 1369 1370 /* 1371 * Start the timer. `timeout` and `repeat` are in milliseconds. 1372 * 1373 * If timeout is zero, the callback fires on the next tick of the event loop. 1374 * 1375 * If repeat is non-zero, the callback fires first after timeout milliseconds 1376 * and then repeatedly after repeat milliseconds. 1377 */ 1378 UV_EXTERN int uv_timer_start(uv_timer_t* handle, 1379 uv_timer_cb cb, 1380 uint64_t timeout, 1381 uint64_t repeat); 1382 1383 UV_EXTERN int uv_timer_stop(uv_timer_t* handle); 1384 1385 /* 1386 * Stop the timer, and if it is repeating restart it using the repeat value 1387 * as the timeout. If the timer has never been started before it returns 1388 * UV_EINVAL. 1389 */ 1390 UV_EXTERN int uv_timer_again(uv_timer_t* handle); 1391 1392 /* 1393 * Set the repeat value in milliseconds. Note that if the repeat value is set 1394 * from a timer callback it does not immediately take effect. If the timer was 1395 * non-repeating before, it will have been stopped. If it was repeating, then 1396 * the old repeat value will have been used to schedule the next timeout. 1397 */ 1398 UV_EXTERN void uv_timer_set_repeat(uv_timer_t* handle, uint64_t repeat); 1399 1400 UV_EXTERN uint64_t uv_timer_get_repeat(const uv_timer_t* handle); 1401 1402 1403 /* 1404 * uv_getaddrinfo_t is a subclass of uv_req_t 1405 * 1406 * Request object for uv_getaddrinfo. 1407 */ 1408 struct uv_getaddrinfo_s { 1409 UV_REQ_FIELDS 1410 /* read-only */ 1411 uv_loop_t* loop; 1412 UV_GETADDRINFO_PRIVATE_FIELDS 1413 }; 1414 1415 1416 /* 1417 * Asynchronous getaddrinfo(3). 1418 * 1419 * Either node or service may be NULL but not both. 1420 * 1421 * hints is a pointer to a struct addrinfo with additional address type 1422 * constraints, or NULL. Consult `man -s 3 getaddrinfo` for details. 1423 * 1424 * Returns 0 on success or an error code < 0 on failure. 1425 * 1426 * If successful, your callback gets called sometime in the future with the 1427 * lookup result, which is either: 1428 * 1429 * a) err == 0, the res argument points to a valid struct addrinfo, or 1430 * b) err < 0, the res argument is NULL. See the UV_EAI_* constants. 1431 * 1432 * Call uv_freeaddrinfo() to free the addrinfo structure. 1433 */ 1434 UV_EXTERN int uv_getaddrinfo(uv_loop_t* loop, 1435 uv_getaddrinfo_t* req, 1436 uv_getaddrinfo_cb getaddrinfo_cb, 1437 const char* node, 1438 const char* service, 1439 const struct addrinfo* hints); 1440 1441 /* 1442 * Free the struct addrinfo. Passing NULL is allowed and is a no-op. 1443 */ 1444 UV_EXTERN void uv_freeaddrinfo(struct addrinfo* ai); 1445 1446 1447 /* uv_spawn() options */ 1448 typedef enum { 1449 UV_IGNORE = 0x00, 1450 UV_CREATE_PIPE = 0x01, 1451 UV_INHERIT_FD = 0x02, 1452 UV_INHERIT_STREAM = 0x04, 1453 1454 /* When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE 1455 * determine the direction of flow, from the child process' perspective. Both 1456 * flags may be specified to create a duplex data stream. 1457 */ 1458 UV_READABLE_PIPE = 0x10, 1459 UV_WRITABLE_PIPE = 0x20 1460 } uv_stdio_flags; 1461 1462 typedef struct uv_stdio_container_s { 1463 uv_stdio_flags flags; 1464 1465 union { 1466 uv_stream_t* stream; 1467 int fd; 1468 } data; 1469 } uv_stdio_container_t; 1470 1471 typedef struct uv_process_options_s { 1472 uv_exit_cb exit_cb; /* Called after the process exits. */ 1473 const char* file; /* Path to program to execute. */ 1474 /* 1475 * Command line arguments. args[0] should be the path to the program. On 1476 * Windows this uses CreateProcess which concatenates the arguments into a 1477 * string this can cause some strange errors. See the note at 1478 * windows_verbatim_arguments. 1479 */ 1480 char** args; 1481 /* 1482 * This will be set as the environ variable in the subprocess. If this is 1483 * NULL then the parents environ will be used. 1484 */ 1485 char** env; 1486 /* 1487 * If non-null this represents a directory the subprocess should execute 1488 * in. Stands for current working directory. 1489 */ 1490 const char* cwd; 1491 /* 1492 * Various flags that control how uv_spawn() behaves. See the definition of 1493 * `enum uv_process_flags` below. 1494 */ 1495 unsigned int flags; 1496 /* 1497 * The `stdio` field points to an array of uv_stdio_container_t structs that 1498 * describe the file descriptors that will be made available to the child 1499 * process. The convention is that stdio[0] points to stdin, fd 1 is used for 1500 * stdout, and fd 2 is stderr. 1501 * 1502 * Note that on windows file descriptors greater than 2 are available to the 1503 * child process only if the child processes uses the MSVCRT runtime. 1504 */ 1505 int stdio_count; 1506 uv_stdio_container_t* stdio; 1507 /* 1508 * Libuv can change the child process' user/group id. This happens only when 1509 * the appropriate bits are set in the flags fields. This is not supported on 1510 * windows; uv_spawn() will fail and set the error to UV_ENOTSUP. 1511 */ 1512 uv_uid_t uid; 1513 uv_gid_t gid; 1514 } uv_process_options_t; 1515 1516 /* 1517 * These are the flags that can be used for the uv_process_options.flags field. 1518 */ 1519 enum uv_process_flags { 1520 /* 1521 * Set the child process' user id. The user id is supplied in the `uid` field 1522 * of the options struct. This does not work on windows; setting this flag 1523 * will cause uv_spawn() to fail. 1524 */ 1525 UV_PROCESS_SETUID = (1 << 0), 1526 /* 1527 * Set the child process' group id. The user id is supplied in the `gid` 1528 * field of the options struct. This does not work on windows; setting this 1529 * flag will cause uv_spawn() to fail. 1530 */ 1531 UV_PROCESS_SETGID = (1 << 1), 1532 /* 1533 * Do not wrap any arguments in quotes, or perform any other escaping, when 1534 * converting the argument list into a command line string. This option is 1535 * only meaningful on Windows systems. On unix it is silently ignored. 1536 */ 1537 UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2), 1538 /* 1539 * Spawn the child process in a detached state - this will make it a process 1540 * group leader, and will effectively enable the child to keep running after 1541 * the parent exits. Note that the child process will still keep the 1542 * parent's event loop alive unless the parent process calls uv_unref() on 1543 * the child's process handle. 1544 */ 1545 UV_PROCESS_DETACHED = (1 << 3), 1546 /* 1547 * Hide the subprocess console window that would normally be created. This 1548 * option is only meaningful on Windows systems. On unix it is silently 1549 * ignored. 1550 */ 1551 UV_PROCESS_WINDOWS_HIDE = (1 << 4) 1552 }; 1553 1554 /* 1555 * uv_process_t is a subclass of uv_handle_t 1556 */ 1557 struct uv_process_s { 1558 UV_HANDLE_FIELDS 1559 uv_exit_cb exit_cb; 1560 int pid; 1561 UV_PROCESS_PRIVATE_FIELDS 1562 }; 1563 1564 /* 1565 * Initializes the uv_process_t and starts the process. If the process is 1566 * successfully spawned, then this function will return 0. Otherwise, the 1567 * negative error code corresponding to the reason it couldn't spawn is 1568 * returned. 1569 * 1570 * Possible reasons for failing to spawn would include (but not be limited to) 1571 * the file to execute not existing, not having permissions to use the setuid or 1572 * setgid specified, or not having enough memory to allocate for the new 1573 * process. 1574 */ 1575 UV_EXTERN int uv_spawn(uv_loop_t* loop, 1576 uv_process_t* handle, 1577 const uv_process_options_t* options); 1578 1579 1580 /* 1581 * Kills the process with the specified signal. The user must still 1582 * call uv_close on the process. 1583 */ 1584 UV_EXTERN int uv_process_kill(uv_process_t*, int signum); 1585 1586 1587 /* Kills the process with the specified signal. */ 1588 UV_EXTERN int uv_kill(int pid, int signum); 1589 1590 1591 /* 1592 * uv_work_t is a subclass of uv_req_t 1593 */ 1594 struct uv_work_s { 1595 UV_REQ_FIELDS 1596 uv_loop_t* loop; 1597 uv_work_cb work_cb; 1598 uv_after_work_cb after_work_cb; 1599 UV_WORK_PRIVATE_FIELDS 1600 }; 1601 1602 /* Queues a work request to execute asynchronously on the thread pool. */ 1603 UV_EXTERN int uv_queue_work(uv_loop_t* loop, uv_work_t* req, 1604 uv_work_cb work_cb, uv_after_work_cb after_work_cb); 1605 1606 /* Cancel a pending request. Fails if the request is executing or has finished 1607 * executing. 1608 * 1609 * Returns 0 on success, or an error code < 0 on failure. 1610 * 1611 * Only cancellation of uv_fs_t, uv_getaddrinfo_t and uv_work_t requests is 1612 * currently supported. 1613 * 1614 * Cancelled requests have their callbacks invoked some time in the future. 1615 * It's _not_ safe to free the memory associated with the request until your 1616 * callback is called. 1617 * 1618 * Here is how cancellation is reported to your callback: 1619 * 1620 * - A uv_fs_t request has its req->result field set to UV_ECANCELED. 1621 * 1622 * - A uv_work_t or uv_getaddrinfo_t request has its callback invoked with 1623 * status == UV_ECANCELED. 1624 * 1625 * This function is currently only implemented on UNIX platforms. On Windows, 1626 * it always returns UV_ENOSYS. 1627 */ 1628 UV_EXTERN int uv_cancel(uv_req_t* req); 1629 1630 1631 struct uv_cpu_info_s { 1632 char* model; 1633 int speed; 1634 struct uv_cpu_times_s { 1635 uint64_t user; 1636 uint64_t nice; 1637 uint64_t sys; 1638 uint64_t idle; 1639 uint64_t irq; 1640 } cpu_times; 1641 }; 1642 1643 struct uv_interface_address_s { 1644 char* name; 1645 char phys_addr[6]; 1646 int is_internal; 1647 union { 1648 struct sockaddr_in address4; 1649 struct sockaddr_in6 address6; 1650 } address; 1651 union { 1652 struct sockaddr_in netmask4; 1653 struct sockaddr_in6 netmask6; 1654 } netmask; 1655 }; 1656 1657 UV_EXTERN char** uv_setup_args(int argc, char** argv); 1658 UV_EXTERN int uv_get_process_title(char* buffer, size_t size); 1659 UV_EXTERN int uv_set_process_title(const char* title); 1660 UV_EXTERN int uv_resident_set_memory(size_t* rss); 1661 UV_EXTERN int uv_uptime(double* uptime); 1662 1663 /* 1664 * This allocates cpu_infos array, and sets count. The array 1665 * is freed using uv_free_cpu_info(). 1666 */ 1667 UV_EXTERN int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count); 1668 UV_EXTERN void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count); 1669 1670 /* 1671 * This allocates addresses array, and sets count. The array 1672 * is freed using uv_free_interface_addresses(). 1673 */ 1674 UV_EXTERN int uv_interface_addresses(uv_interface_address_t** addresses, 1675 int* count); 1676 UV_EXTERN void uv_free_interface_addresses(uv_interface_address_t* addresses, 1677 int count); 1678 1679 /* 1680 * File System Methods. 1681 * 1682 * The uv_fs_* functions execute a blocking system call asynchronously (in a 1683 * thread pool) and call the specified callback in the specified loop after 1684 * completion. If the user gives NULL as the callback the blocking system 1685 * call will be called synchronously. req should be a pointer to an 1686 * uninitialized uv_fs_t object. 1687 * 1688 * uv_fs_req_cleanup() must be called after completion of the uv_fs_ 1689 * function to free any internal memory allocations associated with the 1690 * request. 1691 */ 1692 1693 typedef enum { 1694 UV_FS_UNKNOWN = -1, 1695 UV_FS_CUSTOM, 1696 UV_FS_OPEN, 1697 UV_FS_CLOSE, 1698 UV_FS_READ, 1699 UV_FS_WRITE, 1700 UV_FS_SENDFILE, 1701 UV_FS_STAT, 1702 UV_FS_LSTAT, 1703 UV_FS_FSTAT, 1704 UV_FS_FTRUNCATE, 1705 UV_FS_UTIME, 1706 UV_FS_FUTIME, 1707 UV_FS_CHMOD, 1708 UV_FS_FCHMOD, 1709 UV_FS_FSYNC, 1710 UV_FS_FDATASYNC, 1711 UV_FS_UNLINK, 1712 UV_FS_RMDIR, 1713 UV_FS_MKDIR, 1714 UV_FS_RENAME, 1715 UV_FS_READDIR, 1716 UV_FS_LINK, 1717 UV_FS_SYMLINK, 1718 UV_FS_READLINK, 1719 UV_FS_CHOWN, 1720 UV_FS_FCHOWN 1721 } uv_fs_type; 1722 1723 /* uv_fs_t is a subclass of uv_req_t */ 1724 struct uv_fs_s { 1725 UV_REQ_FIELDS 1726 uv_fs_type fs_type; 1727 uv_loop_t* loop; 1728 uv_fs_cb cb; 1729 ssize_t result; 1730 void* ptr; 1731 const char* path; 1732 uv_stat_t statbuf; /* Stores the result of uv_fs_stat and uv_fs_fstat. */ 1733 UV_FS_PRIVATE_FIELDS 1734 }; 1735 1736 UV_EXTERN void uv_fs_req_cleanup(uv_fs_t* req); 1737 1738 UV_EXTERN int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1739 uv_fs_cb cb); 1740 1741 UV_EXTERN int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, 1742 int flags, int mode, uv_fs_cb cb); 1743 1744 UV_EXTERN int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1745 void* buf, size_t length, int64_t offset, uv_fs_cb cb); 1746 1747 UV_EXTERN int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, 1748 uv_fs_cb cb); 1749 1750 UV_EXTERN int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1751 const void* buf, size_t length, int64_t offset, uv_fs_cb cb); 1752 1753 UV_EXTERN int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, 1754 int mode, uv_fs_cb cb); 1755 1756 UV_EXTERN int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, 1757 uv_fs_cb cb); 1758 1759 UV_EXTERN int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, 1760 const char* path, int flags, uv_fs_cb cb); 1761 1762 UV_EXTERN int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, 1763 uv_fs_cb cb); 1764 1765 UV_EXTERN int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1766 uv_fs_cb cb); 1767 1768 UV_EXTERN int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, 1769 const char* new_path, uv_fs_cb cb); 1770 1771 UV_EXTERN int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1772 uv_fs_cb cb); 1773 1774 UV_EXTERN int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1775 uv_fs_cb cb); 1776 1777 UV_EXTERN int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1778 int64_t offset, uv_fs_cb cb); 1779 1780 UV_EXTERN int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, 1781 uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb); 1782 1783 UV_EXTERN int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, 1784 int mode, uv_fs_cb cb); 1785 1786 UV_EXTERN int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, 1787 double atime, double mtime, uv_fs_cb cb); 1788 1789 UV_EXTERN int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1790 double atime, double mtime, uv_fs_cb cb); 1791 1792 UV_EXTERN int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, 1793 uv_fs_cb cb); 1794 1795 UV_EXTERN int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, 1796 const char* new_path, uv_fs_cb cb); 1797 1798 /* 1799 * This flag can be used with uv_fs_symlink on Windows 1800 * to specify whether path argument points to a directory. 1801 */ 1802 #define UV_FS_SYMLINK_DIR 0x0001 1803 1804 /* 1805 * This flag can be used with uv_fs_symlink on Windows 1806 * to specify whether the symlink is to be created using junction points. 1807 */ 1808 #define UV_FS_SYMLINK_JUNCTION 0x0002 1809 1810 UV_EXTERN int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, 1811 const char* new_path, int flags, uv_fs_cb cb); 1812 1813 UV_EXTERN int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, 1814 uv_fs_cb cb); 1815 1816 UV_EXTERN int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1817 int mode, uv_fs_cb cb); 1818 1819 UV_EXTERN int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, 1820 uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb); 1821 1822 UV_EXTERN int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, 1823 uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb); 1824 1825 1826 enum uv_fs_event { 1827 UV_RENAME = 1, 1828 UV_CHANGE = 2 1829 }; 1830 1831 1832 struct uv_fs_event_s { 1833 UV_HANDLE_FIELDS 1834 char* filename; 1835 UV_FS_EVENT_PRIVATE_FIELDS 1836 }; 1837 1838 1839 /* 1840 * uv_fs_stat() based polling file watcher. 1841 */ 1842 struct uv_fs_poll_s { 1843 UV_HANDLE_FIELDS 1844 /* Private, don't touch. */ 1845 void* poll_ctx; 1846 }; 1847 1848 UV_EXTERN int uv_fs_poll_init(uv_loop_t* loop, uv_fs_poll_t* handle); 1849 1850 /* 1851 * Check the file at `path` for changes every `interval` milliseconds. 1852 * 1853 * Your callback is invoked with `status < 0` if `path` does not exist 1854 * or is inaccessible. The watcher is *not* stopped but your callback is 1855 * not called again until something changes (e.g. when the file is created 1856 * or the error reason changes). 1857 * 1858 * When `status == 0`, your callback receives pointers to the old and new 1859 * `uv_stat_t` structs. They are valid for the duration of the callback 1860 * only! 1861 * 1862 * For maximum portability, use multi-second intervals. Sub-second intervals 1863 * will not detect all changes on many file systems. 1864 */ 1865 UV_EXTERN int uv_fs_poll_start(uv_fs_poll_t* handle, 1866 uv_fs_poll_cb poll_cb, 1867 const char* path, 1868 unsigned int interval); 1869 1870 UV_EXTERN int uv_fs_poll_stop(uv_fs_poll_t* handle); 1871 1872 1873 /* 1874 * UNIX signal handling on a per-event loop basis. The implementation is not 1875 * ultra efficient so don't go creating a million event loops with a million 1876 * signal watchers. 1877 * 1878 * Note to Linux users: SIGRT0 and SIGRT1 (signals 32 and 33) are used by the 1879 * NPTL pthreads library to manage threads. Installing watchers for those 1880 * signals will lead to unpredictable behavior and is strongly discouraged. 1881 * Future versions of libuv may simply reject them. 1882 * 1883 * Some signal support is available on Windows: 1884 * 1885 * SIGINT is normally delivered when the user presses CTRL+C. However, like 1886 * on Unix, it is not generated when terminal raw mode is enabled. 1887 * 1888 * SIGBREAK is delivered when the user pressed CTRL+BREAK. 1889 * 1890 * SIGHUP is generated when the user closes the console window. On SIGHUP the 1891 * program is given approximately 10 seconds to perform cleanup. After that 1892 * Windows will unconditionally terminate it. 1893 * 1894 * SIGWINCH is raised whenever libuv detects that the console has been 1895 * resized. SIGWINCH is emulated by libuv when the program uses an uv_tty_t 1896 * handle to write to the console. SIGWINCH may not always be delivered in a 1897 * timely manner; libuv will only detect size changes when the cursor is 1898 * being moved. When a readable uv_tty_handle is used in raw mode, resizing 1899 * the console buffer will also trigger a SIGWINCH signal. 1900 * 1901 * Watchers for other signals can be successfully created, but these signals 1902 * are never generated. These signals are: SIGILL, SIGABRT, SIGFPE, SIGSEGV, 1903 * SIGTERM and SIGKILL. 1904 * 1905 * Note that calls to raise() or abort() to programmatically raise a signal are 1906 * not detected by libuv; these will not trigger a signal watcher. 1907 */ 1908 struct uv_signal_s { 1909 UV_HANDLE_FIELDS 1910 uv_signal_cb signal_cb; 1911 int signum; 1912 UV_SIGNAL_PRIVATE_FIELDS 1913 }; 1914 1915 UV_EXTERN int uv_signal_init(uv_loop_t* loop, uv_signal_t* handle); 1916 1917 UV_EXTERN int uv_signal_start(uv_signal_t* handle, 1918 uv_signal_cb signal_cb, 1919 int signum); 1920 1921 UV_EXTERN int uv_signal_stop(uv_signal_t* handle); 1922 1923 1924 /* 1925 * Gets load average. 1926 * See: https://en.wikipedia.org/wiki/Load_(computing) 1927 * Returns [0,0,0] on Windows. 1928 */ 1929 UV_EXTERN void uv_loadavg(double avg[3]); 1930 1931 1932 /* 1933 * Flags to be passed to uv_fs_event_start. 1934 */ 1935 enum uv_fs_event_flags { 1936 /* 1937 * By default, if the fs event watcher is given a directory name, we will 1938 * watch for all events in that directory. This flags overrides this behavior 1939 * and makes fs_event report only changes to the directory entry itself. This 1940 * flag does not affect individual files watched. 1941 * This flag is currently not implemented yet on any backend. 1942 */ 1943 UV_FS_EVENT_WATCH_ENTRY = 1, 1944 1945 /* 1946 * By default uv_fs_event will try to use a kernel interface such as inotify 1947 * or kqueue to detect events. This may not work on remote filesystems such 1948 * as NFS mounts. This flag makes fs_event fall back to calling stat() on a 1949 * regular interval. 1950 * This flag is currently not implemented yet on any backend. 1951 */ 1952 UV_FS_EVENT_STAT = 2, 1953 1954 /* 1955 * By default, event watcher, when watching directory, is not registering 1956 * (is ignoring) changes in it's subdirectories. 1957 * This flag will override this behaviour on platforms that support it. 1958 */ 1959 UV_FS_EVENT_RECURSIVE = 4 1960 }; 1961 1962 1963 UV_EXTERN int uv_fs_event_init(uv_loop_t* loop, uv_fs_event_t* handle); 1964 1965 UV_EXTERN int uv_fs_event_start(uv_fs_event_t* handle, 1966 uv_fs_event_cb cb, 1967 const char* filename, 1968 unsigned int flags); 1969 1970 UV_EXTERN int uv_fs_event_stop(uv_fs_event_t* handle); 1971 1972 1973 /* Utility */ 1974 1975 /* Convert string ip addresses to binary structures */ 1976 UV_EXTERN int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr); 1977 UV_EXTERN int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr); 1978 1979 /* Convert binary addresses to strings */ 1980 UV_EXTERN int uv_ip4_name(struct sockaddr_in* src, char* dst, size_t size); 1981 UV_EXTERN int uv_ip6_name(struct sockaddr_in6* src, char* dst, size_t size); 1982 1983 /* Cross-platform IPv6-capable implementation of the 'standard' inet_ntop */ 1984 /* and inet_pton functions. On success they return 0. If an error */ 1985 /* the target of the `dst` pointer is unmodified. */ 1986 UV_EXTERN int uv_inet_ntop(int af, const void* src, char* dst, size_t size); 1987 UV_EXTERN int uv_inet_pton(int af, const char* src, void* dst); 1988 1989 /* Gets the executable path */ 1990 UV_EXTERN int uv_exepath(char* buffer, size_t* size); 1991 1992 /* Gets the current working directory */ 1993 UV_EXTERN int uv_cwd(char* buffer, size_t size); 1994 1995 /* Changes the current working directory */ 1996 UV_EXTERN int uv_chdir(const char* dir); 1997 1998 /* Gets memory info in bytes */ 1999 UV_EXTERN uint64_t uv_get_free_memory(void); 2000 UV_EXTERN uint64_t uv_get_total_memory(void); 2001 2002 /* 2003 * Returns the current high-resolution real time. This is expressed in 2004 * nanoseconds. It is relative to an arbitrary time in the past. It is not 2005 * related to the time of day and therefore not subject to clock drift. The 2006 * primary use is for measuring performance between intervals. 2007 * 2008 * Note not every platform can support nanosecond resolution; however, this 2009 * value will always be in nanoseconds. 2010 */ 2011 UV_EXTERN extern uint64_t uv_hrtime(void); 2012 2013 2014 /* 2015 * Disables inheritance for file descriptors / handles that this process 2016 * inherited from its parent. The effect is that child processes spawned by 2017 * this process don't accidentally inherit these handles. 2018 * 2019 * It is recommended to call this function as early in your program as possible, 2020 * before the inherited file descriptors can be closed or duplicated. 2021 * 2022 * Note that this function works on a best-effort basis: there is no guarantee 2023 * that libuv can discover all file descriptors that were inherited. In general 2024 * it does a better job on Windows than it does on unix. 2025 */ 2026 UV_EXTERN void uv_disable_stdio_inheritance(void); 2027 2028 /* 2029 * Opens a shared library. The filename is in utf-8. Returns 0 on success and 2030 * -1 on error. Call `uv_dlerror(uv_lib_t*)` to get the error message. 2031 */ 2032 UV_EXTERN int uv_dlopen(const char* filename, uv_lib_t* lib); 2033 2034 /* 2035 * Close the shared library. 2036 */ 2037 UV_EXTERN void uv_dlclose(uv_lib_t* lib); 2038 2039 /* 2040 * Retrieves a data pointer from a dynamic library. It is legal for a symbol to 2041 * map to NULL. Returns 0 on success and -1 if the symbol was not found. 2042 */ 2043 UV_EXTERN int uv_dlsym(uv_lib_t* lib, const char* name, void** ptr); 2044 2045 /* 2046 * Returns the last uv_dlopen() or uv_dlsym() error message. 2047 */ 2048 UV_EXTERN const char* uv_dlerror(uv_lib_t* lib); 2049 2050 /* 2051 * The mutex functions return 0 on success or an error code < 0 2052 * (unless the return type is void, of course). 2053 */ 2054 UV_EXTERN int uv_mutex_init(uv_mutex_t* handle); 2055 UV_EXTERN void uv_mutex_destroy(uv_mutex_t* handle); 2056 UV_EXTERN void uv_mutex_lock(uv_mutex_t* handle); 2057 UV_EXTERN int uv_mutex_trylock(uv_mutex_t* handle); 2058 UV_EXTERN void uv_mutex_unlock(uv_mutex_t* handle); 2059 2060 /* 2061 * Same goes for the read/write lock functions. 2062 */ 2063 UV_EXTERN int uv_rwlock_init(uv_rwlock_t* rwlock); 2064 UV_EXTERN void uv_rwlock_destroy(uv_rwlock_t* rwlock); 2065 UV_EXTERN void uv_rwlock_rdlock(uv_rwlock_t* rwlock); 2066 UV_EXTERN int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock); 2067 UV_EXTERN void uv_rwlock_rdunlock(uv_rwlock_t* rwlock); 2068 UV_EXTERN void uv_rwlock_wrlock(uv_rwlock_t* rwlock); 2069 UV_EXTERN int uv_rwlock_trywrlock(uv_rwlock_t* rwlock); 2070 UV_EXTERN void uv_rwlock_wrunlock(uv_rwlock_t* rwlock); 2071 2072 /* 2073 * Same goes for the semaphore functions. 2074 */ 2075 UV_EXTERN int uv_sem_init(uv_sem_t* sem, unsigned int value); 2076 UV_EXTERN void uv_sem_destroy(uv_sem_t* sem); 2077 UV_EXTERN void uv_sem_post(uv_sem_t* sem); 2078 UV_EXTERN void uv_sem_wait(uv_sem_t* sem); 2079 UV_EXTERN int uv_sem_trywait(uv_sem_t* sem); 2080 2081 /* 2082 * Same goes for the condition variable functions. 2083 */ 2084 UV_EXTERN int uv_cond_init(uv_cond_t* cond); 2085 UV_EXTERN void uv_cond_destroy(uv_cond_t* cond); 2086 UV_EXTERN void uv_cond_signal(uv_cond_t* cond); 2087 UV_EXTERN void uv_cond_broadcast(uv_cond_t* cond); 2088 /* Waits on a condition variable without a timeout. 2089 * 2090 * Note: 2091 * 1. callers should be prepared to deal with spurious wakeups. 2092 */ 2093 UV_EXTERN void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex); 2094 /* Waits on a condition variable with a timeout in nano seconds. 2095 * Returns 0 for success or UV_ETIMEDOUT on timeout, It aborts when other 2096 * errors happen. 2097 * 2098 * Note: 2099 * 1. callers should be prepared to deal with spurious wakeups. 2100 * 2. the granularity of timeout on Windows is never less than one millisecond. 2101 * 3. uv_cond_timedwait takes a relative timeout, not an absolute time. 2102 */ 2103 UV_EXTERN int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, 2104 uint64_t timeout); 2105 2106 UV_EXTERN int uv_barrier_init(uv_barrier_t* barrier, unsigned int count); 2107 UV_EXTERN void uv_barrier_destroy(uv_barrier_t* barrier); 2108 UV_EXTERN void uv_barrier_wait(uv_barrier_t* barrier); 2109 2110 /* Runs a function once and only once. Concurrent calls to uv_once() with the 2111 * same guard will block all callers except one (it's unspecified which one). 2112 * The guard should be initialized statically with the UV_ONCE_INIT macro. 2113 */ 2114 UV_EXTERN void uv_once(uv_once_t* guard, void (*callback)(void)); 2115 2116 /* Thread-local storage. These functions largely follow the semantics of 2117 * pthread_key_create(), pthread_key_delete(), pthread_getspecific() and 2118 * pthread_setspecific(). 2119 * 2120 * Note that the total thread-local storage size may be limited. 2121 * That is, it may not be possible to create many TLS keys. 2122 */ 2123 UV_EXTERN int uv_key_create(uv_key_t* key); 2124 UV_EXTERN void uv_key_delete(uv_key_t* key); 2125 UV_EXTERN void* uv_key_get(uv_key_t* key); 2126 UV_EXTERN void uv_key_set(uv_key_t* key, void* value); 2127 2128 UV_EXTERN int uv_thread_create(uv_thread_t *tid, 2129 void (*entry)(void *arg), void *arg); 2130 UV_EXTERN unsigned long uv_thread_self(void); 2131 UV_EXTERN int uv_thread_join(uv_thread_t *tid); 2132 2133 /* The presence of these unions force similar struct layout. */ 2134 #define XX(_, name) uv_ ## name ## _t name; 2135 union uv_any_handle { 2136 UV_HANDLE_TYPE_MAP(XX) 2137 }; 2138 2139 union uv_any_req { 2140 UV_REQ_TYPE_MAP(XX) 2141 }; 2142 #undef XX 2143 2144 2145 struct uv_loop_s { 2146 /* User data - use this for whatever. */ 2147 void* data; 2148 /* Loop reference counting */ 2149 unsigned int active_handles; 2150 void* handle_queue[2]; 2151 void* active_reqs[2]; 2152 /* Internal flag to signal loop stop */ 2153 unsigned int stop_flag; 2154 UV_LOOP_PRIVATE_FIELDS 2155 }; 2156 2157 2158 /* Don't export the private CPP symbols. */ 2159 #undef UV_HANDLE_TYPE_PRIVATE 2160 #undef UV_REQ_TYPE_PRIVATE 2161 #undef UV_REQ_PRIVATE_FIELDS 2162 #undef UV_STREAM_PRIVATE_FIELDS 2163 #undef UV_TCP_PRIVATE_FIELDS 2164 #undef UV_PREPARE_PRIVATE_FIELDS 2165 #undef UV_CHECK_PRIVATE_FIELDS 2166 #undef UV_IDLE_PRIVATE_FIELDS 2167 #undef UV_ASYNC_PRIVATE_FIELDS 2168 #undef UV_TIMER_PRIVATE_FIELDS 2169 #undef UV_GETADDRINFO_PRIVATE_FIELDS 2170 #undef UV_FS_REQ_PRIVATE_FIELDS 2171 #undef UV_WORK_PRIVATE_FIELDS 2172 #undef UV_FS_EVENT_PRIVATE_FIELDS 2173 #undef UV_SIGNAL_PRIVATE_FIELDS 2174 #undef UV_LOOP_PRIVATE_FIELDS 2175 #undef UV_LOOP_PRIVATE_PLATFORM_FIELDS 2176 2177 #ifdef __cplusplus 2178 } 2179 #endif 2180 #endif /* UV_H */ 2181