From 6d89e3e7fe7d6d2c7171de4b112a1c96743bc9c1 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Jan 2019 15:22:49 -0800 Subject: man page updates for tip --- man/tip/index.html | 110 +++++ man/tip/libnng.3.html | 92 ++++ man/tip/nng_http_client_connect.3http.html | 2 +- man/tip/nng_listen.3.html | 25 +- man/tip/nng_listener_start.3.html | 22 +- man/tip/nng_options.5.html | 174 +++++--- man/tip/nng_stat_value.3.html | 2 +- man/tip/nng_tcp.5.html | 656 ++++++++++++++++++++++++++++ man/tip/nng_tcp_close.3tcp.html | 615 ++++++++++++++++++++++++++ man/tip/nng_tcp_dialer.5.html | 593 +++++++++++++++++++++++++ man/tip/nng_tcp_dialer_alloc.3tcp.html | 590 +++++++++++++++++++++++++ man/tip/nng_tcp_dialer_close.3tcp.html | 604 ++++++++++++++++++++++++++ man/tip/nng_tcp_dialer_dial.3tcp.html | 642 +++++++++++++++++++++++++++ man/tip/nng_tcp_dialer_free.3tcp.html | 598 +++++++++++++++++++++++++ man/tip/nng_tcp_dialer_getopt.3tcp.html | 644 +++++++++++++++++++++++++++ man/tip/nng_tcp_dialer_setopt.3tcp.html | 639 +++++++++++++++++++++++++++ man/tip/nng_tcp_free.3tcp.html | 613 ++++++++++++++++++++++++++ man/tip/nng_tcp_getopt.3tcp.html | 646 +++++++++++++++++++++++++++ man/tip/nng_tcp_listener.5.html | 594 +++++++++++++++++++++++++ man/tip/nng_tcp_listener_accept.3tcp.html | 641 +++++++++++++++++++++++++++ man/tip/nng_tcp_listener_alloc.3tcp.html | 591 +++++++++++++++++++++++++ man/tip/nng_tcp_listener_close.3tcp.html | 604 ++++++++++++++++++++++++++ man/tip/nng_tcp_listener_free.3tcp.html | 597 +++++++++++++++++++++++++ man/tip/nng_tcp_listener_getopt.3tcp.html | 644 +++++++++++++++++++++++++++ man/tip/nng_tcp_listener_listen.3tcp.html | 637 +++++++++++++++++++++++++++ man/tip/nng_tcp_listener_setopt.3tcp.html | 639 +++++++++++++++++++++++++++ man/tip/nng_tcp_recv.3tcp.html | 673 +++++++++++++++++++++++++++++ man/tip/nng_tcp_send.3tcp.html | 672 ++++++++++++++++++++++++++++ man/tip/nng_tcp_setopt.3tcp.html | 635 +++++++++++++++++++++++++++ 29 files changed, 14082 insertions(+), 112 deletions(-) create mode 100644 man/tip/nng_tcp.5.html create mode 100644 man/tip/nng_tcp_close.3tcp.html create mode 100644 man/tip/nng_tcp_dialer.5.html create mode 100644 man/tip/nng_tcp_dialer_alloc.3tcp.html create mode 100644 man/tip/nng_tcp_dialer_close.3tcp.html create mode 100644 man/tip/nng_tcp_dialer_dial.3tcp.html create mode 100644 man/tip/nng_tcp_dialer_free.3tcp.html create mode 100644 man/tip/nng_tcp_dialer_getopt.3tcp.html create mode 100644 man/tip/nng_tcp_dialer_setopt.3tcp.html create mode 100644 man/tip/nng_tcp_free.3tcp.html create mode 100644 man/tip/nng_tcp_getopt.3tcp.html create mode 100644 man/tip/nng_tcp_listener.5.html create mode 100644 man/tip/nng_tcp_listener_accept.3tcp.html create mode 100644 man/tip/nng_tcp_listener_alloc.3tcp.html create mode 100644 man/tip/nng_tcp_listener_close.3tcp.html create mode 100644 man/tip/nng_tcp_listener_free.3tcp.html create mode 100644 man/tip/nng_tcp_listener_getopt.3tcp.html create mode 100644 man/tip/nng_tcp_listener_listen.3tcp.html create mode 100644 man/tip/nng_tcp_listener_setopt.3tcp.html create mode 100644 man/tip/nng_tcp_recv.3tcp.html create mode 100644 man/tip/nng_tcp_send.3tcp.html create mode 100644 man/tip/nng_tcp_setopt.3tcp.html diff --git a/man/tip/index.html b/man/tip/index.html index 6734431d..995710ec 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -446,6 +446,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Section 3compat: Compatible Library Functions
  • Section 3http: Supplemental HTTP Functions
  • Section 3supp: Supplemental Functions
  • +
  • Section 3tcp: Supplemental TCP Functions
  • Section 3tls: Supplemental TLS Functions
  • Section 5: Macros and Types
  • Section 7: Protocols and Transports
  • @@ -1490,6 +1491,103 @@ mutual exclusion locks, threading, time keeping, and similar needs.

    +

    Section 3tcp: Supplemental TCP Functions

    +
    +
    +

    This section documents supplemental TCP functions that are available.

    +
    +
    +

    These functions are made available to facilitate using raw TCP connections +with the NNG asynchronous I/O API. +Most applications should never need to use these functions.

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    nng_tcp_close(3tcp)

    close TCP connection

    nng_tcp_dialer_alloc(3tcp)

    allocate TCP dialer

    nng_tcp_dialer_close(3tcp)

    close TCP dialer

    nng_tcp_dialer_dial(3tcp)

    initiate outgoing TCP connection

    nng_tcp_dialer_free(3tcp)

    free TCP dialer

    nng_tcp_dialer_getopt(3tcp)

    get option from TCP dialer

    nng_tcp_dialer_setopt(3tcp)

    set option on TCP dialer

    nng_tcp_free(3tcp)

    free TCP connection

    nng_tcp_getopt(3tcp)

    get option from TCP connection

    nng_tcp_listener_accept(3tcp)

    accept incoming TCP connection

    nng_tcp_listener_alloc(3tcp)

    allocate TCP listener

    nng_tcp_listener_close(3tcp)

    close TCP listener

    nng_tcp_listener_free(3tcp)

    free TCP listener

    nng_tcp_listener_getopt(3tcp)

    get option from TCP listener

    nng_tcp_listener_listen(3tcp)

    bind listener to TCP port

    nng_tcp_listener_setopt(3tcp)

    set option on TCP listener

    nng_tcp_recv(3tcp)

    receive from TCP connection

    nng_tcp_send(3tcp)

    send to TCP connection

    nng_tcp_setopt(3tcp)

    set option on TCP connection

    +
    +
    +

    Section 3tls: Supplemental TLS Functions

    @@ -1639,6 +1737,18 @@ applications need will use.

    nng_stat(5)

    statistic

    + +

    nng_tcp(5)

    +

    TCP connection

    + + +

    nng_tcp_dialer(5)

    +

    TCP dialer

    + + +

    nng_tcp_listener(5)

    +

    TCP listener

    +
    diff --git a/man/tip/libnng.3.html b/man/tip/libnng.3.html index 5db6dc73..2d374ca0 100644 --- a/man/tip/libnng.3.html +++ b/man/tip/libnng.3.html @@ -526,6 +526,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Statistics
  • URL Object
  • Supplemental API
  • +
  • Supplemental TCP
  • HTTP Support
  • TLS Configuration Objects
  • @@ -1317,6 +1318,97 @@ as a convenience to aid in creating portable applications.

    +

    Supplemental TCP

    +
    +

    These TCP functions are available for use with direct TCP access. +Most applications won’t need to use these.

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    nng_tcp_close()

    close TCP connection

    nng_tcp_dialer_alloc()

    allocate TCP dialer

    nng_tcp_dialer_close()

    close TCP dialer

    nng_tcp_dialer_dial()

    initiate outgoing TCP connection

    nng_tcp_dialer_free()

    free TCP dialer

    nng_tcp_dialer_getopt()

    get option from TCP dialer

    nng_tcp_dialer_setopt()

    set option on TCP dialer

    nng_tcp_free()

    free TCP connection

    nng_tcp_getopt()

    get option from TCP connection

    nng_tcp_listener_accept()

    accept incoming TCP connection

    nng_tcp_listener_alloc()

    allocate TCP listener

    nng_tcp_listener_close()

    close TCP listener

    nng_tcp_listener_free()

    free TCP listener

    nng_tcp_listener_getopt()

    get option from TCP listener

    nng_tcp_listener_listen()

    bind TCP listener to port

    nng_tcp_listener_setopt()

    set option on TCP listener

    nng_tcp_recv()

    receive from TCP connection

    nng_tcp_send()

    send to TCP connection

    nng_tcp_setopt()

    set option on TCP connection

    +
    +

    HTTP Support

    The library may be configured with support for HTTP, and this will diff --git a/man/tip/nng_http_client_connect.3http.html b/man/tip/nng_http_client_connect.3http.html index 337b0d61..7054f4e3 100644 --- a/man/tip/nng_http_client_connect.3http.html +++ b/man/tip/nng_http_client_connect.3http.html @@ -578,7 +578,7 @@ obtained by NNG_EADDRINVAL -

    The server is configured with an invalid address.

    +

    The client is configured with an invalid address.

    diff --git a/man/tip/nng_listen.3.html b/man/tip/nng_listen.3.html index 2a99e3cf..af26efdc 100644 --- a/man/tip/nng_listen.3.html +++ b/man/tip/nng_listen.3.html @@ -554,6 +554,9 @@ An incoming connection generally results in and Unlike dialers, listeners generally can create many pipes, which may be open concurrently.

    +
    +

    The flags argument is ignored, but reserved for future use.

    +
    @@ -572,28 +575,6 @@ It may even have some of each at the same time!
    -

    Normally, the act of “binding” to the address indicated by url is done -synchronously, including any necessary name resolution. -As a result, a failure, such as if the address is already in use, will be -returned immediately. -However, if the special value NNG_FLAG_NONBLOCK is supplied in flags, -then this is done asynchronously; furthermore any -failure to bind will be periodically reattempted in the background.

    -
    -
    - - - - - -
    - - -While NNG_FLAG_NONBLOCK can help an application be more resilient, -it also generally makes diagnosing failures somewhat more difficult. -
    -
    -

    Because the listener is started immediately, it is generally not possible to apply extra configuration; if that is needed applications should consider using nng_listener_create() and diff --git a/man/tip/nng_listener_start.3.html b/man/tip/nng_listener_start.3.html index 63e02fd6..7934a2b0 100644 --- a/man/tip/nng_listener_start.3.html +++ b/man/tip/nng_listener_start.3.html @@ -551,27 +551,7 @@ Each new connection results in an nng_pipe which will be attached to the listener’s socket.

    -

    Normally, the act of “binding” to its address is done -synchronously, including any necessary name resolution. -As a result, -a failure, such as if the address is already in use, will be returned -immediately. -However, if the special value NNG_FLAG_NONBLOCK is -supplied in flags, then this is done asynchronously; furthermore any -failure to bind will be periodically reattempted in the background.

    -
    -
    - - - - - -
    - - -While NNG_FLAG_NONBLOCK can help an application be more resilient, -it also generally makes diagnosing failures somewhat more difficult. -
    +

    The flags argument is ignored, but reserved for future use.

    Once a listener has started, it is generally not possible to change diff --git a/man/tip/nng_options.5.html b/man/tip/nng_options.5.html index 3a100634..6d9c46a2 100644 --- a/man/tip/nng_options.5.html +++ b/man/tip/nng_options.5.html @@ -567,25 +567,28 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b retrieved on objects in the nng library.

    -

    Sockets (nng_socket objects) use the functions -nng_getopt() -and nng_setopt() to set and retrieve option values.

    +

    Sockets (nng_socket objects) use the functions +nng_getopt() +and nng_setopt() to set and retrieve option values.

    -

    Dialers (nng_dialer objects) use the functions -nng_dialer_getopt() and -nng_dialer_setopt() to set and retrieve option +

    Dialers (nng_dialer objects) use the functions +nng_dialer_getopt() and +nng_dialer_setopt() to set and retrieve option values.

    -

    Listeners (nng_listener objects) use the functions -nng_listener_getopt() -and nng_listener_setopt() to set and +

    Listeners (nng_listener objects) use the functions +nng_listener_getopt() +and nng_listener_setopt() to set and retrieve option values.

    -

    Pipes (nng_pipe objects) can only retrieve option values using -the nng_pipe_getopt() function.

    +

    Pipes (nng_pipe objects) can only retrieve option values using +the nng_pipe_getopt() function.

    +
    +
    +

    Other object types may have additional methods to access these options.

    In addition to the options listed here, transports and protocols will generally @@ -607,11 +610,28 @@ description of the option.

    NNG_OPT_LOCADDR
    -

    (nng_sockaddr) +

    (nng_sockaddr) This read-only option may be used on listeners, dialers and connected pipes, and -represents the local address used for communication. -Not all transports support this option, and some transports may support it -listeners but not dialers.

    +represents the local address used for communication.

    +
    + + + + + +
    + + +Not all transports support this option, and some transports may support it on +listeners but not dialers. +
    +
    +
    +

    When used on a TCP dialer, this option is used to configure the source IP +address that will be used when initiating outgoing connections. +The specific port number will be ignored, however, and the system will +choose a random ephemeral port instead.

    +
    @@ -624,13 +644,15 @@ listeners but not dialers.

    (bool) This read-only option indicates whether the socket is in “raw” mode. If true, the socket is in “raw” mode, and if false the socket is -in “cooked” mode. -Raw mode sockets generally do not have any protocol-specific semantics applied +in “cooked” mode.

    +
    +

    Raw mode sockets generally do not have any protocol-specific semantics applied to them; instead the application is expected to perform such semantics itself. (For example, in “cooked” mode a rep socket would automatically copy message headers from a received message to the corresponding reply, whereas in “raw” mode this is not done.) See Raw Mode for more details.

    +
    @@ -639,7 +661,7 @@ See Raw Mode for more details.

    NNG_OPT_RECONNMINT

    -(nng_duration) +(nng_duration) This is the minimum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. This can be set on a socket, but it can also be overridden on an individual @@ -654,7 +676,7 @@ The option is irrelevant for listeners.

    -(nng_duration) +(nng_duration) This is the maximum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. @@ -702,9 +724,6 @@ This descriptor will be readable when a message is available fo on the socket. When no message is ready for receiving, then this file descriptor will not be readable.

    -
    - -
    @@ -728,11 +747,14 @@ returned file descriptor. While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. -See nng_aio_alloc(). +See nng_aio_alloc().
    + + +
    NNG_OPT_RECVMAXSZ
    @@ -748,9 +770,6 @@ where a malicious agent can claim to want to send an extraordinarily large message, without sending any data. This option can be set for the socket, but may be overridden for on a per-dialer or per-listener basis.

    - -
    -
    @@ -758,18 +777,21 @@ per-dialer or per-listener basis.

    -Some transports may have further message size restrictions! +Some transports may have further message size restrictions.
    + + +
    NNG_OPT_RECVTIMEO

    -(nng_duration) +(nng_duration) This is the socket receive timeout in milliseconds. When no message is available for receiving at the socket for this period of time, receive operations will fail with a return value of NNG_ETIMEDOUT.

    @@ -780,7 +802,7 @@ time, receive operations will fail with a return value of NNG_ETIMEDOUT
    NNG_OPT_REMADDR
    -

    (nng_sockaddr) +

    (nng_sockaddr) This read-only option may be used on dialers and connected pipes, and represents the address of a remote peer. Not all transports support this option.

    @@ -798,9 +820,6 @@ This is the depth of the socket send buffer as a number of messages. Messages sent by an application may be buffered by the socket until a transport is ready to accept them for delivery. This value must be an integer between 0 and 8192, inclusive.

    -
    -
    -
    @@ -815,6 +834,9 @@ simply discard messages when they cannot be delivered immediately.
    + + +
    NNG_OPT_SENDFD
    @@ -829,13 +851,12 @@ for use with select(), (or on Windows systems WSAPoll()) -and similar functions. -This descriptor will be readable when the socket is able to accept a +and similar functions.

    +
    +

    This descriptor will be readable when the socket is able to accept a message for sending without blocking. When the socket is no longer able to accept such messages without blocking, the descriptor will not be readable.

    - -
    @@ -845,7 +866,7 @@ the descriptor will not be readable.

    Applications should never attempt to read or write to the -returned file descriptor. +returned file descriptor; use should be limited to polling system calls only.
    @@ -860,18 +881,21 @@ returned file descriptor. While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. -See nng_aio_alloc(). +See nng_aio_alloc().
    + + +
    NNG_OPT_SENDTIMEO

    -(nng_duration) +(nng_duration) This is the socket send timeout in milliseconds. When a message cannot be queued for delivery by the socket for this period of time (such as if send buffers are full), the operation will fail with a @@ -888,7 +912,9 @@ return value of NNG_ETIMEDOUT.

    This the socket name. By default this is a string corresponding to the value of the socket. The string must fit within 64-bytes, including the terminating -NUL byte, but it can be changed for other application uses.

    +NUL byte. +The value is intended for application use, and is not used for anything +in the library itself.

    @@ -898,13 +924,10 @@ The string must fit within 64-bytes, including the terminating

    (int) -This is the maximum number of “hops” a message may traverse (see -nng_device()). +This is the maximum number of “hops” a message may traverse across +a nng_device() forwarders. The intention here is to prevent forwarding loops in device chains. When this is supported, it can have a value between 1 and 255, inclusive.

    -
    - -
    @@ -933,6 +956,9 @@ this option.
    + + +
    NNG_OPT_URL
    @@ -943,9 +969,6 @@ this option. This read-only option is used to obtain the URL with which a listener or dialer was configured. Accordingly it can only be used with dialers, listeners, and pipes.

    - -
    -
    @@ -959,6 +982,9 @@ application.
    + + +
    NNG_OPT_PROTO
    @@ -1003,16 +1029,7 @@ the socket.

    (bool) This option is used to disable (or enable) the use of Nagle’s algorithm -for TCP connections. -When true (the default), messages are sent immediately by the underlying -TCP stream without waiting to gather more data. -When false, Nagle’s algorithm is enabled, and the TCP stream may -wait briefly in attempt to coalesce messages. -Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, -but it comes at a cost to latency.

    -
    -
    -
    +for TCP connections.

    @@ -1026,6 +1043,23 @@ See the transport documentation for each transport for details.
    +
    +

    When true (the default), messages are sent immediately by the underlying +TCP stream without waiting to gather more data.

    +
    +
    +

    When false, Nagle’s algorithm is enabled, and the TCP stream may +wait briefly in attempt to coalesce messages. +Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, +but it comes at a cost to latency.

    +
    +
    +

    When used on a dialer or a listener, the value affects how newly +created connections will be configured.

    +
    + + +
    NNG_OPT_TCP_KEEPALIVE
    @@ -1033,15 +1067,7 @@ See the transport documentation for each transport for details.

    (bool) This option is used to enable the sending of keep-alive messages on the underlying TCP stream. -This option is false by default. -When enabled, if no messages are seen for a period of time, then -a zero length TCP message is sent with the ACK flag set in an attempt -to tickle some traffic from the peer. -If none is still seen (after some platform-specific number of retries and -timeouts), then the remote peer is presumed dead, and the connection is closed.

    - -
    -
    +This option is false by default.

    @@ -1055,6 +1081,17 @@ See the transport documentation for each transport for details.
    +
    +

    When enabled, if no messages are seen for a period of time, then +a zero length TCP message is sent with the ACK flag set in an attempt +to tickle some traffic from the peer. +If none is still seen (after some platform-specific number of retries and +timeouts), then the remote peer is presumed dead, and the connection is closed.

    +
    +
    +

    When used on a dialer or a listener, the value affects how newly +created connections will be configured.

    +
    @@ -1070,6 +1107,9 @@ middleware from being expiring due to lack of activity.
    + + + diff --git a/man/tip/nng_stat_value.3.html b/man/tip/nng_stat_value.3.html index 6e4a8560..4e7beee6 100644 --- a/man/tip/nng_stat_value.3.html +++ b/man/tip/nng_stat_value.3.html @@ -547,7 +547,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b If the statistic has a boolean value, then zero is returned for false, and one is returned for true. Otherwise, if the string is not of numeric type, then zero is returned. -See nng_stat_type(3) for a description of statistic types.

    +See nng_stat_type() for a description of statistic types.

    diff --git a/man/tip/nng_tcp.5.html b/man/tip/nng_tcp.5.html new file mode 100644 index 00000000..7b916dec --- /dev/null +++ b/man/tip/nng_tcp.5.html @@ -0,0 +1,656 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp(5) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +typedef struct nng_tcp_s nng_tcp;
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    An nng_tcp represents a connected stream. +TCP stream objects can be used to send or receive data.

    +
    +
    + + + + + +
    + + +The nng_tcp object is used for raw TCP connections, and +should not be confused with a pipe object created using the +nng_tcp(7) transport. +
    +
    +
    + + + + + +
    + + +Most NNG applications should not use this, but instead use the +nng_tcp(7) transport instead. +
    +
    +
    +

    These objects are created either establishing an outgoing connection +with nng_tcp_dialer_dial() or by +accepting in incoming connection with +nng_tcp_listener_accept().

    +
    +
    +

    TCP connections are byte streams, and are “reliable” in that data +will not be delivered out of order, or with portions missing.

    +
    +
    +

    Data can be sent using nng_tcp_send() or +received with nng_tcp_recv().

    +
    +
    +

    When the connection is no longer needed, it should be freed with +nng_tcp_free().

    +
    +
    + + + + + +
    + + +It is possible to close the connection, without freeing it, by +using nng_tcp_close(). +
    +
    +
    +

    Options

    +
    +

    The following options are applicable to TCP connections, and may be +accessed using the nng_tcp_getopt() and +nng_tcp_setopt() functions.

    +
    + +
    +

    Other platform specific options may be available as well.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_close.3tcp.html b/man/tip/nng_tcp_close.3tcp.html new file mode 100644 index 00000000..b2879d14 --- /dev/null +++ b/man/tip/nng_tcp_close.3tcp.html @@ -0,0 +1,615 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_close(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_close(nng_tcp *conn);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_close() function closes the supplied TCP connection, conn.

    +
    +
    +

    If any operations are pending (such as nng_tcp_send() +or nng_tcp_recv() they will be terminated with +an NNG_ECLOSED error condition. +Also, any new operations will fail with NNG_ECLOSED after the connection +is closed.

    +
    +
    + + + + + +
    + + +Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +
    +
    +
    + + + + + +
    + + +Closing the connection does not free the resources associated with it. +Once it is certain that no more operations are pending on the connection, +it should be freed with nng_tcp_free(). +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer.5.html b/man/tip/nng_tcp_dialer.5.html new file mode 100644 index 00000000..03c39184 --- /dev/null +++ b/man/tip/nng_tcp_dialer.5.html @@ -0,0 +1,593 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer(5) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +typedef struct nng_tcp_dialer_s nng_tcp_dialer;
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    +An nng_tcp_dialer is a handle to a TCP “dialer”, which is responsible for +creating a connections (nng_tcp objects) by connecting to +remote systems.

    +
    +
    + + + + + +
    + + +The nng_tcp_dialer object is used for raw TCP connections, and +should not be confused with a dialer object created using the +nng_tcp(7) transport. +
    +
    +
    + + + + + +
    + + +Most NNG applications should not use this, but instead use the +nng_tcp transport instead. +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_alloc.3tcp.html b/man/tip/nng_tcp_dialer_alloc.3tcp.html new file mode 100644 index 00000000..742192b8 --- /dev/null +++ b/man/tip/nng_tcp_dialer_alloc.3tcp.html @@ -0,0 +1,590 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_alloc(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_dialer_alloc(nng_tcp_dialer *dp);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_alloc() allocates a TCP dialer, which can be used +to create outgoing connections over TCP, and stores a pointer to it +it in the location referenced by dp.

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + +
    +NNG_ENOMEM + +

    Insufficient free memory exists.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_close.3tcp.html b/man/tip/nng_tcp_dialer_close.3tcp.html new file mode 100644 index 00000000..6caa4f1f --- /dev/null +++ b/man/tip/nng_tcp_dialer_close.3tcp.html @@ -0,0 +1,604 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_close(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_dialer_close(nng_tcp_dialer *d);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_close() function closes the supplied TCP dialer d, +but does not free the underlying resources associated with it.

    +
    +
    +

    If any dial operations +(see nng_tcp_dialer_dial()) using d are +in progress, they will be terminated with an NNG_ECLOSED error condition.

    +
    +
    +

    Furthermore any future accesses to the dialer d will also result in +NNG_ECLOSED.

    +
    +
    + + + + + +
    + + +This function does not release the memory for the dialer, so the +application should still free the memory using +nng_tcp_dialer_free(3tcp) +once it is certain that nothing else is using it. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_dial.3tcp.html b/man/tip/nng_tcp_dialer_dial.3tcp.html new file mode 100644 index 00000000..662fbd94 --- /dev/null +++ b/man/tip/nng_tcp_dialer_dial.3tcp.html @@ -0,0 +1,642 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_dial(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_dialer_dial(nng_tcp_dialer *d, const nng_sockaddr *sa, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_dial() attempts to establish a TCP connection to the +remote peer identified by sa, using the dialer d. +The operation is completed asynchronously, using aio.

    +
    +
    +

    The address sa must be in the NNG_AF_INET or NNG_AF_INET6 families, +and have a valid IPv4 or IPv6 address and TCP port number.

    +
    +
    +

    If a connection is successfully established, the aio will have the +resulting nng_tcp stored as its first output. +(See nng_aio_get_output().)

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    +NNG_EADDRINVAL + +

    The address specified is invalid.

    +
    +NNG_ECANCELED + +

    The operation was aborted.

    +
    +NNG_ECLOSED + +

    The dialer is closed.

    +
    +NNG_ECONNREFUSED + +

    The TCP connection was refused by the server.

    +
    +NNG_ECONNRESET + +

    The TCP connection was reset by the server.

    +
    +NNG_ENOMEM + +

    Insufficient free memory exists.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_free.3tcp.html b/man/tip/nng_tcp_dialer_free.3tcp.html new file mode 100644 index 00000000..9ef9b47e --- /dev/null +++ b/man/tip/nng_tcp_dialer_free.3tcp.html @@ -0,0 +1,598 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_free(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_dialer_free(nng_tcp_dialer *d);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_free() function closes the supplied TCP dialer d, +and frees the underlying resources associated with it.

    +
    +
    +

    If any dial operations +(see nng_tcp_dialer_dial()) using d are +in progress, they will be terminated with an NNG_ECLOSED error condition.

    +
    +
    + + + + + +
    + + +It is important that the application ensure that no further accesses +are made to d, as the memory backing it will be reclaimed for other uses. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_getopt.3tcp.html b/man/tip/nng_tcp_dialer_getopt.3tcp.html new file mode 100644 index 00000000..ae7d1b73 --- /dev/null +++ b/man/tip/nng_tcp_dialer_getopt.3tcp.html @@ -0,0 +1,644 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_getopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_getopt(nng_tcp_dialer *d, const char *name, void *data, size_t *sizep);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_getopt() is used to retrieve the value of the option name for the TCP dialer d. +The size of the buffer located at data to receive the copy is passed by the +caller at the location referenced by sizep. +If this size is sufficient to hold the entire object, the object is copied into +the buffer specified by data. +In either event, the size of the source object (the amount of data copied, +or that would have been copied if sufficient space were available) is stored +at the location of sizep.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for retrieval from TCP dialers are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The dialer is closed.

    +
    +NNG_EINVAL + +

    There was insufficient space to receive the object. +The amount of data actually needed is returned in sizep.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EWRITEONLY + +

    The option name may not read.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_dialer_setopt.3tcp.html b/man/tip/nng_tcp_dialer_setopt.3tcp.html new file mode 100644 index 00000000..41a6cb82 --- /dev/null +++ b/man/tip/nng_tcp_dialer_setopt.3tcp.html @@ -0,0 +1,639 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_dialer_setopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_dialer_setopt(nng_tcp_dialer *d, const char *name, const void *data, size_t size);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_dialer_setopt() is used to set the option name for the +TCP dialer d. +The value to set is copied from data, which should be size bytes +in length.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for modification on TCP dialers are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The dialer is closed.

    +
    +NNG_EINVAL + +

    Either data or size are invalid.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EREADONLY + +

    The option name may not be modified.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_free.3tcp.html b/man/tip/nng_tcp_free.3tcp.html new file mode 100644 index 00000000..a6699416 --- /dev/null +++ b/man/tip/nng_tcp_free.3tcp.html @@ -0,0 +1,613 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_free(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_free(nng_tcp *conn);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_free() function closes the supplied TCP connection, conn, +and frees the underlying resources associated with it.

    +
    +
    +

    If any operations are pending (such as nng_tcp_send() +or nng_tcp_recv() they will be terminated with +an NNG_ECLOSED error condition.

    +
    +
    + + + + + +
    + + +It is important that the application ensure that no further accesses +are made to conn, as the memory backing it will be reclaimed for other uses. +
    +
    +
    + + + + + +
    + + +Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_getopt.3tcp.html b/man/tip/nng_tcp_getopt.3tcp.html new file mode 100644 index 00000000..18011ea6 --- /dev/null +++ b/man/tip/nng_tcp_getopt.3tcp.html @@ -0,0 +1,646 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_getopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_getopt(nng_tcp *conn, const char *name, void *data, size_t *sizep);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_getopt() is used to retrieve the value of the option name for +the TCP connection conn. +The size of the buffer located at data to receive the copy is passed by the +caller at the location referenced by sizep. +If this size is sufficient to hold the entire object, the object is copied into +the buffer specified by data. +In either event, the size of the source object (the amount of data copied, +or that would have been copied if sufficient space were available) is stored +at the location of sizep.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for retrieval from TCP connections are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The connection conn is closed.

    +
    +NNG_EINVAL + +

    There was insufficient space to receive the object. +The amount of data actually needed is returned in sizep.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EWRITEONLY + +

    The option name may not read.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener.5.html b/man/tip/nng_tcp_listener.5.html new file mode 100644 index 00000000..ff4d3005 --- /dev/null +++ b/man/tip/nng_tcp_listener.5.html @@ -0,0 +1,594 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener(5) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +typedef struct nng_tcp_dialer_s nng_tcp_dialer;
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    +An nng_tcp_listener is a handle to a TCP “listener”, which is responsible +for accepting connections (nng_tcp objects) from remote +systems.

    +
    +
    + + + + + +
    + + +The nng_tcp_listener object is used for raw TCP connections, and +should not be confused with a listener object created using the +nng_tcp(7) transport. +
    +
    +
    + + + + + +
    + + +Most NNG applications should not use this, but instead use the +nng_tcp transport instead. +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_accept.3tcp.html b/man/tip/nng_tcp_listener_accept.3tcp.html new file mode 100644 index 00000000..b25cf27a --- /dev/null +++ b/man/tip/nng_tcp_listener_accept.3tcp.html @@ -0,0 +1,641 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_accept(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_listener_accept(nng_tcp_listener *l, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_accept() attempts to accept an incoming TCP connection +from a remote peer, using the listener l. +The operation is completed asynchronously, using aio.

    +
    +
    +

    This operation can only be done after the listener is already bound to +a TCP port and is listening. +(See nng_tcp_listener_listen().)

    +
    +
    +

    If a connection is successfully established, the aio will have the +resulting nng_tcp stored as its first output. +(See nng_aio_get_output().)

    +
    +
    +

    The address of the remote peer can be determined using the +NNG_OPT_REMADDR option with the +nng_tcp_getopt() function on the +returned nng_tcp.

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + + + + + +
    +NNG_ECANCELED + +

    The operation was aborted.

    +
    +NNG_ECLOSED + +

    The dialer is closed.

    +
    +NNG_ECONNRESET + +

    The TCP connection was reset by the peer.

    +
    +NNG_ENOMEM + +

    Insufficient free memory exists.

    +
    +NNG_ESTATE + +

    The listener is not not listening.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_alloc.3tcp.html b/man/tip/nng_tcp_listener_alloc.3tcp.html new file mode 100644 index 00000000..81349afd --- /dev/null +++ b/man/tip/nng_tcp_listener_alloc.3tcp.html @@ -0,0 +1,591 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_alloc(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_listener_alloc(nng_tcp_listener *lp);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_alloc() allocates a TCP listener, which can be used +to accept incoming connections over TCP, and stores a pointer to it +it in the location referenced by lp.

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + +
    +NNG_ENOMEM + +

    Insufficient free memory exists.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_close.3tcp.html b/man/tip/nng_tcp_listener_close.3tcp.html new file mode 100644 index 00000000..7ea7e663 --- /dev/null +++ b/man/tip/nng_tcp_listener_close.3tcp.html @@ -0,0 +1,604 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_close(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_listener_close(nng_tcp_listener *l);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_close() function closes the supplied TCP listener l, +but does not free the underlying resources associated with it.

    +
    +
    +

    If any acceppt operations +(see nng_tcp_listener_accept()) using l +are in progress, they will be terminated with an NNG_ECLOSED error condition.

    +
    +
    +

    Furthermore any future accesses to the listener l will also result in +NNG_ECLOSED.

    +
    +
    + + + + + +
    + + +This function does not release the memory for the listener, so the +application should still free the memory using +nng_tcp_listener_free(3tcp) +once it is certain that nothing else is using it. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_free.3tcp.html b/man/tip/nng_tcp_listener_free.3tcp.html new file mode 100644 index 00000000..bb769cda --- /dev/null +++ b/man/tip/nng_tcp_listener_free.3tcp.html @@ -0,0 +1,597 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_free(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_listener_free(nng_tcp_listener *l);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_free() function closes the supplied TCP listener l, +and frees the underlying resources associated with it.

    +
    +
    +

    If any accept operations +(see nng_tcp_listener_accept()) using l +are in progress, they will be terminated with an NNG_ECLOSED error condition.

    +
    +
    + + + + + +
    + + +It is important that the application ensure that no further accesses +are made to l, as the memory backing it will be reclaimed for other uses. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_getopt.3tcp.html b/man/tip/nng_tcp_listener_getopt.3tcp.html new file mode 100644 index 00000000..77a0c812 --- /dev/null +++ b/man/tip/nng_tcp_listener_getopt.3tcp.html @@ -0,0 +1,644 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_getopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_listener_getopt(nng_tcp_listener *l, const char *name, void *data, size_t *sizep);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_getopt() is used to retrieve the value of the option name for the TCP listener l. +The size of the buffer located at data to receive the copy is passed by the +caller at the location referenced by sizep. +If this size is sufficient to hold the entire object, the object is copied into +the buffer specified by data. +In either event, the size of the source object (the amount of data copied, +or that would have been copied if sufficient space were available) is stored +at the location of sizep.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for retrieval from TCP listeners are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The dialer is closed.

    +
    +NNG_EINVAL + +

    There was insufficient space to receive the object. +The amount of data actually needed is returned in sizep.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EWRITEONLY + +

    The option name may not read.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_listen.3tcp.html b/man/tip/nng_tcp_listener_listen.3tcp.html new file mode 100644 index 00000000..0ab34e69 --- /dev/null +++ b/man/tip/nng_tcp_listener_listen.3tcp.html @@ -0,0 +1,637 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_listen(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_listener_listen(nng_tcp_listener l, const nng_sockaddr *sa);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_listen() attempts to bind the listener l +to the local address specified by sa, which must be in the +NNG_AF_INET or NNG_AF_INET6 address family.

    +
    +
    +

    This also sets the underlying port into passive mode, ready to +accept an incoming connection, and established a listen queue +for receiving incoming connections. (The queue depth is system +specific, but typically 128.)

    +
    +
    +

    The actual IPv4 or IPv6 address in sa may refer either to a locally +configured interface address, or to a zero-valued adddress to indicate +that all interfaces on the system should be bound.

    +
    +
    +

    The TCP port number may also be zero. In this case the system will +choose a free TCP port at random, and use it.

    +
    +
    +

    The chosen port number may be retrieved using the +NNG_OPT_LOCADDR option with the +nng_tcp_listener_getopt() function.

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_EADDRINUSE + +

    The address specified by sa is already in use.

    +
    +NNG_EADDRINVAL + +

    The address specified by sa is invalid or unavailable.

    +
    +NNG_ECLOSED + +

    The listener l has been closed.

    +
    +NNG_ESTATE + +

    The listener l is already bound.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_listener_setopt.3tcp.html b/man/tip/nng_tcp_listener_setopt.3tcp.html new file mode 100644 index 00000000..40f178dc --- /dev/null +++ b/man/tip/nng_tcp_listener_setopt.3tcp.html @@ -0,0 +1,639 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_listener_setopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_listener_setopt(nng_tcp_listener *l, const char *name, const void *data, size_t size);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_listener_setopt() is used to set the option name for the +TCP listener l. +The value to set is copied from data, which should be size bytes +in length.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for modification on TCP listeners are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The listener is closed.

    +
    +NNG_EINVAL + +

    Either data or size are invalid.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EREADONLY + +

    The option name may not be modified.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_recv.3tcp.html b/man/tip/nng_tcp_recv.3tcp.html new file mode 100644 index 00000000..a8cd6b1c --- /dev/null +++ b/man/tip/nng_tcp_recv.3tcp.html @@ -0,0 +1,673 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_recv(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_recv(nng_tcp *conn, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_recv() function starts an asynchronous receive from the +TCP connection conn, into the scatter/gather vector located in the +asynchronous I/O structure aio.

    +
    +
    + + + + + +
    + + +The nng_aio_set_iov() function must have been +called first, to set the scatter/gather vector for aio. +
    +
    +
    +

    This function returns immediately, with no return value. +Completion of the operation is signaled via the aio, +and the final result may be obtained via +nng_aio_result(). +That result will either be zero or an error code.

    +
    +
    +

    The I/O operation completes as soon as at least one byte has been +received, or an error has occurred. +Therefore, the number of bytes read may be less than requested. +The actual number of bytes read can be determined with +nng_aio_count().

    +
    +
    + + + + + +
    + + +While TCP has the notion of urgent (out-of-band) delivery, that is +used by very few protocols and this API does not support it. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    +NNG_ECANCELED + +

    The operation was canceled.

    +
    +NNG_ECLOSED + +

    The connection was closed.

    +
    +NNG_ECONNRESET + +

    The peer closed the connection.

    +
    +NNG_EINVAL + +

    The aio does not contain a valid scatter/gather vector.

    +
    +NNG_ENOMEM + +

    Insufficient free memory to perform the operation.

    +
    +NNG_ETIMEDOUT + +

    Timeout waiting for data from the connection.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_send.3tcp.html b/man/tip/nng_tcp_send.3tcp.html new file mode 100644 index 00000000..e1e84580 --- /dev/null +++ b/man/tip/nng_tcp_send.3tcp.html @@ -0,0 +1,672 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_send(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +void nng_tcp_send(nng_tcp *conn, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_send() function starts an asynchronous send over the +TCP connection conn from the scatter/gather vector located in the +asynchronous I/O structure aio.

    +
    +
    + + + + + +
    + + +The nng_aio_set_iov() function must have been +called first, to set the scatter/gather vector for aio. +
    +
    +
    +

    This function returns immediately, with no return value. +Completion of the operation is signaled via the aio, and the final +result may be obtained via nng_aio_result(). +That result will either be zero or an error code.

    +
    +
    +

    The I/O operation completes as soon as at least one byte has been +sent, or an error has occurred. +Therefore, the number of bytes sent may be less than requested. +The actual number of bytes sent can be determined with +nng_aio_count().

    +
    +
    + + + + + +
    + + +While TCP has the notion of urgent (out-of-band) delivery, that is +used by very few protocols and this API does not support it. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    +NNG_ECANCELED + +

    The operation was canceled.

    +
    +NNG_ECLOSED + +

    The connection was closed.

    +
    +NNG_ECONNRESET + +

    The peer closed the connection.

    +
    +NNG_EINVAL + +

    The aio does not contain a valid scatter/gather vector.

    +
    +NNG_ENOMEM + +

    Insufficient free memory to perform the operation.

    +
    +NNG_ETIMEDOUT + +

    Timeout waiting for data from the connection.

    +
    +
    +
    +
    + +
    + + diff --git a/man/tip/nng_tcp_setopt.3tcp.html b/man/tip/nng_tcp_setopt.3tcp.html new file mode 100644 index 00000000..31a3f042 --- /dev/null +++ b/man/tip/nng_tcp_setopt.3tcp.html @@ -0,0 +1,635 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_tcp_setopt(3tcp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
    +#include <nng/supplemental/tcp/tcp.h>
    +
    +int nng_tcp_setopt(nng_tcp *conn, const char *name, const void *data, size_t size);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_tcp_setopt() is used to set the option name for the +TCP connection conn. +The value to set is copied from data, which should be size bytes +in length.

    +
    +
    +

    Options

    +
    +

    The options specifically suppported for modification on TCP +connections are:

    +
    + +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    + + + + + + + + + + + + + + + + + +
    +NNG_ECLOSED + +

    The connection conn is closed.

    +
    +NNG_EINVAL + +

    Either data or size are invalid.

    +
    +NNG_ENOTSUP + +

    The option name is not supported.

    +
    +NNG_EREADONLY + +

    The option name may not be modified.

    +
    +
    +
    +
    + +
    + + -- cgit v1.2.3-70-g09d2