From 9d71bbc9f67478ccc28bf6ea9cb1617e8293be94 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Mon, 25 Mar 2024 21:11:43 -0700
Subject: More updates

---
 docs/man/nng_compat.3compat.adoc | 214 ---------------------------------------
 1 file changed, 214 deletions(-)
 delete mode 100644 docs/man/nng_compat.3compat.adoc

(limited to 'docs/man/nng_compat.3compat.adoc')

diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc
deleted file mode 100644
index bd986597..00000000
--- a/docs/man/nng_compat.3compat.adoc
+++ /dev/null
@@ -1,214 +0,0 @@
-= 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 <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>
-----
-
-== DESCRIPTION
-
-(((compatibility layer)))
-xref:nng.7.adoc[_NNG_] provides source-level compatibility for
-most _libnanomsg_ 1.0 applications.
-
-IMPORTANT: This is intended to facilitate converting ((legacy applications)) to
-use _NNG_.
-New applications should use the newer xref:nng.7.adoc[_NNG_] API instead.
-
-Applications making use of this must take care
-to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_.
-
-TIP: While not recommended for long term use, the value returned by
-xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions
-just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`].
-This can be way to facilitate incremental transition to the new API.
-
-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 new API.
-
-NOTE: While reasonable efforts have been made to provide for compatibility,
-some things may behave differently, and some less common parts of the
-_libnanomsg_ 1.0 API are not supported at this time, including certain
-options and the statistics API.
-See the <<Caveats>> section below.
-
-=== Compiling
-
-When compiling legacy _nanomsg_ applications, it will generally be
-necessary to change the include search path to add the `compat` subdirectory
-of the directory where headers were installed.
-For example, if _NNG_ is installed in `$prefix`, then header files will
-normally be located in `$prefix/include/nng`.
-In this case, to build legacy _nanomsg_ apps against _NNG_ you would
-add `$prefix/include/nng/compat` to your compiler's search path.
-
-Alternatively, you can change your source code so that `#include` statements
-referring to `<nanomsg>` instead refer to `<nng/compat/nanomsg>`.
-For example, instead of:
-
-[source,c]
-----
-#include <nanomsg/nn.h>
-#include <nanomsg/reqrep.h>
-----
-
-you would have this:
-
-[source,c]
-----
-#include <nng/compat/nanomsg/nn.h>
-#include <nng/compat/nanomsg/reqrep.h>
-----
-
-Legacy applications built using these methods should be linked against _libnng_
-instead of _libnn_, just like any other _NNG_ application.
-
-=== Functions
-
-The following functions are provided:
-
-// For PDF, we don't have horizontal lists, so we have to conditionalize
-// this and use tables there -- it looks ugly otherwise.
-ifndef::backend-pdf[]
-[horizontal]
-xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket
-xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option
-xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option
-xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers
-xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer
-xref:nn_send.3compat.adoc[`nn_send()`]:: send data
-xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data
-xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint
-xref:nn_close.3compat.adoc[`nn_close()`]:: close socket
-xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets
-xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device
-xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message
-xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message
-xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data
-xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub)
-xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message
-xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message
-xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message
-xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error
-xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error
-xref:nn_term.3compat.adoc[`nn_term()`]:: terminate library
-endif::[]
-ifdef::backend-pdf[]
-// Add links for the following as they are written.
-[.hdlist,width=90%, grid=rows,cols="1,2", align="center"]
-|===
-|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket
-|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option
-|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option
-|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers
-|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer
-|xref:nn_send.3compat.adoc[`nn_send()`]|send data
-|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data
-|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint
-|xref:nn_close.3compat.adoc[`nn_close()`]|close socket
-|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets
-|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device
-|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message
-|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message
-|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data
-|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub)
-|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message
-|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message
-|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message
-|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error
-|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error
-|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library
-|===
-endif::[]
-
-=== Caveats
-
-The following caveats apply when using the legacy API with _NNG_.
-
-* Socket numbers can be quite large.
-  The legacy _libnanomsg_ attempted to reuse socket numbers, like
-  file descriptors in UNIX systems.
-  _NNG_ 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.
-
-* The following options (`nn_getsockopt`) are unsupported:
-  `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
-  The priority options may be supported in the future, when
-  the underlying capability is present in _NNG_.
-
-* Access to statistics using this legacy API
-  (xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported.
-
-* 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.
-
-* Only absolute paths are supported in `ipc://` URLs.
-  For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not.
-
-* The WebSocket transport in this implementation (`ws://` URLs)
-  only supports BINARY frames.
-
-* 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.
-
-* ABI versioning of the compatibility layer is not supported,
-  and the `NN_VERSION_` macros are not present.
-
-* Runtime symbol information is not implemented.
-  Specifically, there is no `nn_symbol()` function yet.
-  (This may be addressed later if there is a need.)
-
-* The TCP transport (`tcp://` 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.)
-
-* The values of `NN_RCVMAXSIZE` are constrained.
-  Specifically, values set larger than 2GB using the new API will be reported
-  as unlimited (`-1`) in the new API, and the value `0` will disable any
-  enforcement, just like `-1`.
-  (There is no practical reason to ever want to limit the receive size to
-  zero.)
-
-* This implementation counts buffers in terms of messages rather than bytes.
-  As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` 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.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng.7.adoc[nng(7)]
-- 
cgit v1.2.3-70-g09d2

