The Hackerlab at `regexps.com`

## A VU Handler for the URL Socket Scheme

up: libhackerlab next: Buffered File Descriptors prev: A VU Handler for the URL File-Descriptor Scheme

These functions provide VU namespace handlers for file-names that designate various kinds of sockets. By using these handlers, your programs can (almost) transparently handle filenames like:

         inet://myserver.host.com:10000

or

         unix:/tmp/.X11-unix/X0

Two kinds of sockets are available: server sockets and client sockets.

server sockets are created with `socket(2)` , `bind(2)` , and `listen(2)` . When `vu_open` is called, a call to `listen(2)` is made and the client connection (if any) is returned.

client sockets are created with `socket(2)` , `bind(2)` , and `connect(2)` .

Sockets may be named in either the `unix` or `inet` domains.

The syntax of these URLs is described in the documentation for `url_socket_push_client_handler` and `url_socket_push_socket_handler` .

Function `url_socket_push_client_handler`

    void url_socket_push_client_handler (enum url_socket_domains domains,
                                         int default_port,
                                         int is_optional);

Push a VU namespace handler for client sockets.

         Domains:                        File Name:
         ------------------------------------------------------------------
         url_socket_unix                 unix:$PATH
         url_socket_inet                 inet://$HOST[:$PORT]
         url_socket_inet_or_unix         unix:$PATH or inet://$HOST[:$PORT]

Note that the `$PATH` of a unix domain socket is subject to ~ expansion using `file_name_tilde_expand` .

(See file_name_tilde_expand.)

`default_port` is used for internet-domain sockets.

If `is_optional` is `0` , the handler is immediately added to the VU namespace. If `is_optional` is not `0` , the handler is added to the list of optional handlers and may be enabled by `vu_enable_optional_name_handler` .

(See vu_enable_optional_name_handler.)

         Domains:                        Optional Handler Name:
         ------------------------------------------------------------------
         url_socket_unix                 client/unix
         url_socket_inet                 client/inet
         url_socket_inet_or_unix         client/any

Function `url_socket_push_socket_handler`

    void url_socket_push_socket_handler
         (enum url_socket_domains domains,
          int server_flags,
          int may_be_client,
          int only_server_url,
          int default_port,
          int backlog,
          url_socket_server_callback server_callback,
          url_socket_connect_callback connection_callback,
          url_socket_server_close_callback server_close_callback,
          void * closure,
          is_optional);

Push a VU namespace handler for server sockets. After this call, a call to `vu_open` with a suitable file name will work by creating a socket.

`server_flags` may be any bitwise combination of:

                 O_NONBLOCK      # Don't block waiting for connections.

There are two kinds of file name patterns: those that can be used to name both clients and servers, and those that can only be used to name servers:

         server only:                    client or server:
         -------------------------------------------------
         unix-server:$PATH               unix:$PATH
         inet-server://$HOST[:$PORT]     inet://$HOST[:$PORT]

By default, both kinds of URL are accepted and interpreted as names of server sockets. Note that:

         `$PATH' of a unix domain socket is  subject to "~" expansion using
         `file_name_tilde_expand'.

         `$HOST' of an internet-domain socket may be `INADDR_LOOPBACK'.
         If the URL is the name of a server, `$HOST' may also be
         `INADDR_ANY'.  (See `inet(4)'.)

         `$PORT' of an internet-domain server may be 0, meaning that the
         system should assign a port number which will be reported in
         the server callback in the `server_addr' parameter (see below).

If `may_be_client` is not `0` , then accept both kinds of URLs, but interpret client or server URLs as naming client sockets (your process will open a connection to some other server).

If `only_server_url` is not `0` , then accept server only URLs, but not client or server URLs. In this case, `may_be_client` is ignored. This is especially useful in combination with `url_socket_push_client_handler` and other calls to `vu_push_name_handler` .

`default_port` is used when creating an internet-domain socket for which the port number was not specified in the file-name.

`backlog` is used for the call to `listen(2)` .

`server_callback` is called when a new server socket has been created successfully. It's arguments are explained below.

`connect_callback` is called when a new connection has been received. It's arguments are explained below.

`server_close_callback` is called when the server descriptor is closed. It's arguments are explained below.

`closure` is an opaque value passed to the callback functions.

If `is_optional` is `0` , the handler is immediately added to the VU namespace. If `is_optional` is non-0, the handler is added to the list of optional handlers and may be enabled by `vu_enable_optional_name_handler` .

      domain(s) only_server_url may_be_client         Optional Handler Name
      --------------------------------------------------------------------
      unix            0               0               server/unix
      inet            0               0               server/inet
      inet_or_unix    0               0               server/any
      unix            0               1               socket/unix
      inet            0               1               socket/inet
      inet_or_unix    0               1               socket/any
      unix            1               *               socket/unix-server
      inet            1               *               socket/inet-server
      inet_or_unix    1               *               socket/any-server

Calling Conventions for Callbacks

     typedef void (*url_socket_server_callback) (char * path,
                                                 int server_flags,
                                                 int flags,
                                                 int mode,
                                                 int server_fd,
                                                 struct sockaddr * server_addr,
                                                 int server_addr_len,
                                                 void * closure);

         `path' is the file name that caused the server socket to
         be created.

         `server_flags' is 0 or a bit-wise combination of `O_NONBLOCK'.

         `flags' is the `flags' parameter passed to `vu_open', if this
         server socket was created by a call to `vu_open', 0 otherwise.

         `mode' is the `mode' parameter passed to `vu_open', if this
         server socket was created by a call to `vu_open', 0 otherwise.

         `server_fd' is the descriptor number of the server socket.

         `server_addr' and `server_addr_len' is the address passed to
         `bind'.

         `closure' is the `closure' argument passed to
         `url_socket_push_socket_handler'.

     typedef void (*url_socket_connect_callback)
                 (char * path,
                  int flags,
                  int mode,
                  int server_fd,
                  int connection_fd,
                  struct sockaddr * client_addr,
                  int client_addr_len,
                  void * closure);

         `path' is the file name that caused the client connection to this
         server to be created.

         `flags' is the `flags' parameter passed to `vu_open'.

         `mode' is the `mode' parameter passed to `vu_open'.

         `server_fd' is the descriptor number of the server socket.

         `connection_fd' is the descriptor number of the client connection.

         `client_addr' and `client_addr_len' is the address from `accept'.

         `closure' is the `closure' argument passed to
         `url_socket_push_socket_handler'.

     typedef void (*url_socket_server_close_callback)
                 (int server_fd,
                  struct sockaddr * server_addr,
                  int server_addr_len,
                  void * closure);

         `server_fd' is the descriptor number of the server socket.

         `server_addr' and `server_addr_len' is the address passed to
         `bind'.

         `closure' is the `closure' argument passed to
         `url_socket_push_socket_handler'.

libhackerlab: The Hackerlab C Library
The Hackerlab at `regexps.com`