mt-libuv 4.1.01 → 4.1.02

data/ext/libuv/docs/src/guide/filesystem.rst

@@ -0,0 +1,330 @@
+Filesystem
+==========
+
+Simple filesystem read/write is achieved using the ``uv_fs_*`` functions and the
+``uv_fs_t`` struct.
+
+.. note::
+
+    The libuv filesystem operations are different from :doc:`socket operations
+    <networking>`. Socket operations use the non-blocking operations provided
+    by the operating system. Filesystem operations use blocking functions
+    internally, but invoke these functions in a `thread pool`_ and notify
+    watchers registered with the event loop when application interaction is
+    required.
+
+.. _thread pool: http://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling
+
+All filesystem functions have two forms - *synchronous* and *asynchronous*.
+
+The *synchronous* forms automatically get called (and **block**) if the
+callback is null. The return value of functions is a :ref:`libuv error code
+<libuv-error-handling>`. This is usually only useful for synchronous calls.
+The *asynchronous* form is called when a callback is passed and the return
+value is 0.
+
+Reading/Writing files
+---------------------
+
+A file descriptor is obtained using
+
+.. code-block:: c
+
+    int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb)
+
+``flags`` and ``mode`` are standard
+`Unix flags <http://man7.org/linux/man-pages/man2/open.2.html>`_.
+libuv takes care of converting to the appropriate Windows flags.
+
+File descriptors are closed using
+
+.. code-block:: c
+
+    int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
+
+
+Filesystem operation callbacks have the signature:
+
+.. code-block:: c
+
+    void callback(uv_fs_t* req);
+
+Let's see a simple implementation of ``cat``. We start with registering
+a callback for when the file is opened:
+
+.. rubric:: uvcat/main.c - opening a file
+.. literalinclude:: ../../code/uvcat/main.c
+    :linenos:
+    :lines: 41-53
+    :emphasize-lines: 4, 6-7
+
+The ``result`` field of a ``uv_fs_t`` is the file descriptor in case of the
+``uv_fs_open`` callback. If the file is successfully opened, we start reading it.
+
+.. rubric:: uvcat/main.c - read callback
+.. literalinclude:: ../../code/uvcat/main.c
+    :linenos:
+    :lines: 26-40
+    :emphasize-lines: 2,8,12
+
+In the case of a read call, you should pass an *initialized* buffer which will
+be filled with data before the read callback is triggered. The ``uv_fs_*``
+operations map almost directly to certain POSIX functions, so EOF is indicated
+in this case by ``result`` being 0. In the case of streams or pipes, the
+``UV_EOF`` constant would have been passed as a status instead.
+
+Here you see a common pattern when writing asynchronous programs. The
+``uv_fs_close()`` call is performed synchronously. *Usually tasks which are
+one-off, or are done as part of the startup or shutdown stage are performed
+synchronously, since we are interested in fast I/O when the program is going
+about its primary task and dealing with multiple I/O sources*. For solo tasks
+the performance difference usually is negligible and may lead to simpler code.
+
+Filesystem writing is similarly simple using ``uv_fs_write()``.  *Your callback
+will be triggered after the write is complete*.  In our case the callback
+simply drives the next read. Thus read and write proceed in lockstep via
+callbacks.
+
+.. rubric:: uvcat/main.c - write callback
+.. literalinclude:: ../../code/uvcat/main.c
+    :linenos:
+    :lines: 16-24
+    :emphasize-lines: 6
+
+.. warning::
+
+    Due to the way filesystems and disk drives are configured for performance,
+    a write that 'succeeds' may not be committed to disk yet.
+
+We set the dominos rolling in ``main()``:
+
+.. rubric:: uvcat/main.c
+.. literalinclude:: ../../code/uvcat/main.c
+    :linenos:
+    :lines: 55-
+    :emphasize-lines: 2
+
+.. warning::
+
+    The ``uv_fs_req_cleanup()`` function must always be called on filesystem
+    requests to free internal memory allocations in libuv.
+
+Filesystem operations
+---------------------
+
+All the standard filesystem operations like ``unlink``, ``rmdir``, ``stat`` are
+supported asynchronously and have intuitive argument order. They follow the
+same patterns as the read/write/open calls, returning the result in the
+``uv_fs_t.result`` field. The full list:
+
+.. rubric:: Filesystem operations
+.. code-block:: c
+
+    int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
+    int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb);
+    int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb);
+    int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb);
+    int uv_fs_copyfile(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
+    int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
+    int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb);
+    int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb);
+    int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent);
+    int uv_fs_opendir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb);
+    int uv_fs_closedir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb);
+    int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
+    int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb);
+    int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
+    int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
+    int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb);
+    int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb);
+    int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
+    int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
+    int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb);
+    int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb);
+    int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb);
+    int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
+    int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
+    int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb);
+    int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
+    int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
+    int uv_fs_lchown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
+
+
+.. _buffers-and-streams:
+
+Buffers and Streams
+-------------------
+
+The basic I/O handle in libuv is the stream (``uv_stream_t``). TCP sockets, UDP
+sockets, and pipes for file I/O and IPC are all treated as stream subclasses.
+
+Streams are initialized using custom functions for each subclass, then operated
+upon using
+
+.. code-block:: c
+
+    int uv_read_start(uv_stream_t*, uv_alloc_cb alloc_cb, uv_read_cb read_cb);
+    int uv_read_stop(uv_stream_t*);
+    int uv_write(uv_write_t* req, uv_stream_t* handle,
+                 const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb);
+
+The stream based functions are simpler to use than the filesystem ones and
+libuv will automatically keep reading from a stream when ``uv_read_start()`` is
+called once, until ``uv_read_stop()`` is called.
+
+The discrete unit of data is the buffer -- ``uv_buf_t``. This is simply
+a collection of a pointer to bytes (``uv_buf_t.base``) and the length
+(``uv_buf_t.len``). The ``uv_buf_t`` is lightweight and passed around by value.
+What does require management is the actual bytes, which have to be allocated
+and freed by the application.
+
+.. ERROR::
+
+    THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER**
+
+To demonstrate streams we will need to use ``uv_pipe_t``. This allows streaming
+local files [#]_. Here is a simple tee utility using libuv.  Doing all operations
+asynchronously shows the power of evented I/O. The two writes won't block each
+other, but we have to be careful to copy over the buffer data to ensure we don't
+free a buffer until it has been written.
+
+The program is to be executed as::
+
+    ./uvtee <output_file>
+
+We start off opening pipes on the files we require. libuv pipes to a file are
+opened as bidirectional by default.
+
+.. rubric:: uvtee/main.c - read on pipes
+.. literalinclude:: ../../code/uvtee/main.c
+    :linenos:
+    :lines: 61-80
+    :emphasize-lines: 4,5,15
+
+The third argument of ``uv_pipe_init()`` should be set to 1 for IPC using named
+pipes. This is covered in :doc:`processes`. The ``uv_pipe_open()`` call
+associates the pipe with the file descriptor, in this case ``0`` (standard
+input).
+
+We start monitoring ``stdin``. The ``alloc_buffer`` callback is invoked as new
+buffers are required to hold incoming data. ``read_stdin`` will be called with
+these buffers.
+
+.. rubric:: uvtee/main.c - reading buffers
+.. literalinclude:: ../../code/uvtee/main.c
+    :linenos:
+    :lines: 19-22,44-60
+
+The standard ``malloc`` is sufficient here, but you can use any memory allocation
+scheme. For example, node.js uses its own slab allocator which associates
+buffers with V8 objects.
+
+The read callback ``nread`` parameter is less than 0 on any error. This error
+might be EOF, in which case we close all the streams, using the generic close
+function ``uv_close()`` which deals with the handle based on its internal type.
+Otherwise ``nread`` is a non-negative number and we can attempt to write that
+many bytes to the output streams. Finally remember that buffer allocation and
+deallocation is application responsibility, so we free the data.
+
+The allocation callback may return a buffer with length zero if it fails to
+allocate memory. In this case, the read callback is invoked with error
+UV_ENOBUFS. libuv will continue to attempt to read the stream though, so you
+must explicitly call ``uv_close()`` if you want to stop when allocation fails.
+
+The read callback may be called with ``nread = 0``, indicating that at this
+point there is nothing to be read. Most applications will just ignore this.
+
+.. rubric:: uvtee/main.c - Write to pipe
+.. literalinclude:: ../../code/uvtee/main.c
+    :linenos:
+    :lines: 9-13,23-42
+
+``write_data()`` makes a copy of the buffer obtained from read. This buffer
+does not get passed through to the write callback trigged on write completion. To
+get around this we wrap a write request and a buffer in ``write_req_t`` and
+unwrap it in the callbacks. We make a copy so we can free the two buffers from
+the two calls to ``write_data`` independently of each other. While acceptable
+for a demo program like this, you'll probably want smarter memory management,
+like reference counted buffers or a pool of buffers in any major application.
+
+.. WARNING::
+
+    If your program is meant to be used with other programs it may knowingly or
+    unknowingly be writing to a pipe. This makes it susceptible to `aborting on
+    receiving a SIGPIPE`_. It is a good idea to insert::
+
+        signal(SIGPIPE, SIG_IGN)
+
+    in the initialization stages of your application.
+
+.. _aborting on receiving a SIGPIPE: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#The_special_problem_of_SIGPIPE
+
+File change events
+------------------
+
+All modern operating systems provide APIs to put watches on individual files or
+directories and be informed when the files are modified. libuv wraps common
+file change notification libraries [#fsnotify]_. This is one of the more
+inconsistent parts of libuv. File change notification systems are themselves
+extremely varied across platforms so getting everything working everywhere is
+difficult. To demonstrate, I'm going to build a simple utility which runs
+a command whenever any of the watched files change::
+
+    ./onchange <command> <file1> [file2] ...
+
+The file change notification is started using ``uv_fs_event_init()``:
+
+.. rubric:: onchange/main.c - The setup
+.. literalinclude:: ../../code/onchange/main.c
+    :linenos:
+    :lines: 26-
+    :emphasize-lines: 15
+
+The third argument is the actual file or directory to monitor. The last
+argument, ``flags``, can be:
+
+.. code-block:: c
+
+    /*
+    * Flags to be passed to uv_fs_event_start().
+    */
+    enum uv_fs_event_flags {
+        UV_FS_EVENT_WATCH_ENTRY = 1,
+        UV_FS_EVENT_STAT = 2,
+        UV_FS_EVENT_RECURSIVE = 4
+    };
+
+``UV_FS_EVENT_WATCH_ENTRY`` and ``UV_FS_EVENT_STAT`` don't do anything (yet).
+``UV_FS_EVENT_RECURSIVE`` will start watching subdirectories as well on
+supported platforms.
+
+The callback will receive the following arguments:
+
+  #. ``uv_fs_event_t *handle`` - The handle. The ``path`` field of the handle
+     is the file on which the watch was set.
+  #. ``const char *filename`` - If a directory is being monitored, this is the
+     file which was changed. Only non-``null`` on Linux and Windows. May be ``null``
+     even on those platforms.
+  #. ``int flags`` - one of ``UV_RENAME`` or ``UV_CHANGE``, or a bitwise OR of
+       both.
+  #. ``int status`` - Currently 0.
+
+In our example we simply print the arguments and run the command using
+``system()``.
+
+.. rubric:: onchange/main.c - file change notification callback
+.. literalinclude:: ../../code/onchange/main.c
+    :linenos:
+    :lines: 9-24
+
+----
+
+.. [#fsnotify] inotify on Linux, FSEvents on Darwin, kqueue on BSDs,
+               ReadDirectoryChangesW on Windows, event ports on Solaris, unsupported on Cygwin
+.. [#] see :ref:`pipes`

data/ext/libuv/docs/src/guide/introduction.rst

@@ -0,0 +1,75 @@
+Introduction
+============
+
+This 'book' is a small set of tutorials about using libuv_ as
+a high performance evented I/O library which offers the same API on Windows and Unix.
+
+It is meant to cover the main areas of libuv, but is not a comprehensive
+reference discussing every function and data structure. The `official libuv
+documentation`_ may be consulted for full details.
+
+.. _official libuv documentation: http://docs.libuv.org/en/v1.x/
+
+This book is still a work in progress, so sections may be incomplete, but
+I hope you will enjoy it as it grows.
+
+Who this book is for
+--------------------
+
+If you are reading this book, you are either:
+
+1) a systems programmer, creating low-level programs such as daemons or network
+   services and clients. You have found that the event loop approach is well
+   suited for your application and decided to use libuv.
+
+2) a node.js module writer, who wants to wrap platform APIs
+   written in C or C++ with a set of (a)synchronous APIs that are exposed to
+   JavaScript. You will use libuv purely in the context of node.js. For
+   this you will require some other resources as the book does not cover parts
+   specific to v8/node.js.
+
+This book assumes that you are comfortable with the C programming language.
+
+Background
+----------
+
+The node.js_ project began in 2009 as a JavaScript environment decoupled
+from the browser. Using Google's V8_ and Marc Lehmann's libev_, node.js
+combined a model of I/O -- evented -- with a language that was well suited to
+the style of programming; due to the way it had been shaped by browsers. As
+node.js grew in popularity, it was important to make it work on Windows, but
+libev ran only on Unix. The Windows equivalent of kernel event notification
+mechanisms like kqueue or (e)poll is IOCP. libuv was an abstraction around libev
+or IOCP depending on the platform, providing users an API based on libev.
+In the node-v0.9.0 version of libuv `libev was removed`_.
+
+Since then libuv has continued to mature and become a high quality standalone
+library for system programming. Users outside of node.js include Mozilla's
+Rust_ programming language, and a variety_ of language bindings.
+
+This book and the code is based on libuv version `v1.3.0`_.
+
+Code
+----
+
+All the code from this book is included as part of the source of the book on
+Github. `Clone`_/`Download`_ the book, then build libuv::
+
+    cd libuv
+    ./autogen.sh
+    ./configure
+    make
+
+There is no need to ``make install``. To build the examples run ``make`` in the
+``code/`` directory.
+
+.. _Clone: https://github.com/nikhilm/uvbook
+.. _Download: https://github.com/nikhilm/uvbook/downloads
+.. _v1.3.0: https://github.com/libuv/libuv/tags
+.. _V8: https://v8.dev
+.. _libev: http://software.schmorp.de/pkg/libev.html
+.. _libuv: https://github.com/libuv/libuv
+.. _node.js: https://www.nodejs.org
+.. _libev was removed: https://github.com/joyent/libuv/issues/485
+.. _Rust: https://www.rust-lang.org
+.. _variety: https://github.com/libuv/libuv/wiki/Projects-that-use-libuv

data/ext/libuv/docs/src/guide/networking.rst

@@ -0,0 +1,250 @@
+Networking
+==========
+
+Networking in libuv is not much different from directly using the BSD socket
+interface, some things are easier, all are non-blocking, but the concepts stay
+the same. In addition libuv offers utility functions to abstract the annoying,
+repetitive and low-level tasks like setting up sockets using the BSD socket
+structures, DNS lookup, and tweaking various socket parameters.
+
+The ``uv_tcp_t`` and ``uv_udp_t`` structures are used for network I/O.
+
+.. NOTE::
+
+  The code samples in this chapter exist to show certain libuv APIs. They are
+  not examples of good quality code. They leak memory and don't always close
+  connections properly.
+
+TCP
+---
+
+TCP is a connection oriented, stream protocol and is therefore based on the
+libuv streams infrastructure.
+
+Server
+++++++
+
+Server sockets proceed by:
+
+1. ``uv_tcp_init`` the TCP handle.
+2. ``uv_tcp_bind`` it.
+3. Call ``uv_listen`` on the handle to have a callback invoked whenever a new
+   connection is established by a client.
+4. Use ``uv_accept`` to accept the connection.
+5. Use :ref:`stream operations <buffers-and-streams>` to communicate with the
+   client.
+
+Here is a simple echo server
+
+.. rubric:: tcp-echo-server/main.c - The listen socket
+.. literalinclude:: ../../code/tcp-echo-server/main.c
+    :linenos:
+    :lines: 68-
+    :emphasize-lines: 4-5,7-10
+
+You can see the utility function ``uv_ip4_addr`` being used to convert from
+a human readable IP address, port pair to the sockaddr_in structure required by
+the BSD socket APIs. The reverse can be obtained using ``uv_ip4_name``.
+
+.. NOTE::
+
+    There are ``uv_ip6_*`` analogues for the ip4 functions.
+
+Most of the setup functions are synchronous since they are CPU-bound.
+``uv_listen`` is where we return to libuv's callback style. The second
+arguments is the backlog queue -- the maximum length of queued connections.
+
+When a connection is initiated by clients, the callback is required to set up
+a handle for the client socket and associate the handle using ``uv_accept``.
+In this case we also establish interest in reading from this stream.
+
+.. rubric:: tcp-echo-server/main.c - Accepting the client
+.. literalinclude:: ../../code/tcp-echo-server/main.c
+    :linenos:
+    :lines: 51-66
+    :emphasize-lines: 9-10
+
+The remaining set of functions is very similar to the streams example and can
+be found in the code. Just remember to call ``uv_close`` when the socket isn't
+required. This can be done even in the ``uv_listen`` callback if you are not
+interested in accepting the connection.
+
+Client
+++++++
+
+Where you do bind/listen/accept on the server, on the client side it's simply
+a matter of calling ``uv_tcp_connect``. The same ``uv_connect_cb`` style
+callback of ``uv_listen`` is used by ``uv_tcp_connect``. Try::
+
+    uv_tcp_t* socket = (uv_tcp_t*)malloc(sizeof(uv_tcp_t));
+    uv_tcp_init(loop, socket);
+
+    uv_connect_t* connect = (uv_connect_t*)malloc(sizeof(uv_connect_t));
+
+    struct sockaddr_in dest;
+    uv_ip4_addr("127.0.0.1", 80, &dest);
+
+    uv_tcp_connect(connect, socket, (const struct sockaddr*)&dest, on_connect);
+
+where ``on_connect`` will be called after the connection is established. The
+callback receives the ``uv_connect_t`` struct, which has a member ``.handle``
+pointing to the socket.
+
+UDP
+---
+
+The `User Datagram Protocol`_ offers connectionless, unreliable network
+communication. Hence libuv doesn't offer a stream. Instead libuv provides
+non-blocking UDP support via the `uv_udp_t` handle (for receiving) and
+`uv_udp_send_t` request (for sending) and related functions. That said, the
+actual API for reading/writing is very similar to normal stream reads. To look
+at how UDP can be used, the example shows the first stage of obtaining an IP
+address from a `DHCP`_ server -- DHCP Discover.
+
+.. note::
+
+    You will have to run `udp-dhcp` as **root** since it uses well known port
+    numbers below 1024.
+
+.. rubric:: udp-dhcp/main.c - Setup and send UDP packets
+.. literalinclude:: ../../code/udp-dhcp/main.c
+    :linenos:
+    :lines: 7-11,104-
+    :emphasize-lines: 8,10-11,17-18,21
+
+.. note::
+
+    The IP address ``0.0.0.0`` is used to bind to all interfaces. The IP
+    address ``255.255.255.255`` is a broadcast address meaning that packets
+    will be sent to all interfaces on the subnet.  port ``0`` means that the OS
+    randomly assigns a port.
+
+First we setup the receiving socket to bind on all interfaces on port 68 (DHCP
+client) and start a read on it. This will read back responses from any DHCP
+server that replies. We use the UV_UDP_REUSEADDR flag to play nice with any
+other system DHCP clients that are running on this computer on the same port.
+Then we setup a similar send socket and use ``uv_udp_send`` to send
+a *broadcast message* on port 67 (DHCP server).
+
+It is **necessary** to set the broadcast flag, otherwise you will get an
+``EACCES`` error [#]_. The exact message being sent is not relevant to this
+book and you can study the code if you are interested. As usual the read and
+write callbacks will receive a status code of < 0 if something went wrong.
+
+Since UDP sockets are not connected to a particular peer, the read callback
+receives an extra parameter about the sender of the packet.
+
+``nread`` may be zero if there is no more data to be read. If ``addr`` is NULL,
+it indicates there is nothing to read (the callback shouldn't do anything), if
+not NULL, it indicates that an empty datagram was received from the host at
+``addr``. The ``flags`` parameter may be ``UV_UDP_PARTIAL`` if the buffer
+provided by your allocator was not large enough to hold the data. *In this case
+the OS will discard the data that could not fit* (That's UDP for you!).
+
+.. rubric:: udp-dhcp/main.c - Reading packets
+.. literalinclude:: ../../code/udp-dhcp/main.c
+    :linenos:
+    :lines: 17-40
+    :emphasize-lines: 1,23
+
+UDP Options
++++++++++++
+
+Time-to-live
+~~~~~~~~~~~~
+
+The TTL of packets sent on the socket can be changed using ``uv_udp_set_ttl``.
+
+IPv6 stack only
+~~~~~~~~~~~~~~~
+
+IPv6 sockets can be used for both IPv4 and IPv6 communication. If you want to
+restrict the socket to IPv6 only, pass the ``UV_UDP_IPV6ONLY`` flag to
+``uv_udp_bind`` [#]_.
+
+Multicast
+~~~~~~~~~
+
+A socket can (un)subscribe to a multicast group using:
+
+.. code::block:: c
+
+    int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership);
+
+where ``membership`` is ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.
+
+The concepts of multicasting are nicely explained in `this guide`_.
+
+.. _this guide: https://www.tldp.org/HOWTO/Multicast-HOWTO-2.html
+
+Local loopback of multicast packets is enabled by default [#]_, use
+``uv_udp_set_multicast_loop`` to switch it off.
+
+The packet time-to-live for multicast packets can be changed using
+``uv_udp_set_multicast_ttl``.
+
+Querying DNS
+------------
+
+libuv provides asynchronous DNS resolution. For this it provides its own
+``getaddrinfo`` replacement [#]_. In the callback you can
+perform normal socket operations on the retrieved addresses. Let's connect to
+Freenode to see an example of DNS resolution.
+
+.. rubric:: dns/main.c
+.. literalinclude:: ../../code/dns/main.c
+    :linenos:
+    :lines: 61-
+    :emphasize-lines: 12
+
+If ``uv_getaddrinfo`` returns non-zero, something went wrong in the setup and
+your callback won't be invoked at all. All arguments can be freed immediately
+after ``uv_getaddrinfo`` returns. The `hostname`, `servname` and `hints`
+structures are documented in `the getaddrinfo man page <getaddrinfo>`_. The
+callback can be ``NULL`` in which case the function will run synchronously.
+
+In the resolver callback, you can pick any IP from the linked list of ``struct
+addrinfo(s)``. This also demonstrates ``uv_tcp_connect``. It is necessary to
+call ``uv_freeaddrinfo`` in the callback.
+
+.. rubric:: dns/main.c
+.. literalinclude:: ../../code/dns/main.c
+    :linenos:
+    :lines: 42-60
+    :emphasize-lines: 8,16
+
+libuv also provides the inverse `uv_getnameinfo`_.
+
+.. _uv_getnameinfo: http://docs.libuv.org/en/v1.x/dns.html#c.uv_getnameinfo
+
+Network interfaces
+------------------
+
+Information about the system's network interfaces can be obtained through libuv
+using ``uv_interface_addresses``. This simple program just prints out all the
+interface details so you get an idea of the fields that are available. This is
+useful to allow your service to bind to IP addresses when it starts.
+
+.. rubric:: interfaces/main.c
+.. literalinclude:: ../../code/interfaces/main.c
+    :linenos:
+    :emphasize-lines: 9,17
+
+``is_internal`` is true for loopback interfaces. Note that if a physical
+interface has multiple IPv4/IPv6 addresses, the name will be reported multiple
+times, with each address being reported once.
+
+.. _c-ares: https://c-ares.haxx.se
+.. _getaddrinfo: https://www.kernel.org/doc/man-pages/online/pages/man3/getaddrinfo.3.html
+
+.. _User Datagram Protocol: https://en.wikipedia.org/wiki/User_Datagram_Protocol
+.. _DHCP: https://tools.ietf.org/html/rfc2131
+
+----
+
+.. [#] https://beej.us/guide/bgnet/html/#broadcast-packetshello-world
+.. [#] on Windows only supported on Windows Vista and later.
+.. [#] https://www.tldp.org/HOWTO/Multicast-HOWTO-6.html#ss6.1
+.. [#] libuv use the system ``getaddrinfo`` in the libuv threadpool. libuv
+    v0.8.0 and earlier also included c-ares_ as an alternative, but this has been
+    removed in v0.9.0.