1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
= nng_compat(3compat)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt). A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//
== NAME
nng_compat - compatibility with nanomsg 1.0
== SYNOPSIS
[source, c]
----
#include <nn/nn.h>
----
== DESCRIPTION
The <<nng.7#,_nng_>> library provides source-level compatibility for
most _nanomsg_ 1.0 applications.
IMPORTANT: This is intended to faciliate converting legacy applications to
use the _nng_ library.
New applications shoud not use the newer <<nng.7#,_nng_>> API instead.
Applications making use of this ((compatibility layer)) take care
to link with <<libnng.3#,_libnng_>> instead of _libnn_.
NOTE: 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 newer <<nng.7#,_nng_>> API.
NOTE: While reasonable efforts have been made to provide for compatibility,
some things may behave differently, and some less common parts of the
_nanomsg_ 1.0 API are not supported at this time, including certain
options and the statistics API.
TIP: If an installation of the older _nanomsg_ library is present on
the build system, it may be necessary to provide a different search
path for header files to ensure that the compatibility definitions are
used in compilation.
=== Functions
The following functions are provided:
// Add links for the following as they are written.
|===
|`nn_socket()`|create a socket
|`nn_getsockopt()`|get socket option
|`nn_setsockopt()`|set socket option
|`nn_bind()`|accept connections from remote peers
|`nn_connect()`|connect to remote peer
|`nn_send()`|send data
|`nn_recv()`|receive data
|`nn_shutdown()`|shut down endpoint
|`nn_close()`|close socket
|`nn_poll()`|poll sockets
|`nn_device()`|create forwarding device
|`nn_recvmsg()`|receive message
|`nn_sendmsg()`|send message
|`nn_get_statistic()`|get statistic (stub)
|`nn_allocmsg()`|allocate message
|`nn_reallocmsg()`|reallocate message
|`nn_freemsg()`|free message
|`nn_errno()`|return most recent error
|`nn_strerror()`|return message for error
|`nn_term()`|terminate library
|===
NOTE: Documentation for the compatibility functions will be
supplied here later.
In the meantime it can be found online at the
http://nanomsg.org[nanomsg site].
There are a few caveats, that should be kept in mind.
NOTE: Socket numbers can be quite large.
The legacy _libnanomsg_ attempted to reuse socket numbers, like
file descriptors in UNIX systems.
The _nng_ library 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.
NOTE: The following options (`nn_getsockopt`) are unsupported:
`NN_PROTOCOL`, `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
Some of these will probably be added back in the future when
the relevant support is added to _nng_.
NOTE: Statistics (`nn_get_statistic`) are unsupported.
The plan is to support statistics in the native _nng_ API, but
we think there is no need for this in a compatibility layer.
Hence, this function returns `ENOTSUP`.
NOTE: Some transports can support longer URLs than legacy _libnanomsg_ can.
It is a good idea to use short pathnames in URLs if interoperability
is a concern.
NOTE: Some transports are unusable from this mode.
In particular, this legacy API offers no way to configure
TLS parameters that are required for use.
NOTE: ABI versioning is not supported.
We don't offer the `NN_VERSION_` macros. Sorry.
NOTE: Runtime symbol information is not implemented.
Specifically, there is no `nn_symbol()` function yet.
(This may be addressed later if there is a need.)
IMPORTANT: The `nn_term()` function is destructive and should be avoided.
This function closes down all sockets, and really there is no good
reason to ever use it.
Removal from existing code is advised.
(Keep track of sockets and close them explicitly if necessary.)
IMPORTANT: It *is* possible at present to intermix sockets between the new and
the old APIs, but this is not a guaranteed feature, and should only
be used temporarily to facilitate transitioning code to the new APIs.
// === Common Functions
//
// The following common functions exist in _libnng_.
//
// |===
// |<<nng_alloc.3#,nng_alloc()>>|allocate memory
// |<<nng_free.3#,nng_free()>>|free memory
// |<<nng_strerror.3#,nng_strerror()>>|return an error description
// |<<nng_version.3#,nng_version()>>|report library version
// |===
//
== SEE ALSO
<<nng.7#,nng(7)>>
|
