'\" t
.\"     Title: nng_compat
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2021-02-08
.\"    Manual: NNG Reference Manual
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NNG_COMPAT" "3compat" "2021-02-08" "\ \&" "NNG Reference Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
nng_compat \- compatibility with nanomsg 1.0
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam C
#include <nanomsg/nn.h>

#include <nanomsg/bus.h>
#include <nanomsg/pair.h>
#include <nanomsg/pipeline.h>
#include <nanomsg/pubsub.h>
#include <nanomsg/reqrep.h>
#include <nanomsg/survey.h>

#include <nanomsg/inproc.h>
#include <nanomsg/ipc.h>
#include <nanomsg/tcp.h>
#include <nanomsg/ws.h>
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp

\fINNG\fP provides source\-level compatibility for
most \fIlibnanomsg\fP 1.0 applications.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Important
.ps -1
.br
.sp
This is intended to facilitate converting legacy applications to
use \fINNG\fP.
New applications should use the newer \fINNG\fP API instead.
.sp .5v
.RE
.sp
Applications making use of this must take care
to link with \fIlibnng\fP instead of \fIlibnn\fP.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Tip
.ps -1
.br
.sp
While not recommended for long term use, the value returned by
\f(CRnng_socket_id()\fP can be used with these functions
just like a value returned by \f(CRnn_socket()\fP.
This can be way to facilitate incremental transition to the new API.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
Some capabilities, protocols, and transports, will not be accessible
using this API, as the compatible API has no provision for expression
of certain concepts introduced in the new API.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
While reasonable efforts have been made to provide for compatibility,
some things may behave differently, and some less common parts of the
\fIlibnanomsg\fP 1.0 API are not supported at this time, including certain
options and the statistics API.
See the Caveats section below.
.sp .5v
.RE
.SS "Compiling"
.sp
When compiling legacy \fInanomsg\fP applications, it will generally be
necessary to change the include search path to add the \f(CRcompat\fP subdirectory
of the directory where headers were installed.
For example, if \fINNG\fP is installed in \f(CR$prefix\fP, then header files will
normally be located in \f(CR$prefix/include/nng\fP.
In this case, to build legacy \fInanomsg\fP apps against \fINNG\fP you would
add \f(CR$prefix/include/nng/compat\fP to your compiler\(cqs search path.
.sp
Alternatively, you can change your source code so that \f(CR#include\fP statements
referring to \f(CR<nanomsg>\fP instead refer to \f(CR<nng/compat/nanomsg>\fP.
For example, instead of:
.sp
.if n .RS 4
.nf
.fam C
#include <nanomsg/nn.h>
#include <nanomsg/reqrep.h>
.fam
.fi
.if n .RE
.sp
you would have this:
.sp
.if n .RS 4
.nf
.fam C
#include <nng/compat/nanomsg/nn.h>
#include <nng/compat/nanomsg/reqrep.h>
.fam
.fi
.if n .RE
.sp
Legacy applications built using these methods should be linked against \fIlibnng\fP
instead of \fIlibnn\fP, just like any other \fINNG\fP application.
.SS "Functions"
.sp
The following functions are provided:
.sp
\f(CRnn_socket()\fP
.RS 4
create socket
.RE
.sp
\f(CRnn_getsockopt()\fP
.RS 4
get socket option
.RE
.sp
\f(CRnn_setsockopt()\fP
.RS 4
set socket option
.RE
.sp
\f(CRnn_bind()\fP
.RS 4
accept connections from remote peers
.RE
.sp
\f(CRnn_connect()\fP
.RS 4
connect to remote peer
.RE
.sp
\f(CRnn_send()\fP
.RS 4
send data
.RE
.sp
\f(CRnn_recv()\fP
.RS 4
receive data
.RE
.sp
\f(CRnn_shutdown()\fP
.RS 4
shut down endpoint
.RE
.sp
\f(CRnn_close()\fP
.RS 4
close socket
.RE
.sp
\f(CRnn_poll()\fP
.RS 4
poll sockets
.RE
.sp
\f(CRnn_device()\fP
.RS 4
create forwarding device
.RE
.sp
\f(CRnn_recvmsg()\fP
.RS 4
receive message
.RE
.sp
\f(CRnn_sendmsg()\fP
.RS 4
send message
.RE
.sp
\f(CRnn_cmsg()\fP
.RS 4
message control data
.RE
.sp
\f(CRnn_get_statistic()\fP
.RS 4
get statistic (stub)
.RE
.sp
\f(CRnn_allocmsg()\fP
.RS 4
allocate message
.RE
.sp
\f(CRnn_reallocmsg()\fP
.RS 4
reallocate message
.RE
.sp
\f(CRnn_freemsg()\fP
.RS 4
free message
.RE
.sp
\f(CRnn_errno()\fP
.RS 4
return most recent error
.RE
.sp
\f(CRnn_strerror()\fP
.RS 4
return message for error
.RE
.sp
\f(CRnn_term()\fP
.RS 4
terminate library
.RE
.SS "Caveats"
.sp
The following caveats apply when using the legacy API with \fINNG\fP.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Socket numbers can be quite large.
The legacy \fIlibnanomsg\fP attempted to reuse socket numbers, like
file descriptors in UNIX systems.
\fINNG\fP avoids this to prevent accidental reuse or
collision after a descriptor is closed.
Consequently, socket numbers can become quite large, and should
probably not be used for array indices.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The following options (\f(CRnn_getsockopt\fP) are unsupported:
\f(CRNN_SNDPRIO\fP, \f(CRNN_RCVPRIO\fP, \f(CRNN_IPV4ONLY\fP.
The priority options may be supported in the future, when
the underlying capability is present in \fINNG\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Access to statistics using this legacy API
(\f(CRnn_get_statistic()\fP) is unsupported.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Some transports can support longer URLs than legacy \fIlibnanomsg\fP can.
It is a good idea to use short pathnames in URLs if interoperability
is a concern.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Only absolute paths are supported in \f(CRipc://\fP URLs.
For example, \f(CRipc:///tmp/mysocket\fP is acceptable, but \f(CRipc://mysocket\fP is not.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The WebSocket transport in this implementation (\f(CRws://\fP URLs)
only supports BINARY frames.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Some newer transports are unusable from this mode.
In particular, this legacy API offers no way to configure
TLS or ZeroTier parameters that may be required for use.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ABI versioning of the compatibility layer is not supported,
and the \f(CRNN_VERSION_\fP macros are not present.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Runtime symbol information is not implemented.
Specifically, there is no \f(CRnn_symbol()\fP function yet.
(This may be addressed later if there is a need.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The TCP transport (\f(CRtcp://\fP URLs) does not support specifying the local
address or interface when binding.  (This could be fixed in the future,
but most likely this will be available only using the new API.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The values of \f(CRNN_RCVMAXSIZE\fP are constrained.
Specifically, values set larger than 2GB using the new API will be reported
as unlimited (\f(CR\-1\fP) in the new API, and the value \f(CR0\fP will disable any
enforcement, just like \f(CR\-1\fP.
(There is no practical reason to ever want to limit the receive size to
zero.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
This implementation counts buffers in terms of messages rather than bytes.
As a result, the buffer sizes accessed with \f(CRNN_SNDBUF\fP and \f(CRNN_RCVBUF\fP are
rounded up to a whole number of kilobytes, then divided by 1024, in order
to approximate buffering assuming 1 KB messages.
Few applications should need to adjust the default values.
.RE
.SH "SEE ALSO"
.sp
libnng(3),
nng(7)