diff --git a/external/nng/.clang-format b/external/nng/.clang-format new file mode 100644 index 0000000..015dab8 --- /dev/null +++ b/external/nng/.clang-format @@ -0,0 +1,16 @@ +BasedOnStyle: WebKit +UseTab: ForIndentation +IndentWidth: 8 +ColumnLimit: 79 +AlignConsecutiveAssignments: true +AlignConsecutiveDeclarations: true +AlignTrailingComments: true +AlignEscapedNewlines: Left +PointerAlignment: Right +DerivePointerAlignment: false +ForEachMacros: ['NNI_LIST_FOREACH'] +AlwaysBreakAfterReturnType: TopLevelDefinitions +SpaceAfterCStyleCast: true +AllowShortFunctionsOnASingleLine: Inline +BreakBeforeBinaryOperators: None +TabWidth: 8 diff --git a/external/nng/.codecov.yml b/external/nng/.codecov.yml new file mode 100644 index 0000000..db5314b --- /dev/null +++ b/external/nng/.codecov.yml @@ -0,0 +1,7 @@ +ignore: + - "tests" + - "src/testing" + - "perf" + - "**/*_test.c" +coverage: + range: 50..95 diff --git a/external/nng/.gitattributes b/external/nng/.gitattributes new file mode 100644 index 0000000..fc158d0 --- /dev/null +++ b/external/nng/.gitattributes @@ -0,0 +1,2 @@ +*.sh text eol=lf + diff --git a/external/nng/.github/FUNDING.yml b/external/nng/.github/FUNDING.yml new file mode 100644 index 0000000..861519f --- /dev/null +++ b/external/nng/.github/FUNDING.yml @@ -0,0 +1,5 @@ +# These are supported funding model platforms +github: gdamore +patreon: gedamore +custom: [ "https://staysail.tech/support/" ] +custom: [ "https://leanpub.com/nngref2e" ] diff --git a/external/nng/.github/ISSUE_TEMPLATE/bug_report.md b/external/nng/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..b000b02 --- /dev/null +++ b/external/nng/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,30 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Actual Behavior** +Describe what occurred. + +**To Reproduce** +If possible include actual reproduction test code here. +Minimal C test cases are perferred. + +** Environment Details ** + - NNG version + - Operating system and version + - Compiler and language used + - Shared or static library + +**Additional context** +Add any other context about the problem here. diff --git a/external/nng/.github/ISSUE_TEMPLATE/feature_request.md b/external/nng/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bbcbbe7 --- /dev/null +++ b/external/nng/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/external/nng/.github/pull_request_template.md b/external/nng/.github/pull_request_template.md new file mode 100644 index 0000000..5ae7c25 --- /dev/null +++ b/external/nng/.github/pull_request_template.md @@ -0,0 +1,7 @@ +fixes # + + + +Note that the above format should be used in your git commit comments. +You agree that by submitting a PR, you have read and agreed to our +contributing guidelines. diff --git a/external/nng/.github/workflows/codeql-analysis.yml b/external/nng/.github/workflows/codeql-analysis.yml new file mode 100644 index 0000000..e6f6fb1 --- /dev/null +++ b/external/nng/.github/workflows/codeql-analysis.yml @@ -0,0 +1,72 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL" + +on: + push: + branches: [ master ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ master ] + schedule: + - cron: '27 2 * * 2' + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'cpp' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ] + # Learn more: + # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + with: + languages: ${{ matrix.language }} + queries: +security-and-quality + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: ./path/to/local/query, your-org/your-repo/queries@main + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v1 + + # ℹī¸ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏ī¸ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 diff --git a/external/nng/.github/workflows/coverage.yml b/external/nng/.github/workflows/coverage.yml new file mode 100644 index 0000000..7aaf317 --- /dev/null +++ b/external/nng/.github/workflows/coverage.yml @@ -0,0 +1,65 @@ +name: coverage +on: [push] +jobs: + + linux-coverage: + name: linux + runs-on: [ ubuntu-latest ] + steps: + - name: Check out code + uses: actions/checkout@v1 + + - name: Install mbedTLS + run: sudo apt-get install libmbedtls-dev + + - name: Install ninja + run: sudo apt-get install ninja-build + + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. + + - name: build + run: cd build && ninja + + - name: Test + run: cd build && ctest --output-on-failure + + - name: Upload report + uses: codecov/codecov-action@v1 + with: + token: ${{ secrets.CODECOV_TOKEN }} + yml: ./.codecov.yml + + darwin-coverage: + name: darwin + runs-on: [ macos-latest ] + steps: + - name: Check out code + uses: actions/checkout@v1 + + - name: Install mbedTLS + run: brew install mbedtls + + - name: Install ninja + run: brew install ninja + + - name: Install lcov + run: brew install lcov + + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. + + - name: build + run: cd build && ninja + + - name: Test + run: cd build && ctest --output-on-failure + + - name: Preprocess + run: cd build && lcov -c -d . -o lcov.info + + - name: Upload report + uses: codecov/codecov-action@v1 + with: + token: ${{ secrets.CODECOV_TOKEN }} + yml: ./.codecov.yml diff --git a/external/nng/.github/workflows/darwin.yml b/external/nng/.github/workflows/darwin.yml new file mode 100644 index 0000000..5029198 --- /dev/null +++ b/external/nng/.github/workflows/darwin.yml @@ -0,0 +1,24 @@ +name: darwin +on: [push, pull_request] +jobs: + build: + name: build + runs-on: [macos-latest] + steps: + - name: Check out code + uses: actions/checkout@v1 + + - name: Install Mbed TLS + run: brew install mbedtls + + - name: Install ninja + run: brew install ninja + + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -DNNG_ENABLE_TLS=ON .. + + - name: build + run: cd build && ninja + + - name: Test + run: cd build && ctest --output-on-failure diff --git a/external/nng/.github/workflows/linux.yml b/external/nng/.github/workflows/linux.yml new file mode 100644 index 0000000..d7386fd --- /dev/null +++ b/external/nng/.github/workflows/linux.yml @@ -0,0 +1,25 @@ +name: linux +on: [push, pull_request] +jobs: + + build: + name: build + runs-on: [ ubuntu-latest ] + steps: + - name: Check out code + uses: actions/checkout@v1 + + - name: Install mbedTLS + run: sudo apt-get install libmbedtls-dev + + - name: Install ninja + run: sudo apt-get install ninja-build + + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -D NNG_ENABLE_TLS=ON .. + + - name: Build + run: cd build && ninja + + - name: Test + run: cd build && ctest --output-on-failure \ No newline at end of file diff --git a/external/nng/.github/workflows/sanitizer.yml b/external/nng/.github/workflows/sanitizer.yml new file mode 100644 index 0000000..e0d9c57 --- /dev/null +++ b/external/nng/.github/workflows/sanitizer.yml @@ -0,0 +1,36 @@ +name: sanitize +on: [push, pull_request] +jobs: + sanitize: + env: + CC: clang + CXX: clang++ + CTEST_OUTPUT_ON_FAILURE: 1 + runs-on: ${{ matrix.os }} + strategy: + matrix: + sanitizer: [ address, undefined, thread ] + os: [ ubuntu-latest ] + + steps: + - uses: actions/checkout@v1 + + - name: Install mbedTLS + run: sudo apt-get install libmbedtls-dev + + - name: Install ninja + run: sudo apt-get install ninja-build + + - name: Configure + run: | + mkdir build + cd build + cmake -G Ninja -DNNG_SANITIZER=${{ matrix.sanitizer }} -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_TLS=ON -DNNG_TOOLS=OFF .. + - name: Build + run: | + cd build + ninja + - name: Test + run: | + cd build + ninja test diff --git a/external/nng/.github/workflows/windows.yml b/external/nng/.github/workflows/windows.yml new file mode 100644 index 0000000..54a04cc --- /dev/null +++ b/external/nng/.github/workflows/windows.yml @@ -0,0 +1,29 @@ +name: windows +on: [push, pull_request] +jobs: + build: + name: build + runs-on: [windows-latest] + steps: + - name: Check out code + uses: actions/checkout@v1 + + - name: vcpkg build + id: vcpkg + uses: johnwason/vcpkg-action@v6 + with: + pkgs: mbedtls + triplet: x64-windows + token: ${{ github.token }} + github-binarycache: true + + - name: Configure + run: cmake ${{ steps.vcpkg.outputs.vcpkg-cmake-config }} -D NNG_ENABLE_TLS=ON -B build + + - name: Build + run: cmake --build build + + - name: Test + run: | + cd build + ctest -C Debug --output-on-failure diff --git a/external/nng/.gitignore b/external/nng/.gitignore new file mode 100644 index 0000000..51f9f27 --- /dev/null +++ b/external/nng/.gitignore @@ -0,0 +1,13 @@ +build +lxbuild +winbuild +wbuild +.cache +.vs +.vscode/.cmaketools.json +.vscode +.idea +.DS_Store +etc/nng.sublime-workspace +cmake-build-* +docs/**/*.html \ No newline at end of file diff --git a/external/nng/.gitmodules b/external/nng/.gitmodules new file mode 100644 index 0000000..7620594 --- /dev/null +++ b/external/nng/.gitmodules @@ -0,0 +1,3 @@ +[submodule "extern/nng-wolfssl"] + path = extern/nng-wolfssl + url = https://github.com/staysail/nng-wolfssl diff --git a/external/nng/.grcov.yml b/external/nng/.grcov.yml new file mode 100644 index 0000000..781860c --- /dev/null +++ b/external/nng/.grcov.yml @@ -0,0 +1,5 @@ +branch: true +ignore-not-existing: true +filter: covered +output-type: lcov +output-file: lcov.info \ No newline at end of file diff --git a/external/nng/CMakeLists.txt b/external/nng/CMakeLists.txt new file mode 100644 index 0000000..4756d30 --- /dev/null +++ b/external/nng/CMakeLists.txt @@ -0,0 +1,312 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# Copyright (c) 2012 Martin Sustrik All rights reserved. +# Copyright (c) 2013 GoPivotal, Inc. All rights reserved. +# Copyright (c) 2015-2016 Jack R. Dunaway. All rights reserved. +# Copyright 2016 Franklin "Snaipe" Mathieu +# Copyright 2018 Capitar IT Group BV +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom +# the Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# + +cmake_minimum_required(VERSION 3.13) + +project(nng C) +include(CheckCCompilerFlag) +include(GNUInstallDirs) + +set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake) + +include(NNGHelpers) +include(NNGOptions) + +set(CMAKE_C_STANDARD 99) +set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) +list(FIND CMAKE_PLATFORM_IMPLICIT_LINK_DIRECTORIES "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}" isSystemDir) +if ("${isSystemDir}" STREQUAL "-1") + set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}") +endif ("${isSystemDir}" STREQUAL "-1") + +set(NNG_DESCRIPTION "High-Performance Scalability Protocols NextGen") +set(ISSUE_REPORT_MSG "Please consider opening an issue at https://github.com/nanomsg/nng") + +# Determine library versions. +file(READ "include/nng/nng.h" nng_ver_h) +string(REGEX MATCH "NNG_MAJOR_VERSION ([0-9]*)" _ ${nng_ver_h}) +set(NNG_MAJOR_VERSION ${CMAKE_MATCH_1}) +string(REGEX MATCH "NNG_MINOR_VERSION ([0-9]*)" _ ${nng_ver_h}) +set(NNG_MINOR_VERSION ${CMAKE_MATCH_1}) +string(REGEX MATCH "NNG_PATCH_VERSION ([0-9]*)" _ ${nng_ver_h}) +set(NNG_PATCH_VERSION ${CMAKE_MATCH_1}) +string(REGEX MATCH "NNG_RELEASE_SUFFIX \"([a-z0-9]*)\"" _ ${nng_ver_h}) +if (NOT ("${CMAKE_MATCH_1}" STREQUAL "")) + set(NNG_PRERELEASE "-${CMAKE_MATCH_1}") +endif () + +set(NNG_ABI_SOVERSION 1) +set(NNG_ABI_VERSION "${NNG_MAJOR_VERSION}.${NNG_MINOR_VERSION}.${NNG_PATCH_VERSION}${NNG_PRERELEASE}") +set(NNG_PACKAGE_VERSION "${NNG_ABI_VERSION}") +message(STATUS "Configuring for NNG version ${NNG_ABI_VERSION}") + +# User-defined options. + +# This prefix is appended to by subdirectories, so that each test +# gets named based on where it is in the tree. +set(NNG_TEST_PREFIX nng) + +# Enable access to private APIs for our own use. +add_definitions(-DNNG_PRIVATE) + +if (NOT (BUILD_SHARED_LIBS)) + set(NNG_STATIC_LIB ON) + message(STATUS "Building static libs.") +endif () + +# These are library targets. The "nng" library is the main public library. +# The "nng_testing" is a full build of the library for test cases +# only, which is done statically and includes even portions of the code +# that are not part of the public library (things that may have been elided.) +# The "nng_private" library is an interface that allows some internal tools +# to obtain details about how the public library was built, so that we can +# include or not include code based on what's actually present. +add_library(nng) + +add_library(nng_testing STATIC EXCLUDE_FROM_ALL) +target_compile_definitions(nng_testing PUBLIC NNG_STATIC_LIB NNG_TEST_LIB NNG_PRIVATE) + +add_library(nng_private INTERFACE) +target_compile_definitions(nng_private INTERFACE NNG_PRIVATE) + +if (NNG_ELIDE_DEPRECATED) + target_compile_definitions(nng PRIVATE NNG_ELIDE_DEPRECATED) +endif() +if (NNG_ENABLE_COMPAT) + target_compile_definitions(nng PRIVATE NNG_ENABLE_COMPAT) +endif() + + +# We can use rlimit to configure the stack size for systems +# that have too small defaults. This is not used for Windows, +# which can grow thread stacks sensibly. (Note that NNG can get +# by with a smallish stack, but application callbacks might require +# larger values if using aio completion callbacks. TLS libraries may +# require larger stacks however.) +if (NOT WIN32) + option(NNG_SETSTACKSIZE "Use rlimit for thread stack size" OFF) + if (NNG_SETSTACKSIZE) + add_definitions(-DNNG_SETSTACKSIZE) + endif () + mark_as_advanced(NNG_SETSTACKSIZE) +endif () + +nng_defines_if(NNG_ENABLE_STATS NNG_ENABLE_STATS) + +# IPv6 enable +nng_defines_if(NNG_ENABLE_IPV6 NNG_ENABLE_IPV6) + +set(NNG_RESOLV_CONCURRENCY 4 CACHE STRING "Resolver (DNS) concurrency.") +mark_as_advanced(NNG_RESOLV_CONCURRENCY) +if (NNG_RESOLV_CONCURRENCY) + add_definitions(-DNNG_RESOLV_CONCURRENCY=${NNG_RESOLV_CONCURRENCY}) +endif () + +set(NNG_NUM_TASKQ_THREADS 0 CACHE STRING "Fixed number of task threads, 0 for automatic") +mark_as_advanced(NNG_NUM_TASKQ_THREADS) +if (NNG_NUM_TASKQ_THREADS) + add_definitions(-DNNG_NUM_TASKQ_THREADS=${NNG_NUM_TASKQ_THREADS}) +endif () + +set(NNG_MAX_TASKQ_THREADS 16 CACHE STRING "Upper bound on task threads, 0 for no limit") +mark_as_advanced(NNG_MAX_TASKQ_THREADS) +if (NNG_MAX_TASKQ_THREADS) + add_definitions(-DNNG_MAX_TASKQ_THREADS=${NNG_MAX_TASKQ_THREADS}) +endif () + +# Expire threads. This runs the timeout handling, and having more of them +# reduces contention on the common locks used for aio expiration. +set(NNG_NUM_EXPIRE_THREADS 0 CACHE STRING "Fixed number of expire threads, 0 for automatic") +mark_as_advanced(NNG_NUM_EXPIRE_THREADS) +if (NNG_NUM_EXPIRE_THREADS) + add_definitions(-DNNG_NUM_EXPIRE_THREADS=${NNG_NUM_EXPIRE_THREADS}) +endif () + +set(NNG_MAX_EXPIRE_THREADS 8 CACHE STRING "Upper bound on expire threads, 0 for no limit") +mark_as_advanced(NNG_MAX_EXPIRE_THREADS) +if (NNG_MAX_EXPIRE_THREADS) + add_definitions(-DNNG_MAX_EXPIRE_THREADS=${NNG_MAX_EXPIRE_THREADS}) +endif() + +# Poller threads. These threads run the pollers. This is mostly used +# on Windows right now, as the POSIX platforms use a single threaded poller. +set(NNG_NUM_POLLER_THREADS 0 CACHE STRING "Fixed number of I/O poller threads, 0 for automatic") +if (NNG_NUM_POLLER_THREADS) + add_definitions(-DNNG_NUM_POLLER_THREADS=${NNG_NUM_POLLER_THREADS}) +endif () +mark_as_advanced(NNG_NUM_POLLER_THREADS) + +set(NNG_MAX_POLLER_THREADS 8 CACHE STRING "Upper bound on I/O poller threads, 0 for no limit") +mark_as_advanced(NNG_MAX_POLLER_THREADS) +if (NNG_MAX_POLLER_THREADS) + add_definitions(-DNNG_MAX_POLLER_THREADS=${NNG_MAX_POLLER_THREADS}) +endif() + +# Platform checks. + +if (CMAKE_C_COMPILER_ID STREQUAL "GNU") + set(NNG_WARN_FLAGS "-Wall -Wextra -fno-omit-frame-pointer") +elseif (CMAKE_C_COMPILER_ID MATCHES "Clang") + set(NNG_WARN_FLAGS "-Wall -Wextra -fno-omit-frame-pointer") +endif () + +include(CheckSanitizer) +CheckSanitizer() +if (NOT NNG_SANITIZER STREQUAL "none") + set(NNG_SANITIZER_FLAGS "-fsanitize=${NNG_SANITIZER}") +endif () + +if (NNG_ENABLE_COVERAGE) + # NB: This only works for GCC and Clang 3.0 and newer. If your stuff + # is older than that, you will need to find something newer. For + # correct reporting, we always turn off all optimizations. + if (CMAKE_C_COMPILER_ID STREQUAL "GNU") + set(NNG_COVERAGE_C_FLAGS "-g -O0 --coverage") + set(CMAKE_SHARED_LINKER_FLAGS --coverage) + elseif (CMAKE_C_COMPILER_ID MATCHES "Clang") + set(NNG_COVERAGE_C_FLAGS "-g -O0 --coverage") + set(CMAKE_SHARED_LINKER_FLAGS --coverage) + else () + message(FATAL_ERROR "Unable to enable coverage for your compiler.") + endif () +endif () + +set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${NNG_WARN_FLAGS} ${NNG_COVERAGE_C_FLAGS} ${NNG_SANITIZER_FLAGS}") +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${NNG_WARN_FLAGS} ${NNG_COVERAGE_C_FLAGS} ${NNG_SANITIZER_FLAGS}") + +# If the compiler is not on Windows, does it support hiding the +# symbols by default? For shared libraries we would like to do this. +if (NOT WIN32 AND NOT CYGWIN) + check_c_compiler_flag(-fvisibility=hidden NNG_HIDDEN_VISIBILITY) + if (NNG_HIDDEN_VISIBILITY) + add_definitions(-DNNG_HIDDEN_VISIBILITY) + endif () +endif () + +if (CMAKE_SYSTEM_NAME MATCHES "Linux") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_LINUX) + add_definitions(-DNNG_USE_EVENTFD) + add_definitions(-DNNG_HAVE_ABSTRACT_SOCKETS) + # Windows subsystem for Linux -- smells like Linux, but it has + # some differences (SO_REUSEADDR for one). + if (CMAKE_SYSTEM_VERSION MATCHES "Microsoft") + add_definitions(-DNNG_PLATFORM_WSL) + endif () + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "Android") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_LINUX) + add_definitions(-DNNG_PLATFORM_ANDROID) + add_definitions(-DNNG_USE_EVENTFD) + set(NNG_PLATFORM_POSIX ON) + +elseif (APPLE) + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_DARWIN) + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "FreeBSD") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_FREEBSD) + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "NetBSD") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_NETBSD) + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "OpenBSD") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_OPENBSD) + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "SunOS") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-DNNG_PLATFORM_SUNOS) + set(NNG_PLATFORM_POSIX ON) + +elseif (CMAKE_SYSTEM_NAME MATCHES "Windows") + add_definitions(-DNNG_PLATFORM_WINDOWS) + add_definitions(-D_CRT_SECURE_NO_WARNINGS) + add_definitions(-D_CRT_RAND_S) + set(NNG_PLATFORM_WINDOWS ON) + + # Target Windows Vista and later + add_definitions(-D_WIN32_WINNT=0x0600) + list(APPEND CMAKE_REQUIRED_DEFINITIONS -D_WIN32_WINNT=0x0600) + +elseif (CMAKE_SYSTEM_NAME MATCHES "QNX") + add_definitions(-DNNG_PLATFORM_POSIX) + add_definitions(-D__EXT_BSD) + add_definitions(-D_QNX_SOURCE) + add_definitions(-DNNG_PLATFORM_QNX) + set(NNG_PLATFORM_POSIX ON) + +else () + message(AUTHOR_WARNING "WARNING: This platform may not be supported: ${CMAKE_SYSTEM_NAME}") + message(AUTHOR_WARNING "${ISSUE_REPORT_MSG}") + # blithely hope for POSIX to work + add_definitions(-DNNG_PLATFORM_POSIX) + set(NNG_PLATFORM_POSIX ON) +endif () + +if (NNG_ENABLE_TLS) + add_definitions(-DNNG_SUPP_TLS) +endif () + +if (NNG_TESTS) + enable_testing() + set(all_tests, "") +endif () + +add_subdirectory(src) + +if (NNG_TESTS) + add_subdirectory(tests) +endif () + +# Build the tools + +add_subdirectory(docs/man) + +set(CPACK_PACKAGE_NAME ${PROJECT_NAME}) +set(CPACK_PACKAGE_VERSION ${NNG_PACKAGE_VERSION}) +set(CPACK_PACKAGE_CONTACT "nanomsg@freelists.org") +set(CPACK_PACKAGE_VENDOR "nanomsg.org") +set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "nanomsg next generation library") +set(CPACK_SOURCE_GENERATOR "TBZ2;TGZ;ZIP") +set(CPACK_SOURCE_IGNORE_FILES "/build/;/.git/;~$;${CPACK_SOURCE_IGNORE_FILES}") +set(CPACK_SOURCE_PACKAGE_FILE_NAME + "${PROJECT_NAME}-v${NNG_PACKAGE_VERSION}-src") +set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.txt) +set(CPACK_PACKAGE_INSTALL_DIRECTORY "nng") +set(CPACK_PACKAGE_FILE_NAME "${PROJECT_NAME}-v${NNG_PACKAGE_VERSION}") + +add_custom_target(dist COMMAND ${CMAKE_MAKE_PROGRAM} package_source) +include(CPack) diff --git a/external/nng/CODE_OF_CONDUCT.adoc b/external/nng/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..771f4d7 --- /dev/null +++ b/external/nng/CODE_OF_CONDUCT.adoc @@ -0,0 +1,74 @@ += NNG Code of Conduct + +== Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +== Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +== Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +== Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at garrett@damore.org. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an +incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-convent.org[Contributor Covenant], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html diff --git a/external/nng/LICENSE.txt b/external/nng/LICENSE.txt new file mode 100644 index 0000000..353da18 --- /dev/null +++ b/external/nng/LICENSE.txt @@ -0,0 +1,22 @@ +The MIT License + +Copyright 2021 Staysail Systems, Inc. +Copyright 2018 Capitar IT Group BV + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom +the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +IN THE SOFTWARE. diff --git a/external/nng/README.adoc b/external/nng/README.adoc new file mode 100644 index 0000000..dad8ef2 --- /dev/null +++ b/external/nng/README.adoc @@ -0,0 +1,180 @@ +ifdef::env-github[] +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +endif::[] += nng - nanomsg-next-gen + +// Note: This README is optimized for display with Asciidoctor, or +// on the GitHub project page at https://github.com/nanomsg/nng. + +image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg[Stand With Ukraine,link="https://stand-with-ukraine.pp.ua"] +image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=master&logoColor=grey&logo=ubuntu&label=[Linux Status,link="https://github.com/nanomsg/nng/actions"] +image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=master&logoColor=grey&logo=windows&label=[Windows Status,link="https://github.com/nanomsg/nng/actions"] +image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=master&logoColor=grey&logo=apple&label=[macOS Status,link="https://github.com/nanomsg/nng/actions"] +image:https://img.shields.io/codecov/c/github/nanomsg/nng?logo=codecov&logoColor=grey&label=[Coverage,link="https://codecov.io/gh/nanomsg/nng"] +image:https://img.shields.io/discord/639573728212156478?label=&logo=discord[Discord,link="https://discord.gg/Xnac6b9"] +image:https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue[Manual,link="https://nng.nanomsg.org/man"] +image:https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue[MIT License,link="https://github.com/nanomsg/nng/blob/master/LICENSE.txt"] +image:https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=[Latest version,link="https://github.com/nanomsg/nng/releases"] + +Please see <> for an important message for the people of Russia. + +NOTE: If you are looking for the legacy version of nanomsg, please +see the https://github.com/nanomsg/nanomsg[nanomsg] repository. + +This project is a rewrite of the Scalability Protocols +library known as https://github.com/nanomsg/nanomsg[libnanomsg], +and adds significant new capabilities, while retaining +compatibility with the original. + +It may help to think of this as "nanomsg-next-generation". + +== NNG: Lightweight Messaging Library + +NNG, like its predecessors http://nanomsg.org[nanomsg] (and to some extent +http://zeromq.org/[ZeroMQ]), is a lightweight, broker-less library, +offering a simple API to solve common recurring messaging problems, +such as publish/subscribe, RPC-style request/reply, or service discovery. +The API frees the programmer from worrying about details like connection +management, retries, and other common considerations, so that they +can focus on the application instead of the plumbing. + +NNG is implemented in C, requiring only C99 and CMake to build. +It can be built as a shared or a static library, and is readily +embeddable. It is also designed to be easy to port to new platforms +if your platform is not already supported. + +== License + +NNG is licensed under a liberal, and commercial friendly, MIT license. +The goal to the license is to minimize friction in adoption, use, and +contribution. + +== Enhancements (Relative to nanomsg) + +Here are areas where this project improves on "nanomsg": + +[horizontal] +*Reliability*:: NNG is designed for production use from the beginning. Every +error case is considered, and it is designed to avoid crashing except in cases +of gross developer error. (Hopefully we don't have any of these in our own +code.) + +*Scalability*:: NNG scales out to engage multiple cores using a bespoke +asynchronous I/O framework, using thread pools to spread load without +exceeding typical system limits. + +*Maintainability*:: NNG's architecture is designed to be modular and +easily grasped by developers unfamiliar with the code base. The code +is also well documented. + +*Extensibility*:: Because it avoids ties to file descriptors, and avoids +confusing interlocking state machines, it is easier to add new protocols +and transports to NNG. This was demonstrated by the addition of the +TLS and ZeroTier transports. + +*Security*:: NNG provides TLS 1.2 and ZeroTier transports, offering +support for robust and industry standard authentication and encryption. +In addition, it is hardened to be resilient against malicious attackers, +with special consideration given to use in a hostile Internet. + +*Usability*:: NNG eschews slavish adherence parts of the more complex and +less well understood POSIX APIs, while adopting the semantics that are +familiar and useful. New APIs are intuitive, and the optional support +for separating protocol context and state from sockets makes creating +concurrent applications vastly simpler than previously possible. + +== Compatibility + +This project offers both wire compatibility and API compatibility, +so most nanomsg users can begin using NNG right away. + +Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications +can inter-operate with NNG applications automatically. + +That said, there are some areas where legacy nanomsg still offers +capabilities NNG lacks -- specifically enhanced observability with +statistics, and tunable prioritization of different destinations +are missing, but will be added in a future release. + +Additionally, some API capabilities that are useful for foreign +language bindings are not implemented yet. + +Some simple single threaded, synchronous applications may perform better under +legacy nanomsg than under NNG. (We believe that these applications are the +least commonly deployed, and least interesting from a performance perspective. +NNG's internal design is slightly less efficient in such scenarios, but it +greatly benefits when concurrency or when multiple sockets or network peers +are involved.) + +== Supported Platforms + +NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris, +FreeBSD, Android, and iOS. Most other POSIX platforms should work out of +the box but have not been tested. Very old versions of otherwise supported +platforms might not work. + +== Requirements + +To build this project, you will need a C99 compatible compiler and +http://www.cmake.org[CMake] version 3.13 or newer. + +We recommend using the https://ninja-build.org[Ninja] build +system (pass "-G Ninja" to CMake) when you can. +(And not just because Ninja sounds like "NNG" -- it's also +blindingly fast and has made our lives as developers measurably better.) + +If you want to build with TLS support you will also need +https://tls.mbed.org[Mbed TLS]. See <> for details. + +== Quick Start + +With a Linux or UNIX environment: + +[source,sh] +---- + $ mkdir build + $ cd build + $ cmake -G Ninja .. + $ ninja + $ ninja test + $ ninja install +---- + +== API Documentation + +The API documentation is provided in Asciidoc format in the +`docs/man` subdirectory, and also +https://nanomsg.github.io/nng[online]. +The <> page provides a conceptual overview and links to +manuals for various patterns. +The <> page is a good starting point for the API reference. + +You can also purchase a copy of the +http://staysail.tech/books/nng_reference/index.html[__NNG Reference Manual__]. +(It is published in both electronic and printed formats.) +Purchases of the book help fund continued development of NNG. + +== Example Programs + +Some demonstration programs have been created to help serve as examples. +These are located in the `demo` directory. + +== Legacy Compatibility + +A legacy `libnanomsg` compatible API is available, and while it offers +less capability than the modern NNG API, it may serve as a transition aid. +Please see <> for details. + +== Commercial Support + +Commercial support for NNG is available. + +Please contact mailto:info@staysail.tech[Staysail Systems, Inc.] to +inquire further. + +== Commercial Sponsors + +The development of NNG has been made possible through the generous +sponsorship of https://www.capitar.com[Capitar IT Group BV] and +http://staysail.tech[Staysail Systems, Inc.]. diff --git a/external/nng/RELEASE_NOTES.adoc b/external/nng/RELEASE_NOTES.adoc new file mode 100644 index 0000000..c27c04b --- /dev/null +++ b/external/nng/RELEASE_NOTES.adoc @@ -0,0 +1,115 @@ +ifdef::env-github[] +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +endif::[] + += RELEASE NOTES FOR NNG v1.7.0 + +This document has the following sections: + +* Notable Changes +* End of Feature Announcements + +== Notable Changes (since 1.6.0) + +A new compile time setting, `NNG_MAX_POLLER_THREADS` is introduced, +with a default value of 8, and will limit the number of threads +used for pollers that are concurrent (currently only Windows). +Additionally, for single core systems only two threads will be started +instead of four. + +A new supplemental API, nng_id_map(3), is made available. +This exposes the internal ID hash API NNG uses mapping integer IDs +(like socket IDs) to data structures. +It also brings back support for 64-bit IDs. +See bug #1740. + +Setting the `NNG_OPT_RECVMAXSZ` setting no longer affects pipes +that are already established. The old behavior was undocumented +and racy. Please set this setting before starting any listeners +or dialers. + +A new transport (experimental), for `socket://` is available. +This allows one to create a connection using sockets created +with `socketpair()` (or the new `nng_socket_pair()` supplemental API), +which can help use cases where file descriptors are passed between +processes or inherited via `fork()`. This API is only available on +Linux. It does have somewhat different semantics for establishing +the connection, so please see the manual page for `nng_socket(5)` for more information. + +WebSocket close is fixed to conform to RFC 6455, sending the +close frame, and waiting to receive the close frame from the +peer. This allows websocket based connections to ensure that +data messages are fully delivered before shutting down. +See bugs #1733, #1734 and #1735. +Thanks @alawn-wang for the inspiration and a first +draft of the change. + +The REQ and SURVEYOR protocols were fixed to improve scalability +when many clients or many contexts are used. As part of this change, +a new option, `NNG_OPT_REQ_RESENDTICK` is available to adjust how +often we check for expired requests. + +A new ability to override compile-time settings for thread counts +is available. This facility is considered experimental, and is not +documented in manual pages -- and is subject to change without notice. +Please see nng_init_set_parameter() in the nng.h header file. The +values that can be tuned are listed there along with comments +describing their use. See bug #1572. + +As part of the fixes for #1572, tunable values for setting fixed +values (rather upper limits) for thread counts are now exposed properly +via CMake variables. These are `NNG_NUM_EXPIRE_THREADS` and `NNG_NUM_TASKQ_THREADS`. + +A new API, `nng_aio_set_expire()` is introduced as a complement to +`nng_aio_set_timeout()`. This provides absolute expiration times, +which may be easier in circumstances involving multiple actions such +as common state-machine based idioms. + +A bug which caused TLS connections to spin on accept, causing high +CPU usage, is fixed. (See bug #1673) +Various minor documentation fixes were made, some contributed by +Patrik Wenger . + +== End of Feature Announcements + +=== Windows Legacy Support + +As announced in 1.6.0, +NNG no longer officially claims support for Windows Vista, Windows 7, Windows 8, or Windows 8.1. +We have no ability to build or test these versions, and Microsoft no longer supports them. +Continued use of these systems may be possible, but future changes may break +compatibility with these systems without further notice. + +=== Windows Named Pipe Support Changes + +A future release of NNG may make the ipc:// URL format operate over UNIX domain sockets by default. +We plan to do this for the other projects we control, such as mangos, as well. + +Should this occur, it will be breaking for Windows versions older than Windows 10 17063. + +=== macOS Legacy Support + +As announced in 1.6.0, +NNG no longer officially supports macOS versions older than 10.12. +Future versions of NNG may depend on features not available on versions of macOS older than 10.12. + +=== Documentation Restructuring + +A future release of NNG may restructure the documentation to make it more +approachable for more users. This would break the organization as UNIX manual +pages, and would also drop the ability to format them as UNIX nroff source. +The best way to view this documentation is on the NNG website, or with the PDF or printed manual. + +=== ZeroTier Incompatible Changes + +A future release of NNG may break compatibility for applications built using earlier versions +of NNG when using the ZeroTier transport. ZeroTier support is an experimental feature. + +=== Pair1 Polyamorous Mode + +A future release of NNG may remove Pair 1 Polyamorous support, but *only* if a suitable +replacement is provided. Pair1 Polyamorous mode is an experimental feature. + +Alternatively we may change the Pair1 wire protocol in a way that breaks compatibility with +earlier versions of Pair1 Polyamorous mode. diff --git a/external/nng/UKRAINE.adoc b/external/nng/UKRAINE.adoc new file mode 100644 index 0000000..4e3a4b1 --- /dev/null +++ b/external/nng/UKRAINE.adoc @@ -0,0 +1,90 @@ +# Ukraine, Russia, and a World Tragedy + +## A message to those inside Russia + +### Written March 4, 2022. + +It is with a very heavy heart that I write this. I am normally opposed to the use of open source +projects to communicate political positions or advocate for things outside the immediate relevancy +to that project. + +However, the events occurring in Ukraine, and specifically the unprecedented invasion of Ukraine by +Russian forces operating under orders from Russian President Vladimir Putin compel me to speak out. + +Those who know me, know that I have family, friends, and colleagues in Russia, and Ukraine both. My closest friends +have historically been Russian friends my wife's hometown of Chelyabinsk. I myself have in the past +frequently traveled to Russia, and indeed operated a software development firm with offices in St. Petersburg. +I had a special kinship with Russia and its people. + +I say "had", because I fear that the actions of Putin, and the massive disinformation campaign that his regime +has waged inside Russia, mean that it's likely that I won't see those friends again. At present, I'm not sure +my wife will see her own mother again. We no longer feel it's safe for either of us to return Russia given +actions taken by the regime to crack down on those who express disagreement. + +Russian citizens are being led to believe it is acting purely defensively, and that only legitimate military +targets are being targeted, and that all the information we have received in the West are fakes. + +I am confident that nothing could be further from the truth. + +This has caused many in Russia, including people whom I respect and believe to be smarter than this, to +stand by Putin, and endorse his actions. The claim is that the entirety of NATO is operating at the behest +of the USA, and that the entirety of Europe was poised to attack Russia. While this is clearly absurd to those +of us with any understanding of western politics, Russian citizens are being fed this lie, and believing it. + +If you're reading this from inside Russia -- YOU are the person that I hope this message reaches. Your +government is LYING to you. Of course, all governments lie all the time. But consider this. Almost the +entire world has condemned the invasion of Ukraine as criminal, and has applied sanctions. Even countries +which have poor relations with the US sanctioning Russia, as well as nations which historically have remained +neutral. (Famously neutral -- even during World War II, Switzerland has acted to apply sanctions in +concert with the rest of the world.) + +Ask yourself, why does Putin fear a free press so much, if what he says is true? Why the crack-downs on +children expressing only a desire for peace with Ukraine? Why would the entire world unified against him, +if Putin was in the right? Why would the only countries that stood with Russia against +the UN resolution to condemn these acts as crimes be Belarus, North Korea, and Syria? Even countries normally +allied to Russia could not bring themselves to do more than abstain from the vote to condemn it. + +To be clear, I do not claim that the actions taken by the West or by the Ukrainian government were completely +blameless. On the contrary, I understand that Western media is biased, and the truth is rarely exactly +as reported. I believe that there is a kernel of truth in the claims of fascists and ultra-nationalist +militias operating in Ukraine and specifically Donbas. However, I am also equally certain that Putin's +response is out of proportion, and that concerns about such militias are principally just a pretext to justify +an invasion. + +Europe is at war, unlike we've seen in my lifetime. The world is more divided, and closer to nuclear holocaust +than it has been since the Cold War. And that is 100% the fault of Putin. + +While Putin remains in power, there cannot really be any way for Russian international relations to return +to normal. Putin has set your country on a path to return to the Cold War, likely because he fancies himself +to be a new Stalin. However, unlike the Soviet Union, the Russian economy does not have the wherewithal to +stand on its own, and the invasion of Ukraine has fully ensured that Russia will not find any friends anywhere +else in Europe, and probably few places in Asia. + +The *only* paths forward for Russia are either a Russia without Putin (and those who would support his agenda), +or a complete breakdown of Russian prosperity, likely followed by the increasing international conflict that will +be the natural escalation from a country that is isolated and impoverished. Those of us observing from the West are +gravely concerned, because we cannot see any end to this madness that does not result in nuclear conflict, +unless from within. + +In the meantime, the worst prices will be paid for by innocents in Ukraine, and by young Russian men +forced to carry out the orders of Putin's corrupt regime. + +And *that* is why I write this -- to appeal to those within Russia to open your eyes, and think with +your minds. It is right and proper to be proud of your country and its rich heritage. But it is also +right and proper to look for ways to save it from the ruinous path that its current leadership has set it upon, +and to recognize when that leadership is no longer acting in interest of the country or its people. + + - Garrett D'Amore, March 4, 2022 + +Updates on March 16, 2024: + +I've made some minor typographical fixes. + +It is extremely distressing to see that two years on, the +people of both Ukraine and Russia continue to suffer under this needless, pointless, conflict fought solely to assuage +the ego of a dictator. + +The actions done here, have killed thousands, probably hundreds of thousands, of soldiers and civilians alike, and there seems to be no end to the madness. I still pray for sanity to return, because the current path, if followed +to its logical conclusion, most likely ends in apocalpyse. + +If you find my sharing these truths uncomfortable, please feel welcome to cease use of my software. While the license does permit use by anyone for any reason, I would not be displeased if the Russian military, and those sympathetic to it, declined from use of any of my work. diff --git a/external/nng/cmake/CheckSanitizer.cmake b/external/nng/cmake/CheckSanitizer.cmake new file mode 100644 index 0000000..b4d4f32 --- /dev/null +++ b/external/nng/cmake/CheckSanitizer.cmake @@ -0,0 +1,30 @@ +# +# Copyright 2019 Staysail Systems, Inc. +# Copyright 2017 Capitar IT Group BV +# +# This software 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. +# + +macro (CheckSanitizer) + + if (CMAKE_C_COMPILER_ID STREQUAL "GNU") + set(NNG_SAN_LIST none address leak memory thread undefined) + elseif (CMAKE_C_COMPILER_ID STREQUAL "Clang") + set(NNG_SAN_LIST none address leak memory thread undefined) + elseif (CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(NNG_SAN_LIST none address thread undefined) + else () + set(NNG_SAN_LIST none) + endif () + set (NNG_SANITIZER none CACHE STRING "Sanitizer to use (clang or gcc).") + set_property(CACHE NNG_SANITIZER PROPERTY STRINGS ${NNG_SAN_LIST}) + mark_as_advanced (NNG_SANITIZER) + + if (NOT NNG_SANITIZER STREQUAL "none") + set (NNG_C_FLAG_SANITIZER "-fsanitize=${NNG_SANITIZER}") + message(STATUS "Enabling sanitizer: ${NNG_C_FLAG_SANITIZER}") + endif() +endmacro () diff --git a/external/nng/cmake/FindMbedTLS.cmake b/external/nng/cmake/FindMbedTLS.cmake new file mode 100644 index 0000000..2d3f05e --- /dev/null +++ b/external/nng/cmake/FindMbedTLS.cmake @@ -0,0 +1,119 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# Copyright 2017 Capitar IT Group BV +# +# This software 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. +# + +# +# Try to find the Mbed TLS libraries. +# This tries to emulate the same expectations that the stock Mbed TLS +# module uses in Mbed TLS v3.x. +# +# Sets the following: +# +# MbedTLS_FOUND - True if we found Mbed TLS. +# MbedTLS_TARGET - Target of the mbedtls library. +# MbedX509_TARGET - Target of the mbedx509 library. +# MbedCrypto_TARGET - Target of the mbedcrypto library. +# MbedTLS_VERSION - $major.$minor.$revision (e.g. ``2.6.0``). +# +# MBEDTLS_CRYPTO_LIBRARY - The mbedcrypto library. +# MBEDTLS_X509_LIBRARY - The mbedx509 library. +# MBEDTLS_TLS_LIBRARY - The mbedtls library. +# MBEDTLS_LIBRARIES - List of all three Mbed TLS libraries. +# +# Hints: +# +# Set ``MBEDTLS_ROOT`` to the root directory of Mbed TLS installation. +# + +set(_MBEDTLS_ROOT_HINTS ${MBEDTLS_ROOT} ENV MBEDTLS_ROOT) +if (NOT _MBEDTLS_ROOT_HINTS) + set(_MBEDTLS_ROOT_HINTS ${MBEDTLS_ROOT_DIR} ENV MBEDTLS_ROOT_DIR) +endif() + +set(_MBED_REQUIRED_VARS MbedTLS_TARGET MbedX509_TARGET MbedCrypto_TARGET MbedTLS_VERSION) + +include(FindPackageHandleStandardArgs) +include(CMakePushCheckState) + +find_path(_MBEDTLS_INCLUDE_DIR + NAMES mbedtls/ssl.h + HINTS ${_MBEDTLS_ROOT_HINTS} + # PATHS /usr/local + PATH_SUFFIXES include) + +find_library(_MBEDCRYPTO_LIBRARY + NAMES mbedcrypto + HINTS ${_MBEDTLS_ROOT_HINTS} + # PATHS /usr/local + # PATH_SUFFIXES lib + ) + +find_library(_MBEDX509_LIBRARY + NAMES mbedx509 + HINTS ${_MBEDTLS_ROOT_HINTS} + #PATHS /usr/local + # PATH_SUFFIXES lib + ) + +find_library(_MBEDTLS_LIBRARY + NAMES mbedtls + HINTS ${_MBEDTLS_ROOT_HINTS} + #PATHS /usr/local + #PATH_SUFFIXES lib + ) + +if ("${_MBEDTLS_TLS_LIBRARY}" STREQUAL "_MBEDTLS_TLS_LIBRARY-NOTFOUND") + message("Failed to find Mbed TLS library") +else() + + cmake_push_check_state(RESET) + set(CMAKE_REQUIRED_INCLUDES ${_MBEDTLS_INCLUDE_DIR} ${CMAKE_REQUIRED_INCLUDES_${BUILD_TYPE}}) + list(APPEND CMAKE_REQUIRED_LIBRARIES ${_MBEDTLS_LIBRARY} ${_MBEDX509_LIBRARY} ${_MBEDCRYPTO_LIBRARY}) + check_symbol_exists(mbedtls_ssl_init "mbedtls/ssl.h" _MBEDTLS_V2_OR_NEWER) + cmake_pop_check_state() + + if (NOT _MBEDTLS_V2_OR_NEWER) + message("Mbed TLS too old (must be version 2 or newer) ${_MBEDTLS_V2_OR_NEWER} UP ${_MbedTLS_V2}") + + else() + # Extract the version from the header... hopefully it matches the library. + if (EXISTS ${_MBEDTLS_INCLUDE_DIR}/mbedtls/build_info.h) + file(STRINGS ${_MBEDTLS_INCLUDE_DIR}/mbedtls/build_info.h _MBEDTLS_VERLINE + REGEX "^#define[ \t]+MBEDTLS_VERSION_STRING[\t ].*") + else () + file(STRINGS ${_MBEDTLS_INCLUDE_DIR}/mbedtls/version.h _MBEDTLS_VERLINE + REGEX "^#define[ \t]+MBEDTLS_VERSION_STRING[\t ].*") + endif () + + string(REGEX REPLACE ".*MBEDTLS_VERSION_STRING[\t ]+\"(.*)\"" "\\1" MbedTLS_VERSION ${_MBEDTLS_VERLINE}) + message("Mbed TLS version: ${MbedTLS_VERSION}") + endif() +endif() + + +add_library(MbedTLS::mbedtls UNKNOWN IMPORTED) +add_library(MbedTLS::mbedx509 UNKNOWN IMPORTED) +add_library(MbedTLS::mbedcrypto UNKNOWN IMPORTED) + + +set_target_properties(MbedTLS::mbedtls PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${_MBEDTLS_INCLUDE_DIR}") +set_target_properties(MbedTLS::mbedx509 PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${_MBEDTLS_INCLUDE_DIR}") +set_target_properties(MbedTLS::mbedcrypto PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${_MBEDTLS_INCLUDE_DIR}") + +set_target_properties(MbedTLS::mbedtls PROPERTIES IMPORTED_LOCATION "${_MBEDTLS_LIBRARY}") +set_target_properties(MbedTLS::mbedx509 PROPERTIES IMPORTED_LOCATION "${_MBEDX509_LIBRARY}") +set_target_properties(MbedTLS::mbedcrypto PROPERTIES IMPORTED_LOCATION "${_MBEDCRYPTO_LIBRARY}") + +set(MbedTLS_TARGET MbedTLS::mbedtls) +set(MbedX509_TARGET MbedTLS::mbedx509) +set(MbedCrypto_TARGET MbedTLS::mbedcrypto) + +find_package_handle_standard_args(MbedTLS REQUIRED_VARS ${_MBED_REQUIRED_VARS}) +mark_as_advanced(${_MBED_REQUIRED_VARS}) + diff --git a/external/nng/cmake/NNGHelpers.cmake b/external/nng/cmake/NNGHelpers.cmake new file mode 100644 index 0000000..b2daa1d --- /dev/null +++ b/external/nng/cmake/NNGHelpers.cmake @@ -0,0 +1,173 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# +# This software 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. +# + +# Some NNG helper functions. + +include(CheckFunctionExists) +include(CheckSymbolExists) +include(CheckStructHasMember) +include(CheckLibraryExists) +include(CheckCSourceCompiles) + +# nng_sources adds library sources using files in the current directory. +function(nng_sources) + foreach (f ${ARGN}) + target_sources(nng PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/${f}) + target_sources(nng_testing PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/${f}) + endforeach () +endfunction() + +# nng_headers adds library sources as public headers taken rooted at the include/ directory. +function(nng_headers) + foreach (f ${ARGN}) + target_sources(nng PRIVATE ${PROJECT_SOURCE_DIR}/include/${f}) + target_sources(nng_testing PRIVATE ${PROJECT_SOURCE_DIR}/include/${f}) + endforeach () +endfunction() + +# nng_defines adds defines unconditionally. +# The public library keeps these defines private, but the test library exposes these definitions +# as some of our test cases would like to know details about how the library was compiled +# as that may modify the tests themselves. +function(nng_defines) + target_compile_definitions(nng PRIVATE ${ARGN}) + target_compile_definitions(nng_testing PUBLIC ${ARGN}) + target_compile_definitions(nng_private INTERFACE ${ARGN}) +endfunction() + +# nng_find_package looks up required package and adds dependency to the cmake config. +macro(nng_find_package PACKAGE_NAME) + find_package(${PACKAGE_NAME} REQUIRED) + list(APPEND NNG_PKGS ${PACKAGE_NAME}) + list(REMOVE_DUPLICATES NNG_PKGS) + set(NNG_PKGS ${NNG_PKGS} CACHE INTERNAL "nng package dependencies" FORCE) +endmacro() + +# nng_link_libraries adds link dependencies to the libraries. +function(nng_link_libraries) + target_link_libraries(nng PRIVATE ${ARGN}) + target_link_libraries(nng_testing PRIVATE ${ARGN}) +endfunction() + +function(nng_link_libraries_public) + target_link_libraries(nng PRIVATE ${ARGN}) + target_link_libraries(nng_testing PRIVATE ${ARGN}) +endfunction() + + +# nng_include_directories adds include directories. +function(nng_include_directories) + target_include_directories(nng PRIVATE ${ARGN}) + target_include_directories(nng_testing PRIVATE ${ARGN}) +endfunction() + + +# nng_sources_if adds the sources unconditionally to the test library, +# but conditionally to the production library. This allows us to get +# full test coverage while allowing a minimized delivery. +function(nng_sources_if COND) + foreach (f ${ARGN}) + if (${COND}) + target_sources(nng PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/${f}) + endif () + target_sources(nng_testing PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/${f}) + endforeach () +endfunction() + +function(nng_headers_if COND) + foreach (f ${ARGN}) + if (COND) + target_sources(nng PRIVATE ${PROJECT_SOURCE_DIR}/include/${f}) + endif () + target_sources(nng_testing PRIVATE ${PROJECT_SOURCE_DIR}/include/${f}) + endforeach () +endfunction() + +function(nng_defines_if COND) + if (${COND}) + target_compile_definitions(nng PRIVATE ${ARGN}) + target_compile_definitions(nng_private INTERFACE ${ARGN}) + endif () + target_compile_definitions(nng_testing PUBLIC ${ARGN}) +endfunction() + +function(nng_link_libraries_if COND) + if (${COND}) + target_link_libraries(nng PRIVATE ${ARGN}) + endif () + target_link_libraries(nng_testing PRIVATE ${ARGN}) +endfunction() + +function(nng_test NAME) + if (NNG_TESTS) + add_executable(${NAME} ${NAME}.c ${ARGN}) + target_link_libraries(${NAME} nng_testing) + target_include_directories(${NAME} PRIVATE + ${PROJECT_SOURCE_DIR}/tests + ${PROJECT_SOURCE_DIR}/src + ${PROJECT_SOURCE_DIR}/include) + add_test(NAME ${NNG_TEST_PREFIX}.${NAME} COMMAND ${NAME} -t -v) + set_tests_properties(${NNG_TEST_PREFIX}.${NAME} PROPERTIES TIMEOUT 180) + endif () +endfunction() + +function(nng_test_if COND NAME) + if (${COND} AND NNG_TESTS) + add_executable(${NAME} ${NAME}.c ${ARGN}) + target_link_libraries(${NAME} nng_testing) + target_include_directories(${NAME} PRIVATE + ${PROJECT_SOURCE_DIR}/tests + ${PROJECT_SOURCE_DIR}/src + ${PROJECT_SOURCE_DIR}/include) + add_test(NAME ${NNG_TEST_PREFIX}.${NAME} COMMAND ${NAME} -t -v) + set_tests_properties(${NNG_TEST_PREFIX}.${NAME} PROPERTIES TIMEOUT 180) + endif () +endfunction() + +function(nng_check_func SYM DEF) + check_function_exists(${SYM} ${DEF}) + if (${DEF}) + target_compile_definitions(nng PRIVATE ${DEF}=1) + target_compile_definitions(nng_testing PUBLIC ${DEF}=1) + target_compile_definitions(nng_private INTERFACE ${DEF}=1) + endif () +endfunction(nng_check_func) + +function(nng_check_sym SYM HDR DEF) + check_symbol_exists(${SYM} ${HDR} ${DEF}) + if (${DEF}) + target_compile_definitions(nng PRIVATE ${DEF}=1) + target_compile_definitions(nng_testing PUBLIC ${DEF}=1) + target_compile_definitions(nng_private INTERFACE ${DEF}=1) + endif () +endfunction(nng_check_sym) + +function(nng_check_lib LIB SYM DEF) + check_library_exists(${LIB} ${SYM} "" ${DEF}) + if (${DEF}) + target_compile_definitions(nng PRIVATE ${DEF}=1) + target_compile_definitions(nng_testing PUBLIC ${DEF}=1) + target_compile_definitions(nng_private INTERFACE ${DEF}=1) + target_link_libraries(nng PRIVATE ${LIB}) + target_link_libraries(nng_testing PRIVATE ${LIB}) + endif () +endfunction(nng_check_lib) + +function(nng_check_struct_member STR MEM HDR DEF) + check_struct_has_member("struct ${STR}" ${MEM} ${HDR} ${DEF}) + if (${DEF}) + target_compile_definitions(nng PRIVATE ${DEF}=1) + target_compile_definitions(nng_testing PUBLIC ${DEF}=1) + target_compile_definitions(nng_private INTERFACE ${DEF}=1) + endif () +endfunction(nng_check_struct_member) + +macro(nng_directory DIR) + set(NNG_TEST_PREFIX ${NNG_TEST_PREFIX}.${DIR}) +endmacro(nng_directory) diff --git a/external/nng/cmake/NNGOptions.cmake b/external/nng/cmake/NNGOptions.cmake new file mode 100644 index 0000000..183e9d9 --- /dev/null +++ b/external/nng/cmake/NNGOptions.cmake @@ -0,0 +1,153 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# +# This software 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. +# + +# NNG Options. These are user configurable knobs. + +include(CMakeDependentOption) + +if (CMAKE_CROSSCOMPILING) + set(NNG_NATIVE_BUILD OFF) +else () + set(NNG_NATIVE_BUILD ON) +endif () + +# Global options. +option(BUILD_SHARED_LIBS "Build shared library" ${BUILD_SHARED_LIBS}) + +# We only build command line tools and tests if we are not in a +# cross-compile situation. Cross-compiling users who still want to +# build these must enable them explicitly. Some of these switches +# must be enabled rather early as we use their values later. +option(NNG_TESTS "Build and run tests." ${NNG_NATIVE_BUILD}) +option(NNG_TOOLS "Build extra tools." ${NNG_NATIVE_BUILD}) +option(NNG_ENABLE_NNGCAT "Enable building nngcat utility." ${NNG_TOOLS}) +option(NNG_ENABLE_COVERAGE "Enable coverage reporting." OFF) +# Eliding deprecated functionality can be used to build a slimmed down +# version of the library, or alternatively to test for application +# preparedness for expected feature removals (in the next major release.) +# Applications can also set the NNG_ELIDE_DEPRECATED preprocessor symbol +# before including -- this will prevent declarations from +# being exposed to applications, but it will not affect their ABI +# availability for existing compiled applications. +# Note: Currently this breaks the test suite, so we only do it +# for the public library. +option(NNG_ELIDE_DEPRECATED "Elide deprecated functionality." OFF) + +# Turning off the compatibility layer can save some space, and +# compilation time, but may break legacy applications It should +# be left enabled when building a shared library. +option(NNG_ENABLE_COMPAT "Enable legacy nanomsg API." ON) + +option(NNG_ENABLE_STATS "Enable statistics." ON) +mark_as_advanced(NNG_ENABLE_STATS) + +# Protocols. +option (NNG_PROTO_BUS0 "Enable BUSv0 protocol." ON) +mark_as_advanced(NNG_PROTO_BUS0) + +option (NNG_PROTO_PAIR0 "Enable PAIRv0 protocol." ON) +mark_as_advanced(NNG_PROTO_PAIR0) + +option (NNG_PROTO_PAIR1 "Enable PAIRv1 protocol." ON) +mark_as_advanced(NNG_PROTO_PAIR1) + +option (NNG_PROTO_PUSH0 "Enable PUSHv0 protocol." ON) +mark_as_advanced(NNG_PROTO_PUSH0) + +option (NNG_PROTO_PULL0 "Enable PULLv0 protocol." ON) +mark_as_advanced(NNG_PROTO_PULL0) + +option (NNG_PROTO_PUB0 "Enable PUBv0 protocol." ON) +mark_as_advanced(NNG_PROTO_PUB0) + +option (NNG_PROTO_SUB0 "Enable SUBv0 protocol." ON) +mark_as_advanced(NNG_PROTO_SUB0) + +option(NNG_PROTO_REQ0 "Enable REQv0 protocol." ON) +mark_as_advanced(NNG_PROTO_REQ0) + +option(NNG_PROTO_REP0 "Enable REPv0 protocol." ON) +mark_as_advanced(NNG_PROTO_REP0) + +option (NNG_PROTO_RESPONDENT0 "Enable RESPONDENTv0 protocol." ON) +mark_as_advanced(NNG_PROTO_RESPONDENT0) + +option (NNG_PROTO_SURVEYOR0 "Enable SURVEYORv0 protocol." ON) +mark_as_advanced(NNG_PROTO_SURVEYOR0) + +# TLS support. + +# Enabling TLS is required to enable support for the TLS transport +# and WSS. It does require a 3rd party TLS engine to be selected. +option(NNG_ENABLE_TLS "Enable TLS support." OFF) +if (NNG_ENABLE_TLS) + set(NNG_SUPP_TLS ON) +endif () + +if (NNG_ENABLE_TLS) + set(NNG_TLS_ENGINES mbed wolf none) + # We assume Mbed for now. (Someday replaced perhaps with Bear.) + set(NNG_TLS_ENGINE mbed CACHE STRING "TLS engine to use.") + set_property(CACHE NNG_TLS_ENGINE PROPERTY STRINGS ${NNG_TLS_ENGINES}) +else () + set(NNG_TLS_ENGINE none) +endif () + +# HTTP API support. +option (NNG_ENABLE_HTTP "Enable HTTP API." ON) +if (NNG_ENABLE_HTTP) + set(NNG_SUPP_HTTP ON) +endif() +mark_as_advanced(NNG_ENABLE_HTTP) + +# Some sites or kernels lack IPv6 support. This override allows us +# to prevent the use of IPv6 in environments where it isn't supported. +option (NNG_ENABLE_IPV6 "Enable IPv6." ON) +mark_as_advanced(NNG_ENABLE_IPV6) + +# +# Transport Options. +# + +option (NNG_TRANSPORT_INPROC "Enable inproc transport." ON) +mark_as_advanced(NNG_TRANSPORT_INPROC) + +option (NNG_TRANSPORT_IPC "Enable IPC transport." ON) +mark_as_advanced(NNG_TRANSPORT_IPC) + +# TCP transport +option (NNG_TRANSPORT_TCP "Enable TCP transport." ON) +mark_as_advanced(NNG_TRANSPORT_TCP) + +# TLS transport +option (NNG_TRANSPORT_TLS "Enable TLS transport." ON) +mark_as_advanced(NNG_TRANSPORT_TLS) + +# WebSocket +option (NNG_TRANSPORT_WS "Enable WebSocket transport." ON) +mark_as_advanced(NNG_TRANSPORT_WS) + +CMAKE_DEPENDENT_OPTION(NNG_TRANSPORT_WSS "Enable WSS transport." ON + "NNG_ENABLE_TLS" OFF) +mark_as_advanced(NNG_TRANSPORT_WSS) + +option (NNG_TRANSPORT_FDC "Enable File Descriptor transport (EXPERIMENTAL)" ON) +mark_as_advanced(NNG_TRANSPORT_FDC) + +# ZeroTier +option (NNG_TRANSPORT_ZEROTIER "Enable ZeroTier transport (requires libzerotiercore)." OFF) +mark_as_advanced(NNG_TRANSPORT_ZEROTIER) + +if (NNG_TRANSPORT_WS OR NNG_TRANSPORT_WSS) + # Make sure things we *MUST* have are enabled. + set(NNG_SUPP_WEBSOCKET ON) + set(NNG_SUPP_HTTP ON) + set(NNG_SUPP_BASE64 ON) + set(NNG_SUPP_SHA1 ON) +endif() diff --git a/external/nng/cmake/nng-config.cmake.in b/external/nng/cmake/nng-config.cmake.in new file mode 100644 index 0000000..3f155e5 --- /dev/null +++ b/external/nng/cmake/nng-config.cmake.in @@ -0,0 +1,26 @@ +# Copyright 2023 Staysail Systems, Inc. +# +# This software 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. + + +@PACKAGE_INIT@ + +set(NNG_MAJOR_VERSION "@NNG_MAJOR_VERSION@") +set(NNG_MINOR_VERSION "@NNG_MINOR_VERSION@") +set(NNG_PATCH_VERSION "@NNG_PATCH_VERSION@") + +set_and_check(NNG_INCLUDE_DIRS "@PACKAGE_INCLUDE_INSTALL_DIRS@") + +include("${CMAKE_CURRENT_LIST_DIR}/nng-targets.cmake") + +# Make sure we find packages for our dependencies +foreach(_PKG IN ITEMS @NNG_PKGS@) + find_package(${_PKG} REQUIRED) +endforeach () + +set(NNG_LIBRARY nng::nng) + +check_required_components(@PROJECT_NAME@) diff --git a/external/nng/demo/async/CMakeLists.txt b/external/nng/demo/async/CMakeLists.txt new file mode 100644 index 0000000..ef9311b --- /dev/null +++ b/external/nng/demo/async/CMakeLists.txt @@ -0,0 +1,27 @@ +# +# Copyright 2018 Capitar IT Group BV +# Copyright 2018 Staysail Systems, Inc. +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.12) + +project(nng-asyncdemo) + +set(PARALLEL 128 CACHE STRING "Parallelism (min 4, max 1000)") + +# Call this from your own project's makefile. +find_package(nng CONFIG REQUIRED) + +find_package(Threads) + +add_executable(server server.c) +target_link_libraries(server nng::nng) +target_compile_definitions(server PRIVATE NNG_ELIDE_DEPRECATED PARALLEL=${PARALLEL}) + +add_executable(client client.c) +target_link_libraries(client nng::nng) +target_compile_definitions(client PRIVATE NNG_ELIDE_DEPRECATED) diff --git a/external/nng/demo/async/README.adoc b/external/nng/demo/async/README.adoc new file mode 100644 index 0000000..87c44ce --- /dev/null +++ b/external/nng/demo/async/README.adoc @@ -0,0 +1,50 @@ += async + +This is a simple asynchronous demo, that demonstrates use of the contexts +and asynchronous message handling and operations, to obtain highly concurrent +processing with minimal fuss. + +== Compiling + +This is set up for configuration with CMake for ease of use. + +You can override the level of concurrency with the `PARALLEL` option. + +This determines how many requests the server will accept +at a time, and keep outstanding. Note that for our toy implementation, +we create this many "logical" flows of execution (contexts) (these are +_NOT_ threads), where a request is followed by a reply. + +The value of `PARALLEL` must be at least one, and may be as large +as your memory will permit. (The default value is 128.) Probably +you want the value to be small enough to ensure that you have enough +file descriptors. (You can create more contexts than this, but generally +you can't have more than one client per descriptor. Contexts can be used +on the client side to support many thousands of concurrent requests over +even just a single TCP connection, however.) + +You can also build this all by hand with Make or whatever. + +On UNIX-style systems: + +[source, bash] +---- +% export CPPFLAGS="-D PARALLEL=32 -I /usr/local/include" +% export LDFLAGS="-L /usr/local/lib -lnng" +% export CC="cc" +% ${CC} ${CPPFLAGS} server.c -o server ${LDFLAGS} +% ${CC} ${CPPFLAGS} client.c -o client ${LDFLAGS} +---- + +== Running + +The easiest thing is to simply use the `run.sh` script, which +sends COUNT (10) random jobs to the server in parallel. + +You can of course run the client and server manually instead. + +The server takes the address (url) as its only argument. + +The client takes the address (url), followed by the number of +milliseconds the server should "wait" before responding (to simulate +an expensive operation.) diff --git a/external/nng/demo/async/client.c b/external/nng/demo/async/client.c new file mode 100644 index 0000000..90fce16 --- /dev/null +++ b/external/nng/demo/async/client.c @@ -0,0 +1,95 @@ +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This software 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. +// + +// This program is just a simple client application for our demo server. +// It is in a separate file to keep the server code clearer to understand. +// +// Our demonstration application layer protocol is simple. The client sends +// a number of milliseconds to wait before responding. The server just gives +// back an empty reply after waiting that long. + +// For example: +// +// % ./server tcp://127.0.0.1:5555 & +// % ./client tcp://127.0.0.1:5555 323 +// Request took 324 milliseconds. + +#include +#include +#include +#include + +#include +#include +#include + +void +fatal(const char *func, int rv) +{ + fprintf(stderr, "%s: %s\n", func, nng_strerror(rv)); + exit(1); +} + +/* The client runs just once, and then returns. */ +int +client(const char *url, const char *msecstr) +{ + nng_socket sock; + int rv; + nng_msg * msg; + nng_time start; + nng_time end; + unsigned msec; + + msec = atoi(msecstr); + + if ((rv = nng_req0_open(&sock)) != 0) { + fatal("nng_req0_open", rv); + } + + if ((rv = nng_dial(sock, url, NULL, 0)) != 0) { + fatal("nng_dial", rv); + } + + start = nng_clock(); + + if ((rv = nng_msg_alloc(&msg, 0)) != 0) { + fatal("nng_msg_alloc", rv); + } + if ((rv = nng_msg_append_u32(msg, msec)) != 0) { + fatal("nng_msg_append_u32", rv); + } + + if ((rv = nng_sendmsg(sock, msg, 0)) != 0) { + fatal("nng_sendmsg", rv); + } + + if ((rv = nng_recvmsg(sock, &msg, 0)) != 0) { + fatal("nng_recvmsg", rv); + } + end = nng_clock(); + nng_msg_free(msg); + nng_close(sock); + + printf("Request took %u milliseconds.\n", (uint32_t)(end - start)); + return (0); +} + +int +main(int argc, char **argv) +{ + int rc; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \n", argv[0]); + exit(EXIT_FAILURE); + } + rc = client(argv[1], argv[2]); + exit(rc == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +} diff --git a/external/nng/demo/async/run.sh b/external/nng/demo/async/run.sh new file mode 100755 index 0000000..b5128eb --- /dev/null +++ b/external/nng/demo/async/run.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash + +ADDR=ipc:///tmp/async_demo +COUNT=10 + +./server $ADDR & +SERVER_PID=$! +trap "kill $SERVER_PID" 0 +typeset -a CLIENT_PID +i=0 +sleep 1 +while (( i < COUNT )) +do + i=$(( i + 1 )) + rnd=$(( RANDOM % 1000 + 500 )) + echo "Starting client $i: server replies after $rnd msec" + ./client $ADDR $rnd & + eval CLIENT_PID[$i]=$! +done + +i=0 +while (( i < COUNT )) +do + i=$(( i + 1 )) + wait ${CLIENT_PID[$i]} +done +kill $SERVER_PID diff --git a/external/nng/demo/async/server.c b/external/nng/demo/async/server.c new file mode 100644 index 0000000..528926e --- /dev/null +++ b/external/nng/demo/async/server.c @@ -0,0 +1,178 @@ +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This software 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. +// + +// This program serves as an example for how to write an async RPC service, +// using the request/reply pattern and contexts (nng_ctx(5)). The server +// allocates a number of contexts up front, which determines the amount of +// parallelism possible. The callbacks are handled asynchronously, so +// this could be done by threads, or something similar. For our uses we +// make use of an event driven architecture that we already have available. + +// Our demonstration application layer protocol is simple. The client sends +// a number of milliseconds to wait before responding. The server just gives +// back an empty reply after waiting that long. + +// To run this program, start the server as async_demo -s +// Then connect to it with the client as async_client . +// +// For example: +// +// % ./server tcp://127.0.0.1:5555 & +// % ./client tcp://127.0.0.1:5555 323 +// Request took 324 milliseconds. + +#include +#include +#include +#include + +#include +#include +#include + +// Parallel is the maximum number of outstanding requests we can handle. +// This is *NOT* the number of threads in use, but instead represents +// outstanding work items. Select a small number to reduce memory size. +// (Each one of these can be thought of as a request-reply loop.) Note +// that you will probably run into limitations on the number of open file +// descriptors if you set this too high. (If not for that limit, this could +// be set in the thousands, each context consumes a couple of KB.) +#ifndef PARALLEL +#define PARALLEL 128 +#endif + +// The server keeps a list of work items, sorted by expiration time, +// so that we can use this to set the timeout to the correct value for +// use in poll. +struct work { + enum { INIT, RECV, WAIT, SEND } state; + nng_aio *aio; + nng_msg *msg; + nng_ctx ctx; +}; + +void +fatal(const char *func, int rv) +{ + fprintf(stderr, "%s: %s\n", func, nng_strerror(rv)); + exit(1); +} + +void +server_cb(void *arg) +{ + struct work *work = arg; + nng_msg * msg; + int rv; + uint32_t when; + + switch (work->state) { + case INIT: + work->state = RECV; + nng_ctx_recv(work->ctx, work->aio); + break; + case RECV: + if ((rv = nng_aio_result(work->aio)) != 0) { + fatal("nng_ctx_recv", rv); + } + msg = nng_aio_get_msg(work->aio); + if ((rv = nng_msg_trim_u32(msg, &when)) != 0) { + // bad message, just ignore it. + nng_msg_free(msg); + nng_ctx_recv(work->ctx, work->aio); + return; + } + work->msg = msg; + work->state = WAIT; + nng_sleep_aio(when, work->aio); + break; + case WAIT: + // We could add more data to the message here. + nng_aio_set_msg(work->aio, work->msg); + work->msg = NULL; + work->state = SEND; + nng_ctx_send(work->ctx, work->aio); + break; + case SEND: + if ((rv = nng_aio_result(work->aio)) != 0) { + nng_msg_free(work->msg); + fatal("nng_ctx_send", rv); + } + work->state = RECV; + nng_ctx_recv(work->ctx, work->aio); + break; + default: + fatal("bad state!", NNG_ESTATE); + break; + } +} + +struct work * +alloc_work(nng_socket sock) +{ + struct work *w; + int rv; + + if ((w = nng_alloc(sizeof(*w))) == NULL) { + fatal("nng_alloc", NNG_ENOMEM); + } + if ((rv = nng_aio_alloc(&w->aio, server_cb, w)) != 0) { + fatal("nng_aio_alloc", rv); + } + if ((rv = nng_ctx_open(&w->ctx, sock)) != 0) { + fatal("nng_ctx_open", rv); + } + w->state = INIT; + return (w); +} + +// The server runs forever. +int +server(const char *url) +{ + nng_socket sock; + struct work *works[PARALLEL]; + int rv; + int i; + + /* Create the socket. */ + rv = nng_rep0_open(&sock); + if (rv != 0) { + fatal("nng_rep0_open", rv); + } + + for (i = 0; i < PARALLEL; i++) { + works[i] = alloc_work(sock); + } + + if ((rv = nng_listen(sock, url, NULL, 0)) != 0) { + fatal("nng_listen", rv); + } + + for (i = 0; i < PARALLEL; i++) { + server_cb(works[i]); // this starts them going (INIT state) + } + + for (;;) { + nng_msleep(3600000); // neither pause() nor sleep() portable + } +} + +int +main(int argc, char **argv) +{ + int rc; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \n", argv[0]); + exit(EXIT_FAILURE); + } + rc = server(argv[1]); + exit(rc == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +} diff --git a/external/nng/demo/http_client/CMakeLists.txt b/external/nng/demo/http_client/CMakeLists.txt new file mode 100644 index 0000000..8f4b62f --- /dev/null +++ b/external/nng/demo/http_client/CMakeLists.txt @@ -0,0 +1,21 @@ +# +# Copyright 2018 Capitar IT Group BV +# Copyright 2018 Staysail Systems, Inc. +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.12) + +project(http_client) + +# Call this from your own project's makefile. +find_package(nng CONFIG REQUIRED) + +find_package(Threads) + +add_executable(http_client http_client.c) +target_link_libraries(http_client nng::nng) +target_compile_definitions(http_client PRIVATE NNG_ELIDE_DEPRECATED) diff --git a/external/nng/demo/http_client/README.adoc b/external/nng/demo/http_client/README.adoc new file mode 100644 index 0000000..f877755 --- /dev/null +++ b/external/nng/demo/http_client/README.adoc @@ -0,0 +1,52 @@ += http_client + +This is a very simple HTTP client. It only performs HTTP GET +operations, and does not follow HTTP redirects. Think of it as +a trivialized version of cURL. It is super simple, taking the +URL on the command line, and emitting the results to stdout. + +For clarity, we are eliding TLS support. + +It may not work on all systems, but it should work anywhere that + both the standard C library and nng itself are available. + +We check for errors, but no effort is made to clean up resources, +since this program just exits. In longer running programs or libraries, +callers should take care to clean up things that they allocate. + +Unfortunately many famous sites use redirects (usually to HTTPS +sites), so it's not a very useful replacement for cURL. + +== Compiling + +The following is an example typical of UNIX and similar systems like +Linux and macOS: + +[source, bash] +---- +% export CPPFLAGS="-I /usr/local/include" +% export LDFLAGS="-L /usr/local/lib -lnng" +% export CC="cc" +% ${CC} ${CPPFLAGS} http_client.c -o http_client ${LDFLAGS} +---- + +Alternatively, CMake can be used. Here's an example if you have +Ninja build handy (highly recommended): + +[source, bash] +---- +% mkdir build +% cd build +% cmake -G Ninja .. +% ninja +---- + +== Running + +Make sure you specify the full URL (if the root page include +the simple "/". The URL parser does not add it for you automatically.) + +[source, bash] +---- +% ./http_client http://httpbin.org/ip +---- diff --git a/external/nng/demo/http_client/http_client.c b/external/nng/demo/http_client/http_client.c new file mode 100644 index 0000000..a00c842 --- /dev/null +++ b/external/nng/demo/http_client/http_client.c @@ -0,0 +1,147 @@ +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This software 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. +// + +// This is a very simple HTTP client. It only performs HTTP GET +// operations, and does not follow HTTP redirects. Think of it as +// a trivialized version of CURL. It is super simple, taking the +// URL on the command line, and emitting the results to stdout. +// For clarity, we are eliding TLS support. + +// It may not work on all systems, but it should work anywhere that +// both the standard C library and nng itself are available. + +// We check for errors, but no effort is made to clean up resources, +// since this program just exits. In longer running programs or libraries, +// callers should take care to clean up things that they allocate. + +// Unfortunately many famous sites use redirects, so you won't see that +// emitted. + +// Example usage: +// +// % export CPPFLAGS="-I /usr/local/include" +// % export LDFLAGS="-L /usr/local/lib -lnng" +// % export CC="cc" +// % ${CC} ${CPPFLAGS} http_client.c -o http_client ${LDFLAGS} +// % ./http_client http://httpbin.org/ip +// + +#include +#include +#include +#include + +void +fatal(int rv) +{ + fprintf(stderr, "%s\n", nng_strerror(rv)); + exit(1); +} + +int +main(int argc, char **argv) +{ + nng_http_client *client; + nng_http_conn * conn; + nng_url * url; + nng_aio * aio; + nng_http_req * req; + nng_http_res * res; + const char * hdr; + int rv; + int len; + void * data; + nng_iov iov; + + if (argc < 2) { + fprintf(stderr, "No URL supplied!\n"); + exit(1); + } + + if (((rv = nng_url_parse(&url, argv[1])) != 0) || + ((rv = nng_http_client_alloc(&client, url)) != 0) || + ((rv = nng_http_req_alloc(&req, url)) != 0) || + ((rv = nng_http_res_alloc(&res)) != 0) || + ((rv = nng_aio_alloc(&aio, NULL, NULL)) != 0)) { + fatal(rv); + } + + // Start connection process... + nng_http_client_connect(client, aio); + + // Wait for it to finish. + nng_aio_wait(aio); + if ((rv = nng_aio_result(aio)) != 0) { + fatal(rv); + } + + // Get the connection, at the 0th output. + conn = nng_aio_get_output(aio, 0); + + // Request is already set up with URL, and for GET via HTTP/1.1. + // The Host: header is already set up too. + + // Send the request, and wait for that to finish. + nng_http_conn_write_req(conn, req, aio); + nng_aio_wait(aio); + + if ((rv = nng_aio_result(aio)) != 0) { + fatal(rv); + } + + // Read a response. + nng_http_conn_read_res(conn, res, aio); + nng_aio_wait(aio); + + if ((rv = nng_aio_result(aio)) != 0) { + fatal(rv); + } + + if (nng_http_res_get_status(res) != NNG_HTTP_STATUS_OK) { + fprintf(stderr, "HTTP Server Responded: %d %s\n", + nng_http_res_get_status(res), + nng_http_res_get_reason(res)); + } + + // This only supports regular transfer encoding (no Chunked-Encoding, + // and a Content-Length header is required.) + if ((hdr = nng_http_res_get_header(res, "Content-Length")) == NULL) { + fprintf(stderr, "Missing Content-Length header.\n"); + exit(1); + } + + len = atoi(hdr); + if (len == 0) { + return (0); + } + + // Allocate a buffer to receive the body data. + data = malloc(len); + + // Set up a single iov to point to the buffer. + iov.iov_len = len; + iov.iov_buf = data; + + // Following never fails with fewer than 5 elements. + nng_aio_set_iov(aio, 1, &iov); + + // Now attempt to receive the data. + nng_http_conn_read_all(conn, aio); + + // Wait for it to complete. + nng_aio_wait(aio); + + if ((rv = nng_aio_result(aio)) != 0) { + fatal(rv); + } + + fwrite(data, 1, len, stdout); + return (0); +} diff --git a/external/nng/demo/pubsub_forwarder/CMakeLists.txt b/external/nng/demo/pubsub_forwarder/CMakeLists.txt new file mode 100644 index 0000000..821e05c --- /dev/null +++ b/external/nng/demo/pubsub_forwarder/CMakeLists.txt @@ -0,0 +1,18 @@ +# This software 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. + +cmake_minimum_required(VERSION 3.10) +project(pubsub_forwarder C) + +# Find the nng library +find_package(nng REQUIRED) + +# Add the executable target +add_executable(pubsub_forwarder pubsub_forwarder.c) + +target_compile_options(pubsub_forwarder PRIVATE -Wall -Wextra -Wpedantic -Werror -O2) + +# Link against the nng library +target_link_libraries(pubsub_forwarder PRIVATE nng) diff --git a/external/nng/demo/pubsub_forwarder/README.adoc b/external/nng/demo/pubsub_forwarder/README.adoc new file mode 100644 index 0000000..55832b9 --- /dev/null +++ b/external/nng/demo/pubsub_forwarder/README.adoc @@ -0,0 +1,62 @@ += PubSub Forwarder + +This is a trivial example of a forwarder/proxy for the pub/sub pattern. + +The concept is as follows: the forwarder will listen for connections on +both a front-end port and a back-end port. The front-end will act as a +subscriber so that publishers can publish to it. The back-end will act +as a publisher so that subscribers can subscribe to it. The front-end +then forwards to the back end. + +== Compiling + +CMake with ninja-build is simplest: + +[source, bash] +---- +cmake -GNinja -B build +cd build +ninja +---- + +Or if you prefer a traditional approach, +the following is an example typical of UNIX and similar systems like +Linux and macOS may appeal: + +[source, bash] +---- +export CPPFLAGS="-I /usr/local/include" +export LDFLAGS="-L /usr/local/lib -lnng" +export CC="cc" +${CC} ${CPPFLAGS} pubsub_forwarder.c -o pubsub_forwarder ${LDFLAGS} +---- + +== Running + +An example setup for running this example would involve the following: + +. Step 1: Run this example binary (in the background or a terminal, etc) +. Step 2: In a new terminal, run the following + +[source, bash] +---- +nngcat --sub --dial "tcp://localhost:3328" --quoted +---- + +. Step 3: In a second terminal, run the same command again to give us two subscribers + +[source, bash] +---- +nngcat --sub --dial "tcp://localhost:3328" --quoted +---- + + +. In a third terminal, run the following to publish a counter + +[source, bash] +---- +for n in $(seq 0 99); do nngcat --pub --dial "tcp://localhost:3327" --data "$n"; done +---- + + + diff --git a/external/nng/demo/pubsub_forwarder/pubsub_forwarder.c b/external/nng/demo/pubsub_forwarder/pubsub_forwarder.c new file mode 100644 index 0000000..e79c04b --- /dev/null +++ b/external/nng/demo/pubsub_forwarder/pubsub_forwarder.c @@ -0,0 +1,96 @@ +// +// This software 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. +// + +// +// Forwarder example based on https://github.com/C-o-r-E/nng_pubsub_proxy +// +// This example shows how to use raw sockets to set up a forwarder or proxy for +// pub/sub. +// +// An example setup for running this example would involve the following: +// +// - Run this example binary (in the background or a terminal, etc) +// - In a new terminal, run +// `nngcat --sub --dial "tcp://localhost:3328" --quoted` +// - In a second terminal, run +// `nngcat --sub --dial "tcp://localhost:3328" --quoted` +// - In a third terminal, run +// `for n in $(seq 0 99);` +// `do nngcat --pub --dial "tcp://localhost:3327" --data "$n";` +// `done` +// +#include +#include +#include + +#include +#include +#include + +#define PROXY_FRONT_URL "tcp://localhost:3327" +#define PROXY_BACK_URL "tcp://localhost:3328" + +void +panic_on_error(int should_panic, const char *format, ...) +{ + if (should_panic) { + va_list args; + va_start(args, format); + vprintf(format, args); + va_end(args); + exit(EXIT_FAILURE); + } +} + +int +main() +{ + nng_socket sock_front_end = NNG_SOCKET_INITIALIZER; + nng_socket sock_back_end = NNG_SOCKET_INITIALIZER; + int ret = 0; + + // + // First we need some nng sockets. Not to be confused with network + // sockets + // + ret = nng_sub0_open_raw(&sock_front_end); + panic_on_error(ret, "Failed to open front end socket\n"); + + ret = nng_pub0_open_raw(&sock_back_end); + panic_on_error(ret, "Failed to open back end socket\n"); + + // + // Now we need to set up a listener for each socket so that they have + // addresses + // + + nng_listener front_ls = NNG_LISTENER_INITIALIZER; + nng_listener back_ls = NNG_LISTENER_INITIALIZER; + + ret = nng_listener_create(&front_ls, sock_front_end, PROXY_FRONT_URL); + panic_on_error(ret, "Failed to create front listener\n"); + + ret = nng_listener_create(&back_ls, sock_back_end, PROXY_BACK_URL); + panic_on_error(ret, "Failed to create back listener\n"); + + ret = nng_listener_start(front_ls, 0); + panic_on_error(ret, "Failed to start front listener\n"); + + ret = nng_listener_start(back_ls, 0); + panic_on_error(ret, "Failed to start back listener\n"); + + // + // Finally let nng do the forwarding/proxying + // + + ret = nng_device(sock_front_end, sock_back_end); + panic_on_error( + ret, "nng_device returned %d: %s\n", ret, nng_strerror(ret)); + + printf("done"); + return 0; +} \ No newline at end of file diff --git a/external/nng/demo/raw/CMakeLists.txt b/external/nng/demo/raw/CMakeLists.txt new file mode 100644 index 0000000..2df8d39 --- /dev/null +++ b/external/nng/demo/raw/CMakeLists.txt @@ -0,0 +1,22 @@ +# +# Copyright 2018 Capitar IT Group BV +# Copyright 2018 Staysail Systems, Inc. +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.12) + +project(raw) + +set(PARALLEL 128 CACHE STRING "Parallelism (min 4, max 1000)") + +find_package(nng CONFIG REQUIRED) + +find_package(Threads) + +add_executable(raw raw.c) +target_link_libraries(raw nng::nng) +target_compile_definitions(raw PRIVATE NNG_ELIDE_DEPRECATED PARALLEL=${PARALLEL}) diff --git a/external/nng/demo/raw/README.adoc b/external/nng/demo/raw/README.adoc new file mode 100644 index 0000000..2190dc4 --- /dev/null +++ b/external/nng/demo/raw/README.adoc @@ -0,0 +1,64 @@ += raw + +This is a simple asynchronous demo, that demonstrates use of the RAW +sockets with a server, along with async message handling, to obtain a +very high level of asynchronous operation, suitable for use in a highly +concurrent server application. + +== Compiling + +You can override the level of concurrency with the `PARALLEL` option. + +This determines how many requests the server will accept +at a time, and keep outstanding. Note that for our toy +implementation, we create this many "logical" flows of execution +(these are _NOT_ threads), where a request is followed by a reply. + +The value of `PARALLEL` must be at least one, and may be as large +as your memory will permit. (The default value is 32.) + +The best way to build is using cmake and Ninja build: + +[source, bash] +---- +% mkdir build +% cd build +% cmake -G Ninja .. +% ninja +---- + +You can also build the hard way. For example, on UNIX-style systems: + +[source, bash] +---- +% export CPPFLAGS="-D PARALLEL=32 -I /usr/local/include" +% export LDFLAGS="-L /usr/local/lib -lnng" +% export CC="cc" +% ${CC} ${CPPFLAGS} raw.c -o raw ${LDFLAGS} +---- + +== Running + +To run the server, use the arguments `__url__ -s`. + +To run the client, use the arguments `__url__ __msec__`. + +The _msec_ is a "delay" time that server will wait before responding. +We have these delays so simulate long running work. + +In the following example, all of the clients should complete within +2 seconds. (Assuming `PARALLEL` is defined to be large enough.) + +[source,bash] +---- +% export URL="tcp://127.0.0.1:55995" +# start the server +% ./raw $URL -s & +# start a bunch of clients +# Note that these all run concurrently! +% ./raw $URL 2 & +% ./raw $URL 2 & +% ./raw $URL 2 & +% ./raw $URL 2 & +% ./raw $URL 2 & +---- diff --git a/external/nng/demo/raw/raw.c b/external/nng/demo/raw/raw.c new file mode 100644 index 0000000..1087fa6 --- /dev/null +++ b/external/nng/demo/raw/raw.c @@ -0,0 +1,220 @@ +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This software 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. +// + +// This program serves as an example for how to write an async RPC service, +// using the RAW request/reply pattern and nn_poll. The server receives +// messages and keeps them on a list, replying to them. + +// Our demonstration application layer protocol is simple. The client sends +// a number of milliseconds to wait before responding. The server just gives +// back an empty reply after waiting that long. + +// To run this program, start the server as async_demo -s +// Then connect to it with the client as async_client . +// +// For example: +// +// % ./async tcp://127.0.0.1:5555 -s & +// % ./async tcp://127.0.0.1:5555 323 +// Request took 324 milliseconds. + +#include +#include +#include +#include + +#include +#include +#include +#include + +// Parallel is the maximum number of outstanding requests we can handle. +// This is *NOT* the number of threads in use, but instead represents +// outstanding work items. Select a small number to reduce memory size. +// (Each one of these can be thought of as a request-reply loop.) +#ifndef PARALLEL +#define PARALLEL 32 +#endif + +// The server keeps a list of work items, sorted by expiration time, +// so that we can use this to set the timeout to the correct value for +// use in poll. +struct work { + enum { INIT, RECV, WAIT, SEND } state; + nng_aio * aio; + nng_socket sock; + nng_msg * msg; +}; + +void +fatal(const char *func, int rv) +{ + fprintf(stderr, "%s: %s\n", func, nng_strerror(rv)); + exit(1); +} + +void +server_cb(void *arg) +{ + struct work *work = arg; + nng_msg * msg; + int rv; + uint32_t when; + + switch (work->state) { + case INIT: + work->state = RECV; + nng_recv_aio(work->sock, work->aio); + break; + case RECV: + if ((rv = nng_aio_result(work->aio)) != 0) { + fatal("nng_recv_aio", rv); + } + msg = nng_aio_get_msg(work->aio); + if ((rv = nng_msg_trim_u32(msg, &when)) != 0) { + // bad message, just ignore it. + nng_msg_free(msg); + nng_recv_aio(work->sock, work->aio); + return; + } + work->msg = msg; + work->state = WAIT; + nng_sleep_aio(when, work->aio); + break; + case WAIT: + // We could add more data to the message here. + nng_aio_set_msg(work->aio, work->msg); + work->msg = NULL; + work->state = SEND; + nng_send_aio(work->sock, work->aio); + break; + case SEND: + if ((rv = nng_aio_result(work->aio)) != 0) { + nng_msg_free(work->msg); + fatal("nng_send_aio", rv); + } + work->state = RECV; + nng_recv_aio(work->sock, work->aio); + break; + default: + fatal("bad state!", NNG_ESTATE); + break; + } +} + +struct work * +alloc_work(nng_socket sock) +{ + struct work *w; + int rv; + + if ((w = nng_alloc(sizeof(*w))) == NULL) { + fatal("nng_alloc", NNG_ENOMEM); + } + if ((rv = nng_aio_alloc(&w->aio, server_cb, w)) != 0) { + fatal("nng_aio_alloc", rv); + } + w->state = INIT; + w->sock = sock; + return (w); +} + +// The server runs forever. +int +server(const char *url) +{ + nng_socket sock; + struct work *works[PARALLEL]; + int rv; + int i; + + /* Create the socket. */ + rv = nng_rep0_open_raw(&sock); + if (rv != 0) { + fatal("nng_rep0_open", rv); + } + + for (i = 0; i < PARALLEL; i++) { + works[i] = alloc_work(sock); + } + + if ((rv = nng_listen(sock, url, NULL, 0)) != 0) { + fatal("nng_listen", rv); + } + + for (i = 0; i < PARALLEL; i++) { + server_cb(works[i]); // this starts them going (INIT state) + } + + for (;;) { + nng_msleep(3600000); // neither pause() nor sleep() portable + } +} + +/* The client runs just once, and then returns. */ +int +client(const char *url, const char *msecstr) +{ + nng_socket sock; + int rv; + nng_msg * msg; + nng_time start; + nng_time end; + unsigned msec; + + msec = atoi(msecstr) * 1000; + + if ((rv = nng_req0_open(&sock)) != 0) { + fatal("nng_req0_open", rv); + } + + if ((rv = nng_dial(sock, url, NULL, 0)) != 0) { + fatal("nng_dial", rv); + } + + start = nng_clock(); + + if ((rv = nng_msg_alloc(&msg, 0)) != 0) { + fatal("nng_msg_alloc", rv); + } + if ((rv = nng_msg_append_u32(msg, msec)) != 0) { + fatal("nng_msg_append_u32", rv); + } + + if ((rv = nng_sendmsg(sock, msg, 0)) != 0) { + fatal("nng_send", rv); + } + + if ((rv = nng_recvmsg(sock, &msg, 0)) != 0) { + fatal("nng_recvmsg", rv); + } + end = nng_clock(); + nng_msg_free(msg); + nng_close(sock); + + printf("Request took %u milliseconds.\n", (uint32_t)(end - start)); + return (0); +} + +int +main(int argc, char **argv) +{ + int rc; + + if (argc < 3) { + fprintf(stderr, "Usage: %s [-s|]\n", argv[0]); + exit(EXIT_FAILURE); + } + if (strcmp(argv[2], "-s") == 0) { + rc = server(argv[1]); + } else { + rc = client(argv[1], argv[2]); + } + exit(rc == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +} diff --git a/external/nng/demo/reqrep/CMakeLists.txt b/external/nng/demo/reqrep/CMakeLists.txt new file mode 100644 index 0000000..0923464 --- /dev/null +++ b/external/nng/demo/reqrep/CMakeLists.txt @@ -0,0 +1,23 @@ +# +# Copyright 2018 Capitar IT Group BV +# Copyright 2018 Staysail Systems, Inc. +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.12) + +project(reqrep) + +find_package(nng CONFIG REQUIRED) + +find_package(Threads) + +# Uncomment to enable ZeroTier transport +# find_package(zerotiercore) + +add_executable(reqrep reqrep.c) +target_link_libraries(reqrep nng::nng) +target_compile_definitions(reqrep PRIVATE NNG_ELIDE_DEPRECATED) diff --git a/external/nng/demo/reqrep/README.adoc b/external/nng/demo/reqrep/README.adoc new file mode 100644 index 0000000..5bc3d04 --- /dev/null +++ b/external/nng/demo/reqrep/README.adoc @@ -0,0 +1,59 @@ += reqrep + +This is a very simple RPC service using the REQ/REP method. +It is derived in part from Tim Dysinger's +http://nanomsg.org/gettingstarted/[Getting Started With Nanomsg] +examples, but we have updated for _nng_, and converted to use binary +frames across the wire instead of string data. + +The protocol is simple: + +* Client will send a 64-bit command (network byte order, i.e. big endian). +* Server sends a 64-bit response (also network byte order.) + +The only command is "DATE", which has value 0x1. The value returned is +a UNIX timestamp (seconds since Jan 1, 1970.) + +(We used 64-bit values for simplicity, and to avoid the Y2038 bug when +compiled on 64-bit systems.) + +== Compiling + +CMake with ninja-build is simplest: + +[source, bash] +---- +% mkdir build +% cd build +% cmake -G Ninja .. +% ninja +---- + +Or if you prefer a traditional approach, +the following is an example typical of UNIX and similar systems like +Linux and macOS may appeal: + +[source, bash] +---- +% export CPPFLAGS="-I /usr/local/include" +% export LDFLAGS="-L /usr/local/lib -lnng" +% export CC="cc" +% ${CC} ${CPPFLAGS} reqrep.c -o reqrep ${LDFLAGS} +---- + +== Running + +You can run either the client or the server, and use whatever legal +_nng_ URL you like: + +[source, bash] +---- +% ./reqrep server tcp://127.0.0.1:8899 & +% ./reqrep client tcp://127.0.0.1:8899 +CLIENT: SENDING DATE REQUEST +SERVER: RECEIVED DATE REQUEST +SERVER: SENDING DATE: Thu Feb 8 10:26:18 2018 +CLIENT: RECEIVED DATE: Thu Feb 8 10:26:18 2018 +---- + + diff --git a/external/nng/demo/reqrep/reqrep.c b/external/nng/demo/reqrep/reqrep.c new file mode 100644 index 0000000..62ff29a --- /dev/null +++ b/external/nng/demo/reqrep/reqrep.c @@ -0,0 +1,216 @@ +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2021 Capitar IT Group BV +// +// This software 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. +// + +// +// This is just a simple REQ/REP demonstration application. It is derived +// from the legacy nanomsg demonstration program of the same name, written +// by Tim Dysinger, but updated for nng. I've also updated it to pass simpler +// binary data rather than strings over the network. +// +// The program implements a simple RPC style service, which just returns +// the date in UNIX time (seconds since 1970). +// +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +#define CLIENT "client" +#define SERVER "server" +#define DATECMD 1 + +#define PUT64(ptr, u) \ + do { \ + (ptr)[0] = (uint8_t)(((uint64_t)(u)) >> 56); \ + (ptr)[1] = (uint8_t)(((uint64_t)(u)) >> 48); \ + (ptr)[2] = (uint8_t)(((uint64_t)(u)) >> 40); \ + (ptr)[3] = (uint8_t)(((uint64_t)(u)) >> 32); \ + (ptr)[4] = (uint8_t)(((uint64_t)(u)) >> 24); \ + (ptr)[5] = (uint8_t)(((uint64_t)(u)) >> 16); \ + (ptr)[6] = (uint8_t)(((uint64_t)(u)) >> 8); \ + (ptr)[7] = (uint8_t)((uint64_t)(u)); \ + } while (0) + +#define GET64(ptr, v) \ + v = (((uint64_t)((uint8_t)(ptr)[0])) << 56) + \ + (((uint64_t)((uint8_t)(ptr)[1])) << 48) + \ + (((uint64_t)((uint8_t)(ptr)[2])) << 40) + \ + (((uint64_t)((uint8_t)(ptr)[3])) << 32) + \ + (((uint64_t)((uint8_t)(ptr)[4])) << 24) + \ + (((uint64_t)((uint8_t)(ptr)[5])) << 16) + \ + (((uint64_t)((uint8_t)(ptr)[6])) << 8) + \ + (((uint64_t)(uint8_t)(ptr)[7])) + +void +fatal(const char *func, int rv) +{ + fprintf(stderr, "%s: %s\n", func, nng_strerror(rv)); + exit(1); +} + +void +showdate(time_t now) +{ + struct tm *info = localtime(&now); + printf("%s", asctime(info)); +} + +int +server(const char *url) +{ + nng_socket sock; + nng_listener listener; + int rv; + int count = 0; + + if ((rv = nng_rep0_open(&sock)) != 0) { + fatal("nng_rep0_open", rv); + } + + if ((rv = nng_listener_create(&listener, sock, url)) != 0) { + fatal("nng_listener_create", rv); + } + + if (strncmp(url, "zt://", 5) == 0) { + printf("ZeroTier transport will store its keys in current working directory.\n"); + printf("The server and client instances must run in separate directories.\n"); + nng_listener_set_string(listener, NNG_OPT_ZT_HOME, "."); + nng_listener_set_ms(listener, NNG_OPT_RECONNMINT, 1); + nng_listener_set_ms(listener, NNG_OPT_RECONNMAXT, 1000); + nng_socket_set_ms(sock, NNG_OPT_REQ_RESENDTIME, 2000); + nng_socket_set_ms(sock, NNG_OPT_RECVMAXSZ, 0); + nng_listener_set_ms(listener, NNG_OPT_ZT_PING_TIME, 10000); + nng_listener_set_ms(listener, NNG_OPT_ZT_CONN_TIME, 1000); + } else { + nng_socket_set_ms(sock, NNG_OPT_REQ_RESENDTIME, 2000); + } + nng_listener_start(listener, 0); + + for (;;) { + char * buf = NULL; + size_t sz; + uint64_t val; + count++; + if ((rv = nng_recv(sock, &buf, &sz, NNG_FLAG_ALLOC)) != 0) { + fatal("nng_recv", rv); + } + if ((sz == sizeof(uint64_t)) && + ((GET64(buf, val)) == DATECMD)) { + time_t now; + printf("SERVER: RECEIVED DATE REQUEST\n"); + now = time(&now); + if (count == 6) { + printf("SERVER: SKIP SENDING REPLY\n"); + nng_free(buf, sz); + continue; + } + printf("SERVER: SENDING DATE: "); + showdate(now); + + // Reuse the buffer. We know it is big enough. + PUT64(buf, (uint64_t) now); + rv = nng_send(sock, buf, sz, NNG_FLAG_ALLOC); + if (rv != 0) { + fatal("nng_send", rv); + } + continue; + } + // Unrecognized command, so toss the buffer. + nng_free(buf, sz); + } +} + +int +client(const char *url) +{ + nng_socket sock; + nng_dialer dialer; + int rv; + size_t sz; + char * buf = NULL; + uint8_t cmd[sizeof(uint64_t)]; + int sleep = 0; + + PUT64(cmd, DATECMD); + + if ((rv = nng_req0_open(&sock)) != 0) { + fatal("nng_socket", rv); + } + + if ((rv = nng_dialer_create(&dialer, sock, url)) != 0) { + fatal("nng_dialer_create", rv); + } + + if (strncmp(url, "zt://", 5) == 0) { + printf("ZeroTier transport will store its keys in current working directory\n"); + printf("The server and client instances must run in separate directories.\n"); + nng_dialer_set_string(dialer, NNG_OPT_ZT_HOME, "."); + nng_dialer_set_ms(dialer, NNG_OPT_RECONNMINT, 1); + nng_dialer_set_ms(dialer, NNG_OPT_RECONNMAXT, 1000); + nng_socket_set_ms(sock, NNG_OPT_REQ_RESENDTIME, 2000); + nng_socket_set_ms(sock, NNG_OPT_RECVMAXSZ, 0); + nng_dialer_set_ms(dialer, NNG_OPT_ZT_PING_TIME, 10000); + nng_dialer_set_ms(dialer, NNG_OPT_ZT_CONN_TIME, 1000); + } else { + nng_socket_set_ms(sock, NNG_OPT_REQ_RESENDTIME, 2000); + } + + nng_dialer_start(dialer, NNG_FLAG_NONBLOCK); + + while (1) { + + printf("CLIENT: SENDING DATE REQUEST\n"); + if ((rv = nng_send(sock, cmd, sizeof(cmd), 0)) != 0) { + fatal("nng_send", rv); + } + if ((rv = nng_recv(sock, &buf, &sz, NNG_FLAG_ALLOC)) != 0) { + fatal("nng_recv", rv); + } + + if (sz == sizeof(uint64_t)) { + uint64_t now; + GET64(buf, now); + printf("CLIENT: RECEIVED DATE: "); + showdate((time_t) now); + } else { + printf("CLIENT: GOT WRONG SIZE!\n"); + } + nng_msleep(sleep); + sleep++; + if (sleep == 4) { + sleep = 4000; + } + } + + // This assumes that buf is ASCIIZ (zero terminated). + nng_free(buf, sz); + nng_close(sock); + return (0); +} + +int +main(const int argc, const char **argv) +{ + if ((argc > 1) && (strcmp(CLIENT, argv[1]) == 0)) + return (client(argv[2])); + + if ((argc > 1) && (strcmp(SERVER, argv[1]) == 0)) + return (server(argv[2])); + + fprintf(stderr, "Usage: reqrep %s|%s ...\n", CLIENT, SERVER); + return (1); +} diff --git a/external/nng/demo/rest/CMakeLists.txt b/external/nng/demo/rest/CMakeLists.txt new file mode 100644 index 0000000..d5dd4fe --- /dev/null +++ b/external/nng/demo/rest/CMakeLists.txt @@ -0,0 +1,20 @@ +# +# Copyright 2018 Capitar IT Group BV +# Copyright 2018 Staysail Systems, Inc. +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.12) + +project(rest) + +find_package(nng CONFIG REQUIRED) + +find_package(Threads) + +add_executable(rest-server server.c) +target_link_libraries(rest-server nng::nng) +target_compile_definitions(rest-server PRIVATE NNG_ELIDE_DEPRECATED) diff --git a/external/nng/demo/rest/README.adoc b/external/nng/demo/rest/README.adoc new file mode 100644 index 0000000..39f626f --- /dev/null +++ b/external/nng/demo/rest/README.adoc @@ -0,0 +1,45 @@ += REST API Gateway demo + +This is a somewhat contrived demonstration, but may be useful +in a pattern for solving real world problems. + +There is a single "server" (rest-server) program, that does these: + +. REST API at /api/rest/rot13 - this API takes data from HTTP POST commands, + and forwards them to an NNG REQ socket. When the REQ response comes, + the reply is redirected back to the server. (For the purposes of the + demonstration, our server just performs ROT13 on input.) + +. REP server (implemented in the same program using inproc, for demonstration + purposes. In a real world scenario this might instead go to another + process on another computer.) + +[source, bash] +---- +% env PORT=8888 # default +% ./rest-server & +% curl -d ABC http://127.0.0.1:8888/api/rest/rot13; echo +NOP +% curl -d NOP http://127.0.0.1:8888/api/rest/rot13; echo +ABC +---- + +== Compiling + +To build the program, we recommend CMake and Ninja-Build. + +[source, bash] +---- +% mkdir build +% cd build +% cmake -G Ninja .. +% ninja +---- + +Alternatively, you can go old-school. +Here's the simplest option for Linux: + +[source, bash] +---- +% cc server.c -o rest-server -I /usr/local/include -lnng +---- diff --git a/external/nng/demo/rest/server.c b/external/nng/demo/rest/server.c new file mode 100644 index 0000000..5a59756 --- /dev/null +++ b/external/nng/demo/rest/server.c @@ -0,0 +1,372 @@ +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This software 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. +// + +#define INPROC_URL "inproc://rot13" +#define REST_URL "http://127.0.0.1:%u/api/rest/rot13" + +// REST API -> NNG REP server demonstration. + +// This is a silly demo -- it listens on port 8888 (or $PORT if present), +// and accepts HTTP POST requests at /api/rest/rot13 +// +// These requests are converted into an NNG REQ message, and sent to an +// NNG REP server (builtin inproc_server, for demonstration purposes only). +// The reply is obtained from the server, and sent back to the client via +// the HTTP server framework. + +// Example usage: +// +// % export CPPFLAGS="-I /usr/local/include" +// % export LDFLAGS="-L /usr/local/lib -lnng" +// % export CC="cc" +// % ${CC} ${CPPFLAGS} server.c -o server ${LDFLAGS} +// % ./server & +// % curl -d TEST http://127.0.0.1:8888/api/rest/rot13 +// GRFG +// + +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +// utility function +void +fatal(const char *what, int rv) +{ + fprintf(stderr, "%s: %s\n", what, nng_strerror(rv)); + exit(1); +} + +// This server acts as a proxy. We take HTTP POST requests, convert them to +// REQ messages, and when the reply is received, send the reply back to +// the original HTTP client. +// +// The state flow looks like: +// +// 1. Receive HTTP request & headers +// 2. Receive HTTP request (POST) data +// 3. Send POST payload as REQ body +// 4. Receive REP reply (including payload) +// 5. Return REP message body to the HTTP server (which forwards to client) +// 6. Restart at step 1. +// +// The above flow is pretty linear, and so we use contexts (nng_ctx) to +// obtain parallelism. + +typedef enum { + SEND_REQ, // Sending REQ request + RECV_REP, // Receiving REQ reply +} job_state; + +typedef struct rest_job { + nng_aio * http_aio; // aio from HTTP we must reply to + nng_http_res * http_res; // HTTP response object + job_state state; // 0 = sending, 1 = receiving + nng_msg * msg; // request message + nng_aio * aio; // request flow + nng_ctx ctx; // context on the request socket + struct rest_job *next; // next on the freelist +} rest_job; + +nng_socket req_sock; + +// We maintain a queue of free jobs. This way we don't have to +// deallocate them from the callback; we just reuse them. +nng_mtx * job_lock; +rest_job *job_freelist; + +static void rest_job_cb(void *arg); + +static void +rest_recycle_job(rest_job *job) +{ + if (job->http_res != NULL) { + nng_http_res_free(job->http_res); + job->http_res = NULL; + } + if (job->msg != NULL) { + nng_msg_free(job->msg); + job->msg = NULL; + } + if (nng_ctx_id(job->ctx) != 0) { + nng_ctx_close(job->ctx); + } + + nng_mtx_lock(job_lock); + job->next = job_freelist; + job_freelist = job; + nng_mtx_unlock(job_lock); +} + +static rest_job * +rest_get_job(void) +{ + rest_job *job; + + nng_mtx_lock(job_lock); + if ((job = job_freelist) != NULL) { + job_freelist = job->next; + nng_mtx_unlock(job_lock); + job->next = NULL; + return (job); + } + nng_mtx_unlock(job_lock); + if ((job = calloc(1, sizeof(*job))) == NULL) { + return (NULL); + } + if (nng_aio_alloc(&job->aio, rest_job_cb, job) != 0) { + free(job); + return (NULL); + } + return (job); +} + +static void +rest_http_fatal(rest_job *job, const char *fmt, int rv) +{ + char buf[128]; + nng_aio * aio = job->http_aio; + nng_http_res *res = job->http_res; + + job->http_res = NULL; + job->http_aio = NULL; + snprintf(buf, sizeof(buf), fmt, nng_strerror(rv)); + nng_http_res_set_status(res, NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR); + nng_http_res_set_reason(res, buf); + nng_aio_set_output(aio, 0, res); + nng_aio_finish(aio, 0); + rest_recycle_job(job); +} + +static void +rest_job_cb(void *arg) +{ + rest_job *job = arg; + nng_aio * aio = job->aio; + int rv; + + switch (job->state) { + case SEND_REQ: + if ((rv = nng_aio_result(aio)) != 0) { + rest_http_fatal(job, "send REQ failed: %s", rv); + return; + } + job->msg = NULL; + // Message was sent, so now wait for the reply. + nng_aio_set_msg(aio, NULL); + job->state = RECV_REP; + nng_ctx_recv(job->ctx, aio); + break; + case RECV_REP: + if ((rv = nng_aio_result(aio)) != 0) { + rest_http_fatal(job, "recv reply failed: %s", rv); + return; + } + job->msg = nng_aio_get_msg(aio); + // We got a reply, so give it back to the server. + rv = nng_http_res_copy_data(job->http_res, + nng_msg_body(job->msg), nng_msg_len(job->msg)); + if (rv != 0) { + rest_http_fatal(job, "nng_http_res_copy_data: %s", rv); + return; + } + // Set the output - the HTTP server will send it back to the + // user agent with a 200 response. + nng_aio_set_output(job->http_aio, 0, job->http_res); + nng_aio_finish(job->http_aio, 0); + job->http_aio = NULL; + job->http_res = NULL; + // We are done with the job. + rest_recycle_job(job); + return; + default: + fatal("bad case", NNG_ESTATE); + break; + } +} + +// Our rest server just takes the message body, creates a request ID +// for it, and sends it on. This runs in raw mode, so +void +rest_handle(nng_aio *aio) +{ + struct rest_job *job; + nng_http_req * req = nng_aio_get_input(aio, 0); + nng_http_conn * conn = nng_aio_get_input(aio, 2); + const char * clen; + size_t sz; + nng_iov iov; + int rv; + void * data; + + if ((job = rest_get_job()) == NULL) { + nng_aio_finish(aio, NNG_ENOMEM); + return; + } + if (((rv = nng_http_res_alloc(&job->http_res)) != 0) || + ((rv = nng_ctx_open(&job->ctx, req_sock)) != 0)) { + rest_recycle_job(job); + nng_aio_finish(aio, rv); + return; + } + + nng_http_req_get_data(req, &data, &sz); + job->http_aio = aio; + + if ((rv = nng_msg_alloc(&job->msg, sz)) != 0) { + rest_http_fatal(job, "nng_msg_alloc: %s", rv); + return; + } + + memcpy(nng_msg_body(job->msg), data, sz); + nng_aio_set_msg(job->aio, job->msg); + job->state = SEND_REQ; + nng_ctx_send(job->ctx, job->aio); +} + +void +rest_start(uint16_t port) +{ + nng_http_server * server; + nng_http_handler *handler; + char rest_addr[128]; + nng_url * url; + int rv; + + if ((rv = nng_mtx_alloc(&job_lock)) != 0) { + fatal("nng_mtx_alloc", rv); + } + job_freelist = NULL; + + // Set up some strings, etc. We use the port number + // from the argument list. + snprintf(rest_addr, sizeof(rest_addr), REST_URL, port); + if ((rv = nng_url_parse(&url, rest_addr)) != 0) { + fatal("nng_url_parse", rv); + } + + // Create the REQ socket, and put it in raw mode, connected to + // the remote REP server (our inproc server in this case). + if ((rv = nng_req0_open(&req_sock)) != 0) { + fatal("nng_req0_open", rv); + } + if ((rv = nng_dial(req_sock, INPROC_URL, NULL, NNG_FLAG_NONBLOCK)) != + 0) { + fatal("nng_dial(" INPROC_URL ")", rv); + } + + // Get a suitable HTTP server instance. This creates one + // if it doesn't already exist. + if ((rv = nng_http_server_hold(&server, url)) != 0) { + fatal("nng_http_server_hold", rv); + } + + // Allocate the handler - we use a dynamic handler for REST + // using the function "rest_handle" declared above. + rv = nng_http_handler_alloc(&handler, url->u_path, rest_handle); + if (rv != 0) { + fatal("nng_http_handler_alloc", rv); + } + + if ((rv = nng_http_handler_set_method(handler, "POST")) != 0) { + fatal("nng_http_handler_set_method", rv); + } + // We want to collect the body, and we (arbitrarily) limit this to + // 128KB. The default limit is 1MB. You can explicitly collect + // the data yourself with another HTTP read transaction by disabling + // this, but that's a lot of work, especially if you want to handle + // chunked transfers. + if ((rv = nng_http_handler_collect_body(handler, true, 1024 * 128)) != + 0) { + fatal("nng_http_handler_collect_body", rv); + } + if ((rv = nng_http_server_add_handler(server, handler)) != 0) { + fatal("nng_http_handler_add_handler", rv); + } + if ((rv = nng_http_server_start(server)) != 0) { + fatal("nng_http_server_start", rv); + } + + nng_url_free(url); +} + +// +// inproc_server - this just is a simple REP server that listens for +// messages, and performs ROT13 on them before sending them. This +// doesn't have to be in the same process -- it is hear for demonstration +// simplicity only. (Most likely this would be somewhere else.) Note +// especially that this uses inproc, so nothing can get to it directly +// from outside the process. +// +void +inproc_server(void *arg) +{ + nng_socket s; + int rv; + nng_msg * msg; + + if (((rv = nng_rep0_open(&s)) != 0) || + ((rv = nng_listen(s, INPROC_URL, NULL, 0)) != 0)) { + fatal("unable to set up inproc", rv); + } + // This is simple enough that we don't need concurrency. Plus it + // makes for an easier demo. + for (;;) { + char *body; + if ((rv = nng_recvmsg(s, &msg, 0)) != 0) { + fatal("inproc recvmsg", rv); + } + body = nng_msg_body(msg); + for (int i = 0; i < nng_msg_len(msg); i++) { + // Table lookup would be faster, but this works. + if (isupper(body[i])) { + char base = body[i] - 'A'; + base = (base + 13) % 26; + body[i] = base + 'A'; + } else if (islower(body[i])) { + char base = body[i] - 'a'; + base = (base + 13) % 26; + body[i] = base + 'a'; + } + } + if ((rv = nng_sendmsg(s, msg, 0)) != 0) { + fatal("inproc sendmsg", rv); + } + } +} + +int +main(int argc, char **argv) +{ + int rv; + nng_thread *inproc_thr; + uint16_t port = 0; + + rv = nng_thread_create(&inproc_thr, inproc_server, NULL); + if (rv != 0) { + fatal("cannot start inproc server", rv); + } + if (getenv("PORT") != NULL) { + port = (uint16_t) atoi(getenv("PORT")); + } + port = port ? port : 8888; + rest_start(port); + + // This runs forever. The inproc_thr never exits, so we + // just block behind its condition variable. + nng_thread_destroy(inproc_thr); +} diff --git a/external/nng/demo/stream/CMakeLists.txt b/external/nng/demo/stream/CMakeLists.txt new file mode 100644 index 0000000..3b76769 --- /dev/null +++ b/external/nng/demo/stream/CMakeLists.txt @@ -0,0 +1,27 @@ +# +# Copyright 2020 Hugo LindstrÃļm +# +# This software 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. + +cmake_minimum_required (VERSION 2.8.7) + +project(stream) + +find_package(nng CONFIG REQUIRED) + +add_executable(${PROJECT_NAME}) + +target_sources(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/stream.c) + +if (CMAKE_SYSTEM_NAME MATCHES "Linux") + target_sources(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/platform/posix/server.c) +endif() + +if (CMAKE_SYSTEM_NAME MATCHES "Windows") + target_sources(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/platform/windows/server.c) +endif() + +target_link_libraries(stream nng::nng) diff --git a/external/nng/demo/stream/platform/posix/server.c b/external/nng/demo/stream/platform/posix/server.c new file mode 100644 index 0000000..1b238f1 --- /dev/null +++ b/external/nng/demo/stream/platform/posix/server.c @@ -0,0 +1,53 @@ +// Copyright 2020 Hugo LindstrÃļm + +// This software 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. + +#include +#include +#include +#include +#include +#include + +void +error(const char *msg) +{ + perror(msg); + exit(1); +} + +int +server(int portno) +{ + int sockfd, newsockfd; + socklen_t clilen; + struct sockaddr_in serv_addr, cli_addr; + int n; + sockfd = socket(AF_INET, SOCK_STREAM, 0); + if (sockfd < 0) { + error("ERROR opening socket"); + } + bzero((char *) &serv_addr, sizeof(serv_addr)); + serv_addr.sin_family = AF_INET; + serv_addr.sin_addr.s_addr = INADDR_ANY; + serv_addr.sin_port = htons(portno); + if (bind(sockfd, (struct sockaddr *) &serv_addr, sizeof(serv_addr)) < + 0) { + error("ERROR on binding"); + } + listen(sockfd, 5); + clilen = sizeof(cli_addr); + newsockfd = accept(sockfd, (struct sockaddr *) &cli_addr, &clilen); + if (newsockfd < 0) { + error("ERROR on accept"); + } + n = write(newsockfd, "Hello Client!", 13); + if (n < 0) + error("ERROR writing to socket"); + close(newsockfd); + close(sockfd); + return 0; +} diff --git a/external/nng/demo/stream/platform/windows/server.c b/external/nng/demo/stream/platform/windows/server.c new file mode 100644 index 0000000..09603eb --- /dev/null +++ b/external/nng/demo/stream/platform/windows/server.c @@ -0,0 +1,87 @@ +// Copyright 2020 Hugo LindstrÃļm + +// This software 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. + +#include +#include +#include + +void +wsa_fatal(const char *func) +{ + fprintf(stderr, "%s: %d\n", func, WSAGetLastError()); + exit(1); +} + +int +server(int portno) +{ + WSADATA wsa; + SOCKET s, new_socket; + struct sockaddr_in server, client; + int c; + char * message; + + printf("Initialising Winsock...\n"); + + if (WSAStartup(MAKEWORD(2, 2), &wsa) != 0) { + wsa_fatal("Failed to call WSAStartup"); + } + + printf("Initialised WSA.\n"); + + // Create a socket + if ((s = socket(AF_INET, SOCK_STREAM, 0)) == INVALID_SOCKET) { + wsa_fatal("Could not create socket"); + } + + printf("Socket created.\n"); + + // Prepare the sockaddr_in structure + server.sin_family = AF_INET; + server.sin_addr.s_addr = INADDR_ANY; + server.sin_port = htons(portno); + + // Bind + if (bind(s, (struct sockaddr *) &server, sizeof(server)) == + SOCKET_ERROR) { + wsa_fatal("Bind failed"); + } + + printf("Bind done\n"); + + // Listen to incoming connections + listen(s, 3); + + // Accept and incoming connection + printf("Waiting for incoming connections...\n"); + + c = sizeof(struct sockaddr_in); + + while ((new_socket = accept(s, (struct sockaddr *) &client, &c)) != + INVALID_SOCKET) { + printf("Connection accepted\n"); + // Reply to the client + message = "Hello Client!"; + if (send(new_socket, message, (int) strlen(message), 0) == + SOCKET_ERROR) { + wsa_fatal("Failed to send message to client!"); + } + } + + if (new_socket == INVALID_SOCKET) { + wsa_fatal("accept failed"); + } + + if (closesocket(s) == SOCKET_ERROR) { + wsa_fatal("Failed to close socket"); + } + + if (WSACleanup() == SOCKET_ERROR) { + wsa_fatal("Failed to WSACleanup"); + } + return 0; +} diff --git a/external/nng/demo/stream/stream.c b/external/nng/demo/stream/stream.c new file mode 100644 index 0000000..c6cc9b2 --- /dev/null +++ b/external/nng/demo/stream/stream.c @@ -0,0 +1,109 @@ +// Copyright 2020 Hugo LindstrÃļm + +// This software 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. +// + +// This program serves as an example for how to write async communication with +// an arbitrary socket using nng_stream. The server receives a connection and +// sends a hello message to the nng_stream iov. + +// To run this program, start the server as stream -s +// Then connect to it with the client as stream -c +// +// For example: +// +// % ./stream -s 5555 & +// % ./stream -c tcp://127.0.0.1:5555 + +#include +#include +#include +#include + +void +nng_fatal(const char *func, int rv) +{ + fprintf(stderr, "%s: %s\n", func, nng_strerror(rv)); + exit(1); +} + +int server(int port); +int client(const char *url); + +int +main(int argc, char **argv) +{ + int rc; + + if (argc < 3) { + fprintf(stderr, "Usage: %s [-s port|-c url]\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (strcmp(argv[1], "-s") == 0) { + rc = server(atoi(argv[2])); + } else { + rc = client(argv[2]); + } + exit(rc == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +} + +int +client(const char *url) +{ + nng_stream_dialer *dialer; + nng_aio * aio; + nng_iov iov; + int rv; + + // Allocatate dialer and aio assoicated with this connection + if ((rv = nng_stream_dialer_alloc(&dialer, url)) != 0) { + nng_fatal("call to nng_stream_dialer_alloc failed", rv); + } + + if ((rv = nng_aio_alloc(&aio, NULL, NULL)) != 0) { + nng_fatal("call to nng_aio_alloc", rv); + } + nng_aio_set_timeout(aio, 5000); // 5 sec + + // Allocatate a buffer to recv + iov.iov_len = 100; + iov.iov_buf = (char *) malloc(sizeof(char) * iov.iov_len); + if ((rv = nng_aio_set_iov(aio, 1, &iov)) != 0) { + nng_fatal("call to nng_aio_alloc", rv); + } + // Connect to the socket via url provided to alloc + nng_stream_dialer_dial(dialer, aio); + + // Wait for connection + nng_aio_wait(aio); + if ((rv = nng_aio_result(aio)) != 0) { + nng_fatal("waiting for ng_stream_dialer_dial failed", rv); + } + + // Get the stream (connection) at position 0 + nng_stream *c1 = (nng_stream *) nng_aio_get_output(aio, 0); + nng_stream_recv(c1, aio); + nng_aio_wait(aio); + if ((rv = nng_aio_result(aio)) != 0) { + nng_fatal("waiting for nng_stream_recv failed", rv); + } + + size_t recv_count = nng_aio_count(aio); + if (recv_count <= 0) { + nng_fatal("Recv count was 0!", NNG_ECONNABORTED); + } else { + printf("received %zu bytes, message: '%s'\n", recv_count, + (char *) iov.iov_buf); + } + + // Send ELCOSE to send/recv associated wit this stream + free(iov.iov_buf); + nng_stream_free(c1); + nng_aio_free(aio); + nng_stream_dialer_free(dialer); + return 0; +} diff --git a/external/nng/docs/BUILD_ANDROID.adoc b/external/nng/docs/BUILD_ANDROID.adoc new file mode 100644 index 0000000..7cb4033 --- /dev/null +++ b/external/nng/docs/BUILD_ANDROID.adoc @@ -0,0 +1,84 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + += Building for Android + +NOTE: This work has received only cursory testing. As always, _caveat emptor_. + +== Pre-Requisites + +Android Studio::: + + There are probably other ways to cross-build for Android, but if you're + not using Android Studio, then you probably don't need much help here. + +Android NDK:: + + A copy of the Android NDK is required to build native code applications. + Android Studio has information for downloading it within the app. + +== Steps + +You need to use the CMake that is included with Android Studio, because +it knows how to build the Gradle targets. (At least on macOS, the system +default cmake does not have the right generator support.) + +You will also use the Android toolchain file for CMake that is included +with the NDK. + +NOTE: You *must* use the _NDK_ toolchain, not the one that came with the _SDK_. +The _SDK_ toolchain file is too old and will not work with modern NDKs! + +When building for Android, by default we build static libraries, and +we do not build tools or tests. The tools and tests won't work since +they assume a shell environment, and you don't want to deal with the +dependency nightmare that is dynamic libraries anyway. Trust us. + +The Android NDK includes documentation for how to run +CMake including the options that can be set. Details are located +here: https://developer.android.com/ndk/guides/cmake + +TIP: It is *highly* recommended you review the NDK documentation, +because you will most likely want to change some of the default values +for the ABI or API level. +For the sake of clarity, we are assuming only the defaults here. + +Set the following environment variables: + +`CMAKE`:: + + Path to the Android SDK supplied CMake binary. For example, on + our macOS install of Android Studio, we have it located in + `$HOME/Library/Android/sdk/cmake/3.6.4111459/bin/cmake`. + +`NDK`:: + + Path to the Android NDK. In the same installation, on our system, + it is in `$HOME/Library/Android/sdk/ndk-bundle` + +Using the above toolchain file, we can build for Android using +the CMake standard `CMAKE_TOOLCHAIN_FILE` macro, and using the +Android supplied CMake: + +If you have checked out this repository in `$SRC`, and your copy of the +Android SDK is located in `$SDK`, the following should work: + +[source, sh] +---- +% cd $SRC +% mkdir android-build +% cd android-build +% ${CMAKE} -DCMAKE_TOOLCHAIN_FILE=${NDK}/build/cmake/android.toolchain.cmake .. +---- + +Then you can build using Xcode, or simply use cmake to drive the build: + +[source, sh] +---- +% ${CMAKE} --build . +---- + +Extra effort may be required to enable the use of mbedTLS; you will +need to review the mbedTLS documentation for configuring that for use +in Android. diff --git a/external/nng/docs/BUILD_CROSSCOMPILE.adoc b/external/nng/docs/BUILD_CROSSCOMPILE.adoc new file mode 100644 index 0000000..ba080b3 --- /dev/null +++ b/external/nng/docs/BUILD_CROSSCOMPILE.adoc @@ -0,0 +1,49 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + += Building for Cross Compilation + +TIP: Cross-compiling is used when the operating system or process architecure +the software is being built for is different than the system where the software +is being compiled. If you don't know what this means, this does not apply to +and you should ignore this file. + +When building for cross-compilation, you can use CMake's native support +`CMAKE_TOOLCHAIN_FILE` to configure the location of the toolchain. + +You'll need that toolchain to have your compiler, linker, header files, +and possibly any other libraries that need to be linked at build time. + +This is all relatively standard stuff for CMake. + +A lot more detail is located here: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling + +NOTE: When _NNG_ detects that it is being built in a Cross-Compile +situation (i.e. when `CMAKE_CROSSCOMPILING` is true), it will default +to disabling the building of the test suite and tools. +This is normally preferable, since many embedded environments cannot host +command line applications or shell environments. + + + +To enable tools or tests to build anyway, the values of either +`NNG_TOOLS` or `NNG_TESTS` (or both) may be set to `ON`. + +== Cross-compiling for Android + +More details for Android are located in the <> file. + +== Cross-compiling for iOS + +More details for iOS (and tvOS, etc.) are located in the <> file. + +== Cross-compiling for Windows or Linux or MACOS - Using vcpkg + +You can download and install nng using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: + + git clone https://github.com/Microsoft/vcpkg.git + cd vcpkg + ./bootstrap-vcpkg.sh + ./vcpkg integrate install + ./vcpkg install nng + +The nng port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. diff --git a/external/nng/docs/BUILD_IOS.adoc b/external/nng/docs/BUILD_IOS.adoc new file mode 100644 index 0000000..80f7c90 --- /dev/null +++ b/external/nng/docs/BUILD_IOS.adoc @@ -0,0 +1,65 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + += Building for iOS (and tvOS, watchOS) + +NOTE: This work has had only minimal validation. As always, _caveat emptor_. + +== Pre-Requisites + +macOS:: + + As far as we know, the only way to build iOS applications is on a + macOS host system. + +Xcode:: + + You will need Xcode. We tested this with Xcode 9.3. + +CMake:: + + We tested this with CMake 3.9. Other versions may work. + +iOS cmake toolchain file:: + + At the time of this writing (May 28, 2018), the toolchain file + located at https://github.com/leetal/ios-cmake is appears to work + reasonably well. + +== Steps + +When building for iOS and similar targets, only static libraries may be built. +(This is good for avoiding dependency nightmares anyway.) + +Using the above toolchain file, we can build for iOS using +the CMake standard CMAKE_TOOLCHAIN_FILE macro, and using +the IOS_PLATFORM macro to set the target. (See the iOS CMake +toolchain README for valid options; we select "OS" for iOS.) + +The test suite and command line tools will automatically be removed +from the build, since they aren't interesting or useful in cross-compile +environment. (There is no way to run them.) + +If you have checked out this repository in $SRC, the following should work: + +[source, sh] +---- +% cd $SRC +% mkdir ios-build +% cd ios-build +% git clone https://github.com/leetal/ios-cmake +% cmake -G Xcode \ + -DCMAKE_TOOLCHAIN_FILE=`pwd`/ios-cmake/ios.toolchain.cmake \ + -DIOS_PLATFORM=OS .. +---- + +Then you can build using Xcode, or simply use cmake to drive the build: + +[source, sh] +---- +% cmake --build . +---- + +Extra effort may be required to enable the use of mbedTLS (NNG does not +at the time of writing support Secure Transport. See issue #497 for status.) diff --git a/external/nng/docs/BUILD_TLS.adoc b/external/nng/docs/BUILD_TLS.adoc new file mode 100644 index 0000000..80a843d --- /dev/null +++ b/external/nng/docs/BUILD_TLS.adoc @@ -0,0 +1,60 @@ +ifdef::env-github[] +:important-caption: :heavy_exclamation_mark: +endif::[] + += Building for TLS Support + +If you want to include support for Transport Layer Security +(tls+tcp:// and wss:// URLs) you should follow these directions. + +At this time, TLS support depends on the https://tls.mbed.org/[Mbed TLS] +library. + +IMPORTANT: Mbed TLS is licensed under different terms than NNG. +You are responsible for reading those license terms, and ensuring +that your use conforms to them. + +On many distributions you may be able to install a pre-packaged version +of Mbed TLS. We recommend doing so if this is an option for you. +For example, Ubuntu users can install the `libmbedtls-dev` package. + +You can also build Mbed TLS from source; if you choose to do so, +please make sure you also *install* it somewhere (even a temporary +staging directory). + +== Configuring NNG with Mbed TLS + +TLS support is not enabled by default, but can be enabled by configuring +with the CMake option `NNG_ENABLE_TLS=ON`. + +By default NNG searches for an installed copy of Mbed TLS in `/usr/local`, +as well as the normal installation directories for libraries on your system. + +If you have installed Mbed TLS elsewhere, you can direct the NNG configuration +to it by setting the `MBEDTLS_ROOT_DIR` CMake variable. + +== Example + +The following example would work on either Linux or macOS, and assumes +that we have checked out github source trees into `$HOME/work`. +It also assumes that Mbed TLS is already installed in /usr/local or +a standard search path. + +[source, sh] +---- +$ export NNGDIR=$HOME/work/nng +$ mkdir build +$ cd build + +$ cmake -DNNG_ENABLE_TLS=ON .. + + ... (lots of lines of output from cmake...) + +$ make + + ... (lots of lines of output from make...) + +$ ./tests/tls +ok ./tests/tls 1.503s + +---- diff --git a/external/nng/docs/BUILD_ZEROTIER.adoc b/external/nng/docs/BUILD_ZEROTIER.adoc new file mode 100644 index 0000000..80ee072 --- /dev/null +++ b/external/nng/docs/BUILD_ZEROTIER.adoc @@ -0,0 +1,80 @@ +ifdef::env-github[] +:important-caption: :heavy_exclamation_mark: +endif::[] + += Building for ZeroTier Support + +If you want to include support for the experimental ZeroTier +transport (`zt://` URLs), you should follow these directions. + +Staysail has created a package that builds a clean CMake project +that you can import. +Download this from https://github.com/staysail/libzerotiercore[GitHub]. + + +IMPORTANT: ZeroTierOne is licensed under different terms than NNG. +You are responsible for reading those license terms, and ensuring that +your use conforms to them. + +IMPORTANT: The ZeroTier transport, and these build instructions, +are experimental. +We expect both to change over time as ZeroTier and the NNG `zt://` transport +both mature. +As always, _caveat emptor_. + +== Building libzerotiercore + +Using "CMake", you can build libzerotiercore +using any normal CMake generator. +You should install it as well. +Normally it will install into `/usr/local` on +Linux and UNIX systems. + +== Configuring NNG with ZT + +You will need to enable ZeroTier within NNG using the CMake option `NNG_TRANSPORT_ZEROTIER=ON`. +If you have installed the libzerotiercore in +one of the default locations, then that should be all +that is needed. + +If you have specified a different location, you will +need to inform CMake of this by setting the CMake +variable `-Dzerotier_DIR=` + +== Example + +The following example would work on either Linux or macOS, and assumes +that we have checked out github source trees into `$HOME/work`. + +[source, sh] +---- +$ export NNGDIR=$HOME/work/nng +$ export ZTDIR=$HOME/work/libzerotiercore +$ git clone https://github.com/staysail/libzerotiercore $ZTDIR +$ cd $ZTDIR +$ mkdir build +$ cd build +$ cmake .. + + ... (lots of lines of output from cmake...) + +$ make + + ... (lots of lines of output from make...) + +$ make install +$ cd $NNGDIR +$ mkdir build +$ cd build +$ cmake -DNNG_TRANSPORT_ZEROTIER=ON .. + + ... (lots of lines of output from cmake...) + +$ make + + ... (lots of lines of output from make...) + +$ ./tests/zt + +ok ./tests/zt 22.837s +---- diff --git a/external/nng/docs/CONTRIBUTING.adoc b/external/nng/docs/CONTRIBUTING.adoc new file mode 100644 index 0000000..a9b82d0 --- /dev/null +++ b/external/nng/docs/CONTRIBUTING.adoc @@ -0,0 +1,129 @@ += NNG Contributing Guidelines + +Legal stuff: + +For any submission you make to us, either by filing an issue, or submitting a +defect, or sending us a message, you agree and certify that: + + ** You are the author or legal owner of the content submitted, or + you have authorization to submit the content by the owner + (such as your employer). + + ** Unless the submission is otherwise labeled, you or the owner + are granting the NNG Project, its contributors, and licensees, + a non-exclusive license to your use submission under the terms of + MIT License (as documented in the <> file in this + repository.) This grant shall include a right to use for any + patents covering content in the submission. + + ** You are not aware of any legal encumbrances to the use of the + submission (such as patents held by others) unless explicitly + stated otherwise. + + ** You have read, and agree to abide by, our + <>. + + ** You understand that participation in this project is voluntary, + and at no point shall any of the project members or leadership + be obligated to review, merge, or handle any submission. + +== Filing Issues + +We use github issues for NNG. We ask that you keep in mind the following +when filing issues: + +* First look to see if your issue is already covered by an existing issue. + +* Synopsis should be brief, but descriptive. (We may alter the synopsis + to correct its accuracy or improve its brevity.) + +* Include details about the platform (operating system, language). + +* Include CMake configuration used to build NNG. + +* Include expected results or behavior, and observed results or behavior. + +* If at all possible, a reproducible test case is helpful. We prefer test + cases as the minimal amount of C code to demonstrate the defect. + +* Please file issues only when filing things that should be fixed by + changes to the source or documentation in the repository (such as bugs + or feature requests). For support questions and other discussion, please + instead use the mailing list + https://www.freelists.org/list/nanomsg + or Gitter chat + https://gitter.im/nanomsg/nanomsg . + +== Pull Requests + +* We use Github PRs + +* Please follow the existing coding style. + + ** See the `.clang-format` for whitespace rules. + ** Return values should be enclosed in parenthesis. + ** Conditional clauses are always enclosed in braces, and thus + span multiple lines. + +TIP: The `.clang-format` file and `clang-format` may be helpful, but +is not necessarily complete. Also you may need to use a recent version +of `clang-format` as older versions can differ in their output. + +* If you submit a PR, we would appreciate it if you would respond to review + feedback, rather than just leaving your baby on our doorstep. Abandoned + PRs or issues may be closed without further action. + +* Commits should have comments formatted like this: + +---- + fixes # + fixes # + + +---- + +* We have an "always release ready" policy for our tree, meaning we should + be able to build a functional release at any commit boundary. This ensures + that others taking the work can use git bisect and similar approaches when + hunting down regressions, or when cherry-picking changes for their own + forked copies. This has a few consequences: + + ** PRs should be functionally complete (that is, don't submit a + PR with partial work in progress, unless you have reached a + milestone that can stand on its own merit.) + + ** Each commit in a PR should also be "complete", so that + a release could be cut in between your commits without + leaving the tree in a broken or dysfunctional state. + + ** Usually this means its best to address only one issue in a PR, + with just one commit (squashed). + + ** Please have already merged and tested your code against the + latest changes in master. (If your code has merge conflicts, + your PR will be rejected until you have fixed the conflicts.) + +* As a special exception, you may submit a PR for handling by our test + infrastructure; in that case please clearly identify that the PR is + submitted for that purpose, and should not considered for integration + yet. When that testing is done, please close the PR, and submit a new + one when you are ready for final review and integration. + +* Code submitted should contain updates to any copyright files to add + your copyright to the license. We prefer you follow the existing + style of copyright, `// Copyright ` + +NOTE: We only use the most recent year, and we do not use `\(C)` which has +no legal value when the word "`Copyright`" is already present. We also +do not use the old "`All rights reserved.`" statement, which is equally +meaningless under current international copyright law. + +* When updating an existing file, any new Copyright notice should be + added immediately below the pre-existing one, just before the license + boilerplate. + +* All new files should use the MIT license and the same boilerplate + from one of the other files. We do not normally approve submissions + with different license or boilerplates -- please contact us if you + have a compelling reason for wanting to do that. diff --git a/external/nng/docs/LICENSE.adoc b/external/nng/docs/LICENSE.adoc new file mode 100644 index 0000000..dc27488 --- /dev/null +++ b/external/nng/docs/LICENSE.adoc @@ -0,0 +1,22 @@ += The MIT License + +Copyright 2018 Staysail Systems, Inc. + +Copyright 2018 Capitar IT Group BV + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom +the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +IN THE SOFTWARE. diff --git a/external/nng/docs/RATIONALE.adoc b/external/nng/docs/RATIONALE.adoc new file mode 100644 index 0000000..b78a5b1 --- /dev/null +++ b/external/nng/docs/RATIONALE.adoc @@ -0,0 +1,340 @@ += Rationale: Or why am I bothering to rewrite nanomsg? +Garrett D'Amore +v0.3, April 10, 2018 + + +NOTE: You might want to review + http://nanomsg.org/documentation-zeromq.html[Martin Sustrik's rationale] + for nanomsg vs. ZeroMQ. + + +== Background + +I became involved in the +http://www.nanomsg.org[nanomsg] community back in 2014, when +I wrote https://github.com/go-mangos/mangos[mangos] as a pure +http://www.golang.org[Go] implementation of the wire protocols behind +_nanomsg_. I did that work because I was dissatisfied with the +http://zeromq.org[_ZeroMQ_] licensing model +and the {cpp} baggage that came with it. I also needed something that would +work with _Go_ on http://www.illumos.org[illumos], which at the time +lacked support for `cgo` (so I could not just use an FFI binding.) + + +At the time, it was the only alternate implementation those protocols. +Writing _mangos_ gave me a lot of detail about the internals of _nanomsg_ and +the SP protocols. + +It would not be wrong to say that one of the goals of _mangos_ was to teach +me about _Go_. It was my first non-trivial _Go_ project. + +While working with _mangos_, I wound up implementing a number of additional +features, such as a TLS transport, the ability to bind to wild card ports, +and the ability to determine more information about the sender of a message. +This was incredibly useful in a number of projects. + +I initially looked at _nanomsg_ itself, as I wanted to add a TLS transport +to it, and I needed to make some bug fixes (for protocol bugs for example), +and so forth. + +== Lessons Learned + +Perhaps it might be better to state that there were a number of opportunities +to learn from the lessons of _nanomsg_, as well as lessons we learned while +building _nng_ itself. + +=== State Machine Madness + +What I ran into in _nanomsg_, when attempting to improve it, was a +challenging mess of state machines. _nanomsg_ has dozens of state machines, +many of which feed into others, such that tracking flow through the state +machines is incredibly painful. + +Worse, these state machines are designed to be run from a single worker +thread. This means that a given socket is entirely single theaded; you +could in theory have dozens, hundreds, or even thousands of connections +open, but they would be serviced only by a single thread. (Admittedly +non-blocking I/O is used to let the OS kernel calls run asynchronously +perhaps on multiple cores, but nanomsg itself runs all socket code on +a single worker thread.) + +There is another problem too -- the `inproc` code that moves messages +between one socket and another was incredibly racy. This is because the +two sockets have different locks, and so dealing with the different +contexts was tricky (and consequently buggy). (I've since, I think, fixed +the worst of the bugs here, but only after many hours of pulling out hair.) + +The state machines also make fairly linear flow really difficult to follow. +For example, there is a state machine to read the header information. This +may come a byte a time, and the state machine has to add the bytes, check +for completion, and possibly change state, even if it is just reading a +single 32-bit word. This is a lot more complex than most programmers are +used to, such as `read(fd, &val, 4)`. + +Now to be fair, Martin Sustrik had the best intentions when he created the +state machine model around which _nanomsg_ is built. I do think that from +experience this is one of the most dense and unapproachable parts of _nanomsg_, +in spite of the fact that Martin's goal was precisely the opposite. I +consider this a "failed experiment" -- but hey failed experiments are the +basis of all great science. + +=== Thread Challenges + +While _nanomsg_ is mostly internally single threaded, I decided to try to +emulate the simple architecture of _mangos_ using system threads. (_mangos_ +benefits greatly from _Go_'s excellent coroutine facility.) Having been well +and truly spoiled by _illumos_ threading (and especially _illumos_ kernel +threads), I thought this would be a reasonable architecture. + +Sadly, this initial effort, while it worked, scaled incredibly poorly -- +even so-called "modern" operating systems like _macOS_ 10.12 and _Windows_ 8.1 +simply melted or failed entirely when creating any non-trivial number of +threads. (To me, creating 100 threads should be a no-brainer, especially if +one limits the stack size appropriately. I'm used to be able to create +thousands of threads without concern. As I said, I've been spoiled. +If your system falls over at a mere 200 threads I consider it a toy +implementation of threading. Unfortunately most of the mainstream operating +systems are therefore toy implementations.) + +Chalk up another failed experiment. + +I did find another approach which is discussed further. + +=== File Descriptor Driven + +Most of the underlying I/O in _nanomsg_ is built around file descriptors, +and it's internal usock structure, which is also state machine driven. +This means that implementing new transports which might need something +other than a file descriptor, is really non-trivial. This stymied my +first attempt to add http://www.openssl.org[OpenSSL] support to get TLS +added -- _OpenSSL_ has it's own `struct BIO` for this stuff, and I could +not see an easy way to convert _nanomsg_'s `usock` stuff to accomodate the +`struct BIO`. + +In retrospect, _OpenSSL_ wasn't the ideal choice for an SSL/TLS library, +and we have since chosen another (https://tls.mbed.org[mbed TLS]). +Still, we needed an abstraction model that was better than just file +descriptors for I/O. + +=== Poll + +In order to support use in event driven programming, asynchronous +situations, etc. _nanomsg_ offers non-blocking I/O. In order to make +this work for end-users, a notification mechanism is required, and +nanomsg, in the spirit of following POSIX, offers a notification method +based on `poll(2)` or `select(2)`. + +In order for this to work, it offers up a selectable file descriptor +for send and another one for receive. When events occur, these are +written to, and the user application "clears" these by reading from +them. (This is done on behalf of the application by _nanomsg_'s API calls.) + +This means that in addition to the context switch code, there are not +fewer than 2 extra system calls executed per message sent or received, and +on a mostly idle system as many as 3. This means that to send a message +from one process to another you may have to execute up to 6 extra system +calls, beyond the 2 required to actually send and receive the message. + +NOTE: Its even more hideous to support this on Windows, where there is no + `pipe(2)` system call, so we have to cobble up a loopback TCP connection + just for this event notification, in addition to the system call + explosion. + +There are cases where this file descriptor logic is easier for existing +applications to integrate into event loops (e.g. they already have a thread +blocked in `poll()`.) + +But for many cases this is not necessary. A simple callback mechanism +would be far better, with the FDs available only as an option for code +that needs them. This is the approach that we have taken with _nng_. + +As another consequence of our approach, we do not require file descriptors +for sockets at all, so it is possible to create applications containing +_many_ thousands of `inproc` sockets with no files open at all. (Obviously +if you're going to perform real I/O to other processes or other systems, +you're going to need to have the underlying transport file descriptors +open, but then the only real limit should be the number of files that you +can open on your system. And the number of active connections you can maintain +should ideally approach that system limit closely.) + +=== POSIX APIs + +Another of Martin's goals, which seems worthwhile at first, was the +attempt to provide a familiar POSIX API (based upon the BSD socket API). +As a C programmer coming from UNIX systems, this really attracted me. + +The problem is that the POSIX APIs are actually really horrible. In +particular the semantics around `cmsg` are about as arcane and painful as +one can imagine. Largely, this has meant that extensions to the `cmsg` +API simply have not occurred in _nanomsg_. + +The `cmsg` API specified by POSIX is as bad as it is because POSIX had +requirements not to break APIs that already existed, and they needed to +shim something that would work with existing implementations, including +getting across a system call boundary. _nanomsg_ has never had such +constraints. + +Oh, and there was that whole "design by committee" aspect. + +Attempting to retain low numbered "socket descriptors" had its own +problems -- a huge source of use-after-close bugs, which made the +use of `nn_close()` incredibly dangerous for multithreaded sockets. +(If one thread closes and opens a new socket, other threads still using +the old socket might wind up accessing the "new" socket without realizing +it.) + +The other thing is that BSD socket APIs are super familiar to UNIX C +programmers -- but experience with _nanomsg_ has taught us already that these +are actually in the minority of _nanomsg_'s users. Most of our users are +coming to us from {cpp} (object oriented), _Java_, and _Python_ backgrounds. +For them the BSD sockets API is frankly somewhat bizarre and alien. + +With _nng_, we realized that constraining ourselves to the mistakes of the +POSIX API was hurting rather than helping. So _nng_ provides a much friendlier +interface for getting properties associated with messages. + +In _nng_ we also generally try hard to avoid reusing +an identifier until no other option exists. This generally means most +applications won't see socket reuse until billions of other sockets +have been opened. There is little chance for accidental reuse. + + +== Compatibility + +Of course, there are a number of existing _nanomsg_ consumers "in the wild" +already. It is important to continue to support them. So I decided from +the get go to implement a "compatibility" layer, that provides the same +API, and as much as possible the same ABI, as legacy _nanomsg_. However, +new features and capabilities would not necessarily be exposed to the +the legacy API. + +Today _nng_ offers this. You can relink an existing _nanomsg_ binary against +_libnng_ instead of _libnn_, and it usually Just Works(TM). Source +compatibility is almost as easy, although the application code needs to be +modified to use different header files. + +NOTE: I am considering changing the include file in the future so that +it matches exactly the _nanomsg_ include path, so that only a compiler +flag change would be needed. + +== Asynchronous IO + +As a consequence of our experience with threads being so unscalable, +we decided to create a new underlying abstraction modeled largely on +Windows IO completion ports. (As bad as so many of the Windows APIs +are, the IO completion port stuff is actually pretty nice.) Under the +hood in _nng_ all I/O is asynchronous, and we have `nni_aio` objects +for each pending I/O. These have an associated completion routine. + +The completion routines are _usually_ run on a separate worker thread +(we have many such workers; in theory the number should be tuned to the +available number of CPU cores to ensure that we never wait while a CPU +core is available for work), but they can be run "synchronously" if +the I/O provider knows it is safe to do so (for example the completion +is occuring in a context where no locks are held.) + +The `nni_aio` structures are accessible to user applications as well, which can +lead to much more efficient and easier to write asynchronous applications, +and can aid integration into event-driven systems and runtimes, without +requiring extra system calls required by the legacy _nanomsg_ approach. + +There is still performance tuning work to do, especially optimization for +specific pollers like `epoll()` and `kqueue()` to address the C10K problem, +but that work is already in progress. + +== Portability & Embeddability + +A significant goal of _nng_ is to be portable to many kinds of different +kinds of systems, and embedded in systems that do not support POSIX or Win32 +APIs. To that end we have a clear platform portability layer. We do require +that platforms supply entry points for certain networking, synchronization, +threading, and timekeeping functions, but these are fairly straight-forward +to implement on any reasonable 32-bit or 64-bit system, including most +embedded operating systems. + +Additionally, this portability layer may be used to build other kinds of +experiments -- for example it should be relatively straight-forward to provide +a "platform" based on one of the various coroutine libraries such as Martin's +http://libdill.org[libdill] or https://swtch.com/libtask/[libtask]. + +TIP: If you want to write a coroutine-based platform, let me know! + +== New Transports + +The other, most critical, motivation behind _nng_ was to enable an easier +creation of new transports. In particular, one client ( +http://www.capitar.com[Capitar IT Group BV]) +contracted the creation of a http://www.zerotier.com[ZeroTier] transport for +_nanomsg_. + +After beating my head against the state machines some more, I finally asked +myself if it would not be easier just to rewrite _nanomsg_ using the model +I had created for _mangos_. + +In retrospect, I'm not sure that the answer was a clear and definite yes +in favor of _nng_, but for the other things I want to do, it has enabled a +lot of new work. The ZeroTier transport was created with a relatively +modest amount of effort, in spite of being based upon a connectionless +transport. I do not believe I could have done this easily in the existing +_nanomsg_. + +I've since added a rich TLS transport, and have implemented a WebSocket +transport that is far more capable than that in _nanomsg_, as it can +support TLS and sharing the TCP port across multiple _nng_ sockets (using +the path to discriminate) or even other HTTP services. + +There are already plans afoot for other kinds of transports using QUIC +or KCP or SSH, as well as a pure UDP transport. The new _nng_ transport +layer makes implementation of these all fairly straight-forward. + +== HTTP and Other services + +As part of implementing a real WebSocket transport, it was necessary to +implement at least some HTTP capabilities. Rather than just settle for a toy +implementation, _nng_ has a very capable HTTP server and client framework. +The server can be used to build real web services, so it becomes possible +for example to serve static content, REST API, and _nng_ based services +all from the same TCP port using the same program. + +We've also made the WebSocket services fairly generic, which may support +a plethora of other kinds of transports and services. + +There is also a portability layer -- so some common services (threading, +timing, etc.) are provided in the _nng_ library to help make writing +portable _nng_ applications easier. + +It will not surprise me if developers start finding uses for _nng_ that +have nothing to do with Scalability Protocols. + +== Separate Contexts + +As part of working on a demo suite of applications, I realized that the +requirement to use raw mode sockets for concurrent applications was rather +onerous, forcing application developers to re-implement much of the +same logic that is already in _nng_. + +Thus was the born the idea of separating the context for protocols from +the socket, allowing multiple contexts (each of which managing it's own +REQ/REP state machinery) to be allocated and used on a single socket. + +This was a large change indeed, but we believe application developers +are going to find it *much* easier to write scalable applications, +and hopefully the uses of raw mode and applications needing to inspect +or generate their own application headers will vanish. + +Note that these contexts are entirely optional -- an application can +still use the implicit context associated with the socket just like +always, if it has no need for extra concurrency. + +One side benefit of this work was that we identified several places +to make _nng_ perform more efficiently, reducing the number of context +switches and extra raw vs. cooked logic. + +== Towards _nanomsg_ 2.0 + +It is my intention that _nng_ ultimately replace _nanomsg_. I do think of it +as "nanomsg 2.0". In fact "nng" stands for "nanomsg next generation" in +my mind. Some day soon I'm hoping that the various website +references to nanomsg my simply be updated to point at _nng_. It is not +clear to me whether at that time I will simply rename the existing +code to _nanomsg_, nanomsg2, or leave it as _nng_. diff --git a/external/nng/docs/README.txt b/external/nng/docs/README.txt new file mode 100644 index 0000000..5331f67 --- /dev/null +++ b/external/nng/docs/README.txt @@ -0,0 +1,11 @@ +This contains the nng documentation for API users. + +The documentation is written in asciidoc in the form of man pages. It is +automatically formatted for display on the website. + +It is possible to emit TROFF sources for use by the UNIX man page, and HTML +for online viewing. asciidoctor supports PDF and EPUB formats via plugins, +so there are still more options available. + +The man pages are in the "man" directory. The reason those are separate +is that they get special treatment. Other documentation is located here. diff --git a/external/nng/docs/man/CMakeLists.txt b/external/nng/docs/man/CMakeLists.txt new file mode 100644 index 0000000..e839b0d --- /dev/null +++ b/external/nng/docs/man/CMakeLists.txt @@ -0,0 +1,446 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# Copyright 2018 Capitar IT Group BV +# Copyright 2019 Devolutions +# +# This software 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. + +# We default to off here. +option(NNG_ENABLE_DOC "Enable building documentation." OFF) + +if (NNG_ENABLE_DOC) + find_program(ASCIIDOCTOR asciidoctor) + if (NOT ASCIIDOCTOR) + message(WARNING "Could not find asciidoctor: skipping docs") + set(NNG_ENABLE_DOC OFF) + else () + message(STATUS "Using asciidoctor at ${ASCIIDOCTOR}") + endif () +endif () + +if (NNG_ENABLE_DOC) + set(NNG_DOCDIR ${CMAKE_CURRENT_SOURCE_DIR}) + + set(NNG_A2M ${ASCIIDOCTOR} -b manpage -amanmanual='NNG Reference Manual') + set(NNG_A2H ${ASCIIDOCTOR} -a nofooter -atoc=left -aicons=font -d manpage -b html5) + + macro(nng_man NAME SECT) + + add_custom_command( + OUTPUT ${NAME}.${SECT} + COMMAND ${NNG_A2M} -o ${NAME}.${SECT} ${NNG_DOCDIR}/${NAME}.${SECT}.adoc + MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc + ) + + add_custom_command( + OUTPUT ${NAME}.${SECT}.html + COMMAND ${NNG_A2H} -o ${NAME}.${SECT}.html ${NNG_DOCDIR}/${NAME}.${SECT}.adoc + MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc + ) + + set(NNG_MANS ${NNG_MANS} ${NAME}.${SECT}) + set(NNG_HTMLS ${NNG_HTMLS} ${NAME}.${SECT}.html) + + install( + FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT}.html + DESTINATION ${CMAKE_INSTALL_DOCDIR} + ) + install( + FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT} + DESTINATION ${CMAKE_INSTALL_MANDIR}/man${SECT} + ) + + endmacro(nng_man) + + set(NNG_MAN1 + nngcat + ) + + set(NNG_MAN3 + libnng + nng_aio_abort + nng_aio_alloc + nng_aio_begin + nng_aio_cancel + nng_aio_count + nng_aio_defer + nng_aio_finish + nng_aio_free + nng_aio_get_input + nng_aio_get_msg + nng_aio_get_output + nng_aio_result + nng_aio_set_input + nng_aio_set_iov + nng_aio_set_msg + nng_aio_set_output + nng_aio_set_timeout + nng_aio_stop + nng_aio_wait + nng_alloc + nng_bus_open + nng_close + nng_ctx_close + nng_ctx_get + nng_ctx_getopt + nng_ctx_id + nng_ctx_open + nng_ctx_recv + nng_ctx_send + nng_ctx_set + nng_ctx_setopt + nng_device + nng_dial + nng_dialer_close + nng_dialer_create + nng_dialer_get + nng_dialer_getopt + nng_dialer_id + nng_dialer_set + nng_dialer_setopt + nng_dialer_start + nng_free + nng_getopt + nng_inproc_register + nng_ipc_register + nng_listen + nng_listener_close + nng_listener_create + nng_listener_get + nng_listener_getopt + nng_listener_id + nng_listener_set + nng_listener_setopt + nng_listener_start + nng_log + nng_log_get_level + nng_log_set_facility + nng_log_set_level + nng_log_set_logger + nng_msg_alloc + nng_msg_append + nng_msg_body + nng_msg_chop + nng_msg_clear + nng_msg_dup + nng_msg_free + nng_msg_get_pipe + nng_msg_header + nng_msg_header_append + nng_msg_header_chop + nng_msg_header_clear + nng_msg_header_insert + nng_msg_header_len + nng_msg_header_trim + nng_msg_insert + nng_msg_len + nng_msg_realloc + nng_msg_set_pipe + nng_msg_trim + nng_pair_open + nng_pipe_close + nng_pipe_dialer + nng_pipe_get + nng_pipe_getopt + nng_pipe_id + nng_pipe_listener + nng_pipe_notify + nng_pipe_socket + nng_pub_open + nng_pull_open + nng_push_open + nng_recv + nng_recv_aio + nng_recvmsg + nng_rep_open + nng_req_open + nng_respondent_open + nng_send + nng_send_aio + nng_sendmsg + nng_setopt + nng_sleep_aio + nng_socket_id + nng_socket_get + nng_socket_set + nng_stats_free + nng_stats_get + nng_stat_bool + nng_stat_child + nng_stat_desc + nng_stat_find + nng_stat_find_dialer + nng_stat_find_listener + nng_stat_find_socket + nng_stat_name + nng_stat_next + nng_stat_string + nng_stat_timestamp + nng_stat_type + nng_stat_unit + nng_stat_value + nng_str_sockaddr + nng_strdup + nng_strerror + nng_strfree + nng_sub_open + nng_surveyor_open + nng_tcp_register + nng_tls_register + nng_url_clone + nng_url_free + nng_url_parse + nng_version + nng_ws_register + nng_wss_register + nng_zt_register + ) + + set(NNG_MAN3COMPAT + nn_allocmsg + nn_bind + nn_close + nn_cmsg + nn_connect + nn_device + nn_errno + nn_freemsg + nn_get_statistic + nn_getsockopt + nn_poll + nn_reallocmsg + nn_recv + nn_recvmsg + nn_send + nn_sendmsg + nn_setsockopt + nn_shutdown + nn_socket + nn_strerror + nn_term + nng_compat + ) + + set(NNG_MAN3HTTP + nng_http_client_alloc + nng_http_client_connect + nng_http_client_free + nng_http_client_get_tls + nng_http_client_set_tls + nng_http_client_transact + nng_http_conn_close + nng_http_conn_read + nng_http_conn_read_all + nng_http_conn_read_req + nng_http_conn_read_res + nng_http_conn_transact + nng_http_conn_write + nng_http_conn_write_all + nng_http_conn_write_req + nng_http_conn_write_res + nng_http_handler_alloc + nng_http_handler_free + nng_http_handler_get_data + nng_http_handler_set_data + nng_http_handler_set_host + nng_http_handler_set_method + nng_http_handler_set_tree + nng_http_hijack + nng_http_req_add_header + nng_http_req_alloc + nng_http_req_copy_data + nng_http_req_del_header + nng_http_req_free + nng_http_req_get_data + nng_http_req_get_header + nng_http_req_get_method + nng_http_req_get_uri + nng_http_req_get_version + nng_http_req_reset + nng_http_req_set_data + nng_http_req_set_header + nng_http_req_set_method + nng_http_req_set_uri + nng_http_req_set_version + nng_http_res_add_header + nng_http_res_alloc + nng_http_res_alloc_error + nng_http_res_copy_data + nng_http_res_del_header + nng_http_res_free + nng_http_res_get_data + nng_http_res_get_header + nng_http_res_get_reason + nng_http_res_get_status + nng_http_res_get_version + nng_http_res_reset + nng_http_res_set_data + nng_http_res_set_header + nng_http_res_set_reason + nng_http_res_set_status + nng_http_res_set_version + nng_http_server_add_handler + nng_http_server_del_handler + nng_http_server_get_addr + nng_http_server_get_tls + nng_http_server_hold + nng_http_server_release + nng_http_server_set_tls + nng_http_server_start + nng_http_server_stop + ) + + set(NNG_MAN3SUPP + nng_clock + nng_cv_alloc + nng_cv_free + nng_cv_until + nng_cv_wait + nng_cv_wake + nng_cv_wake1 + nng_id_map + nng_msleep + nng_mtx_alloc + nng_mtx_free + nng_mtx_lock + nng_mtx_unlock + nng_opts_parse + nng_random + nng_socket_pair + nng_thread_create + nng_thread_destroy + nng_thread_set_name + ) + + set(NNG_MAN3STR + nng_stream_close + nng_stream_free + nng_stream_get + nng_stream_recv + nng_stream_send + nng_stream_set + nng_stream_dialer_alloc + nng_stream_dialer_close + nng_stream_dialer_dial + nng_stream_dialer_free + nng_stream_dialer_get + nng_stream_dialer_set + nng_stream_listener_accept + nng_stream_listener_alloc + nng_stream_listener_close + nng_stream_listener_free + nng_stream_listener_get + nng_stream_listener_listen + nng_stream_listener_set + ) + + set(NNG_MAN3TLS + nng_tls_config_alloc + nng_tls_config_auth_mode + nng_tls_config_ca_chain + nng_tls_config_ca_file + nng_tls_config_cert_key_file + nng_tls_config_free + nng_tls_config_hold + nng_tls_config_own_cert + nng_tls_config_server_name + nng_tls_engine_description + nng_tls_engine_fips_mode + nng_tls_engine_name + ) + + set(NNG_MAN5 + nng_aio + nng_ctx + nng_dialer + nng_duration + nng_iov + nng_listener + nng_msg + nng_options + nng_pipe + nng_sockaddr + nng_sockaddr_abstract + nng_sockaddr_in + nng_sockaddr_in6 + nng_sockaddr_inproc + nng_sockaddr_ipc + nng_sockaddr_zt + nng_socket + nng_stat + nng_url + + nng_stream + nng_stream_dialer + nng_stream_listener + + nng_tcp_options + nng_ipc_options + nng_tls_config + nng_tls_engine + nng_tls_options + ) + + set(NNG_MAN7 + nng + nng_bus + nng_inproc + nng_ipc + nng_pair + nng_pub + nng_pull + nng_push + nng_rep + nng_req + nng_respondent + nng_socket + nng_sub + nng_surveyor + nng_tcp + nng_tls + nng_ws + nng_zerotier + ) + + foreach (F ${NNG_MAN1}) + nng_man(${F} 1) + endforeach () + + foreach (F ${NNG_MAN3}) + nng_man(${F} 3) + endforeach () + + foreach (F ${NNG_MAN3COMPAT}) + nng_man(${F} 3compat) + endforeach () + + foreach (F ${NNG_MAN3HTTP}) + nng_man(${F} 3http) + endforeach () + + foreach (F ${NNG_MAN3STR}) + nng_man(${F} 3str) + endforeach () + + foreach (F ${NNG_MAN3SUPP}) + nng_man(${F} 3supp) + endforeach () + + foreach (F ${NNG_MAN3TLS}) + nng_man(${F} 3tls) + endforeach () + + foreach (F ${NNG_MAN5}) + nng_man(${F} 5) + endforeach () + + foreach (F ${NNG_MAN7}) + nng_man(${F} 7) + endforeach () + + add_custom_target(man ALL DEPENDS ${NNG_MANS}) + add_custom_target(html ALL DEPENDS ${NNG_HTMLS}) +endif () diff --git a/external/nng/docs/man/libnng.3.adoc b/external/nng/docs/man/libnng.3.adoc new file mode 100644 index 0000000..3e2900a --- /dev/null +++ b/external/nng/docs/man/libnng.3.adoc @@ -0,0 +1,484 @@ += libnng(3) +// +// Copyright 2023 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// Copyright 2020 Dirac Research +// +// 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 + +libnng - nanomsg next generation library + +== SYNOPSIS + +*cc* [_flags_] _files_ *-lnng* [_libraries_] + +== DESCRIPTION + +xref:nng.7.adoc[_NNG_] provides a common messaging framework +intended to solve common communication problems in distributed applications. + +It provides a C language API. + +=== Common Functions + +The following common functions exist in _libnng_. + +|=== +|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory +|xref:nng_free.3.adoc[nng_free()]|free memory +|xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string +|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description +|xref:nng_strfree.3.adoc[nng_strfree()]|free string +|xref:nng_version.3.adoc[nng_version()]|report library version +|=== + +=== Socket Functions + +The following functions operate on sockets. + +|=== +|xref:nng_close.3.adoc[nng_close()]|close socket +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_getopt.3.adoc[nng_getopt()]|get socket option +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_recv.3.adoc[nng_recv()]|receive data +|xref:nng_send.3.adoc[nng_send()]|send data +|xref:nng_setopt.3.adoc[nng_setopt()]|set socket option +|xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option +|xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier +|xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option +|=== + +=== Connection Management + +The following functions are used with either listeners, or dialers. +Listeners accept incoming connection requests, and dialers make them. + +|=== +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_dialer_close.3.adoc[nng_dialer_close()]|close dialer +|xref:nng_dialer_create.3.adoc[nng_dialer_create()]|create dialer +|xref:nng_dialer_get.3.adoc[nng_dialer_get()]|get dialer option +|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt()]|get dialer option +|xref:nng_dialer_id.3.adoc[nng_dialer_id()]|get numeric dialer identifier +|xref:nng_dialer_set.3.adoc[nng_dialer_set()]|set dialer option +|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt()]|set dialer option +|xref:nng_dialer_start.3.adoc[nng_dialer_start()]|start dialer +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener +|xref:nng_listener_create.3.adoc[nng_listener_create()]|create listener +|xref:nng_listener_get.3.adoc[nng_listener_get()]|get listener option +|xref:nng_listener_getopt.3.adoc[nng_listener_getopt()]|get listener option +|xref:nng_listener_id.3.adoc[nng_listener_id()]|get numeric listener identifier +|xref:nng_listener_set.3.adoc[nng_listener_set()]|set listener option +|xref:nng_listener_setopt.3.adoc[nng_listener_setopt()]|set listener option +|xref:nng_listener_start.3.adoc[nng_listener_start()]|start listener +|xref:nng_pipe_close.3.adoc[nng_pipe_close()]|close pipe +|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer()]|return dialer that created pipe +|xref:nng_pipe_get.3.adoc[nng_pipe_get()]|get pipe option +|xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt()]|get pipe option +|xref:nng_pipe_id.3.adoc[nng_pipe_id()]|get numeric pipe identifier +|xref:nng_pipe_listener.3.adoc[nng_pipe_listener()]|return listener that created pipe +|xref:nng_pipe_notify.3.adoc[nng_pipe_notify()]|register pipe notification callback +|xref:nng_pipe_socket.3.adoc[nng_pipe_socket()]|return owning socket for pipe +|=== + +=== Message Handling Functions + +Applications desiring to use the richest part of _libnng_ will want to +use the message API, where a message structure is passed between functions. +This API provides the most power support for zero-copy. + +Messages are divided into a header and body, where the body generally carries +user-payload and the header carries protocol specific header information. +Most applications will only interact with the body. + +|=== +|xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message +|xref:nng_msg_append.3.adoc[nng_msg_append()]|append to message body +|xref:nng_msg_body.3.adoc[nng_msg_body()]|return message body +|xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body +|xref:nng_msg_chop.3.adoc[nng_msg_chop()]|remove data from end of message body +|xref:nng_msg_clear.3.adoc[nng_msg_clear()]|clear message body +|xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message +|xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message +|xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe()]|get pipe for message +|xref:nng_msg_insert.3.adoc[nng_msg_insert()]|prepend to message body +|xref:nng_msg_len.3.adoc[nng_msg_len()]|return the message body length +|xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message +|xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body +|xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe()]|set pipe for message +|xref:nng_msg_trim.3.adoc[nng_msg_trim()]|remove data from start of message body +|xref:nng_recvmsg.3.adoc[nng_recvmsg()]|receive a message +|xref:nng_sendmsg.3.adoc[nng_sendmsg()]|send a message +|=== + +==== Message Header Handling + +TIP: Few applications will need these functions, as message headers are only +used to carry protocol-specific content. However, applications which use raw +mode may need to access the header of messages. + +|=== +|xref:nng_msg_header.3.adoc[nng_msg_header()]|return message header +|xref:nng_msg_header_append.3.adoc[nng_msg_header_append()]|append to message header +|xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop()]|remove data from end of message header +|xref:nng_msg_header_clear.3.adoc[nng_msg_header_clear()]|clear message header +|xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert()]|prepend to message header +|xref:nng_msg_header_len.3.adoc[nng_msg_header_len()]|return the message header length +|xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim()]|remove data from start of message header +|=== + +=== Asynchronous Operations + +Most applications will interact with _NNG_ synchronously; that is that +functions such as xref:nng_send.3.adoc[`nng_send()`] will block the calling +thread until the operation has completed. + +NOTE: Synchronous operations which send messages may return before the +message has actually been received, or even transmitted. Instead, These +functions return as soon as the message was successfully queued for +delivery. + +Asynchronous operations behave differently. These operations are +initiated by the calling thread, but control returns immediately to +the calling thread. When the operation is subsequently completed (regardless +of whether this was successful or not), then a user supplied function +is executed. + +A context structure, an xref:nng_aio.5.adoc[`nng_aio`], is allocated and +associated with each asynchronous operation. +Only a single asynchronous operation may be associated with an +`nng_aio` at any time. + +The following functions are used in the asynchronous model: + +|=== +|xref:nng_aio_abort.3.adoc[nng_aio_abort()]|abort asynchronous I/O operation +|xref:nng_aio_alloc.3.adoc[nng_aio_alloc()]|allocate asynchronous I/O handle +|xref:nng_aio_begin.3.adoc[nng_aio_begin()]|begin asynchronous I/O operation +|xref:nng_aio_busy.3.adoc[nng_aio_busy()]|test if asynchronous I/O is busy +|xref:nng_aio_cancel.3.adoc[nng_aio_cancel()]|cancel asynchronous I/O operation +|xref:nng_aio_count.3.adoc[nng_aio_count()]|return number of bytes transferred +|xref:nng_aio_defer.3.adoc[nng_aio_defer()]|defer asynchronous I/O operation +|xref:nng_aio_finish.3.adoc[nng_aio_finish()]|finish asynchronous I/O operation +|xref:nng_aio_free.3.adoc[nng_aio_free()]|free asynchronous I/O handle +|xref:nng_aio_get_input.3.adoc[nng_aio_get_input()]|return input parameter +|xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg()]|get message from an asynchronous receive +|xref:nng_aio_get_output.3.adoc[nng_aio_get_output()]|return output result +|xref:nng_aio_free.3.adoc[nng_aio_reap()]|reap asynchronous I/O handle +|xref:nng_aio_result.3.adoc[nng_aio_result()]|return result of asynchronous operation +|xref:nng_aio_set_input.3.adoc[nng_aio_set_input()]|set input parameter +|xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov()]|set scatter/gather vector +|xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg()]|set message for an asynchronous send +|xref:nng_aio_set_output.3.adoc[nng_aio_set_output()]|set output result +|xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout()]|set asynchronous I/O timeout +|xref:nng_aio_stop.3.adoc[nng_aio_stop()]|stop asynchronous I/O operation +|xref:nng_aio_wait.3.adoc[nng_aio_wait()]|wait for asynchronous I/O operation +|xref:nng_recv_aio.3.adoc[nng_recv_aio()]|receive message asynchronously +|xref:nng_send_aio.3.adoc[nng_send_aio()]|send message asynchronously +|xref:nng_sleep_aio.3.adoc[nng_sleep_aio()]|sleep asynchronously +|=== + +=== Protocols + +The following functions are used to construct a socket with a specific protocol: + +|=== +|xref:nng_bus_open.3.adoc[nng_bus_open()]|open a bus socket +|xref:nng_pair_open.3.adoc[nng_pair_open()]|open a pair socket +|xref:nng_pub_open.3.adoc[nng_pub_open()]|open a pub socket +|xref:nng_pull_open.3.adoc[nng_pull_open()]|open a pull socket +|xref:nng_push_open.3.adoc[nng_push_open()]|open a push socket +|xref:nng_rep_open.3.adoc[nng_rep_open()]|open a rep socket +|xref:nng_req_open.3.adoc[nng_req_open()]|open a req socket +|xref:nng_respondent_open.3.adoc[nng_respondent_open()]|open a respondent socket +|xref:nng_sub_open.3.adoc[nng_sub_open()]|open a sub socket +|xref:nng_surveyor_open.3.adoc[nng_surveyor_open()]|open a surveyor socket +|=== + +=== Transports + +The following functions are used to register a transport for use. + +|=== +| xref:nng_inproc_register.3.adoc[nng_inproc_register()]|register inproc transport +| xref:nng_ipc_register.3.adoc[nng_ipc_register()]|register IPC transport +| xref:nng_tcp_register.3.adoc[nng_tcp_register()]|register TCP transport +| xref:nng_tls_register.3.adoc[nng_tls_register()]|register TLS transport +| xref:nng_ws_register.3.adoc[nng_ws_register()]|register WebSocket transport +| xref:nng_wss_register.3.adoc[nng_wss_register()]|register WebSocket Secure transport +| xref:nng_zt_register.3.adoc[nng_zt_register()]|register ZeroTier transport +|=== + +=== Protocol Contexts + +The following functions are useful to separate the protocol processing +from a socket object, into a separate context. +This can allow multiple contexts to be created on a single socket for +concurrent applications. + +|=== +|xref:nng_ctx_close.3.adoc[nng_ctx_close()]|close context +|xref:nng_ctx_get.3.adoc[nng_ctx_get()]|get context option +|xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt()]|get context option +|xref:nng_ctx_id.3.adoc[nng_ctx_id()]|get numeric context identifier +|xref:nng_ctx_open.3.adoc[nng_ctx_open()]|create context +|xref:nng_ctx_recv.3.adoc[nng_ctx_recv()]|receive message using context asynchronously +|xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg()]|receive a message using context +|xref:nng_ctx_send.3.adoc[nng_ctx_send()]|send message using context asynchronously +|xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg()]|send a message using context +|xref:nng_ctx_set.3.adoc[nng_ctx_set()]|set context option +|xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt()]|set context option +|=== + +=== Devices, Relays + +The following function family is used to create forwarders or relayers +that route messages from one socket to another. + +|=== +|xref:nng_device.3.adoc[nng_device()]|message forwarding device +|=== + +=== Statistics + +The following functions provide access to statistics which can be used +to observe program behaviors and as an aid in troubleshooting. + +|=== +|xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value +|xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic +|xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description +|xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name +|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics +|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics +|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics +|xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name +|xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic +|xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value +|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp +|xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type +|xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit +|xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value +|xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics +|xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics +|=== + +=== URL Object + +Common functionality is supplied for parsing and handling +universal resource locators (URLS). + +|=== +|xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure +|xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure +|xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string +|=== + +=== Logging Support + +Common functionality for message logging. + +|=== +|xref:nng_log.3.adoc[nng_log()]|log a message +|xref:nng_log_facility.3.adoc[nng_log_set_facility()]|set log facility +|xref:nng_log_level.3.adoc[nng_log_set_level()]|set log level +|xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler +|=== + +=== Supplemental API + +These supplemental functions are not intrinsic to building +network applications with _NNG_, but they are made available +as a convenience to aid in creating portable applications. + +|=== +|xref:nng_clock.3supp.adoc[nng_clock()]|get time +|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable +|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable +|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout +|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition +|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters +|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter +|xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table +|xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds +|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex +|xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex +|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex +|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex +|xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options +|xref:nng_random.3supp.adoc[nng_random()]|get random number +|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets +|xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread +|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread +|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name +|=== + +=== Byte Streams + +These functions are available for use with byte streams. +They are considered low-level, for uses where the higher level functions +using Scalability Protocols are inappropriate. + +Byte streams, represented by +xref:nng_stream.5.adoc[`nng_stream`] objects, correspond to underlying +connections such as TCP connections or named pipes. +They are created by either +xref:nng_stream_dialer.5.adoc[`nng_stream_dialer`] or +xref:nng_stream_listener.5.adoc[`nng_stream_listener`] objects. + +|=== +|xref:nng_stream_close.3str.adoc[nng_stream_close()]|close byte stream +|xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc()]|allocate byte stream dialer +|xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close()]|close byte stream dialer +|xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial()]|initiate outgoing byte stream +|xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free()]|free byte stream dialer +|xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get()]|get option from byte stream dialer +|xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set()]|set option on byte stream dialer +|xref:nng_stream_free.3str.adoc[nng_stream_free()]|free byte stream +|xref:nng_stream_get.3str.adoc[nng_stream_get()]|get option from byte stream +|xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept()]|accept incoming byte stream +|xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc()]|allocate byte stream listener +|xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close()]|close byte stream listener +|xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free()]|free byte stream listener +|xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get()]|get option from byte stream listener +|xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen()]|bind byte stream listener to address +|xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set()]|set option on byte stream listener +|xref:nng_stream_recv.3str.adoc[nng_stream_recv()]|receive from byte stream +|xref:nng_stream_send.3str.adoc[nng_stream_send()]|send to byte stream +|xref:nng_stream_set.3str.adoc[nng_stream_set()]|set option on byte stream +|=== + +=== HTTP Support + +The library may be configured with support for HTTP, and this will +be the case if WebSocket support is configured as well. +In this case, it is possible to access functionality to support the creation of +HTTP (and HTTP/S if TLS support is present) servers and clients. + +==== Common HTTP Functions + +The following functions are used to work with HTTP requests, responses, +and connections. + +|=== +|xref:nng_http_conn_close.3http.adoc[nng_http_conn_close()]|close HTTP connection +|xref:nng_http_conn_read.3http.adoc[nng_http_conn_read()]|read from HTTP connection +|xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all()]|read all from HTTP connection +|xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req()]|read HTTP request +|xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res()]|read HTTP response +|xref:nng_http_conn_write.3http.adoc[nng_http_conn_write()]|write to HTTP connection +|xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all()]|write all to HTTP connection +|xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req()]|write HTTP request +|xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res()]|write HTTP response +|xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header()]|add HTTP request header +|xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc()]|allocate HTTP request structure +|xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data()]|copy HTTP request body +|xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header()]|delete HTTP request header +|xref:nng_http_req_free.3http.adoc[nng_http_req_free()]|free HTTP request structure +|xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data()]|get HTTP request body +|xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header()]|return HTTP request header +|xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method()]|return HTTP request method +|xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri()]|return HTTP request URI +|xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version()]|return HTTP request protocol version +|xref:nng_http_req_reset.3http.adoc[nng_http_req_reset()]|reset HTTP request structure +|xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data()]|set HTTP request body +|xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header()]|set HTTP request header +|xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method()]|set HTTP request method +|xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri()]|set HTTP request URI +|xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version()]|set HTTP request protocol version +|xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header()]|add HTTP response header +|xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc()]|allocate HTTP response structure +|xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error()]|allocate HTTP error response +|xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data()]|copy HTTP response body +|xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header()]|delete HTTP response header +|xref:nng_http_res_free.3http.adoc[nng_http_res_free()]|free HTTP response structure +|xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data()]|get HTTP response body +|xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header()]|return HTTP response header +|xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason()]|return HTTP response reason +|xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status()]|return HTTP response status +|xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version()]|return HTTP response protocol version +|xref:nng_http_res_reset.3http.adoc[nng_http_res_reset()]|reset HTTP response structure +|xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data()]|set HTTP response body +|xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header()]|set HTTP response header +|xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason()]|set HTTP response reason +|xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status()]|set HTTP response status +|xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version()]|set HTTP response protocol version +|=== + +==== HTTP Client Functions + +These functions are intended for use with HTTP client applications. + +|=== +|xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc()]|allocate HTTP client +|xref:nng_http_client_connect.3http.adoc[nng_http_client_connect()]|establish HTTP client connection +|xref:nng_http_client_free.3http.adoc[nng_http_client_free()]|free HTTP client +|xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls()]|get HTTP client TLS configuration +|xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls()]|set HTTP client TLS configuration +|xref:nng_http_client_transact.3http.adoc[nng_http_client_transact()]|perform one HTTP transaction +|xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact()]|perform one HTTP transaction on connection +|=== + +==== HTTP Server Functions + +These functions are intended for use with HTTP server applications. + +|=== +|xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc()]|allocate HTTP server handler +|xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body()]|set HTTP handler to collect request body +|xref:nng_http_handler_free.3http.adoc[nng_http_handler_free()]|free HTTP server handler +|xref:nng_http_handler_get_data.3http.adoc[nng_http_handler_get_data()]|return extra data for HTTP handler +|xref:nng_http_handler_set_data.3http.adoc[nng_http_handler_set_data()]|set extra data for HTTP handler +|xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host()]|set host for HTTP handler +|xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method()]|set HTTP handler method +|xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree()]|set HTTP handler to match trees +|xref:nng_http_hijack.3http.adoc[nng_http_hijack()]|hijack HTTP server connection +|xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler()]|add HTTP server handler +|xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler()]|delete HTTP server handler +|xref:nng_http_server_get_addr.3http.adoc[nng_http_server_get_addr()]|get HTTP server address +|xref:nng_http_server_get_tls.3http.adoc[nng_http_server_get_tls()]|get HTTP server TLS configuration +|xref:nng_http_server_hold.3http.adoc[nng_http_server_hold()]|get and hold HTTP server instance +|xref:nng_http_server_release.3http.adoc[nng_http_server_release()]|release HTTP server instance +|xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file()]|set custom HTTP error file +|xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page()]|set custom HTTP error page +|xref:nng_http_server_set_tls.3http.adoc[nng_http_server_set_tls()]|set HTTP server TLS configuration +|xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error()]|use HTTP server error page +|xref:nng_http_server_start.3http.adoc[nng_http_server_start()]|start HTTP server +|xref:nng_http_server_stop.3http.adoc[nng_http_server_stop()]|stop HTTP server +|=== + +=== TLS Configuration Objects + +The following functions are used to manipulate transport layer security +(TLS) configuration objects. Most of these functions will not be used even +by TLS applications. + +NOTE: These functions will only be present if the library has been built +with TLS support. + +|=== +|xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc()]|allocate TLS configuration +|xref:nng_tls_config_auth_mode.3tls.adoc[nng_tls_config_auth_mode()]|set authentication mode +|xref:nng_tls_config_ca_chain.3tls.adoc[nng_tls_config_ca_chain()]|set certificate authority chain +|xref:nng_tls_config_ca_file.3tls.adoc[nng_tls_config_ca_file()]|load certificate authority from file +|xref:nng_tls_config_cert_key_file.3tls.adoc[nng_tls_config_cert_key_file()]|load own certificate and key from file +|xref:nng_tls_config_own_cert.3tls.adoc[nng_tls_config_own_cert()]|set own certificate and key +|xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free()]|free TLS configuration +|xref:nng_tls_config_server_name.3tls.adoc[nng_tls_config_server_name()]|set remote server name +|=== + + +== SEE ALSO + +[.text-left] +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/man1.desc b/external/nng/docs/man/man1.desc new file mode 100644 index 0000000..a512251 --- /dev/null +++ b/external/nng/docs/man/man1.desc @@ -0,0 +1,2 @@ +This section documents utilities and programs that are included +with the distribution. diff --git a/external/nng/docs/man/man1.sect b/external/nng/docs/man/man1.sect new file mode 100644 index 0000000..026bbf3 --- /dev/null +++ b/external/nng/docs/man/man1.sect @@ -0,0 +1 @@ +Commands and Utilities diff --git a/external/nng/docs/man/man3.desc b/external/nng/docs/man/man3.desc new file mode 100644 index 0000000..8daa876 --- /dev/null +++ b/external/nng/docs/man/man3.desc @@ -0,0 +1,6 @@ +This section documents core libary functions supporting Scalability +Protocols. + +Most Scalability Protocols applications can be written using just +the functions documented in this section, as this represents the +primary API for building such applications. diff --git a/external/nng/docs/man/man3.sect b/external/nng/docs/man/man3.sect new file mode 100644 index 0000000..f711bdc --- /dev/null +++ b/external/nng/docs/man/man3.sect @@ -0,0 +1 @@ +Library Functions diff --git a/external/nng/docs/man/man3compat.desc b/external/nng/docs/man/man3compat.desc new file mode 100644 index 0000000..2b0b4b3 --- /dev/null +++ b/external/nng/docs/man/man3compat.desc @@ -0,0 +1,13 @@ +This section documents the _nanomsg_ 1.0 libary compatible functions. + +These functions are provided as a transition aid, for application +developers coming to _NNG_ from _libnanomsg_, and are discouraged +from use in new applications. + +TIP: While this is discouraged for long term use, as a transition aid +applications may use the value returned by the +xref:nng_socket_id.3.adoc[`nng_socket_id()`] in these functions just like a +socket descriptor (as if the socket were opened via +xref:nn_socket.3compat.adoc[`nn_socket()`]). +This sort of API intermixing should only be used during transition from +the legacy API to the new API. diff --git a/external/nng/docs/man/man3compat.sect b/external/nng/docs/man/man3compat.sect new file mode 100644 index 0000000..75a97a0 --- /dev/null +++ b/external/nng/docs/man/man3compat.sect @@ -0,0 +1 @@ +Compatible Library Functions diff --git a/external/nng/docs/man/man3http.desc b/external/nng/docs/man/man3http.desc new file mode 100644 index 0000000..b6659eb --- /dev/null +++ b/external/nng/docs/man/man3http.desc @@ -0,0 +1,13 @@ +This section documents supplemental HTTP (HyperText Transport Protocol) +support functions that are available. + +These functions can be used in conjunction with the +xref:nng_ws.7.adoc[WebSocket] transport for Scalability Protocols, or they +may be used to construct other types of applications that communicate +using HTTP. + +It is also possible to combine the two, such that an HTTP server providing +static or dynamic content can also be used to host one or more Scalability +Protocols sockets. + +NOTE: At present NNG only supports HTTP/1.0 and HTTP/1.1. diff --git a/external/nng/docs/man/man3http.sect b/external/nng/docs/man/man3http.sect new file mode 100644 index 0000000..3ae1b81 --- /dev/null +++ b/external/nng/docs/man/man3http.sect @@ -0,0 +1 @@ +Supplemental HTTP Functions diff --git a/external/nng/docs/man/man3str.desc b/external/nng/docs/man/man3str.desc new file mode 100644 index 0000000..e1fe5f9 --- /dev/null +++ b/external/nng/docs/man/man3str.desc @@ -0,0 +1,7 @@ +This section documents supplemental byte stream functions that +are available. + +These functions are made available to facilitate using raw byte stream +connections with the NNG asynchronous I/O API. +These byte streams may be useful for applications that need to +communicate with raw TCP/IP or IPC streams instead of Scalability Protocols. diff --git a/external/nng/docs/man/man3str.sect b/external/nng/docs/man/man3str.sect new file mode 100644 index 0000000..ed1b830 --- /dev/null +++ b/external/nng/docs/man/man3str.sect @@ -0,0 +1 @@ +Supplemental TCP Functions diff --git a/external/nng/docs/man/man3supp.desc b/external/nng/docs/man/man3supp.desc new file mode 100644 index 0000000..caea4f9 --- /dev/null +++ b/external/nng/docs/man/man3supp.desc @@ -0,0 +1,7 @@ +This section documents supplemental functions that are available. +These functions are not intrinsic to building Scalability Protocols +applications with this library. + +However, their use may facilitate writing portable applications by +providing uniform functions for common application needs such as +mutual exclusion locks, threading, time keeping, and similar needs. diff --git a/external/nng/docs/man/man3supp.sect b/external/nng/docs/man/man3supp.sect new file mode 100644 index 0000000..7c8e382 --- /dev/null +++ b/external/nng/docs/man/man3supp.sect @@ -0,0 +1 @@ +Supplemental Functions diff --git a/external/nng/docs/man/man3tls.desc b/external/nng/docs/man/man3tls.desc new file mode 100644 index 0000000..48b20d3 --- /dev/null +++ b/external/nng/docs/man/man3tls.desc @@ -0,0 +1,17 @@ +This section documents supplemental TLS (Transport Layer Security) +functions that are available. +TLS support is available when using Scalability Protocols with +the xref:nng_tls.7.adoc[TLS] transport, or when using WebSocket, either +with the xref:nng_ws.7.adoc[WebSocket] transport for Scalability Protocols, +or combined with other HTTP capabilities. + +These functions depend on library support that is not included directly +with _NNG_ however, so their presence will depend on whether this +additional support was present and enabled with _libnng_ was built. + +Currently, this extra support can be provided by the +https://tls.mbed.org[mbedTLS library] or by external plug-ins. + +TIP: Contact https://staysail.tech[Staysail Systems, Inc.] for +details about commercially available options, including support for +FIPS 140-2 validated cryptography and TLS v1.3. diff --git a/external/nng/docs/man/man3tls.sect b/external/nng/docs/man/man3tls.sect new file mode 100644 index 0000000..6f789cc --- /dev/null +++ b/external/nng/docs/man/man3tls.sect @@ -0,0 +1 @@ +Supplemental TLS Functions diff --git a/external/nng/docs/man/man5.desc b/external/nng/docs/man/man5.desc new file mode 100644 index 0000000..f99b91f --- /dev/null +++ b/external/nng/docs/man/man5.desc @@ -0,0 +1,4 @@ +This section documents core macros and types that are available. + +These are the core types and macros that most Scalabilty Protocols +applications need will use. diff --git a/external/nng/docs/man/man5.sect b/external/nng/docs/man/man5.sect new file mode 100644 index 0000000..a3d77c9 --- /dev/null +++ b/external/nng/docs/man/man5.sect @@ -0,0 +1 @@ +Macros and Types diff --git a/external/nng/docs/man/man7.desc b/external/nng/docs/man/man7.desc new file mode 100644 index 0000000..eae6694 --- /dev/null +++ b/external/nng/docs/man/man7.desc @@ -0,0 +1,14 @@ +This sections documents various protocols and transports that are +available in the distribution. + +(((protocol))) +Protocols implement communication patterns, such as +request/reply, publish/subscribe, and so forth. +A given xref:nng_socket.5.adoc[socket] is created with exactly one protocol, and that +protocol defines the key behavior of the socket. + +(((transport))) +Conversely, transports are the underlying mechansims by which messages +are moved between participants, such as TCP/IP or UNIX domain IPC. +A given xref:nng_socket.5.adoc[socket] may be using several transports at the same +time. diff --git a/external/nng/docs/man/man7.sect b/external/nng/docs/man/man7.sect new file mode 100644 index 0000000..b82263d --- /dev/null +++ b/external/nng/docs/man/man7.sect @@ -0,0 +1 @@ +Protocols and Transports diff --git a/external/nng/docs/man/nn_allocmsg.3compat.adoc b/external/nng/docs/man/nn_allocmsg.3compat.adoc new file mode 100644 index 0000000..a53da55 --- /dev/null +++ b/external/nng/docs/man/nn_allocmsg.3compat.adoc @@ -0,0 +1,67 @@ += nn_allocmsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_allocmsg - allocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +void *nn_allocmsg(size_t size, int type); +---- + +== DESCRIPTION + +The `nn_allocmsg()` allocates a message structure of size _size_, and is +primarily used to support zero-copy send operations, making use of the +`NNG_MSG` special size indicator. +The value returned is a pointer to the start of the message payload buffer. + +The value of _size_ must be positive, and small enough to hold reasonable +message data plus book-keeping information. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The value of _type_ *must* be zero. +(This argument was reserved to support different kinds of memory spaces +for RDMA devices, but this was never developed in the legacy API.) + +The returned message must be disposed of by either +xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] or +xref:nn_send.3compat.adoc[`nn_send()`] when the caller is finished with it. + +== RETURN VALUES + +This function returns a pointer to message buffer space, or `NULL` +on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`EINVAL`:: An invalid _size_ or _type_ was specified. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_reallocmsg.3compat.adoc[nn_reallocmsg(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_bind.3compat.adoc b/external/nng/docs/man/nn_bind.3compat.adoc new file mode 100644 index 0000000..a4ca004 --- /dev/null +++ b/external/nng/docs/man/nn_bind.3compat.adoc @@ -0,0 +1,68 @@ += nn_bind(3compat) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_bind - accept connections from remote peers (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_bind(int sock, const char *url) +---- + +== DESCRIPTION + +The `nn_bind()` function arranges for the socket _sock_ to +accept connections at the address specified by _url_. +An identifier for this socket's association with the _url_ is +returned to the caller on success. +This identfier can be used with +xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to +remove the association later. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +NOTE: The bind operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +IMPORTANT: Only transports supported by legacy _libnanomsg_ may be +used with this function. +In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are +supported with this function. +(Use the xref:libnng.3.adoc[modern API] to use other schemes.) + +== RETURN VALUES + +This function returns a positive identifier on success, and -1 on error. + +== ERRORS + +[horizontal] +`EADDRINUSE`:: The address specified by _url_ is already in use. +`EADDRNOTAVAIL`:: The address specified by _url_ is not available. +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _url_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_connect.3compat.adoc[nn_connect(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_close.3compat.adoc b/external/nng/docs/man/nn_close.3compat.adoc new file mode 100644 index 0000000..1970b57 --- /dev/null +++ b/external/nng/docs/man/nn_close.3compat.adoc @@ -0,0 +1,51 @@ += nn_close(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_close - close socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_close(int sock); +---- + +== DESCRIPTION + +The `nn_close()` function closes the socket _sock_. +Any operations that are currently in progress will be terminated, and will +fail with error `EBADF`. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket is not open. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_cmsg.3compat.adoc b/external/nng/docs/man/nn_cmsg.3compat.adoc new file mode 100644 index 0000000..32d3181 --- /dev/null +++ b/external/nng/docs/man/nn_cmsg.3compat.adoc @@ -0,0 +1,78 @@ += nn_cmsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_cmsg - message control data (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +struct nn_cmsghdr { + size_t cmsg_len; + int cmsg_level; + int cmsg_type; +}; +---- + +== DESCRIPTION + +The `nn_cmsghdr` structure describes a block of control data that is +associated with a message either sent by xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`] +or received by xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]. + +NOTE: This structure and supporting macros are provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +Each header is followed by `cmsg_len` bytes of data, plus any padding required +to align the structure. + +The only defined ancillary data at this time is the protocol headers used by +the protocols. +This uses `cmsg_level` set to `PROTO_SP` and the `cmsg_type` set to +`SP_HDR`. +The actual data for this will vary from depending on the protocol used. + +Convenience macros are provided to make working with these fields easier. + +`struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *__hdr__)`:: +This macro returns the first `struct nn_cmsghdr` header in _hdr_. + +`struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *__hdr__, struct nn_cmsghdr *__ch__)`:: +This macro returns a pointer to the next `struct nn_cmsghdr` in _hdr_ after _ch_. + +`void *NN_CMSG_DATA(struct nn_cmsghdr *__ch__)`:: +This macro returns a pointer to the header-specific data for _ch_. + +`size_t NN_CMSG_ALIGN(size_t __len__)`:: +This macro returns the length specified by _len_, plus any padding required to +provide the necessary alignment for another structure. + +`size_t NN_CMSG_SPACE(size_t __len__)`:: +This macro returns the amount of space required for a header, with _len_ +bytes of following data, and any necessary padding. + +`size_t NN_CMSG_LEN(size_t __len__)`:: +This macro evaluates to the length of the header (including alignment), +and the associated data of length _len_, but without any trailing padding +to align for another header. + +== SEE ALSO + +[.text-left] +xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], +xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_connect.3compat.adoc b/external/nng/docs/man/nn_connect.3compat.adoc new file mode 100644 index 0000000..e498f8d --- /dev/null +++ b/external/nng/docs/man/nn_connect.3compat.adoc @@ -0,0 +1,67 @@ += nn_connect(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_connect - connect to remote peer (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_connect(int sock, const char *url) +---- + +== DESCRIPTION + +The `nn_connect()` function arranges for the socket _sock_ to +initiate connection to a peer at the address specified by _url_. +An identifier for this socket's association with the _url_ is +returned to the caller on success. +This identifier can be used with +xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to +remove the association later. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +NOTE: The connect operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +IMPORTANT: Only transports supported by legacy _libnanomsg_ may be +used with this function. +In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are +supported with this function. +(Use the xref:libnng.3.adoc[modern API] to use other schemes.) + +== RETURN VALUES + +This function returns a positive identifier success, and -1 on error. + +== ERRORS + +[horizontal] +`ECONNREFUSED`:: The connection attempt was refused. +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _url_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_bind.3compat.adoc[nn_bind(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_device.3compat.adoc b/external/nng/docs/man/nn_device.3compat.adoc new file mode 100644 index 0000000..c69e1e0 --- /dev/null +++ b/external/nng/docs/man/nn_device.3compat.adoc @@ -0,0 +1,59 @@ += nn_device(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_device - create forwarding device (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_device(int sock1, int sock2); +---- + +== DESCRIPTION + +The `nn_device()` function is used to create a forwarder, where messages +received on one of the two sockets _sock1_ and _sock2_ are forwarded to +the other. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The two sockets must be compatible, and must be +xref:nng.7.adoc#raw_mode[raw mode] +sockets. +More detail about devices and how they can be used is available in the +new style xref:nng_device.3.adoc[nng_device()] documentation. + +== RETURN VALUES + +This function blocks forever, and will return -1 only when +one of the sockets is closed or an error occurs. + +== ERRORS + +[horizontal] +`EBADF`:: One of the two sockets is invalid or not open, or has +`EINVAL`:: The sockets are not compatible with each other, or not both raw. +`ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_errno.3compat.adoc b/external/nng/docs/man/nn_errno.3compat.adoc new file mode 100644 index 0000000..a048543 --- /dev/null +++ b/external/nng/docs/man/nn_errno.3compat.adoc @@ -0,0 +1,79 @@ += nn_errno(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_errno - return most recent error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_errno(void); +---- + +== DESCRIPTION + +The `nn_errno()` function returns the error number corresponding to the +most recent failed operation by the calling thread. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: The error numbers returned from this function may include +errors caused by system functions, which overlap the usual `errno` variable, +and this function simply returns the value of `errno`. +However, the values returned may include numeric values that are not +defined by the system, but are unique to _libnanomsg_, such as `EFSM`. + +This library implements the following error numbers, in addition to any others +that might be set for `errno` by the underlying system: + + +== RETURN VALUES + +This function returns the value of `errno`. +If no operation has failed, then this will be zero. + +== ERRORS + +[horizontal] +`EINTR`:: Operation interrupted. +`ENOMEM`:: Insufficient memory. +`EINVAL`:: Invalid argument. +`EBUSY`:: Resource is busy. +`ETIMEDOUT`:: Operation timed out. +`ECONNREFUSED`:: Connection refused by peer. +`EBADF`:: Invalid or closed socket. +`EAGAIN`:: Operation would block. +`ENOTSUP`:: Protocol or option not supported. +`EADDRINUSE`:: Requested address is already in use. +`EFSM`:: Protocol state incorrect. +`EPROTO`:: Protocol error. +`EHOSTUNREACH`:: Remote peer is unreachable. +`EADDRNOTAVAIL`:: Requested address is not available. +`EACCES`:: Permission denied. +`EMSGSIZE`:: Message is too large. +`ECONNABORTED`:: Connection attempt aborted. +`ECONNRESET`:: Connection reset by peer. +`EEXIST`:: Resource already exists. +`EMFILE`:: Too many open files. +`ENOSPC`:: Insufficient persistent storage. + +== SEE ALSO + +[.text-left] +xref:nn_strerror.3compat.adoc[nn_strerror(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_freemsg.3compat.adoc b/external/nng/docs/man/nn_freemsg.3compat.adoc new file mode 100644 index 0000000..61127c3 --- /dev/null +++ b/external/nng/docs/man/nn_freemsg.3compat.adoc @@ -0,0 +1,49 @@ += nn_freemsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_freemsg - free message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_freemsg(void *msg); +---- + +== DESCRIPTION + +The `nn_freemsg()` deallocates a message previously allocated with +xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or similar functions. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function always returns 0. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_get_statistic.3compat.adoc b/external/nng/docs/man/nn_get_statistic.3compat.adoc new file mode 100644 index 0000000..89b11de --- /dev/null +++ b/external/nng/docs/man/nn_get_statistic.3compat.adoc @@ -0,0 +1,46 @@ += nn_get_statistic(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_get_statistic - get statistic (stub) + +== SYNOPSIS + +[source,c] +---- +#include + +uint64_t nn_get_statistic(int sock, int stat); +---- + +== DESCRIPTION + +The `nn_get_statistic()` function exists only as a stub, and always returns +zero. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +Zero. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_getsockopt.3compat.adoc b/external/nng/docs/man/nn_getsockopt.3compat.adoc new file mode 100644 index 0000000..0c476cc --- /dev/null +++ b/external/nng/docs/man/nn_getsockopt.3compat.adoc @@ -0,0 +1,228 @@ += nn_getsockopt(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_getsockopt - get socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp); +---- + +== DESCRIPTION + +The `nn_getsockopt()` function gets a socket option on socket _sock_. +The option retrieved is determined by the _level_ and _option_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The value pointed to by _szp_ must be initialized to the size of the buffer +pointed to by _val_. +No more than this many bytes of the option will be copied into the destination +buffer on success. +On success, the value pointed to by _szp_ will be updated with the actual +size of the option. + +TIP: To determine the size to receive an option, first call this function +with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero. + +The _level_ determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows: + +[horizontal] +`NN_SOL_SOCKET`:: Generic socket option +`NN_IPC`:: Transport specific option for IPC. +`NN_TCP`:: Transport specific option for TCP. +`NN_WS`:: Transport specific option for WebSocket. + +The following generic socket options are possible (all are of type `int` and +thus size 4, unless otherwise indicated.) + +`NN_SNDBUF`:: +Send buffer size in bytes. + +NOTE: In _NNG_ buffers are sized as a count of messages rather than +bytes; accordingly this value is the queue depth multiplied by 1024 +(representing an estimate that the average message size is 1kB). +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. + +`NN_RCVBUF`:: +Receive buffer size in bytes. + +NOTE: The same caveats for `NN_SNDBUF` apply here as well. + +`NN_SNDTIMEO`:: +Send time-out in milliseconds. +Send operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVTIMEO`:: +Receive time-out in milliseconds. +Receive operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVMAXSIZE`:: +Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit. + +`NN_RECONNECT_IVL`:: +Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100. + +`NN_RECONNECT_IVL_MAX`:: +Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by `NN_RECONNECT_IVL`. +The default is zero. + +`NN_LINGER`:: +This option is always zero and exists only for compatibility. + +NOTE: This option was unreliable in early releases of _libnanomsg_, and +is unsupported in _NNG_ and recent _libnanomsg_ releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the `NN_REQ` protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. + + +`NN_SNDPRIO`:: +This option is not implemented at this time. + +`NN_RCVPRIO`:: +This option is not implemented at this time. + +`NN_IPV4ONLY`:: +This option is not implemented at this time. + +`NN_SOCKET_NAME`:: +This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes. + +`NN_MAXTTL`:: +Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +xref:nng_device.3.adoc[device] chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +`NN_DOMAIN`:: +This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, +corresponding to the value that the socket was created with. + +`NN_PROTOCOL`:: +This option option of type `int` contains the numeric protocol number +that the socket is used with. + +`NN_RCVFD`:: +This option returns a file descriptor suitable for use in with `poll()` or +`select()` (or other system-specific polling functions). +This descriptor will be readable when a message is available for receiving +at the socket. +This option is of type `int` on all systems except Windows, where it is of +type `SOCKET`. + +NOTE: The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. + +`NN_SNDFD`:: +This option returns a file descriptor suitable for use in with `poll()` or +`select()` (or other system-specific polling functions). +This descriptor will be readable when the socket is able to accept a message +for sending. +This option is of type `int` on all systems except Windows, where it is of +type `SOCKET`. + +NOTE: The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. +Furthermore, the file descriptor should only be polled for _readability_. + +The following option is available for `NN_REQ` sockets +using the `NN_REQ` level: + +`NN_REQ_RESEND_IVL`:: +Request retry interval in milliseconds. +If an `NN_REQ` socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute). + +The following option is available for `NN_SURVEYOR` sockets +using the `NN_SURVEYOR` level: + +`NN_SURVEYOR_DEADLINE`:: +Survey deadline in milliseconds for `NN_SURVEYOR` sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded. + +In addition, the following transport specific options are offered: + +`NN_IPC_SEC_ATTR`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_OUTBUFSZ`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_INBUFSZE`:: +This `NN_IPC` option is not supported at this time. + +`NN_TCP_NODELAY`:: +This `NN_TCP` option is not supported at this time. + +`NN_WS_MSG_TYPE`:: +This `NN_WS` option is not supported, as _NNG_ only supports binary messages +in this implementation. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not an open socket. +`ENOMEM`:: Insufficient memory is available. +`ENOPROTOOPT`:: The level and/or option is invalid. +`EINVAL`:: The option, or the value passed, is invalid. +`ETERM`:: The library is shutting down. +`EACCES`:: The option cannot be changed. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_poll.3compat.adoc b/external/nng/docs/man/nn_poll.3compat.adoc new file mode 100644 index 0000000..c115fe4 --- /dev/null +++ b/external/nng/docs/man/nn_poll.3compat.adoc @@ -0,0 +1,102 @@ += nn_poll(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_poll - poll sockets (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +#define NN_POLLIN 1 +#define NN_POLLOUT 2 + +struct nn_pollfd { + int fd; + uint16_t events; + uint16_t revents; +}; + +int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout); +---- + +== DESCRIPTION + +The `nn_poll()` function polls a group of sockets for readiness to send or receive. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The array of _nfds_ sockets to poll for are passed into _pfds_. +Each member of this array is initialized with the `fd` field set to +the socket, and the `events` field set to a mask that can contain either or both +of the flags `NN_POLLIN` and `NN_POLLOUT`. + +The flag `NN_POLLIN` indicates that a socket is ready for receiving without +blocking (a message is available on the socket), and the flag `NN_POLLOUT` +indicates that a socket is ready for sending without blocking. + +Upon success, the function returns the number of updates the `revents` +field of each member of the _pfds_ array, setting it to indicate +whether the requested status is true or not. + +NOTE: The `revents` field will only have a flag set if the corresponding +flag was also set in the `events` field. + +If the _timeout_ field is positive, then this function will wait for +up the that many milliseconds. +If none of the requested events occurs before that timeout occurs, then +the function will return -1 and set the error to `ETIMEDOUT`. + +If the _timeout_ is zero, then this function will return immediately, +after updating the current status of the sockets. + +If the _timeout_ is -1, then the function waits forever, or until one of the +requested events occurs. + +IMPORTANT: This function is only suitable for use with sockets obtained with the +xref:nn_socket.3compat.adoc[`nn_socket()`] function, and is not compatible +with file descriptors obtained via any other means. +This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD` +options with xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`] + +NOTE: This function is significantly less efficient than other polling +or asynchronous I/O mechanisms, and is provided for API compatibility only. +It's use is discouraged. + +NOTE: This function is *not* supported on systems other than POSIX derived +platforms and Windows. + +== RETURN VALUES + +This function returns the number of sockets with events on success, or -1 on error. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory available. +`EBADF`:: One of the sockets is not open. +`ETIMEDOUT`:: Operation timed out. +`ENOTSUP`:: This function is not supported on this platform. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_reallocmsg.3compat.adoc b/external/nng/docs/man/nn_reallocmsg.3compat.adoc new file mode 100644 index 0000000..d48b5d4 --- /dev/null +++ b/external/nng/docs/man/nn_reallocmsg.3compat.adoc @@ -0,0 +1,59 @@ += nn_reallocmsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_reallocmsg - reallocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +void *nn_reallocmsg(void *old, size_t size); +---- + +== DESCRIPTION + +The `nn_reallocmsg()` reallocates the message _old_, making it of size _size_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +On success, the contents of _old_ are copied into the new message +(truncating if appropriate), then _old_ is deallocated, and a pointer +to the new message payload is returned. + +On failure, the _old_ message is unchanged, and the value `NULL` is returned +to the caller. + +== RETURN VALUES + +This function returns a pointer to message buffer space, or `NULL` +on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`EINVAL`:: An invalid _size_ was specified. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_recv.3compat.adoc b/external/nng/docs/man/nn_recv.3compat.adoc new file mode 100644 index 0000000..2a71714 --- /dev/null +++ b/external/nng/docs/man/nn_recv.3compat.adoc @@ -0,0 +1,75 @@ += nn_recv(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_recv - receive data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_recv(int sock, void *data, size_t size, int flags) +---- + +== DESCRIPTION + +The `nn_recv()` function receives a message from the socket _sock_. +The message body must fit within _size_ bytes, and will be stored +at the location specified by _data_, unless _size_ is the +special value `NN_MSG`, indicating a zero-copy operation. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +If _size_ has the special value `NN_MSG`, then a zero-copy operation +is performed. +In this case, instead of copying the message data into the address +specified by _data_, a new message large enough to hold the message data +will be allocated (as if by the +function xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), and the message +payload will be stored accordingly. +In this case, the value stored at _data_ will not be message data, +but a pointer to the message itself. +In this case, on success, the caller shall take responsibility for +the final disposition of the message (such as by sending it to +another peer using xref:nn_send.3compat.adoc[`nn_send()`]) or +xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the no message is available for immediate receipt, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot receive in this state. +`ENOTSUP`:: This protocol cannot receive. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_recvmsg.3compat.adoc b/external/nng/docs/man/nn_recvmsg.3compat.adoc new file mode 100644 index 0000000..e0fcc75 --- /dev/null +++ b/external/nng/docs/man/nn_recvmsg.3compat.adoc @@ -0,0 +1,99 @@ += nn_recvmsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_recvmsg - receive message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_recvmsg(int sock, struct nn_msghdr *hdr, int flags); +---- + +== DESCRIPTION + +The `nn_recvmsg()` function receives a message into the header described by +_hdr_ using the socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if no message is ready for receiving on _sock_, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +The _hdr_ points to a structure of type `struct nn_msghdr`, which has the +following definition: + +[source, c] +---- +struct nn_iovec { + void * iov_base; + size_t iov_len; +}; + +struct nn_msghdr { + struct nn_iovec *msg_iov; + int msg_iovlen; + void * msg_control; + size_t msg_controllen; +}; +---- + +The `msg_iov` is an array of scatter items, permitting the message +to be spread into different memory blocks. +There are `msg_iovlen` elements in this array, each of which +has the base address (`iov_base`) and length (`iov_len`) indicated. + +The last member of this array may have the `iov_len` field set to `NN_MSG`, +in which case the function shall allocate a message buffer, and store the +pointer to it at the address indicated by `iov_base`. +This can help save an extra copy operation. +The buffer should be deallocated by xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] +or similar when it is no longer needed. + +The values of `msg_control` and `msg_controllen` describe a buffer +of ancillary data associated with the message. +This is currently only useful to obtain the message headers +used with xref:nng.7.adoc#raw_mode[raw mode] sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. + +== RETURN VALUES + +This function returns the number of bytes received on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot receive in this state. +`EINVAL`:: The _hdr_ is invalid. +`ENOTSUP`:: This protocol cannot receive. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_send.3compat.adoc b/external/nng/docs/man/nn_send.3compat.adoc new file mode 100644 index 0000000..050bea1 --- /dev/null +++ b/external/nng/docs/man/nn_send.3compat.adoc @@ -0,0 +1,74 @@ += nn_send(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_send - send data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_send(int sock, const void *data, size_t size, int flags) +---- + +== DESCRIPTION + +The `nn_send()` function creates a message containing _data_ (of size _size_), +and sends using the socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +If _size_ has the special value `NN_MSG`, then a zero-copy operation +is performed. +In this case, _data_ points not to the message content itself, but instead +is a pointer to the pointer, an extra level of pointer indirection. +The message must have been previously allocated by +xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or +xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]`, using the same `NN_MSG` size. +In this case, the ownership of the message shall remain with +the caller, unless the function returns 0, indicating that the +function has taken responsibility for delivering or disposing of the +message. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +NOTE: The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot send in this state. +`ENOTSUP`:: This protocol cannot send. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_sendmsg.3compat.adoc b/external/nng/docs/man/nn_sendmsg.3compat.adoc new file mode 100644 index 0000000..b339bfe --- /dev/null +++ b/external/nng/docs/man/nn_sendmsg.3compat.adoc @@ -0,0 +1,107 @@ += nn_sendmsg(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_sendmsg - send message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_sendmsg(int sock, const struct nn_msghdr *hdr, int flags); +---- + +== DESCRIPTION + +The `nn_sendmsg()` function sends the message described by _hdr_ using the +socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +The _hdr_ points to a structure of type `struct nn_msghdr`, which has the +following definition: + +[source, c] +---- +struct nn_iovec { + void * iov_base; + size_t iov_len; +}; + +struct nn_msghdr { + struct nn_iovec *msg_iov; + int msg_iovlen; + void * msg_control; + size_t msg_controllen; +}; +---- + +The `msg_iov` is an array of gather items, permitting the message +to be spread into different memory blocks. +There are `msg_iovlen` elements in this array, each of which +has the base address (`iov_base`) and length (`iov_len`) indicated. + +For buffers allocated for zero copy +(such as by xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), the value +of `iov_base` should be the address of the pointer to the buffer, +rather than the address of the buffer itself. +In this case, the value of `iov_len` should be `NN_MSG`, +as the length is inferred from the allocated message. +If the `msg_iovlen` field is `NN_MSG`, then this function will free +the associated buffer after it is done with it, if it returns successfully. +(If the function returns with an error, then the caller retains ownership +of the associated buffer and may retry the operation or free the buffer +at its choice.) + +The values of `msg_control` and `msg_controllen` describe a buffer +of ancillary data to send the message. +This is currently only useful to provide the message headers +used with xref:nng.7.adoc#raw_mode[raw mode] sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. + +NOTE: The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot send in this state. +`EINVAL`:: The _hdr_ is invalid. +`ENOTSUP`:: This protocol cannot send. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_setsockopt.3compat.adoc b/external/nng/docs/man/nn_setsockopt.3compat.adoc new file mode 100644 index 0000000..860d522 --- /dev/null +++ b/external/nng/docs/man/nn_setsockopt.3compat.adoc @@ -0,0 +1,205 @@ += nn_setsockopt(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_setsockopt - set socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz); +---- + +== DESCRIPTION + +The `nn_setsockopt()` function sets a socket option on socket _sock_, +affecting the behavior of the socket. +The option set is determined by the _level_ and _option_. +The value of the option is set by _val_, and _sz_, which are pointers to +the actual value and the size of the value, respectively. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _level_ determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows: + +[horizontal] +`NN_SOL_SOCKET`:: Generic socket option +`NN_IPC`:: Transport specific option for IPC. +`NN_TCP`:: Transport specific option for TCP. +`NN_WS`:: Transport specific option for WebSocket. + +The following generic socket options are possible (all are of type `int` and +thus size 4, unless otherwise indicated.) + +`NN_SNDBUF`:: +Send buffer size in bytes. + +NOTE: In _NNG_ buffers are sized as a count of messages rather than +bytes, and so an attempt to estimate a conversion based upon a predetermined +message size of 1kB is made. +The value supplied is rounded up to the nearest value divisible by 1024, and +then divided by 1024 to convert to a message count. +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. + +`NN_RCVBUF`:: +Receive buffer size in bytes. + +NOTE: The same caveats for `NN_SNDBUF` apply here as well. + +`NN_SNDTIMEO`:: +Send time-out in milliseconds. +Send operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVTIMEO`:: +Receive time-out in milliseconds. +Receive operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVMAXSIZE`:: +Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit. + +`NN_RECONNECT_IVL`:: +Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100. + +`NN_RECONNECT_IVL_MAX`:: +Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by `NN_RECONNECT_IVL`. +The default is zero. + +`NN_LINGER`:: +This option is ignored, and exists only for compatibility. + +NOTE: This option was unreliable in early releases of _libnanomsg_, and +is unsupported in _NNG_ and recent _libnanomsg_ releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the `NN_REQ` protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. + +`NN_SNDPRIO`:: +This option is not implemented at this time. + +`NN_RCVPRIO`:: +This option is not implemented at this time. + +`NN_IPV4ONLY`:: +This option is not implemented at this time. + +`NN_SOCKET_NAME`:: +This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes. + +`NN_MAXTTL`:: +Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +xref:nng_device.3.adoc[device] chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +The following option is available for `NN_REQ` sockets +using the `NN_REQ` level: + +`NN_REQ_RESEND_IVL`:: +Request retry interval in milliseconds. +If an `NN_REQ` socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute). + +The following options are available for `NN_SUB` sockets using the `NN_SUB` level: + +`NN_SUB_SUBSCRIBE`:: +Subscription topic, for `NN_SUB` sockets. +This sets a subscription topic. +When a message from a publisher arrives, it is compared against all +subscriptions. +If the first _sz_ bytes of the message are not identical to _val_, +then the message is silently discarded. + +TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero). + +`NN_SUB_UNSUBSCRIBE`:: +Removes a subscription topic that was earlier established. + +The following option is available for `NN_SURVEYOR` sockets +using the `NN_SURVEYOR` level: + +`NN_SURVEYOR_DEADLINE`:: +Survey deadline in milliseconds for `NN_SURVEYOR` sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded. + +In addition, the following transport specific options are offered: + +`NN_IPC_SEC_ATTR`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_OUTBUFSZ`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_INBUFSZE`:: +This `NN_IPC` option is not supported at this time. + +`NN_TCP_NODELAY`:: +This `NN_TCP` option is not supported at this time. + +`NN_WS_MSG_TYPE`:: +This `NN_WS` option is not supported at this time. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not an open socket. +`ENOMEM`:: Insufficient memory is available. +`ENOPROTOOPT`:: The level and/or option is invalid. +`EINVAL`:: The option, or the value passed, is invalid. +`ETERM`:: The library is shutting down. +`EACCES`:: The option cannot be changed. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_shutdown.3compat.adoc b/external/nng/docs/man/nn_shutdown.3compat.adoc new file mode 100644 index 0000000..06a5cd5 --- /dev/null +++ b/external/nng/docs/man/nn_shutdown.3compat.adoc @@ -0,0 +1,55 @@ += nn_shutdown(3compat) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_shutdown - shut down endpoint (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +int nn_shutdown(int sock, int ep) +---- + +== DESCRIPTION + +The `nn_shutdown()` shuts down the endpoint _ep_, which is either a listener or +a dialer) on the socket _sock_. +This will stop the socket from either accepting new connections, or establishing +old ones. +Additionally, any established connections associated with _ep_ will be closed. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns zero on success, and -1 on error. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _ep_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_bind.3compat.adoc[nn_bind(3compat)], +xref:nn_connect.3compat.adoc[nn_connect(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_socket.3compat.adoc b/external/nng/docs/man/nn_socket.3compat.adoc new file mode 100644 index 0000000..c4bbb70 --- /dev/null +++ b/external/nng/docs/man/nn_socket.3compat.adoc @@ -0,0 +1,78 @@ += nn_socket(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_socket - create socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +int nn_socket(int af, int proto); +---- + +== DESCRIPTION + +The `nn_socket()` function creates socket using the address family _af_ and +protocol _proto_ and returns it. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: Mixing the compatibility API and the modern API is not supported +on a given socket. + +NOTE: Some protocols, transports, and features are only available in the modern API. + +The address family _af_ can be one of two values: + +[horizontal] +`AF_SP`:: Normal socket. +`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode[Raw mode] socket. + +The protocol indicates the protocol to be used when creating the socket. +The following protocols are defined: + +[horizontal] +`NN_PAIR`:: xref:nng_pair.7.adoc[Pair] protocol. +`NN_PUB`:: xref:nng_pub.7.adoc[Publisher] protocol. +`NN_SUB`:: xref:nng_sub.7.adoc[Subscriber] protocol. +`NN_REQ`:: xref:nng_req.7.adoc[Requestor] protocol. +`NN_REP`:: xref:nng_rep.7.adoc[Replier] protocol. +`NN_PUSH`:: xref:nng_push.7.adoc[Push] protocol. +`NN_PULL`:: xref:nng_pull.7.adoc[Pull] protocol. +`NN_SURVEYOR`:: xref:nng_surveyor.7.adoc[Surveyor] protocol. +`NN_RESPONDENT`:: xref:nng_respondent.7.adoc[Respondent] protocol. +`NN_BUS`:: xref:nng_bus.7.adoc[Bus] protocol. + +== RETURN VALUES + +This function returns a valid socket number on success, and -1 on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`ENOTSUP`:: The protocol is not supported. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_strerror.3compat.adoc b/external/nng/docs/man/nn_strerror.3compat.adoc new file mode 100644 index 0000000..3fc2dc2 --- /dev/null +++ b/external/nng/docs/man/nn_strerror.3compat.adoc @@ -0,0 +1,47 @@ += nn_strerror(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_strerror - return message for error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +const char *nn_strerror(int err); +---- + +== DESCRIPTION + +The `nn_strerror()` function returns a human readable message corresponding +to the given error number _err_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns the message corresponding to _err_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nn_term.3compat.adoc b/external/nng/docs/man/nn_term.3compat.adoc new file mode 100644 index 0000000..79b6a1e --- /dev/null +++ b/external/nng/docs/man/nn_term.3compat.adoc @@ -0,0 +1,59 @@ += nn_term(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +nn_term - terminate library (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +void nn_term(void); +---- + +== DESCRIPTION + +The `nn_term()` function closes any open sockets, and frees all resources +allocated by the library. +Any operations that are currently in progress will be terminated, and will +fail with error `EBADF` or `ETERM`. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: This function is not thread-safe, and is not suitable for use +in library calls. +The intended purpose of this is to clean up at application termination; for +example by registering this function with `atexit()`. +This can help prevent false leak reports caused when memory checkers notice +global resources allocated by the library. +Libraries should never use this function, but should explicitly close their +own sockets directly. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng.7.adoc b/external/nng/docs/man/nng.7.adoc new file mode 100644 index 0000000..c0e1a64 --- /dev/null +++ b/external/nng/docs/man/nng.7.adoc @@ -0,0 +1,195 @@ += nng(7) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 - nanomsg next generation + +== SYNOPSIS + +*cc* ['flags'] 'files' *-lnng* ['libraries'] + +== DESCRIPTION + +_NNG_ provides a common messaging framework intended to +solve common communication problems in distributed applications. +It offers a number of _protocols_, and also a number of _transports_. + +The _protocols_ implement the semantics associated with particular +communications scenarios, such as RPC style services, service discovery, +publish/subscribe, and so forth. + +The _transports_ provide support for underlying transport methods, such +as TCP, IPC, websockets, and so forth. + +_NNG_ is designed to permit easy creation of new _transports_ and, +to a lesser extent, new _protocols_. + +_NNG_ is wire compatible with the SP protocols described in +the nanomsg project; projects using +https://github.com/nanomsg/nanomsg[_libnanomsg_] can inter-operate with +nng as well as other conforming implementations. (One such implementation +is https://github.com/go-mangos/mangos[_mangos_].) +Applications using _NNG_ +which wish to communicate with other libraries must ensure that they only +use protocols or transports offered by the other library. + +_NNG_ also offers a compatible API, permitting legacy code to +be recompiled or relinked against _NNG_. When doing this, support for +certain enhancements or features will likely be absent, requiring the +application developer to use the new-style API. + +_NNG_ is implemented in pure C; if you need bindings for +other languages please check the http://nanomsg.org/[website]. + +=== Protocols + +[horizontal] +xref:nng_bus.7.adoc[nng_bus(7)]:: Bus protocol +xref:nng_pair.7.adoc[nng_pair(7)]:: Pair protocol +xref:nng_pub.7.adoc[nng_pub(7)]:: Publisher side of publish/subscribe protocol +xref:nng_pull.7.adoc[nng_pull(7)]:: Pull side of pipeline protocol +xref:nng_push.7.adoc[nng_push(7)]:: Push side of pipeline protocol +xref:nng_sub.7.adoc[nng_sub(7)]:: Subscriber side of publish/subscribe protocol +xref:nng_rep.7.adoc[nng_rep(7)]:: Reply side of request/reply protocol +xref:nng_req.7.adoc[nng_req(7)]:: Request side of request/reply protocol +xref:nng_respondent.7.adoc[nng_respondent(7)]:: Respondent side of survey protocol +xref:nng_surveyor.7.adoc[nng_surveyor(7)]:: Surveyor side of survey protocol + +=== Transports + +[horizontal] +xref:nng_inproc.7.adoc[nng_inproc(7)]:: Intra-process transport +xref:nng_ipc.7.adoc[nng_ipc(7)]:: Inter-process transport +xref:nng_socket.7.adoc[nng_socket(7)]:: BSD socket transport +xref:nng_tls.7.adoc[nng_tls(7)]:: TLSv1.2 over TCP transport +xref:nng_tcp.7.adoc[nng_tcp(7)]:: TCP (and TCPv6) transport +xref:nng_ws.7.adoc[nng_ws(7)]:: WebSocket transport +xref:nng_zerotier.7.adoc[nng_zerotier(7)]:: ZeroTier transport + +=== Conceptual Overview + +_NNG_ presents a _socket_ view of networking. +The sockets are constructed using protocol-specific functions, as a given +socket implements precisely one protocol. + +Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. +For example, xref:nng_sub.7.adoc[_sub_] sockets automatically filter incoming +messages to discard those for topics that have not been subscribed. + +_NNG_ sockets are message oriented, so that messages are either delivered +wholly, or not at all. Partial delivery is not possible. +Furthermore, _NNG_ does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered +(Some protocols, such as xref:nng_req.7.adoc[_req_] may offer stronger +guarantees by performing their own retry and validation schemes.) + +Each socket can have zero, one, or many endpoints, which are either +_listeners_ or _dialers_. +(A given socket may freely choose whether it uses listeners, dialers, or both.) +These endpoints provide access to underlying transports, such as TCP, etc. + +Each endpoint is associated with a URL, which is a service address. +For dialers, this will be the service address that will be contacted, whereas +for listeners this is where the listener will accept new connections. + +Endpoints do not themselves transport data. +They are instead responsible for the creation of _pipes_, which can be +thought of as message-oriented connected streams. +Pipes frequently correspond to a single underlying byte stream. +For example both IPC and TCP transports implement their +pipes using a 1:1 relationship with a connected operating system socket. + +Endpoints create pipes as needed. +Listeners will create them when a new client connection request arrives, +and dialers will generally create one, then wait for it to disconnect before +reconnecting. + +Most applications should not have to worry about endpoints or pipes at +all; the socket abstraction should provide all the functionality needed +other than in a few specific circumstances. + +[[raw_mode]] +==== Raw Mode + +(((cooked mode)))(((raw mode))) +Most applications will use sockets in normal, or _cooked_, mode. +This mode provides the full semantics of the protocol. +For example, xref:nng_req.7.adoc[_req_] sockets will automatically +match a reply to a request, and resend requests periodically if no reply +was received. + +There are situations, such as with xref:nng_device.3.adoc[proxies], +where it is desirable to bypass these semantics and simply pass messages +to and from the socket with no extra semantic handling. +This is possible using _raw_ mode sockets. + +Raw mode sockets are generally constructed with a different function, +such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`]. +Using these sockets, the application can simply send and receive messages, +and is responsible for supplying any additional socket semantics. +Typically this means that the application will need to inspect message +headers on incoming messages, and supply them on outgoing messages. + +TIP: The xref:nng_device.3.adoc[`nng_device()`] function only works with raw mode +sockets, but as it only forwards the messages, no additional application +processing is needed. + +==== URLs + +(((URL))) +_NNG_ uses ((universal resource locators)) (URLs) +following the format specified in +https://tools.ietf.org/html/rfc3986[RFC 3986], +including some schemes that are unique +to SP. +(((URL, canonicalized))) +The URLs used in _NNG_ are canonicalized as follows, mostly in +accordance with +https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: + + . The URL is parsed into scheme, userinfo, host, port, path, query and + fragment components. (Not all of these members are necessarily present.) + . The scheme, hostname, and port if present, are converted to lower case. + . Percent-encoded values for + https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] + converted to their unencoded forms. + . Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded. + . The resulting path is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid. + . Path segments consisting of `.` and `..` are resolved as per + https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. + . Further, empty path segments are removed, meaning that duplicate + slash (`/`) separators are removed from the path. + +Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of +applications, without violating RFC 3986 itself. + +TIP: Port numbers may be service names in some instances, but it is recommended +that numeric port numbers be used when known. +If service names are used, it is recommended that they follow the naming +conventions for C identifiers, and not be longer than 32 characters in length. +This will maximize compatibility across systems and minimize opportunities for +confusion when they are parsed on different systems. + +=== API + +The library API is documented at xref:libnng.3.adoc[libnng(3)]. + +== SEE ALSO + +[.text-left] +xref:libnng.3.adoc[libnng(3)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)] diff --git a/external/nng/docs/man/nng_aio.5.adoc b/external/nng/docs/man/nng_aio.5.adoc new file mode 100644 index 0000000..d2b1032 --- /dev/null +++ b/external/nng/docs/man/nng_aio.5.adoc @@ -0,0 +1,70 @@ += nng_aio(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio - asynchronous I/O handle + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_aio nng_aio; +---- + +== DESCRIPTION + +An `nng_aio`(((aio))) is an opaque structure used in conjunction with +((asynchronous I/O)) operations. +Every asynchronous operation uses one of these structures, each of which +can only be used with a single operation at a time. + +Asynchronous operations are performed without blocking calling application +threads. +Instead the application registers a callback function to be executed +when the operation is complete (whether successfully or not). +This callback will be executed exactly once. + +The asynchronous I/O framework also supports cancellation of +operations that are already in progress +(see xref:nng_aio_cancel.3.adoc[`nng_aio_cancel()`]), as well setting a maximum +timeout for them to complete within +(see xref:nng_aio_set_timeout.3.adoc[`nng_aio_set_timeout()`]). + +It is also possible to initiate an asynchronous operation, and wait for it to +complete using xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. + +These structures are created using the xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`], +and destroyed using xref:nng_aio_free.3.adoc[`nng_aio_free()`]. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_free.3.adoc[nng_aio_free(3)], +xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)], +xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_abort.3.adoc b/external/nng/docs/man/nng_aio_abort.3.adoc new file mode 100644 index 0000000..8d4e904 --- /dev/null +++ b/external/nng/docs/man/nng_aio_abort.3.adoc @@ -0,0 +1,55 @@ += nng_aio_abort(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_abort - abort asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_abort(nng_aio *aio, int err); +---- + +== DESCRIPTION + +The `nng_aio_abort()` function aborts an operation previously started +with the handle _aio_. +If the operation is aborted, then the callback +for the handle will be called, and the function +xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return the error _err_. + +This function does not wait for the operation to be fully aborted, but +returns immediately. + +If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_alloc.3.adoc b/external/nng/docs/man/nng_aio_alloc.3.adoc new file mode 100644 index 0000000..6a424e3 --- /dev/null +++ b/external/nng/docs/man/nng_aio_alloc.3.adoc @@ -0,0 +1,88 @@ += nng_aio_alloc(3) +// +// Copyright 2022 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_alloc - allocate asynchronous I/O handle + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); +---- + +== DESCRIPTION + +The `nng_aio_alloc()` function allocates a handle for ((asynchronous I/O)) +operations, and stores a pointer to it in __aiop__. +The handle is initialized with a completion ((callback)) of _callb_, +which will be executed when an associated asynchronous operation finishes. +It will be called with the argument _arg_. + +NOTE: The callback _callb_ must not perform any blocking operations, and +must complete its execution quickly. If _callb_ does block, this can +lead ultimately to an apparent "hang" or deadlock in the application. +This also means you should avoid operations such as allocating new objects, +which also means opening or closing sockets, dialers, and so forth. + +TIP: If more complex or blocking work needs to be performed by _callb_, a separate +thread can be used, along with a xref:nng_cv_alloc.3supp.adoc[condition variable] +which can be signaled by the callback. + +Asynchronous I/O operations all take an xref:nng_aio.5.adoc[`nng_aio`] +handle such as allocated by this function. +Such operations are usually started by a function that returns immediately. +The operation is then run asynchronously, and completes sometime later. +When that operation is complete, the callback supplied here is called, +and that callback is able to determine the result of the operation using +xref:nng_aio_result.3.adoc[`nng_aio_result()`], +xref:nng_aio_count.3.adoc[`nng_aio_count()`], +and xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. + +It is possible to wait synchronously for an otherwise asynchronous operation +by using the function xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. +In that case, it is permissible for _callb_ and _arg_ to both be `NULL`. +Note that if these are `NULL`, then it will not be possible to determine when the +operation is complete except by calling the aforementioned +xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_free.3.adoc[nng_aio_free(3)], +xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)], +xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_begin.3.adoc b/external/nng/docs/man/nng_aio_begin.3.adoc new file mode 100644 index 0000000..30a7364 --- /dev/null +++ b/external/nng/docs/man/nng_aio_begin.3.adoc @@ -0,0 +1,64 @@ += nng_aio_begin(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_begin - begin asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +bool nng_aio_begin(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_begin()` function is called by the I/O provider to indicate that +it is going to process the operation. + +The function may return `false`, indicating that the _aio_ has been closed +by the caller asynchronously. +In this case the provider should abandon the operation and do nothing else. + +This operation should be called at the start of any I/O operation, and must +be called not more than once for a given I/O operation on a given _aio_. + +Once this function is called, if `true` is returned, then the provider MUST +guarantee that xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called for the _aio_ +exactly once, when the operation is complete or canceled. + +NOTE: This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the _aio_ should not call this function. + +== RETURN VALUES + +[horizontal] +`true`:: The operation has been started. +`false`:: The operation cannot be started. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], +xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_busy.3.adoc b/external/nng/docs/man/nng_aio_busy.3.adoc new file mode 100644 index 0000000..4aaf09b --- /dev/null +++ b/external/nng/docs/man/nng_aio_busy.3.adoc @@ -0,0 +1,56 @@ += nng_aio_busy(3) +// +// Copyright 2022 Staysail Systems, Inc. +// +// 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_aio_busy - test if asynchronous I/O is busy + +== SYNOPSIS + +[source, c] +---- +#include + +bool nng_aio_busy(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_busy()` function returns true if the +_aio_ is currently busy performing an asynchronous I/O +operation or is executing a completion callback. + +If no operation has been started, or the operation has +been completed or canceled, and any callback has been +executed, then it returns false. + +This is the same test used internally by +xref:nng_aio_wait.3.adoc[`nng_aio_wait()`] + +NOTE: Care should be taken to ensure that the _aio_ object is not +freed when using this function. The caller is responsible for +coordinating any use of this with any reuse of the _aio_. + +== RETURN VALUES + +True if the _aio_ is busy, false otherwise. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_cancel.3.adoc b/external/nng/docs/man/nng_aio_cancel.3.adoc new file mode 100644 index 0000000..3b32c82 --- /dev/null +++ b/external/nng/docs/man/nng_aio_cancel.3.adoc @@ -0,0 +1,58 @@ += nng_aio_cancel(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_cancel - cancel asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_cancel(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_cancel()` function aborts an operation previously started +with the handle _aio_. +If the operation is aborted, then the callback +for the handle will be called, and the function +xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return the error `NNG_ECANCELED`. + +This function does not wait for the operation to be fully aborted, but +returns immediately. + +If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect. + +NOTE: This function is the same as calling +xref:nng_aio_abort.3.adoc[`nng_aio_abort()`] with the error `NNG_ECANCELED`. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_count.3.adoc b/external/nng/docs/man/nng_aio_count.3.adoc new file mode 100644 index 0000000..daf9771 --- /dev/null +++ b/external/nng/docs/man/nng_aio_count.3.adoc @@ -0,0 +1,61 @@ += nng_aio_count(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_count - return number of bytes transferred + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_aio_count(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_count()` returns the number of bytes transferred by the +asynchronous operation associated with the handle _aio_. + +Some asynchronous operations do not provide meaningful data for this +function; for example operations that establish connections do not +transfer user data (they may transfer protocol data though) -- in this case +this function will generally return zero. + +This function is most useful when used with operations that make use of +of a scatter/gather vector (set by xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`]). + +NOTE: The return value from this function is undefined if the operation +has not completed yet. +Either call this from the handle's completion callback, +or after waiting for the operation to complete with +xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. + +== RETURN VALUES + +The number of bytes transferred by the operation. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_defer.3.adoc b/external/nng/docs/man/nng_aio_defer.3.adoc new file mode 100644 index 0000000..5664a6d --- /dev/null +++ b/external/nng/docs/man/nng_aio_defer.3.adoc @@ -0,0 +1,78 @@ += nng_aio_defer(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_defer - defer asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err); + +void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg); +---- + +== DESCRIPTION + +The `nng_aio_defer()` function marks operation associated with _aio_ as +being deferred for asynchronous completion, and also registers a cancellation +function _fn_ and associated argument _arg_, thereby +permitting the operation to be canceled. + +If the _aio_ is being canceled, the cancellation routine _fn_ will be called +with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error +value in _err_, which is the reason that the operation is being canceled. + +The operation may not be cancelable; for example it may have already been +completed, or be in a state where it is no longer possible to unschedule it. +In this case, the _cancelfn_ should just return without making any changes. + +If the cancellation routine successfully canceled the operation, it should +ensure that xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called, with the +error code specified by _err_. + +IMPORTANT: It is mandatory that I/O providers call +xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] +*EXACTLY ONCE* when they are finished with the operation. + +NOTE: This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the _aio_ should not call this function. + +NOTE: Care must be taken to ensure that cancellation and completion of +the routine are multi-thread safe; this will usually involve the use +of locks or other synchronization primitives. + +TIP: For operations that complete synchronously, without any need to be +deferred, the provider should not bother to call `nng_aio_defer()`, +although it is harmless if it does. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_finish.3.adoc b/external/nng/docs/man/nng_aio_finish.3.adoc new file mode 100644 index 0000000..91ad188 --- /dev/null +++ b/external/nng/docs/man/nng_aio_finish.3.adoc @@ -0,0 +1,60 @@ += nng_aio_finish(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_finish - finish asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_finish(nng_aio *aio, int err); +---- + +== DESCRIPTION + +The `nng_aio_finish()` function marks operation associated with _aio_ as +complete, with the status _err_. +This will be the result returned by +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. + +This function causes the callback associated with the _aio_ to called. + +IMPORTANT: It is mandatory that operation providers call this function +*exactly once* when they are finished with the operation. +After calling this function they *must not* perform any further accesses +to the _aio_. + +NOTE: This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the _aio_ should not have any need for this function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_begin.3.adoc[nng_aio_begin(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_free.3.adoc b/external/nng/docs/man/nng_aio_free.3.adoc new file mode 100644 index 0000000..c252863 --- /dev/null +++ b/external/nng/docs/man/nng_aio_free.3.adoc @@ -0,0 +1,54 @@ += nng_aio_free(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_free - free asynchronous I/O handle + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_free(nng_aio *aio); +void nng_aio_reap(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_free()` function frees an allocated asynchronous I/O handle. +If any operation is in progress, the operation is canceled, and the +caller is blocked until the operation is completely canceled, to ensure +that it is safe to deallocate the handle and any associated resources. +(This is done by implicitly calling xref:nng_aio_stop.3.adoc[`nng_aio_stop()`].) + +The `nng_aio_reap()` function is the same as `nng_aio_free()`, but does +its work in a background thread. +This can be useful to discard the _aio_ object from within the callback for the _aio_. + +IMPORTANT: Once either of these functions are called, the _aio_ object is invalid and must not be used again. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_get_input.3.adoc b/external/nng/docs/man/nng_aio_get_input.3.adoc new file mode 100644 index 0000000..204ec43 --- /dev/null +++ b/external/nng/docs/man/nng_aio_get_input.3.adoc @@ -0,0 +1,53 @@ += nng_aio_get_input(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_get_input - return input parameter + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_aio_get_input(nng_aio *aio, unsigned int index); +---- + +== DESCRIPTION + +The `nng_aio_get_input()` function returns the value of the input parameter +previously set at _index_ on _aio_ with the +xref:nng_aio_set_input.3.adoc[`nng_aio_set_input()`] function. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +(This limit could increase in the future.) +If the index supplied is outside of this range, +or of the input parameter was not previously set, then `NULL` is returned. + +== RETURN VALUES + +Value previously set, or `NULL`. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_get_msg.3.adoc b/external/nng/docs/man/nng_aio_get_msg.3.adoc new file mode 100644 index 0000000..c420565 --- /dev/null +++ b/external/nng/docs/man/nng_aio_get_msg.3.adoc @@ -0,0 +1,49 @@ += nng_aio_get_msg(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_get_msg - get message from asynchronous receive + +== SYNOPSIS + +[source, c] +---- +#include + +nng_msg *nng_aio_get_msg(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_get_msg()` function gets any message stored in _aio_ as +either a result of a successful receive +(see xref:nng_recv_aio.3.adoc[`nng_recv_aio()`]) +or that was previously stored with xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`]. + +IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_recv_aio.3.adoc[nng_recv_aio(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_get_output.3.adoc b/external/nng/docs/man/nng_aio_get_output.3.adoc new file mode 100644 index 0000000..4dfd67c --- /dev/null +++ b/external/nng/docs/man/nng_aio_get_output.3.adoc @@ -0,0 +1,56 @@ += nng_aio_get_output(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_get_output - return output result + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_aio_get_output(nng_aio *aio, unsigned int index); +---- + +== DESCRIPTION + +The `nng_aio_get_output()` function returns the output result at _index_ +resulting from the asynchronous operation associated with _aio_. + +The type and semantics of output parameters are determined by specific +operations. + +NOTE: If the _index_ does not correspond to a defined output for the operation, +or the operation did not succeed, then the return value will be `NULL`. + +IMPORTANT: It is an error to call this function while the _aio_ is currently +in use by an active asynchronous operation, or if no operation has been +performed using the _aio_ yet. + +== RETURN VALUES + +The __index__th result of the operation, or `NULL`. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_result.3.adoc b/external/nng/docs/man/nng_aio_result.3.adoc new file mode 100644 index 0000000..e1886a6 --- /dev/null +++ b/external/nng/docs/man/nng_aio_result.3.adoc @@ -0,0 +1,59 @@ += nng_aio_result(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_result - return result of asynchronous operation + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_aio_result(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_result()` returns the result of the operation associated +with the handle _aio_. +If the operation was successful, then 0 is returned. +Otherwise a non-zero error code is returned. + +NOTE: The return value from this function is undefined if the operation +has not completed yet. +Either call this from the handle's completion +callback, or after waiting for the operation to complete with +xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. + +== RETURN VALUES + +The result of the operation, either zero on success, or an error +number on failure. + +== ERRORS + +[horizontal] +`NNG_ETIMEDOUT`:: The operation timed out. +`NNG_ECANCELED`:: The operation was canceled. + +Various other return values are possible depending on the operation. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_set_input.3.adoc b/external/nng/docs/man/nng_aio_set_input.3.adoc new file mode 100644 index 0000000..37cf3cd --- /dev/null +++ b/external/nng/docs/man/nng_aio_set_input.3.adoc @@ -0,0 +1,63 @@ += nng_aio_set_input(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_set_input - set input parameter + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); +---- + +== DESCRIPTION + +The `nng_aio_set_input()` function sets the input parameter at _index_ +to _param_ for the asynchronous operation associated with _aio_. + +The type and semantics of input parameters are determined by specific +operations; the caller must supply appropriate inputs for the operation +to be performed. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +(This limit could increase in the future.) + +NOTE: If the _index_ does not correspond to a defined input for the operation, +then this function will have no effect. + +IMPORTANT: It is an error to call this function while the _aio_ is currently +in use by an active asynchronous operation. + +An input parameter set with this function may be retrieved later with +the xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`] function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_set_iov.3.adoc b/external/nng/docs/man/nng_aio_set_iov.3.adoc new file mode 100644 index 0000000..8312801 --- /dev/null +++ b/external/nng/docs/man/nng_aio_set_iov.3.adoc @@ -0,0 +1,67 @@ += nng_aio_set_iov(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_set_iov - set scatter/gather vector + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); +---- + +== DESCRIPTION + +The `nng_aio_set_iov()` function sets a ((scatter/gather)) vector _iov_ on the handle _aio_. + +The _iov_ is a pointer to an array of _niov_ xref:nng_iov.5.adoc[`nng_iov`] +structures, which have the following definition: + +[source,c] +---- + typedef struct nng_iov { + void * iov_buf; + size_t iov_len; + }; +---- + +The _iov_ is copied into storage in the _aio_ itself, so that callers may use stack allocated `nng_iov` structures. +The values pointed to by the `iov_buf` members are *not* copied by this function though. + +A maximum of four (4) `nng_iov` members may be supplied. + +NOTE: Earlier versions of the library could accept longer scatter-gather lists. +However, no known consumers have ever needed a scatter-gather list longer than 4 vectors. +As a result, the implementation limit was reduced, and heap allocations which could fail were removed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: Value of specified _niov_ is too large. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_iov.5.adoc[nng_iov(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_set_msg.3.adoc b/external/nng/docs/man/nng_aio_set_msg.3.adoc new file mode 100644 index 0000000..e0ea3e4 --- /dev/null +++ b/external/nng/docs/man/nng_aio_set_msg.3.adoc @@ -0,0 +1,47 @@ += nng_aio_set_msg(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_set_msg - set message for asynchronous send + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_aio_set_msg()` function sets the message that will be used +for an asynchronous send operation (see xref:nng_send_aio.3.adoc[`nng_send_aio()`]). + +IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_send_aio.3.adoc[nng_send_aio(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_set_output.3.adoc b/external/nng/docs/man/nng_aio_set_output.3.adoc new file mode 100644 index 0000000..67f8ac6 --- /dev/null +++ b/external/nng/docs/man/nng_aio_set_output.3.adoc @@ -0,0 +1,60 @@ += nng_aio_set_output(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_set_output - set output result + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result); +---- + +== DESCRIPTION + +The `nng_aio_set_output()` function sets the output result at _index_ +to _result_ for the asynchronous operation associated with _aio_. + +The type and semantics of output results are determined by specific +operations; the operation must supply appropriate output results when +the operation completes successfully. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can return more than four results. +(This limit could increase in the future.) + +NOTE: Note that attempts to set results with an _index_ greater than +three (3) will be ignored. + +An output result set with this function may be retrieved later with +the xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_set_timeout.3.adoc b/external/nng/docs/man/nng_aio_set_timeout.3.adoc new file mode 100644 index 0000000..a82b0c8 --- /dev/null +++ b/external/nng/docs/man/nng_aio_set_timeout.3.adoc @@ -0,0 +1,74 @@ += nng_aio_set_timeout(3) +// +// Copyright 2023 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_set_timeout - set asynchronous I/O timeout + +== SYNOPSIS + +[source, c] +---- +#include + +typedef int nng_duration; +void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout); + +typedef uint64_t nng_time; +void nng_aio_set_expire(nng_aio *aio, nng_time expiration); +---- + +== DESCRIPTION + +The `nng_aio_set_timeout()` function sets a _timeout_(((timeout))) +for the asynchronous operation associated with _aio_. +This causes a timer to be started when the operation is actually started. +If the timer expires before the operation is completed, then it is +aborted with an error of `NNG_ETIMEDOUT`. +The _timeout_ is specified as a relative number of milliseconds. + +If the timeout is `NNG_DURATION_INFINITE`, then no timeout is used. +If the timeout is `NNG_DURATION_DEFAULT`, then a "default" or socket-specific +timeout is used. +(This is frequently the same as `NNG_DURATION_INFINITE`.) + +The `nng_aio_set_expire()` function is similar to `nng_aio_set_timeout()`, but sets +an absolute expiration time based on the system clock. The _expiration_ +is expressed as a number of milliseconds since some point in the past. +The xref:nng_clock.3supp.adoc[`nng_clock()`] function can be used to determine +the current value of the clock. + +TIP: As most operations involve some context switching, it is usually a good +idea to allow at least a few tens of milliseconds before timing them out -- +a too small timeout might not allow the operation to properly begin before +giving up! + +The value of _timeout_ set for the _aio_ is persistent, so that if the +handle is reused for multiple operations, they will have the same relative +timeout. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_stop.3.adoc b/external/nng/docs/man/nng_aio_stop.3.adoc new file mode 100644 index 0000000..d5037c5 --- /dev/null +++ b/external/nng/docs/man/nng_aio_stop.3.adoc @@ -0,0 +1,60 @@ += nng_aio_stop(3) +// +// Copyright 2024 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_stop - stop asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_stop(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_stop()` function stops the asynchronous I/O operation +associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits +for it to complete or to be completely aborted, and for the +callback associated with the _aio_ to have completed executing. + +Further calls to +xref:nng_aio_begin.3.adoc[`nng_aio_begin()`] using this _aio_ will return false. + +It is safe to call this for an _aio_, even when no operation is currently +pending for it. + +TIP: When multiple asynchronous I/O handles are in use and need to be +shut down, it is safest to stop all of them, before deallocating any of +them with xref:nng_aio_free.3.adoc[`nng_aio_free()`], particularly if the callbacks +might attempt to reschedule additional operations. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], +xref:nng_aio_free.3.adoc[nng_aio_free(3)], +xref:nng_aio_begin.3.adoc[nng_aio_begin(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_aio_wait.3.adoc b/external/nng/docs/man/nng_aio_wait.3.adoc new file mode 100644 index 0000000..acac6fd --- /dev/null +++ b/external/nng/docs/man/nng_aio_wait.3.adoc @@ -0,0 +1,54 @@ += nng_aio_wait(3) +// +// Copyright 2023 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_aio_wait - wait for asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_aio_wait(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_wait()` function waits for an asynchronous I/O operation +to complete. +If the operation has not been started, or has already +completed, then it returns immediately. + +If a callback was set with _aio_ when it was allocated, then this +function will not be called until the callback has completed. + +IMPORTANT: This function should never be called from a function that itself +is a callback of an xref:nng_aio.5.adoc[`aio`], either this one or any other. +Doing so may result in a deadlock. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_busy.3.adoc[nng_aio_busy(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_alloc.3.adoc b/external/nng/docs/man/nng_alloc.3.adoc new file mode 100644 index 0000000..93c0311 --- /dev/null +++ b/external/nng/docs/man/nng_alloc.3.adoc @@ -0,0 +1,56 @@ += nng_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_alloc - allocate memory + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_alloc(size_t size); +---- + +== DESCRIPTION + +The `nng_alloc()` function allocates a contiguous memory region of +at least _size_ bytes. +The memory will be 64-bit aligned. + +The returned memory can be used to hold message buffers, in which +case it can be directly passed to xref:nng_send.3.adoc[`nng_send()`] using +the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no +longer needed using xref:nng_free.3.adoc[`nng_free()`]. + +IMPORTANT: Do not use the system `free()` function to release this memory. +On some platforms this may work, but it is not guaranteed and may lead +to a crash or other undesirable and unpredictable behavior. + +== RETURN VALUES + +This function returns a pointer to the allocated memory on success, +and `NULL` otherwise. + +== ERRORS + +No errors are returned, but a `NULL` return value should be +treated the same as `NNG_ENOMEM`. + +== SEE ALSO + +[.text-left] +xref:nng_free.3.adoc[nng_free(3)], +xref:nng_send.3.adoc[nng_send(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_bus.7.adoc b/external/nng/docs/man/nng_bus.7.adoc new file mode 100644 index 0000000..67b3d97 --- /dev/null +++ b/external/nng/docs/man/nng_bus.7.adoc @@ -0,0 +1,84 @@ += nng_bus(7) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_bus - bus protocol + +== SYNOPSIS + +[source,c] +---- +#include +---- + +== DESCRIPTION + +(((protocol, _bus_))) +The ((_bus_ protocol)) provides for building mesh networks where +every peer is connected to every other peer. +In this protocol, each message sent by a node is sent to every one of +its directly connected peers. + +TIP: Messages are only sent to directly connected peers. +This means that in the event that a peer is connected indirectly, it will not +receive messages. +When using this protocol to build mesh networks, it +is therefore important that a _fully-connected_ mesh network be constructed. + +All message delivery in this pattern is ((best-effort)), which means that +peers may not receive messages. +Furthermore, delivery may occur to some, +all, or none of the directly connected peers. +(Messages are not delivered when peer nodes are unable to receive.) +Hence, send operations will never block; instead if the +message cannot be delivered for any reason it is discarded. + +TIP: In order to minimize the likelihood of message loss, this protocol +should not be used for high throughput communications. +Furthermore, the more traffic _in aggregate_ that occurs across the topology, +the more likely that message loss is to occur. + +=== Socket Operations + +The xref:nng_bus_open.3.adoc[`nng_bus0_open()`] functions create a bus socket. +This socket may be used to send and receive messages. +Sending messages will attempt to deliver to each directly connected peer. + +=== Protocol Versions + +Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.) + +=== Protocol Options + +The _bus_ protocol has no protocol-specific options. + +=== Protocol Headers + +When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will +contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header. +If a message containing such a header is sent using a raw _bus_ socket, then, +the message will be delivered to all connected pipes _except_ the one +identified in the header. +This behavior is intended for use with xref:nng_device.3.adoc[device] +configurations consisting of just a single socket. +Such configurations are useful in the creation of rebroadcasters, and this +capability prevents a message from being routed back to its source. +If no header is present, then a message is sent to all connected pipes. + +When using normal (cooked mode) _bus_ sockets, no message headers are present. + +== SEE ALSO + +[.text-left] +xref:nng_bus_open.3.adoc[nng_bus_open(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_bus_open.3.adoc b/external/nng/docs/man/nng_bus_open.3.adoc new file mode 100644 index 0000000..3477a90 --- /dev/null +++ b/external/nng/docs/man/nng_bus_open.3.adoc @@ -0,0 +1,52 @@ += nng_bus_open(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_bus_open - create bus socket + +== SYNOPSIS + +[source,c] +---- +#include +#include + +int nng_bus0_open(nng_socket *s); + +int nng_bus0_open_raw(nng_socket *s); +---- + +== DESCRIPTION + +The `nng_bus0_open()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 +xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. + +The `nng_bus0_open_raw()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 +xref:nng_socket.5.adoc[socket] in +xref:nng.7.adoc#raw_mode[raw] mode, and returns it at the location pointed to by _s_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng_bus.7.adoc[nng_bus(7)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_clock.3supp.adoc b/external/nng/docs/man/nng_clock.3supp.adoc new file mode 100644 index 0000000..d413f1b --- /dev/null +++ b/external/nng/docs/man/nng_clock.3supp.adoc @@ -0,0 +1,59 @@ += nng_clock(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_clock - get time + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef uint64_t nng_time; + +nng_time nng_clock(void); +---- + +== DESCRIPTION + +The `nng_clock()` returns the number of elapsed milliseconds since some +arbitrary time in the past. +The resolution of the clock depends on the underlying timing facilities +of the system. +This function may be used for timing, but applications should not expect +very fine-grained values. + +IMPORTANT: The reference time will be the same for a given program, +but different programs may have different references. + +TIP: This function is intended mostly to help with setting appropriate +timeouts using xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. + +== RETURN VALUES + +Milliseconds since reference time. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_sleep_aio.3.adoc[nng_sleep_aio(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], +xref:nng_msleep.3supp.adoc[nng_msleep(3supp)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_close.3.adoc b/external/nng/docs/man/nng_close.3.adoc new file mode 100644 index 0000000..1867df0 --- /dev/null +++ b/external/nng/docs/man/nng_close.3.adoc @@ -0,0 +1,59 @@ += nng_close(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_close - close socket + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_close(nng_socket s); +---- + +== DESCRIPTION + +The `nng_close()` function closes the supplied socket, _s_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport. + +Further attempts to use the socket after this call returns will result +in `NNG_ECLOSED`. +Threads waiting for operations on the socket when this +call is executed may also return with an `NNG_ECLOSED` result. + +NOTE: Closing the socket 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. +It is recommended to wait a brief period after calling +xref:nng_send.3.adoc[`nng_send()`] or similar functions, before calling this +function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The socket _s_ is already closed or was never opened. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_compat.3compat.adoc b/external/nng/docs/man/nng_compat.3compat.adoc new file mode 100644 index 0000000..bd98659 --- /dev/null +++ b/external/nng/docs/man/nng_compat.3compat.adoc @@ -0,0 +1,214 @@ += nng_compat(3compat) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +---- + +== 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 <> 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 `` instead refer to ``. +For example, instead of: + +[source,c] +---- +#include +#include +---- + +you would have this: + +[source,c] +---- +#include +#include +---- + +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)] diff --git a/external/nng/docs/man/nng_ctx.5.adoc b/external/nng/docs/man/nng_ctx.5.adoc new file mode 100644 index 0000000..63e8736 --- /dev/null +++ b/external/nng/docs/man/nng_ctx.5.adoc @@ -0,0 +1,176 @@ += nng_ctx(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx - protocol context + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_ctx_s nng_ctx +---- + +== DESCRIPTION + +An `nng_ctx`(((context))) is a handle to an underlying context object, +which keeps the protocol state for some stateful protocols. +The purpose of a separate context object is to permit applications to +share a single socket, with its various underlying +xref:nng_dialer.5.adoc[dialers], +xref:nng_listener.5.adoc[listeners], +and xref:nng_pipe.5.adoc[pipes], +while still benefiting from separate state tracking. + +For example, a xref:nng_req.7.adoc[_req_] context will contain the request ID +of any sent request, a timer to retry the request on failure, and so forth. +A separate context on the same socket can have similar data, but corresponding +to a completely different request. + +IMPORTANT: The `nng_ctx` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + +All contexts share the same socket, and so some options, as well as the +underlying transport details, will be common to all contexts on that socket. + +NOTE: Not every protocol supports separate contexts. +See the protocol-specific documentation for further details about whether +contexts are supported, and details about what options are supported for +contexts. + +Protocols that make use of contexts will also have a default context +that is used when the socket global operations are used. +Operations using the global context will generally not interfere with +any other contexts, except that certain socket options may affect socket +global behavior. + +(((concurrent)))(((raw mode))) +Historically, applications wanting to use a stateful protocol concurrently +would have to resort to xref:nng.7.adoc#raw_mode[raw mode] sockets, which bypasses +much of the various protocol handling, leaving it to up to the application +to do so. +Contexts make it possible to still benefit from advanced protocol handling, +including timeouts, retries, and matching requests to responses, while doing so +concurrently. + +NOTE: xref:nng.7.adoc#raw_mode[Raw mode] sockets do not support contexts, since +there is generally no state tracked for them, and thus contexts make no sense. + +TIP: Contexts are an excellent mechanism to use when building concurrent +applications, and should be used in lieu of +xref:nng.7.adoc#raw_mode[raw mode] sockets when possible. + +IMPORTANT: Use of file descriptor polling (with descriptors +obtained using the +xref:nng_options.5.adoc#NNG_OPT_RECVFD[`NNG_OPT_RECVFD`] or +xref:nng_options.5.adoc#NNG_OPT_SENDFD[`NNG_OPT_SENDFD`] options) while contexts +are in use on the same socket is not supported, and may lead to unpredictable +behavior. +These asynchronous methods should not be mixed on the same socket. + +[[NNG_CTX_INITIALIZER]] +=== Initialization + +A context may be initialized using the macro `NNG_CTX_INITIALIZER` +before it is opened, to prevent confusion with valid open contexts. + +== EXAMPLE + +The following program fragment demonstrates the use of contexts to implement +a concurrent xref:nng_rep.7.adoc[_rep_] service that simply echos messages back +to the sender. + +[source, c] +---- + +struct echo_context { + nng_ctx ctx; + nng_aio *aio; + enum { INIT, RECV, SEND } state; +}; + +void +echo(void *arg) +{ + struct echo_context *ec = arg; + + switch (ec->state) { + case INIT: + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + case RECV: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + // We reuse the message on the ec->aio + ec->state = SEND; + nng_ctx_send(ec->ctx, ec->aio); + return; + case SEND: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + } +} +---- + +Given the above fragment, the following example shows setting up the +service. It assumes that the xref:nng_socket.5.adoc[socket] has already been +created and any transports set up as well with functions such as +xref:nng_dial.3.adoc[`nng_dial()`] +or xref:nng_listen.3.adoc[`nng_listen()`]. + +[source,c] +---- +#define CONCURRENCY 1024 + +static struct echo_context ecs[CONCURRENCY]; + +void +start_echo_service(nng_socket rep_socket) +{ + for (int i = 0; i < CONCURRENCY; i++) { + // error checks elided for clarity + nng_ctx_open(&ecs[i].ctx, rep_socket); + nng_aio_alloc(&ecs[i].aio, echo, ecs+i); + ecs[i].state = INIT; + echo(ecs+i); // start it running + } +} +---- + +== SEE ALSO + +[.text-left] +xref:libnng.3.adoc[libnng(3)], +xref:nng_ctx_close.3.adoc[nng_ctx_close(3)], +xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], +xref:nng_ctx_get.3.adoc[nng_ctx_get(3)], +xref:nng_ctx_id.3.adoc[nng_ctx_id(3)], +xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], +xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg(3)], +xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], +xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg(3)], +xref:nng_ctx_set.3.adoc[nng_ctx_set(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_close.3.adoc b/external/nng/docs/man/nng_ctx_close.3.adoc new file mode 100644 index 0000000..cfc51bf --- /dev/null +++ b/external/nng/docs/man/nng_ctx_close.3.adoc @@ -0,0 +1,54 @@ += nng_ctx_close(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_close - close context + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_close(nng_ctx ctx); +---- + +== DESCRIPTION + +The `nng_ctx_close()` function closes the context _ctx_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport. + +Further attempts to use the context after this call returns will result +in `NNG_ECLOSED`. +Threads waiting for operations on the context when this +call is executed may also return with an `NNG_ECLOSED` result. + +NOTE: Closing the socket associated with _ctx_ +(using xref:nng_close.3.adoc[`nng_close()`]) also closes this context. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The context _ctx_ is already closed or was never opened. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_get.3.adoc b/external/nng/docs/man/nng_ctx_get.3.adoc new file mode 100644 index 0000000..48237b2 --- /dev/null +++ b/external/nng/docs/man/nng_ctx_get.3.adoc @@ -0,0 +1,131 @@ += nng_ctx_get(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_get - get context option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_get(nng_ctx ctx, const char *opt, void *val, size_t *valszp); + +int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *bvalp); + +int nng_ctx_get_int(nng_ctx ctx, const char *opt, int *ivalp); + +int nng_ctx_get_ms(nng_ctx ctx, const char *opt, nng_duration *durp); + +int nng_ctx_get_size(nng_ctx ctx, const char *opt, size_t *zp); + +int nng_ctx_get_string(nng_ctx ctx, const char *opt, char **strp); + +int nng_ctx_get_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +(((options, context))) +The `nng_ctx_get()` functions are used to retrieve option values for +the xref:nng_ctx.5.adoc[context] _ctx_. +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. + +NOTE: Context options are protocol specific. +The details will be documented with the protocol. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the context _ctx_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_ctx_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _valszp_ does not exceed the original buffer size. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_ctx_get_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _ivalp_. + +`nng_ctx_get_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_ctx_get_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_ctx_get_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_ctx_get_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_ctx_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_set.3.adoc[nng_ctx_set(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_getopt.3.adoc b/external/nng/docs/man/nng_ctx_getopt.3.adoc new file mode 100644 index 0000000..2214a3e --- /dev/null +++ b/external/nng/docs/man/nng_ctx_getopt.3.adoc @@ -0,0 +1,134 @@ += nng_ctx_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_getopt - get context option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_getopt(nng_ctx ctx, const char *opt, void *val, size_t *valszp); + +int nng_ctx_getopt_bool(nng_ctx ctx, const char *opt, bool *bvalp); + +int nng_ctx_getopt_int(nng_ctx ctx, const char *opt, int *ivalp); + +int nng_ctx_getopt_ms(nng_ctx ctx, const char *opt, nng_duration *durp); + +int nng_ctx_getopt_size(nng_ctx ctx, const char *opt, size_t *zp); + +int nng_ctx_getopt_string(nng_ctx ctx, const char *opt, char **strp); + +int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_get.3.adoc[nng_ctx_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, context))) +The `nng_ctx_getopt()` functions are used to retrieve option values for +the xref:nng_ctx.5.adoc[context] _ctx_. +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. + +NOTE: Context options are protocol specific. +The details will be documented with the protocol. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the context _ctx_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_ctx_getopt()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _valszp_ does not exceed the original buffer size. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_ctx_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _ivalp_. + +`nng_ctx_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_ctx_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_ctx_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_ctx_getopt_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_ctx_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_id.3.adoc b/external/nng/docs/man/nng_ctx_id.3.adoc new file mode 100644 index 0000000..51b833a --- /dev/null +++ b/external/nng/docs/man/nng_ctx_id.3.adoc @@ -0,0 +1,51 @@ += nng_ctx_id(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_id - return numeric context identifier + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_id(nng_ctx c); +---- + +== DESCRIPTION + +The `nng_ctx_id()` function returns a positive identifier for the context _c_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A context is considered valid if it was ever opened with +xref:nng_ctx_open.3.adoc[`nng_ctx_open()`] function. +Contexts that are allocated on the stack or statically should be +initialized with the macro +xref:nng_ctx.5.adoc#NNG_CTX_INITIALIZER[`NNG_CTX_INITIALIZER`] to ensure that +they cannot be confused with a valid context before they are opened. + +== RETURN VALUES + +This function returns the positive value for the context identifier, or +`-1` if the context is invalid. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_open.3.adoc b/external/nng/docs/man/nng_ctx_open.3.adoc new file mode 100644 index 0000000..76842b7 --- /dev/null +++ b/external/nng/docs/man/nng_ctx_open.3.adoc @@ -0,0 +1,71 @@ += nng_ctx_open(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_open - create context + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_ctx_open(nng_ctx *ctxp, nng_socket s); +---- + +== DESCRIPTION + +The `nng_ctx_open()` function creates a separate ((context)) to be used with +the socket _s_, +and returns it at the location pointed by _ctxp_. + +NOTE: Not every protocol supports creation of separate contexts. + +Contexts allow the independent and concurrent use of stateful operations +using the same socket. +For example, two different contexts created on a xref:nng_rep.7.adoc[_rep_] +socket can each receive requests, and send replies to them, without any +regard to or interference with each other. + +(((raw mode))) +TIP: Using contexts is an excellent way to write simpler concurrent +applications, while retaining the benefits of the protocol-specific +advanced processing, avoiding the need to bypass that with +xref:nng.7.adoc#raw_mode[raw mode] sockets. + +NOTE: Use of contexts with xref:nng.7.adoc#raw_mode[raw mode] sockets is +nonsensical, and not supported. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol does not support separate contexts, or the socket was opened in raw mode. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_close.3.adoc[nng_ctx_close(3)], +xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], +xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], +xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], +xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng_rep.7.adoc[nng_rep(7)], +xref:nng_req.7.adoc[nng_req(7)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_recv.3.adoc b/external/nng/docs/man/nng_ctx_recv.3.adoc new file mode 100644 index 0000000..bb3d7cf --- /dev/null +++ b/external/nng/docs/man/nng_ctx_recv.3.adoc @@ -0,0 +1,74 @@ += nng_ctx_recv(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_recv - receive message using context asynchronously + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_ctx_recv()` receives a xref:nng_msg.5.adoc[message] using the +xref:nng_ctx.5.adoc[context] _s_ asynchronously. + +When a message is successfully received by the context, it is +stored in the _aio_ by an internal call equivalent to +xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`], then the completion +callback on the _aio_ is executed. +In this case, xref:nng_aio_result.3.adoc[`nng_aio_result()`] will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately. + +IMPORTANT: Failing to accept and dispose of messages in this +case can lead to memory leaks. + +If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but xref:nng_aio_result.3.adoc[`nng_aio_result()`] will be non-zero. + +NOTE: The semantics of what receiving a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. + +== RETURN VALUES + +None. (The operation completes asynchronously.) + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The context _ctx_ is not open. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol for context _ctx_ does not support receiving. +`NNG_ESTATE`:: The context _ctx_ cannot receive data in this state. +`NNG_ETIMEDOUT`:: The receive timeout expired. + +== SEE ALSO + +[.text-left] +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_recvmsg.3.adoc b/external/nng/docs/man/nng_ctx_recvmsg.3.adoc new file mode 100644 index 0000000..9651c34 --- /dev/null +++ b/external/nng/docs/man/nng_ctx_recvmsg.3.adoc @@ -0,0 +1,63 @@ += nng_ctx_recvmsg(3) +// +// Copyright 2021 Staysail Systems, Inc. +// +// 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_ctx_recvmsg - receive message using socket + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags); +---- + +== DESCRIPTION + +The `nng_ctx_recvmsg()` receives a message on context _ctx_, storing the +received message at the location pointed to by _msgp_. + +The _flags_ may contain the following value: + +`NNG_FLAG_NONBLOCK`:: + The function returns immediately, even if no message is available. + Without this flag, the function will wait until a message is receivable + on the context _ctx_, or any configured timer expires. + +NOTE: The semantics of what receiving a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +`NNG_ECLOSED`:: The context or socket is not open. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol does not support receiving. +`NNG_ESTATE`:: The context cannot receive data in this state. +`NNG_ETIMEDOUT`:: The operation timed out. + +== SEE ALSO + +[.text-left] +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], +xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], +xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_send.3.adoc b/external/nng/docs/man/nng_ctx_send.3.adoc new file mode 100644 index 0000000..8724c1a --- /dev/null +++ b/external/nng/docs/man/nng_ctx_send.3.adoc @@ -0,0 +1,88 @@ += nng_ctx_send(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_send - send message using context asynchronously + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_ctx_send(nng_ctx ctx, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_ctx_send()` sends a xref:nng_msg.5.adoc[message] using the +xref:nng_ctx.5.adoc[context] _ctx_ asynchronously. + +The message to send must have previously been set on the _aio_ +using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. +The function assumes ownership of the message. + +If the message was successfully queued for delivery to the socket, +then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] +will return zero. +In this case the socket will dispose of the message when it is finished with it. + +NOTE: The operation will be completed, and the callback associated +with the _aio_ executed, as soon as the socket accepts the message +for sending. +This does _not_ indicate that the message was actually delivered, as it +may still be buffered in the sending socket, buffered in the receiving +socket, or in flight over physical media. + +If the operation fails for any reason (including cancellation or timeout), +then the _aio_ callback will be executed and +xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the _aio_ with xref:nng_aio_get_msg.3.adoc[`nng_aio_get_msg()`] and dispose of +it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with xref:nng_msg_free.3.adoc[`nng_msg_free()`].) + +NOTE: The semantics of what sending a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. + +TIP: Context send operations are asynchronous. +If a synchronous operation is needed, one can be constructed by using a +`NULL` callback on the _aio_ and then waiting for the operation using +xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. + +== RETURN VALUES + +None. (The operation completes asynchronously.) + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The context _ctx_ is not open. +`NNG_EMSGSIZE`:: The message is too large. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol for context _ctx_ does not support sending. +`NNG_ESTATE`:: The context _ctx_ cannot send data in this state. +`NNG_ETIMEDOUT`:: The send timeout expired. + +== SEE ALSO + +[.text-left] +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_sendmsg.3.adoc b/external/nng/docs/man/nng_ctx_sendmsg.3.adoc new file mode 100644 index 0000000..8e2c97f --- /dev/null +++ b/external/nng/docs/man/nng_ctx_sendmsg.3.adoc @@ -0,0 +1,84 @@ += nng_ctx_sendmsg(3) +// +// Copyright 2021 Staysail Systems, Inc. +// +// 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_ctx_sendmsg - send message using context + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_sendmsg(nng_ctx c, nng_msg *msg, int flags); +---- + +== DESCRIPTION + +The `nng_ctx_sendmsg()` sends message _msg_ using the context _ctx_. + +If the function returns zero, indicating it has accepted the message for +delivery, then the _msg_ is owned by the socket _s_, and the caller +must not make any further use of it. +The socket will free the message when it is finished. + +If the function returns non-zero, then it is the caller's responsibility +to dispose of the _msg_, which may include freeing it, sending it to +another socket, or simply trying again later. + +NOTE: The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. + +The _flags_ may contain the following value: + +`NNG_FLAG_NONBLOCK`:: + The function returns immediately, regardless of whether + the context is able to accept the data or not. + If the context is unable to accept the data (such as if backpressure exists + because the peers are consuming messages too slowly, or no peer is present), + then the function will return with `NNG_EAGAIN`. + If this flag is not specified, then the function will block if such a + condition exists. + + +NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +`NNG_ECLOSED`:: The context or socket is not open. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_EMSGSIZE`:: The value of _size_ is too large. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol does not support sending. +`NNG_ESTATE`:: The context cannot send data in this state. +`NNG_ETIMEDOUT`:: The operation timed out. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], +xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg(3)], +xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], +xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_set.3.adoc b/external/nng/docs/man/nng_ctx_set.3.adoc new file mode 100644 index 0000000..9bfeb43 --- /dev/null +++ b/external/nng/docs/man/nng_ctx_set.3.adoc @@ -0,0 +1,113 @@ += nng_ctx_set(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_set - set context option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_set(nng_ctx ctx, const char *opt, const void *val, size_t valsz); + +int nng_ctx_set_bool(nng_ctx ctx, const char *opt, int bval); + +int nng_ctx_set_int(nng_ctx ctx, const char *opt, int ival); + +int nng_ctx_set_ms(nng_ctx ctx, const char *opt, nng_duration dur); + +int nng_ctx_set_size(nng_ctx ctx, const char *opt, size_t z); + +int nng_ctx_set_string(nng_ctx ctx, const char *opt, const char *str); + +int nng_ctx_set_uint64(nng_ctx ctx, const char *opt, uint64_t u64); +---- + +== DESCRIPTION + +NOTE: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. + +(((options, context))) +The `nng_ctx_set()` functions are used to configure options for +the context _ctx_. +The actual options that may be configured in this way vary, and are +specified by _opt_. + +NOTE: Context options are protocol specific. +The details will be documented with the protocol. + +=== Forms + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_ctx_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_ctx_set_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_ctx_set_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_ctx_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_ctx_set_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_ctx_set_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_ctx_set_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_get.3.adoc[nng_ctx_get(3)], +xref:nng_socket_set.3.adoc[nng_socket_set(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ctx_setopt.3.adoc b/external/nng/docs/man/nng_ctx_setopt.3.adoc new file mode 100644 index 0000000..f6f7f9e --- /dev/null +++ b/external/nng/docs/man/nng_ctx_setopt.3.adoc @@ -0,0 +1,114 @@ += nng_ctx_setopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ctx_setopt - set context option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_setopt(nng_ctx ctx, const char *opt, const void *val, size_t valsz); + +int nng_ctx_setopt_bool(nng_ctx ctx, const char *opt, int bval); + +int nng_ctx_setopt_int(nng_ctx ctx, const char *opt, int ival); + +int nng_ctx_setopt_ms(nng_ctx ctx, const char *opt, nng_duration dur); + +int nng_ctx_setopt_size(nng_ctx ctx, const char *opt, size_t z); + +int nng_ctx_setopt_string(nng_ctx ctx, const char *opt, const char *str); + +int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64); +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, context))) +The `nng_ctx_setopt()` functions are used to configure options for +the context _ctx_. +The actual options that may be configured in this way vary, and are +specified by _opt_. + +NOTE: Context options are protocol specific. +The details will be documented with the protocol. + +=== Forms + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_ctx_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_ctx_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_ctx_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_ctx_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_ctx_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_ctx_setopt_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_ctx_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. + +== SEE ALSO + +[.text-left] +xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], +xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_ctx.5.adoc[nng_ctx(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_alloc.3supp.adoc b/external/nng/docs/man/nng_cv_alloc.3supp.adoc new file mode 100644 index 0000000..9e58e3f --- /dev/null +++ b/external/nng/docs/man/nng_cv_alloc.3supp.adoc @@ -0,0 +1,60 @@ += nng_cv_alloc(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_alloc - allocate condition variable + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef struct nng_cv nng_cv; + +int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); +---- + +== DESCRIPTION + +The `nng_cv_alloc()` function allocates a condition variable, using +the mutex _mtx_, and returns it in _cvp_. + +Every condition variable is associated with a mutex, which must be +owned when a thread waits for the condition using +xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or +xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. +The mutex must also be owned when signaling the condition using the +xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or +xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] functions. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_cv_free.3supp.adoc[nng_cv_free(3supp)], +xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], +xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], +xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], +xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_free.3supp.adoc b/external/nng/docs/man/nng_cv_free.3supp.adoc new file mode 100644 index 0000000..0610b52 --- /dev/null +++ b/external/nng/docs/man/nng_cv_free.3supp.adoc @@ -0,0 +1,42 @@ += nng_cv_free(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_free - free condition variable + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_cv_free(nng_cv *cv); +---- + +== DESCRIPTION + +The `nng_cv_free()` function frees the condition variable _cv_. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_until.3supp.adoc b/external/nng/docs/man/nng_cv_until.3supp.adoc new file mode 100644 index 0000000..9cf7c71 --- /dev/null +++ b/external/nng/docs/man/nng_cv_until.3supp.adoc @@ -0,0 +1,91 @@ += nng_cv_until(3supp) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_until - wait for condition or timeout + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_cv_until(nng_cv *cv, nng_time when); +---- + +== DESCRIPTION + +The `nng_cv_until()` waits until either the condition variable _cv_ is signaled +by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or +xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`], or the system clock (as tracked +by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.) + +NOTE: Any condition may be used or checked, but the condition must be +checked, as it is possible for this function to wake up spuriously. +The best way to do this is inside a loop that repeats until the condition +tests for true. + +== EXAMPLE + +The following example demonstrates use of this function: + +.Example 1: Waiting for the condition +[source, c] +---- + + expire = nng_clock() + 1000; // 1 second in the future + nng_mtx_lock(m); // assume cv was allocated using m + while (!condition_true) { + if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { + printf("Time out reached!\n"); + break; + } + } + // condition_true is true + nng_mtx_unlock(m); +---- + +.Example 2: Signaling the condition +[source, c] +---- + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +---- + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], +xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], +xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_wait.3supp.adoc b/external/nng/docs/man/nng_cv_wait.3supp.adoc new file mode 100644 index 0000000..1d9c16b --- /dev/null +++ b/external/nng/docs/man/nng_cv_wait.3supp.adoc @@ -0,0 +1,86 @@ += nng_cv_wait(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_wait - wait for condition + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_cv_wait(nng_cv *cv); +---- + +== DESCRIPTION + +The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled +by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or +xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`]. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.) + +NOTE: Any condition may be used or checked, but the condition must be +checked, as it is possible for this function to wake up spuriously. +The best way to do this is inside a loop that repeats until the condition +tests for true. + +== EXAMPLE + +The following example demonstrates use of this function: + +.Example 1: Waiting for the condition +[source, c] +---- + + nng_mtx_lock(m); // assume cv was allocated using m + while (!condition_true) { + nng_cv_wait(cv); + } + // condition_true is true + nng_mtx_unlock(m); +---- + +.Example 2: Signaling the condition +[source, c] +---- + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +---- + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], +xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], +xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_wake.3supp.adoc b/external/nng/docs/man/nng_cv_wake.3supp.adoc new file mode 100644 index 0000000..6ee2945 --- /dev/null +++ b/external/nng/docs/man/nng_cv_wake.3supp.adoc @@ -0,0 +1,61 @@ += nng_cv_wake(3supp) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_wake - wake all waiters + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_cv_wake(nng_cv *cv); +---- + +== DESCRIPTION + +The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ +to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or +xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +NOTE: The caller should already have set the condition that the waiters +will check, while holding the mutex. + +TIP: This function wakes all threads, which is generally safer but can +lead to a performance problem when there are many waiters, as they are all +woken simultaneously and may contend for resources. +See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], +xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], +xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_cv_wake1.3supp.adoc b/external/nng/docs/man/nng_cv_wake1.3supp.adoc new file mode 100644 index 0000000..4f8b832 --- /dev/null +++ b/external/nng/docs/man/nng_cv_wake1.3supp.adoc @@ -0,0 +1,61 @@ += nng_cv_wake1(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_cv_wake1 - wake one waiter + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_cv_wake1(nng_cv *cv); +---- + +== DESCRIPTION + +The `nng_cv_wake1()` wakes at most one thread waiting for the condition +variable _cv_ +to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or +xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +NOTE: The caller should already have set the condition that the waiters +will check, while holding the mutex. + +NOTE: The caller cannot predict which waiter will be woken, and so the design must +ensure that it is sufficient that _any_ waiter be woken. +When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], +xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], +xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_device.3.adoc b/external/nng/docs/man/nng_device.3.adoc new file mode 100644 index 0000000..7151239 --- /dev/null +++ b/external/nng/docs/man/nng_device.3.adoc @@ -0,0 +1,122 @@ += nng_device(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_device - message forwarding device + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_device(nng_socket s1, nng_socket s2); + +void nng_device_aio(nng_aio *aio, nng_socket s1, nng_socket s2); +---- + +== DESCRIPTION + +The `nng_device()` and `nng_device_aio()` functions forward messages received from one +xref:nng_socket.5.adoc[socket] _s1_ to another socket _s2_, and vice versa. + +These functions are used to create forwarders, which can be used to create +complex network topologies to provide for improved ((horizontal scalability)), +reliability, and isolation. + +Only xref:nng_options.5.adoc#NNG_OPT_RAW[raw] mode sockets may be used with this +function. +These can be created using `_raw` forms of the various socket constructors, +such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`]. + +The `nng_device()` function does not return until one of the sockets +is closed. +The `nng_device_aio()` function returns immediately, and operates completely in +the background. + +=== Reflectors + +One of the sockets passed may be an unopened socket initialized with +the `NNG_SOCKET_INITIALIZER` special value. +If this is the case, then the other socket must be valid, and must use +a protocol that is bidirectional and can peer with itself (such as +xref:nng_pair.7.adoc[_pair_] or +xref:nng_bus.7.adoc[_bus_].) +In this case the device acts as a ((reflector)) or loop-back device, +where messages received from the valid socket are merely returned +to the sender. + +=== Forwarders + +When both sockets are valid, then the result is a ((forwarder)) or proxy. +In this case sockets _s1_ and _s2_ must be compatible with each other, +which is to say that they should represent the opposite halves of a two +protocol pattern, or both be the same protocol for a single protocol +pattern. +For example, if _s1_ is a xref:nng_pub.7.adoc[_pub_] socket, then _s2_ must +be a xref:nng_sub.7.adoc[_sub_] socket. +Or, if _s1_ is a xref:nng_bus.7.adoc[_bus_] socket, then _s2_ must also +be a _bus_ socket. + +=== Operation + +The `nng_device()` function moves messages between the provided sockets. + +When a protocol has a ((backtrace)) style header, routing information +is present in the header of received messages, and is copied to the +header of the output bound message. +The underlying raw mode protocols supply the necessary header +adjustments to add or remove routing headers as needed. +This allows replies to be +returned to requesters, and responses to be routed back to surveyors. + +The caller of these functions is required to close the sockets when the +device is stopped. + +Additionally, some protocols have a maximum ((time-to-live)) to protect +against forwarding loops and especially amplification loops. +In these cases, the default limit (usually 8), ensures that messages will +self-terminate when they have passed through too many forwarders, +protecting the network from unlimited message amplification that can arise +through misconfiguration. +This is controlled via the xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`] +option. + +IMPORTANT: Not all protocols have support for guarding against forwarding loops, +and even for those that do, forwarding loops can be extremely detrimental +to network performance. + +NOTE: Devices (forwarders and reflectors) act in best-effort delivery mode only. +If a message is received from one socket that cannot be accepted by the +other (due to backpressure or other issues), then the message is discarded. + +TIP: Use the request/reply pattern, which includes automatic retries by +the requester, if reliable delivery is needed. + +== RETURN VALUES + +This function continues running, and only returns an appropriate error when +one occurs, or if one of the sockets is closed. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: At least one of the sockets is not open. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EINVAL`:: The sockets are not compatible, or are both invalid. + +== SEE ALSO + +[.text-left] +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dial.3.adoc b/external/nng/docs/man/nng_dial.3.adoc new file mode 100644 index 0000000..00df455 --- /dev/null +++ b/external/nng/docs/man/nng_dial.3.adoc @@ -0,0 +1,95 @@ += nng_dial(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dial - create and start dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags); +---- + +== DESCRIPTION + +The `nng_dial()` function creates a newly initialized +xref:nng_dialer.5.adoc[`nng_dialer`] object, +associated with socket _s_, and configured to dial the +address specified by _url_, and starts it. +If the value of _dp_ is not `NULL`, then +the newly created dialer is stored at the address indicated by _dp_. + +Dialers initiate a remote connection to a listener. +Upon a successful +connection being established, they create a xref:nng_pipe.5.adoc[pipe], +add it to the socket, and then wait for that pipe to be closed. +When the pipe is closed, the dialer attempts to re-establish the connection. +Dialers will also periodically retry a connection automatically if an attempt +to connect asynchronously fails. + +TIP: While it is convenient to think of dialers as clients, the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. +For example, a xref:nng_req.7.adoc[_req_] +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +Normally, the first attempt to connect to the address indicated by _url_ is done +synchronously, including any necessary name resolution. +As a result, a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken. + +However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then the connection attempt is made asynchronously. + +Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Because the dialer is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using xref:nng_dialer_create.3.adoc[`nng_dialer_create()`] and +xref:nng_dialer_start.3.adoc[`nng_dialer_start()`] instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ECONNREFUSED`:: The remote peer refused the connection. +`NNG_ECONNRESET`:: The remote peer reset the connection. +`NNG_EINVAL`:: An invalid set of _flags_ or an invalid _url_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EPEERAUTH`:: Authentication or authorization failure. +`NNG_EPROTO`:: A protocol error occurred. +`NNG_EUNREACHABLE`:: The remote address is not reachable. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_close.3.adoc[nng_dialer_close(3)], +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_start.3.adoc[nng_dialer_start(3)], +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_pipe.5.adoc[nng_pipe(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer.5.adoc b/external/nng/docs/man/nng_dialer.5.adoc new file mode 100644 index 0000000..eb4d7c1 --- /dev/null +++ b/external/nng/docs/man/nng_dialer.5.adoc @@ -0,0 +1,80 @@ += nng_dialer(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer - dialer + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_dialer_s nng_dialer; +---- + +== DESCRIPTION + +(((dialer))) +An `nng_dialer` is a handle to a dialer object, which is responsible for +creating a single xref:nng_pipe.5.adoc[`nng_pipe`] at a time by +establishing an outgoing connection. + +If the connection is broken, or fails, the dialer object will automatically +attempt to reconnect, and will keep doing so until the dialer or socket is +destroyed. + +Dialer objects are created by the +xref:nng_dialer_create.3.adoc[`nng_dialer_create()`] +or xref:nng_dial.3.adoc[`nng_dial()`] functions, and are always associated +with a single xref:nng_socket.5.adoc[`nng_socket`]. + +IMPORTANT: The `nng_dialer` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + +TIP: A given xref:nng_socket.5.adoc[`nng_socket`] may have multiple dialer +objects, multiple xref:nng_listener.5.adoc[listener] objects, or even some +of both. + +TIP: The client/server relationship described by dialer/listener is +completely orthogonal to any similar relationship in the protocols. +For example, a xref:nng_rep.7.adoc[_rep_] socket may use a dialer +to connect to a listener on an xref:nng_req.7.adoc[_req_] socket. +This orthogonality can lead to innovative solutions to otherwise +challenging communications problems. + +Dialer objects may be destroyed by the +xref:nng_dialer_close.3.adoc[`nng_dialer_close()`] function. +They are also closed when their associated socket is closed. + +[[NNG_DIALER_INITIALIZER]] +=== Initialization + +A dialer may be initialized using the macro `NNG_DIALER_INITIALIZER` +before it is opened, to prevent confusion with valid open dialers. + +== SEE ALSO + +[.text-left] +xref:nng_dial.3.adoc[nng_dial(3)], +xref:nng_dialer_close.3.adoc[nng_dialer_close(3)], +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)], +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], +xref:nng_dialer_id.3.adoc[nng_dialer_id(3)], +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], +xref:nng_dialer_start.3.adoc[nng_dialer_start(3)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_pipe.5.adoc[nng_pipe(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_close.3.adoc b/external/nng/docs/man/nng_dialer_close.3.adoc new file mode 100644 index 0000000..6af73ae --- /dev/null +++ b/external/nng/docs/man/nng_dialer_close.3.adoc @@ -0,0 +1,56 @@ += nng_dialer_close(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_close - close dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_close(nng_dialer d); +---- + +== DESCRIPTION + +The `nng_dialer_close()` function closes the dialer _d_. +This also closes any xref:nng_pipe.5.adoc[`nng_pipe`] objects that have +been created by the dialer. + +Once this function returns, the dialer _d_ and any of its resources +are deallocated. +Therefore it is an error to attempt to access _d_ after +this function has returned. +(Attempts to do so will result in `NNG_ECLOSED` errors.) + +Dialers are implicitly closed when the socket they are associated with is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. + +== SEE ALSO + +[.text-left] +xref:nng_close.3.adoc[nng_close(3)], +xref:nng_dial.3.adoc[nng_dial(3)], +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_create.3.adoc b/external/nng/docs/man/nng_dialer_create.3.adoc new file mode 100644 index 0000000..d4df92f --- /dev/null +++ b/external/nng/docs/man/nng_dialer_create.3.adoc @@ -0,0 +1,80 @@ += nng_dialer_create(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_create - create dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_create(nng_dialer *dialerp, nng_socket s, const char *url); +---- + +== DESCRIPTION + +The `nng_dialer_create()` function creates a newly initialized +xref:nng_dialer.5.adoc[`nng_dialer`] object, associated with socket _s_, +and configured to connect to the +address specified by _url_, and stores a pointer to at the location +referenced by _dialerp_. + +Dialers initiate a remote connection to a listener. +Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. +When the pipe is closed, they will re-initiate the connection. +Dialers will also periodically retry a connection automatically if +an attempt to connect asynchronously +fails. + +TIP: While it is convenient to think of dialers as clients, the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. +For example, a xref:nng_req.7.adoc[_req_] +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +The dialer is not started, but may be further configured with +the xref:nng_dialer_setopt.3.adoc[`nng_dialer_setopt()`] family of functions. + +Once it is fully configured, the dialer may be started using the +xref:nng_dialer_start.3.adoc[`nng_dialer_start()`] function. + +TIP: If no specific configuration is required, consider using the +simpler xref:nng_dial.3.adoc[`nng_dial()`] function instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +[.text-left] +xref:nng_dial.3.adoc[nng_dial(3)], +xref:nng_dialer_close.3.adoc[nng_dialer_close(3)], +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], +xref:nng_dialer_start.3.adoc[nng_dialer_start(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_get.3.adoc b/external/nng/docs/man/nng_dialer_get.3.adoc new file mode 100644 index 0000000..e23ecd2 --- /dev/null +++ b/external/nng/docs/man/nng_dialer_get.3.adoc @@ -0,0 +1,146 @@ += nng_dialer_get(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_get - get dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_get(nng_dialer d, const char *opt, void *val, size_t *valszp); + +int nng_dialer_get_bool(nng_dialer d, const char *opt, bool *bvalp); + +int nng_dialer_get_int(nng_dialer d, const char *opt, int *ivalp); + +int nng_dialer_get_ms(nng_dialer d, const char *opt, nng_duration *durp); + +int nng_dialer_get_ptr(nng_dialer d, const char *opt, void **ptr); + +int nng_dialer_get_size(nng_dialer d, const char *opt, size_t *zp); + +int nng_dialer_get_addr(nng_dialer d, const char *opt, nng_sockaddr *sap); + +int nng_dialer_get_string(nng_dialer d, const char *opt, char **strp); + +int nng_dialer_get_uint64(nng_dialer d, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +(((options, dialer))) +The `nng_dialer_get()` functions are used to retrieve option values for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the dialer _d_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_dialer_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. +Therefore the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_dialer_get_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_dialer_get_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_dialer_get_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_dialer_get_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_dialer_get_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_dialer_get_addr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_dialer_get_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_dialer_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_set.3.adoc[nng_dialer_set(3)] +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_getopt.3.adoc b/external/nng/docs/man/nng_dialer_getopt.3.adoc new file mode 100644 index 0000000..a408381 --- /dev/null +++ b/external/nng/docs/man/nng_dialer_getopt.3.adoc @@ -0,0 +1,149 @@ += nng_dialer_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_getopt - get dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); + +int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp); + +int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); + +int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); + +int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); + +int nng_dialer_getopt_size(nng_dialer d, const char *opt, size_t *zp); + +int nng_dialer_getopt_sockaddr(nng_dialer d, const char *opt, nng_sockaddr *sap); + +int nng_dialer_getopt_string(nng_dialer d, const char *opt, char **strp); + +int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_get.3.adoc[nng_dialer_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, dialer))) +The `nng_dialer_getopt()` functions are used to retrieve option values for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the dialer _d_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_dialer_getopt()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. +Therefore the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_dialer_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_dialer_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_dialer_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_dialer_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_dialer_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_dialer_getopt_sockaddr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_dialer_getopt_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_dialer_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_id.3.adoc b/external/nng/docs/man/nng_dialer_id.3.adoc new file mode 100644 index 0000000..e964310 --- /dev/null +++ b/external/nng/docs/man/nng_dialer_id.3.adoc @@ -0,0 +1,52 @@ += nng_dialer_id(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_id - return numeric dialer identifier + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_id(nng_dialer d); +---- + +== DESCRIPTION + +The `nng_dialer_id()` function returns a positive identifier for the dialer _d_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A dialer is considered valid if it was ever created with the +xref:nng_dialer_create.3.adoc[`nng_dialer_create()`] or +xref:nng_dial.3.adoc[`nng_dial()`] functions. +Dialers that are allocated on the stack or statically should be +initialized with the macro +xref:nng_ctx.5.adoc#NNG_DIALER_INITIALIZER[`NNG_DIALER_INITIALIZER`] to ensure that +they cannot be confused with a valid dialer before they are created properly. + +== RETURN VALUES + +This function returns the positive value for the dialer identifier, or +`-1` if the dialer is invalid. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_set.3.adoc b/external/nng/docs/man/nng_dialer_set.3.adoc new file mode 100644 index 0000000..3363eae --- /dev/null +++ b/external/nng/docs/man/nng_dialer_set.3.adoc @@ -0,0 +1,130 @@ += nng_dialer_set(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_set - set dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_set(nng_dialer d, const char *opt, const void *val, + size_t valsz); + +int nng_dialer_set_bool(nng_dialer d, const char *opt, bool bval); + +int nng_dialer_set_int(nng_dialer d, const char *opt, int ival); + +int nng_dialer_set_ms(nng_dialer d, const char *opt, nng_duration dur); + +int nng_dialer_set_ptr(nng_dialer d, const char *opt, void *ptr); + +int nng_dialer_set_size(nng_dialer d, const char *opt, size_t z); + +int nng_dialer_set_string(nng_dialer d, const char *opt, const char *str); + +int nng_dialer_set_uint64(nng_dialer d, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +(((options, dialer))) +The `nng_dialer_set()` functions are used to configure options for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +NOTE: Once a dialer has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the dialer _d_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_dialer_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_dialer_set_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_dialer_set_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_dialer_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_dialer_set_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) +can be passed this way. + +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_dialer_set_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_dialer_set_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_dialer_set_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and such. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The dialer _d_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_get.3.adoc[nng_dialer_get(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_setopt.3.adoc b/external/nng/docs/man/nng_dialer_setopt.3.adoc new file mode 100644 index 0000000..3aaff1e --- /dev/null +++ b/external/nng/docs/man/nng_dialer_setopt.3.adoc @@ -0,0 +1,134 @@ += nng_dialer_setopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_setopt - set dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, + size_t valsz); + +int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval); + +int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); + +int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); + +int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); + +int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); + +int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); + +int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_set.3.adoc[nng_dialer_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, dialer))) +The `nng_dialer_setopt()` functions are used to configure options for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the +transports themselves. + +NOTE: Once a dialer has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the dialer _d_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_dialer_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_dialer_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_dialer_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_dialer_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_dialer_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) +can be passed this way. + +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_dialer_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_dialer_setopt_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_dialer_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and such. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The dialer _d_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_dialer_start.3.adoc b/external/nng/docs/man/nng_dialer_start.3.adoc new file mode 100644 index 0000000..b6cb6e8 --- /dev/null +++ b/external/nng/docs/man/nng_dialer_start.3.adoc @@ -0,0 +1,77 @@ += nng_dialer_start(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_dialer_start - start dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_start(nng_dialer d, int flags); +---- + +== DESCRIPTION + +The `nng_dialer_start()` function starts the dialer _d_. + +This causes the dialer to start connecting to the address with which it was +created. + +When a connection is established, it results in a pipe being created, +which will be attached to the dialer's socket. + +Normally, the first attempt to connect to the dialer's address is done +synchronously, including any necessary name resolution. +As a result, a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken. + +However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then the connection attempt is made asynchronously. + +Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Once a dialer has started, it is generally not possible to change +its configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ECONNREFUSED`:: The remote peer refused the connection. +`NNG_ECONNRESET`:: The remote peer reset the connection. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EPEERAUTH`:: Authentication or authorization failure. +`NNG_EPROTO`:: A protocol error occurred. +`NNG_ESTATE`:: The dialer _d_ is already started. +`NNG_EUNREACHABLE`:: The remote address is not reachable. + +== SEE ALSO + +[.text-left] +xref:nng_dial.3.adoc[nng_dial(3)], +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_duration.5.adoc b/external/nng/docs/man/nng_duration.5.adoc new file mode 100644 index 0000000..fbd172b --- /dev/null +++ b/external/nng/docs/man/nng_duration.5.adoc @@ -0,0 +1,50 @@ += nng_duration(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_duration - relative time in milliseconds + +== SYNOPSIS + +[source, c] +---- +#include + +typedef int32_t nng_duration; + +#define NNG_DURATION_INFINITE (-1) +#define NNG_DURATION_DEFAULT (-2) +#define NNG_DURATION_ZERO (0) +---- + +== DESCRIPTION + +An `nng_duration`(((duration))) is a relative time, measured in +milliseconds. +This type is most often used in conjunction with timers and timeouts. + +A couple of special values have been set aside, and carry special meanings. + +((`NNG_DURATION_DEFAULT`))::: +Indicates a context-specific default value should be used. + +((`NNG_DURATION_INFINITE`))::: +Effectively an infinite duration; used most often to disable timeouts. + +((`NNG_DURATION_ZERO`))::: +Zero length duration; used to perform a single polling operation. + +== SEE ALSO + +[.text-left] +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_free.3.adoc b/external/nng/docs/man/nng_free.3.adoc new file mode 100644 index 0000000..b4fdc24 --- /dev/null +++ b/external/nng/docs/man/nng_free.3.adoc @@ -0,0 +1,53 @@ += nng_free(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_free - free memory + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_free(void *ptr, size_t size); +---- + +== DESCRIPTION + +The `nng_free()` function deallocates a memory region of size _size_, +that was previously allocated by xref:nng_alloc.3.adoc[`nng_alloc()`] or +xref:nng_recv.3.adoc[`nng_recv()`] with the `NNG_FLAG_ALLOC` flag. + +IMPORTANT: It is very important that _size_ match the allocation size +used to allocate the memory. + +IMPORTANT: Do not attempt to use this function to deallocate memory +obtained by a call to the system `malloc()` or `calloc()` functions, +or the {cpp} `new` operator. +Doing so may result in unpredictable +behavior, including corruption of application memory. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_alloc.3.adoc[nng_alloc(3)], +xref:nng_recv.3.adoc[nng_recv(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_getopt.3.adoc b/external/nng/docs/man/nng_getopt.3.adoc new file mode 100644 index 0000000..364d8f7 --- /dev/null +++ b/external/nng/docs/man/nng_getopt.3.adoc @@ -0,0 +1,145 @@ += nng_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_getopt - get socket option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); + +int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp); + +int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); + +int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); + +int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); + +int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); + +int nng_getopt_string(nng_socket s, const char *opt, char **strp); + +int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_socket_get.3.adoc[nng_socket_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, socket))) +The `nng_getopt()` functions are used to retrieve option values for +the xref:nng_socket.5.adoc[socket] _s_. +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally transport-specific options and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the socket _s_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_getopt()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_valszp_. ++ +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _valszp_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_getopt_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_alloc.3http.adoc b/external/nng/docs/man/nng_http_client_alloc.3http.adoc new file mode 100644 index 0000000..f433001 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_alloc.3http.adoc @@ -0,0 +1,49 @@ += nng_http_client_alloc(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_alloc - allocate HTTP client + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_client_alloc(nng_http_client *clientp, const nng_url *url); +---- + +== DESCRIPTION + +The `nng_http_client_alloc()` allocates an HTTP client suitable for +connecting to the server identified by _url_ and stores a pointer to +it in the location referenced by _clientp_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_free.3http.adoc[nng_http_client_free(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_url_parse.3.adoc[nng_url_parse(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_connect.3http.adoc b/external/nng/docs/man/nng_http_client_connect.3http.adoc new file mode 100644 index 0000000..e2a3e23 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_connect.3http.adoc @@ -0,0 +1,98 @@ += nng_http_client_connect(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_connect - establish HTTP client connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_client_connect(nng_http_client *client, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_client_connect()` starts the process of establishing an HTTP +connection from _client_ to the server that was indicated in the URL that +_client_ was configured with. + +The result of the operation will be stored in the _aio_ when the operation +is complete, and will be obtainable via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. + +On success, a pointer to the underlying HTTP client (type `nng_http_conn *`) +will be stored in the first output result of the _aio_, and can be +obtained by +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] with an _index_ of zero (0). + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: The client is configured with an invalid address. +`NNG_ECANCELED`:: The operation was aborted. +`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. + +== EXAMPLE + +[source, c] +---- + nng_aio *aio; + nng_url *url; + nng_http_client *client; + nng_http_conn *conn; + int rv; + + // Error checks elided for clarity. + nng_url_parse(&url, "http://www.google.com"); + nng_aio_alloc(&aio, NULL, NULL); + nng_http_client_alloc(&client, url); + + nng_http_client_connect(client, aio); + + // Wait for connection to establish (or attempt to fail). + nng_aio_wait(aio); + + if ((rv = nng_aio_result(aio)) != 0) { + printf("Connection failed: %s\n", nng_strerror(rv)); + } else { + // Connection established, get it. + conn = nng_aio_get_output(aio, 0); + + // ... do something with it here + + // Close the connection when done to avoid leaking it. + nng_http_conn_close(conn); + } +---- + +== SEE ALSO + +[.text-left] +xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], +xref:nng_http_conn_close.3http.adoc[nng_http_conn_close(3http)], +xref:nng_http_conn_read.3http.adoc[nng_http_conn_read(3http)], +xref:nng_http_conn_write.3http.adoc[nng_http_conn_write(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_free.3http.adoc b/external/nng/docs/man/nng_http_client_free.3http.adoc new file mode 100644 index 0000000..2343672 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_free.3http.adoc @@ -0,0 +1,48 @@ += nng_http_client_free(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_free - free HTTP client + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_client_free(nng_http_client *client); +---- + +== DESCRIPTION + +The `nng_http_client_free()` frees the HTTP client and any associated +resources referenced by _client_. + +NOTE: Any connections created by +xref:nng_http_client_connect.3http.adoc[`nng_http_client_connect()`] are unaffected, +and so the caller must close those explicitly if desired. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_get_tls.3http.adoc b/external/nng/docs/man/nng_http_client_get_tls.3http.adoc new file mode 100644 index 0000000..89f0302 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_get_tls.3http.adoc @@ -0,0 +1,59 @@ += nng_http_client_get_tls(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_get_tls - get HTTP client TLS configuration + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **cfgp); +---- + +== DESCRIPTION + +The `nng_http_client_get_tls()` obtains the TLS configuration of _client_ and +saves a pointer to it in the address referenced by _cfgp_. + +The object will be returned with an extra hold (see +xref:nng_tls_config_hold.3tls.adoc[`nng_tls_config_hold()`]) +placed on it on behalf of the caller. +The caller should free this hold by calling +xref:nng_tls_config_free.3tls.adoc[`nng_tls_config_free()`] with it is done +with the TLS configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: TLS not configured on client. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls(3http)], +xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], +xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free(3tls)], +xref:nng_tls_config_hold.3tls.adoc[nng_tls_config_hold(3tls)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_set_tls.3http.adoc b/external/nng/docs/man/nng_http_client_set_tls.3http.adoc new file mode 100644 index 0000000..023b8a4 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_set_tls.3http.adoc @@ -0,0 +1,57 @@ += nng_http_client_set_tls(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_set_tls - set HTTP client TLS configuration + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *cfg); +---- + +== DESCRIPTION + +The `nng_http_client_set_tls()` sets the TLS configuration of _client_ to _cfg_. + +This change overwrites any previous TLS configuration. + +IMPORTANT: This also invalidates any previously obtained values from +xref:nng_http_client_get_tls.3http.adoc[`nng_http_client_get_tls()`]. + +NOTE: Any connections established with +xref:nng_http_client_connect.3http.adoc[`nng_http_client_connect()`] +will continue to use any TLS configuration that they were started with. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls(3http)], +xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_client_transact.3http.adoc b/external/nng/docs/man/nng_http_client_transact.3http.adoc new file mode 100644 index 0000000..0585fa7 --- /dev/null +++ b/external/nng/docs/man/nng_http_client_transact.3http.adoc @@ -0,0 +1,84 @@ += nng_http_client_transact(3http) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_client_transact - perform one HTTP transaction + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_client_transact(nng_http_client *client, nng_http_req *req, + nng_http_res *res, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_client_transact()` function is used to perform a complete +HTTP exchange. +It creates a new connection using _client_, performs the transaction by +sending the request _req_ +(and attached body data) to the remote server, then reading the response +_res_, and finally closes the connection that it created. +The entire response is read, including any associated body, which can +subsequently be obtained using +xref:nng_http_res_get_data.3http.adoc[`nng_http_res_get_data()`]. + +This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction. + +A similar function, +xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`], +exists. +That function behaves similarily, but uses an existing connection, which +can be reused. + +WARNING: If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported, or peer sent chunked encoding. +`NNG_EPROTO`:: An HTTP protocol error occurred. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], +xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_close.3http.adoc b/external/nng/docs/man/nng_http_conn_close.3http.adoc new file mode 100644 index 0000000..95c266e --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_close.3http.adoc @@ -0,0 +1,47 @@ += nng_http_conn_close(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_close - close HTTP connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_close(nng_http_conn *conn); +---- + +== DESCRIPTION + +The `nng_http_conn_close()` function closes the supplied HTTP connection _conn_, +including any disposing of any underlying file descriptors or related resources. + +Once this function, no further access to the _conn_ structure may be made. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_read.3http.adoc b/external/nng/docs/man/nng_http_conn_read.3http.adoc new file mode 100644 index 0000000..dfb6e08 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_read.3http.adoc @@ -0,0 +1,77 @@ += nng_http_conn_read(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_read - read from HTTP connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_read(nng_http_conn *conn, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_read()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The xref:nng_aio_set_iov.3.adoc[`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 +xref:nng_aio_result.3.adoc[`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 +read, 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 +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +TIP: This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`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_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_read_all.3http.adoc b/external/nng/docs/man/nng_http_conn_read_all.3http.adoc new file mode 100644 index 0000000..21b892f --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_read_all.3http.adoc @@ -0,0 +1,78 @@ += nng_http_conn_read_all(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_read_all - read all from HTTP connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_read_all(nng_http_conn *conn, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_read_all()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The xref:nng_aio_set_iov.3.adoc[`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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been read, or an error has occurred. +If the operation +completes successfully, then the entire requested data has been read. + +It is still possible for a partial read to complete in the event of an error. +The actual number of bytes read can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +TIP: The main purpose for this function is to facilitate reading HTTP +body content, after first determining the length of the body content +from the relevant HTTP headers (typically `Content-Length`). + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`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_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3)], +xref:nng_http_conn_read.3http.adoc[nng_http_conn_read(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_read_req.3http.adoc b/external/nng/docs/man/nng_http_conn_read_req.3http.adoc new file mode 100644 index 0000000..01d790c --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_read_req.3http.adoc @@ -0,0 +1,66 @@ += nng_http_conn_read_req(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_read_req - read HTTP request + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_read_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_read_req()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP request into the _req_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the request is *not* read +automatically. +The caller should use +xref:nng_http_conn_read_all.3http.adoc[`nng_http_conn_read_all()`] +to read the entity data, based on the details of the request itself. + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_read_res.3http.adoc b/external/nng/docs/man/nng_http_conn_read_res.3http.adoc new file mode 100644 index 0000000..ff5cd7a --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_read_res.3http.adoc @@ -0,0 +1,75 @@ += nng_http_conn_read_res(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_read_res - read HTTP response + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_read_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_read_res()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP response into the _res_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the response is *not* read +automatically. +The caller should use +xref:nng_http_conn_read_all.3http.adoc[`nng_http_conn_read_all`] to read the entity +data, based on the details of the response itself. + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +NOTE: Consider using the +xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or +xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], +xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_transact.3http.adoc b/external/nng/docs/man/nng_http_conn_transact.3http.adoc new file mode 100644 index 0000000..7239f62 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_transact.3http.adoc @@ -0,0 +1,93 @@ += nng_http_conn_transact(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_transact - perform one HTTP transaction on connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_transact(nng_http_conn *conn, nng_http_req *req, + nng_http_res *res, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_transact()` function is used to perform a complete +HTTP exchange over the connection _conn_, sending the request _req_ +(and attached body data) to the remote server, and reading the response +_res_. +The entire response is read, including any associated body, which can +subsequently be obtained using +xref:nng_http_res_get_data.3http.adoc[`nng_http_res_get_data()`]. + +This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction. + +If an error occurs, the caller should close _conn_ with +xref:nng_http_conn_close.3http.adoc[`nng_http_conn_close()`], as it may not +necessarily be usable with other transactions. + +A similar function, +xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`], +exists. +That function behaves similarily, but creates a connection on demand +for the transaction, and disposes of it when finished. + +WARNING: If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. + +WARNING: A given connection _conn_ should be used with only one +operation or transaction at a time as HTTP/1.1 has no support for +request interleaving. + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_EPROTO`:: An HTTP protocol error occurred. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], +xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], +xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_write.3http.adoc b/external/nng/docs/man/nng_http_conn_write.3http.adoc new file mode 100644 index 0000000..d2e1ac3 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_write.3http.adoc @@ -0,0 +1,76 @@ += nng_http_conn_write(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_write - write to HTTP connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_write(nng_http_conn *conn, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_write()` function starts an asynchronous write to the +HTTP connection _conn_ from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The xref:nng_aio_set_iov.3.adoc[`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 xref:nng_aio_result.3.adoc[`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 +written, or an error has occurred. +Therefore, the number of bytes written may be less than requested. +The actual number of bytes written can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +TIP: This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`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_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all(3http)], +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_write_all.3http.adoc b/external/nng/docs/man/nng_http_conn_write_all.3http.adoc new file mode 100644 index 0000000..329a830 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_write_all.3http.adoc @@ -0,0 +1,96 @@ += nng_http_conn_write_all(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_write_all - write all to HTTP connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_write_all(nng_http_conn *conn, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_write_all()` function starts an asynchronous write to the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The xref:nng_aio_set_iov.3.adoc[`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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been written, or an error has occurred. +If the operation completes successfully, then the entire requested data has +been written. + +It is still possible for a partial write to complete in the event of an error. +The actual number of bytes written can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +TIP: The main purpose for this function is to facilitate writing HTTP +body content. + +TIP: Usually an HTTP request or response will have been written immediately +prior to this with xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_req()`] or +xref:nng_http_conn_write_res.3http.adoc[`http_conn_write_res()`]. +In that case the request or response should have also contained +an `Content-Length` header, and possibly a `Content-Type` header. + +TIP: An easier solution to sending HTTP content data, is to include the +content with the request or reply using a function like +xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`]. +In that case, the body data will be written automatically by the +xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_req()`] or +xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_res()`] function. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`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_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_conn_write.3http.adoc[nng_http_conn_write(3http)], +xref:nng_http_conn_write_req.3http.adoc[http_conn_write_req(3http)], +xref:nng_http_conn_write_res.3http.adoc[http_conn_write_res(3http)], +xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], +xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], +xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_write_req.3http.adoc b/external/nng/docs/man/nng_http_conn_write_req.3http.adoc new file mode 100644 index 0000000..faed760 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_write_req.3http.adoc @@ -0,0 +1,72 @@ += nng_http_conn_write_req(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_write_req - write HTTP request + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_write_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_write_req()` function starts an asynchronous write of +the HTTP request _req_ to the connection _conn_. +The entire request is sent, +including headers, and if present, the request body data. +(The request body can be set with +xref:nng_http_req_set_data.3http.adoc[`nng_http_req_set_data()`] or +xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`].) + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +NOTE: Consider using the +xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or +xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_conn_write_res.3http.adoc b/external/nng/docs/man/nng_http_conn_write_res.3http.adoc new file mode 100644 index 0000000..6c99878 --- /dev/null +++ b/external/nng/docs/man/nng_http_conn_write_res.3http.adoc @@ -0,0 +1,81 @@ += nng_http_conn_write_res(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_conn_write_res - write HTTP response + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_write_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_write_res()` function starts an asynchronous write of +the HTTP response _res_ to the connection _conn_. +The entire response is sent, +including headers, and if present, the response body data. +(The response body can be set with +xref:nng_http_res_set_data.3http.adoc[`nng_http_res_set_data()`] or +xref:nng_http_res_copy_data.3http.adoc[`nng_http_res_copy_data()`].) + +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 xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +=== Persistent Connections + +By default, for `HTTP/1.1` connections, the connection is kept open, and +will be reused to receive new requests. + +If however the _res_ contains a header of `Connection:` with a value +of `Close` (case-insensitive) or the response corresponds to `HTTP/1.0`, +then the connection is immediately after sending the response. + +NOTE: Consider using the +xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or +xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], +xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], +xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], +xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_alloc.3http.adoc b/external/nng/docs/man/nng_http_handler_alloc.3http.adoc new file mode 100644 index 0000000..c7d4699 --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_alloc.3http.adoc @@ -0,0 +1,193 @@ += nng_http_handler_alloc(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2020 Dirac Research +// +// 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_http_handler_alloc - allocate HTTP server handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef struct nng_http_handler nng_http_handler; + +int nng_http_handler_alloc(nng_http_handler **hp, const char *path, + void (*func)(nng_aio *); + +int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, + const char *dirname); + +int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, + const char *filename); + +int nng_http_handler_alloc_redirect(nng_http_handler **hp, const char *path, + uint16_t status, const char *location); + +int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path, + const void *data, size_t size, const char *content_type); +---- + +== DESCRIPTION + +The `nng_http_handler_alloc()` family of functions allocate a handler +which will be used to process requests coming into an HTTP server. +On success, a pointer to the handler is stored at the located pointed to +by _hp_. + +Every handler has a Request-URI to which it refers, which is determined +by the _path_ argument. +Only the path component of the Request URI is +considered when determining whether the handler should be called. + +Additionally each handler has a method it is registered to handle +(the default is `GET`, see +xref:nng_http_handler_set_method.3http.adoc[`nng_http_handler_set_method()`]), and +optionally a 'Host' header it can be matched against (see +xref:nng_http_handler_set_host.3http.adoc[`nng_http_handler_set_host()`]). + +In some cases, a handler may reference a logical tree rather (directory) +rather than just a single element. +(See xref:nng_http_handler_set_tree.3http.adoc[`nng_http_handler_set_tree()`]). + +=== Custom Handler + +The generic (first) form of this creates a handler that uses a user-supplied +function to process HTTP requests. +This function uses the asynchronous I/O framework. +The function takes a pointer to an xref:nng_aio.5.adoc[`nng_aio`] structure. + +The _aio_ will be passed with the following input values (retrieved with +xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`]): + + 0: `nng_http_req *` __request__:: The client's HTTP request. + 1: `nng_http_handler *` __handler__:: Pointer to the handler object. + 2: `nng_http_conn *` __conn__:: The underlying HTTP connection. + +The handler should create an `nng_http_res *` response (such as via +xref:nng_http_res_alloc.3http.adoc[`nng_http_res_alloc()`] or +xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`]) and store that +in as the first output (index 0) with +xref:nng_aio_set_output.3.adoc[`nng_aio_set_output()`]. + +Alternatively, the handler may send the HTTP response (and any associated +body data) itself using the connection. +In that case the output at index 0 of the _aio_ should be NULL. + +Finally, using the xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] function, the +_aio_ should be completed successfully. +If any non-zero status is returned back to the caller instead, +then a generic 500 response will be created and +sent, if possible, and the connection will be closed. + +The _aio_ may be scheduled for deferred completion using the +xref:nng_aio_defer.3.adoc[`nng_aio_defer()`] function. + +NOTE: The callback function should *NOT* call +xref:nng_aio_begin.3.adoc[`nng_aio_begin()`], +as that will already have been done by the server framework. + +=== Directory Handler + +The second member of this family, `nng_http_handler_alloc_directory()`, creates +a handler configured to serve a directory tree. +The _uri_ is taken as the root, and files are served from the directory +tree rooted at _path_. + +When the client Request-URI resolves to a directory in the file system, +the handler looks first for a file named `index.html` or `index.htm`. +If one is found, then that file is returned back to the client. +If no such index file exists, then an `NNG_HTTP_STATUS_NOT_FOUND` (404) error is +sent back to the client. + +The `Content-Type` will be set automatically based upon the extension +of the requested file name. If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +The directory handler is created as a tree handler initially in exclusive mode (see +xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive]). +This can be changed by calling +xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree(3http)] +after creating the directory handler. + +=== File Handler + +The third member of this family, `nng_http_handler_alloc_file()`, creates +a handler to serve up a single file; it does not traverse directories +or search for `index.html` or `index.htm` files. + +The `Content-Type` will be set automatically based upon the extension +of the requested file name. +If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +=== Redirect Handler + +The fourth member is used to arrange for a server redirect from one +URL to another. +The reply will be with status code __status__, which should be a 3XX +code such as 301, and a `Location:` header will contain the URL +referenced by __location__, with any residual suffix from the request +URI appended. + +TIP: Use xref:nng_http_handler_set_tree.3http.adoc[`nng_http_handler_set_tree()`] +to redirect an entire tree. +For example, it is possible to redirect an entire HTTP site to another +HTTPS site by specifying `/` as the path and then using the base +of the new site, such as `https://newsite.example.com` as the +new location. + +TIP: Be sure to use the appropriate value for __status__. +Permanent redirection should use 301 and temporary redirections should use 307. +In REST APIs, using a redirection to supply the new location of an object +created with `POST` should use 303. + +=== Static Handler + +The fifth member of this family, `nng_http_handler_alloc_static()`, creates +a handler to serve up fixed content located in program data. +The client is +sent the _data_, with `Content-Length` of _size_ bytes, and `Content-Type` of +__content_type__. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: An invalid _path_ was specified. +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], +xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], +xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], +xref:nng_aio_set_output.3.adoc[nng_aio_set_output(3)], +xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body(3http)], +xref:nng_http_handler_free.3http.adoc[nng_http_handler_free(3http)], +xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host(3http)], +xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method(3http)], +xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree(3http)], +xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive(3http)], +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_collect_body.3http.adoc b/external/nng/docs/man/nng_http_handler_collect_body.3http.adoc new file mode 100644 index 0000000..b614f67 --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_collect_body.3http.adoc @@ -0,0 +1,78 @@ += nng_http_handler_collect_body(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_collect_body - set HTTP handler to collect request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); +---- + +== DESCRIPTION + +The `nng_http_handler_collect_body()` function causes the _handler_ to +collect any request body that was submitted with the request, and attach +it to the `nng_http_req` before the handler is called. + +Subsequently the data can be retrieved by the handler from the request with the +xref:nng_http_req_get_data.3http.adoc[`nng_http_req_get_data()`] function. + +The collection is enabled if _want_ is true. +Furthermore, the data that the client may sent is limited by the +value of _maxsz_. +If the client attempts to send more data than _maxsz_, then the +request will be terminated with a 400 `Bad Request` status. + +TIP: Limiting the size of incoming request data can provide protection +against denial of service attacks, as a buffer of the client-supplied +size must be allocated to receive the data. + +In order to provide an unlimited size, use `(size_t)-1` for _maxsz_. +The value `0` for _maxsz_ can be used to prevent any data from being passed +by the client. + +The built-in handlers for files, directories, and static data limit the +_maxsz_ to zero by default. +Otherwise the default setting is to enable this capability with a default +value of _maxsz_ of 1 megabyte. + +NOTE: The handler looks for data indicated by the `Content-Length:` HTTP +header. +If this header is absent, the request is assumed not to contain any data. + +NOTE: This specifically does not support the `Chunked` transfer-encoding. +This is considered a bug, and is a deficiency for full HTTP/1.1 compliance. +However, few clients send data in this format, so in practice this should +create few limitations. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_free.3http.adoc b/external/nng/docs/man/nng_http_handler_free.3http.adoc new file mode 100644 index 0000000..c7b30e0 --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_free.3http.adoc @@ -0,0 +1,47 @@ += nng_http_handler_free(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_free - free HTTP server handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_handler_free(nng_http_handler *h); +---- + +== DESCRIPTION + +The `nng_http_handler_free()` function frees an allocated HTTP server handler. + +IMPORTANT: It is an error to free a handler that is registered with a server. +Any handlers that are registered with servers are automatically freed +when the server itself is deallocated. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_get_data.3http.adoc b/external/nng/docs/man/nng_http_handler_get_data.3http.adoc new file mode 100644 index 0000000..0467b2b --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_get_data.3http.adoc @@ -0,0 +1,46 @@ += nng_http_handler_get_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_get_data - return extra data for HTTP handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void *nng_http_handler_get_data(nng_http_handler *handler); +---- + +== DESCRIPTION + +The `nng_http_handler_get_data()` function returns the data previously +stored on _handler_ using the function +xref:nng_http_handler_set_data.3http.adoc[`nng_http_handler_set_data()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_handler_set_data.3http.adoc[nng_http_server_set_data(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_set_data.3http.adoc b/external/nng/docs/man/nng_http_handler_set_data.3http.adoc new file mode 100644 index 0000000..cb94adb --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_set_data.3http.adoc @@ -0,0 +1,55 @@ += nng_http_handler_set_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_set_data - set extra data for HTTP handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_handler_set_data(nng_http_handler *handler, void *data, + void (*dtor)(void *)); +---- + +== DESCRIPTION + +The `nng_http_handler_set_data()` function is used to set an additional +_data_ for the _handler_. +The stored _data_ can be retrieved later in the handler function using +xref:nng_http_handler_get_data.3http.adoc[`nng_http_handler_get_data()`]. + +Additionally, when the handler is deallocated, if _dtor_ is not `NULL`, +then it will be called with _data_ as its argument. +The intended use of +this function is deallocate any resources associated with _data_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_handler_get_data.3http.adoc[nng_http_server_get_data(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_set_host.3http.adoc b/external/nng/docs/man/nng_http_handler_set_host.3http.adoc new file mode 100644 index 0000000..0deae48 --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_set_host.3http.adoc @@ -0,0 +1,59 @@ += nng_http_handler_set_host(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_set_host - set host for HTTP handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_handler_set_host(nng_http_handler *handler, const char *host); +---- + +== DESCRIPTION + +The `nng_http_handler_set_host()` function is used to limit the scope of the +_handler_ so that it will only be called when the specified _host_ matches +the value of the `Host:` HTTP header. + +TIP: This can be used to create servers with multiple handlers for virtual +hosting. + +The value of the _host_ can include a colon and port, and should match +exactly the value of the `Host` header sent by the client. +(Canonicalization of the host name is performed though.) + +TIP: As the server framework does not support listening on multiple +ports, the port number can be elided. +The matching test only considers +the hostname or IP address, and ignores any trailing port number. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_set_method.3http.adoc b/external/nng/docs/man/nng_http_handler_set_method.3http.adoc new file mode 100644 index 0000000..f79f0fa --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_set_method.3http.adoc @@ -0,0 +1,61 @@ += nng_http_handler_set_method(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_handler_set_method - set HTTP handler method + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_handler_set_method(nng_http_handler *handler, const char *method); +---- + +== DESCRIPTION + +The `nng_http_handler_set_method()` function sets the _method_ that the +_handler_ will be called for, such as "GET" or "POST". +(By default the "GET" method is handled.) +If _method_ is `NULL`, then the request method +is not examined, and the handler will be executed regardless of the +method. + +NOTE: The server will automatically call "GET" handlers if the client +sends a "HEAD" request, and will suppress HTTP body data in the responses +sent for such requests. + +NOTE: No validation of the _method_ is performed, but HTTP specifications +insist that the actual method sent over the wire be capitalized. + +The handler may always examine the actual method used using the +xref:nng_http_req_get_method.3http.adoc[`nng_http_req_get_method()`] function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_handler_set_tree.3http.adoc b/external/nng/docs/man/nng_http_handler_set_tree.3http.adoc new file mode 100644 index 0000000..f0ecc4c --- /dev/null +++ b/external/nng/docs/man/nng_http_handler_set_tree.3http.adoc @@ -0,0 +1,67 @@ += nng_http_handler_set_tree(3http) + +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2020 Dirac Research +// +// 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_http_handler_set_tree - set HTTP handler to match trees + +== SYNOPSIS + +[source,c] +---- +#include +#include + +int nng_http_handler_set_tree(nng_http_handler *handler); + +int nng_http_handler_set_tree_exclusive(nng_http_handler *handler); +---- + +== DESCRIPTION + +The `nng_http_handler_set_tree()` function causes the _handler_ to be matched if the request URI sent +by the client is a logical child of the path for _handler_, and no more specific +_handler_ has been registered. + +The `nng_http_handler_set_tree_exclusive()` function is similar to `nng_http_server_set_tree()` +with the distinction that the _handler_ will be considered to *exclusively* handle its request URI. +Unlike `nng_http_server_set_tree()`, it will not be possible to register additional +handlers in logical subdirectories of _handler_. + +This is useful in cases when the handler would like to examine the entire path +and possibly behave differently; for example a REST API that uses the rest of +the path to pass additional parameters. + +TIP: These methods are useful when constructing API handlers where a single +service address (path) supports dynamically generated children. + +TIP: The non-exclusive form is also useful for providing a default handler to be +generated when a more specific child does not exist. +This can provide a better experience for users than the standard 404 error +handling. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_hijack.3http.adoc b/external/nng/docs/man/nng_http_hijack.3http.adoc new file mode 100644 index 0000000..5123142 --- /dev/null +++ b/external/nng/docs/man/nng_http_hijack.3http.adoc @@ -0,0 +1,65 @@ += nng_http_hijack(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_hijack - hijack HTTP server connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_hijack(nng_http_conn *conn); +---- + +== DESCRIPTION +(((HTTP, hijack))) +The `nng_http_hijack()` function hijacks the connection _conn_, causing it +to be disassociated from the HTTP server where it was created. + +The purpose of this function is the creation of HTTP upgraders (such as +WebSocket), where the underlying HTTP connection will be taken over for +some other purpose, and should not be used any further by the server. + +This function is most useful when called from a handler function. +(See xref:nng_http_handler_alloc.3http.adoc[`nng_http_handler_alloc()`].) + +NOTE: It is the responsibility of the caller to dispose of the underlying +connection when it is no longer needed. +Furthermore, the HTTP server will no longer send any responses to the +hijacked connection, so the caller should do that as well if appropriate. +(See xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`].) + +TIP: This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The connection was closed. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_add_header.3http.adoc b/external/nng/docs/man/nng_http_req_add_header.3http.adoc new file mode 100644 index 0000000..bf95254 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_add_header.3http.adoc @@ -0,0 +1,65 @@ += nng_http_req_add_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_add_header - add HTTP request header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_add_header(nng_http_req *req, const char *key, + const char *val); +---- + +== DESCRIPTION + +The `nng_http_req_add_header()` adds an HTTP header for the request +_req_ and the _key_ to the _val_. The _key_ and _val_ are copied. + +If a header with the value of _key_ already exists, then a comma +and whitespace separate are appended to it, followed by _val_. + +If no such header already exists, then one is created with the value _val_. + +TIP: The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. + +TIP: See xref:nng_http_req_set_header.3http.adoc[`nng_http_req_set_header()`] if +replacement of an existing header rather than appending to it is desired. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], +xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], +xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_alloc.3http.adoc b/external/nng/docs/man/nng_http_req_alloc.3http.adoc new file mode 100644 index 0000000..706ef9d --- /dev/null +++ b/external/nng/docs/man/nng_http_req_alloc.3http.adoc @@ -0,0 +1,68 @@ += nng_http_req_alloc(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_alloc - allocate HTTP request structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_alloc(nng_http_req **reqp, const nng_url *url); +---- + +== DESCRIPTION + +The `nng_http_req_alloc()` function allocates a new HTTP request structure +and stores a pointer to it in __reqp__. +The request will be initialized +to perform an HTTP/1.1 `GET` operation using the URL specified in __url__. + +TIP: It is possible to specify `NULL` for the URL. +In this case the URI for the request must be specified by a subsequent call +to xref:nng_http_req_set_uri.3http.adoc[`nng_http_req_set_uri()`]. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req(3http)], +xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], +xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], +xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], +xref:nng_http_req_free.3http.adoc[nng_http_req_free(3http)], +xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], +xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri(3http)], +xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], +xref:nng_http_req_reset.3http.adoc[nng_http_req_reset(3http)], +xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], +xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method(3http)], +xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], +xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version(3http)], +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_url_parse.3.adoc[nng_url_parse(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_copy_data.3http.adoc b/external/nng/docs/man/nng_http_req_copy_data.3http.adoc new file mode 100644 index 0000000..7ab864f --- /dev/null +++ b/external/nng/docs/man/nng_http_req_copy_data.3http.adoc @@ -0,0 +1,62 @@ += nng_http_req_copy_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_copy_data - copy HTTP request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_copy_data(nng_http_req *req, const void *body, size_t size); +---- + +== DESCRIPTION + +The `nng_http_req_copy_data()` makes a copy of _body_ (of size __size__) +and sets the HTTP body for the request _req_ to it. +The copy will be deallocated automatically when _req_ is freed. + +The copied body data will be automatically sent with the request when it +is sent using xref:nng_http_conn_write_req.3http.adoc[`nng_http_conn_write_req()`]. + +This also updates the relevant `Content-Length` header of _req_. + +NOTE: The current framework does not support sending data via chunked +transfer-encoding. + +TIP: To avoid copying data, the +xref:nng_http_req_set_data.3http.adoc[`nng_http_req_set_data()`] may be used instead. + +TIP: It is a good idea to also set the `Content-Type` header. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], +xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_del_header.3http.adoc b/external/nng/docs/man/nng_http_req_del_header.3http.adoc new file mode 100644 index 0000000..d54f65e --- /dev/null +++ b/external/nng/docs/man/nng_http_req_del_header.3http.adoc @@ -0,0 +1,53 @@ += nng_http_req_del_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_del_header - delete HTTP request header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_del_header(nng_http_req *req, const char *key); +---- + +== DESCRIPTION + +The `nng_http_req_del_header()` removes all HTTP headers with the +associated _key_ from the request structure _req_. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: No header with the key _key_ was present. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], +xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], +xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_free.3http.adoc b/external/nng/docs/man/nng_http_req_free.3http.adoc new file mode 100644 index 0000000..daa858b --- /dev/null +++ b/external/nng/docs/man/nng_http_req_free.3http.adoc @@ -0,0 +1,47 @@ += nng_http_req_free(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_free - free HTTP request structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_req_free(nng_http_req *req); +---- + +== DESCRIPTION + +The `nng_http_req_free()` function deallocates the HTTP request structure +_req_ entirely. + +TIP: Instead of freeing and reallocating request structures, it is possible +to reuse _req_ with xref:nng_http_req_reset.3http.adoc[`nng_http_req_reset()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_reset.3http.adoc[nng_http_req_reset(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_get_data.3http.adoc b/external/nng/docs/man/nng_http_req_get_data.3http.adoc new file mode 100644 index 0000000..e006bb1 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_get_data.3http.adoc @@ -0,0 +1,50 @@ += nng_http_req_get_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_get_data - get HTTP request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_req_get_data(nng_http_req *req, void **bodyp, size_t *sizep); +---- + +== DESCRIPTION + +The `nng_http_req_get_data()` gets the HTTP body associated with +the request _req_, storing a pointer to the buffer at the location referenced +by _bodyp_, and the length of the associated buffer at the location referenced +by _sizep_. + +NOTE: The buffer returned is owned by _req_, and will automatically freed +when the request is freed. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_get_header.3http.adoc b/external/nng/docs/man/nng_http_req_get_header.3http.adoc new file mode 100644 index 0000000..2b01f95 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_get_header.3http.adoc @@ -0,0 +1,52 @@ += nng_http_req_get_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_get_header - return HTTP request header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_req_get_header(nng_http_req *req, const char *key); +---- + +== DESCRIPTION + +The `nng_http_req_get_header()` looks for an HTTP header _key_ in +the request _req_, and returns the associated value if found, +or `NULL` if not found. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` will not find anything. + + +== RETURN VALUES + +HTTP header value for _key_, if it exists, or NULL otherwise. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], +xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_get_method.3http.adoc b/external/nng/docs/man/nng_http_req_get_method.3http.adoc new file mode 100644 index 0000000..85e8127 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_get_method.3http.adoc @@ -0,0 +1,46 @@ += nng_http_req_get_method(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_get_method - return HTTP request method + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_req_get_method(nng_http_req *req); +---- + +== DESCRIPTION + +The `nng_http_req_get_method()` returns the HTTP method associated with +the request _req_. +The value will be a string, such as "GET" or "POST". + + +== RETURN VALUES + +Request method as a string. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_get_uri.3http.adoc b/external/nng/docs/man/nng_http_req_get_uri.3http.adoc new file mode 100644 index 0000000..6239efc --- /dev/null +++ b/external/nng/docs/man/nng_http_req_get_uri.3http.adoc @@ -0,0 +1,47 @@ += nng_http_req_get_uri(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_get_uri - return HTTP request URI + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_req_get_uri(nng_http_req *req); +---- + +== DESCRIPTION + +The `nng_http_req_get_uri()` returns the URI (path) associated with the HTTP +request _req_. +The value returned includes the path, as well as any query information or +fragment. The value will look like a file system path +with those optional components appended, such as `/api/get_info.cgi?name=garrett`. + +== RETURN VALUES + +Request URI as a string. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_get_version.3http.adoc b/external/nng/docs/man/nng_http_req_get_version.3http.adoc new file mode 100644 index 0000000..ef526df --- /dev/null +++ b/external/nng/docs/man/nng_http_req_get_version.3http.adoc @@ -0,0 +1,45 @@ += nng_http_req_get_version(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_get_version - return HTTP request protocol version + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_req_get_version(nng_http_req *req); +---- + +== DESCRIPTION + +The `nng_http_req_get_version()` returns a string representing the HTTP +protocol version associated with the request _req_, such as "HTTP/1.1". + + +== RETURN VALUES + +Request version as a string. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_reset.3http.adoc b/external/nng/docs/man/nng_http_req_reset.3http.adoc new file mode 100644 index 0000000..58dcc14 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_reset.3http.adoc @@ -0,0 +1,48 @@ += nng_http_req_reset(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_reset - reset HTTP request structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_req_reset(nng_http_req *req); +---- + +== DESCRIPTION + +The `nng_http_req_reset()` function resets the request __req__ so that it +is just as if it had been freshly allocated with +xref:nng_http_req_alloc.3http.adoc[`nng_http_req_alloc()`] with a `NULL` URL. + +NOTE: Before using this with an HTTP operation, the URI must be set using +xref:nng_http_req_set_uri.3http.adoc[`nng_http_req_set_uri()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_set_data.3http.adoc b/external/nng/docs/man/nng_http_req_set_data.3http.adoc new file mode 100644 index 0000000..583d7a5 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_set_data.3http.adoc @@ -0,0 +1,64 @@ += nng_http_req_set_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_set_data - set HTTP request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_set_data(nng_http_req *req, const void *body, size_t size); +---- + +== DESCRIPTION + +The `nng_http_req_set_data()` sets the HTTP body associated with +the request _req_ to _body_, and the size of the body to _size_. +This body data will be automatically sent with the request when it +is sent using xref:nng_http_conn_write_req.3http.adoc[`nng_http_conn_write_req()`]. + +This also updates the relevant `Content-Length` header of _req_. + +NOTE: The current framework does not support sending data via chunked +transfer-encoding. + +The _body_ is *not* copied, and the caller must ensure that it is available +until the _req_ is deallocated. + +TIP: To have a local copy allocated with _req_ that will be automatically +deallocated when _req_ is freed, +see xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`]. + +TIP: It is a good idea to also set the `Content-Type` header. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_set_header.3http.adoc b/external/nng/docs/man/nng_http_req_set_header.3http.adoc new file mode 100644 index 0000000..e38b566 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_set_header.3http.adoc @@ -0,0 +1,59 @@ += nng_http_req_set_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_set_header - set HTTP request header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_set_header(nng_http_req *req, const char *key, + const char *val); +---- + +== DESCRIPTION + +The `nng_http_req_set_header()` sets the HTTP header for the request +_req_ and the _key_ to the _val_. +The _key_ and _val_ are copied. +Any previous header with the same _key_ is replaced. + +TIP: See xref:nng_http_req_add_header.3http.adoc[`nng_http_req_add_header()`] to +add additional headers with the same _key_ without replacing them. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], +xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], +xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_set_method.3http.adoc b/external/nng/docs/man/nng_http_req_set_method.3http.adoc new file mode 100644 index 0000000..bc80b83 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_set_method.3http.adoc @@ -0,0 +1,52 @@ += nng_http_req_set_method(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_set_method - set HTTP request method + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_set_method(nng_http_req *req, const char *method); +---- + +== DESCRIPTION + +The `nng_http_req_set_method()` sets the HTTP method associated with +the request _req_ to _method_. The _method_ must be a string, +such as "GET" or "POST", and the HTTP specifications indicate that it must +be upper case. + +The default value method for newly allocated requests is "GET". + +A local copy of the _method_ is made in the request _req_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_set_uri.3http.adoc b/external/nng/docs/man/nng_http_req_set_uri.3http.adoc new file mode 100644 index 0000000..fd6961d --- /dev/null +++ b/external/nng/docs/man/nng_http_req_set_uri.3http.adoc @@ -0,0 +1,59 @@ += nng_http_req_set_uri(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_set_uri - set HTTP request URI + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_set_uri(nng_http_req *req, const char *uri); +---- + +== DESCRIPTION + +The `nng_http_req_set_uri()` sets the Request-URI associated with +the request _req_ to _uri_. +The _uri_ should contain precisely the +string that will be sent to the HTTP server in the request, including +any query information or fragment. + +A local copy of the _uri_ is made in the request _req_. + +NOTE: No validation or canonicalization of the _uri_ is performed. + +TIP: The xref:nng_url_parse.3.adoc[`nng_url_parse()`] function can be used to +perform validation and canonicalization. +The `u_requri` member will +contain a suitable value that can be used with this function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri(3http)], +xref:nng_url_parse.3.adoc[nng_url_parse(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_req_set_version.3http.adoc b/external/nng/docs/man/nng_http_req_set_version.3http.adoc new file mode 100644 index 0000000..04fd1b0 --- /dev/null +++ b/external/nng/docs/man/nng_http_req_set_version.3http.adoc @@ -0,0 +1,58 @@ += nng_http_req_set_version(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_req_set_version - set HTTP request protocol version + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_req_set_version(nng_http_req *req, const char *version); +---- + +== DESCRIPTION + +The `nng_http_req_set_version()` sets the HTTP protocol version associated with +the request _req_ to _version_. +The _version_ must be a string containing +a valid HTTP protocol version, such as "HTTP/1.0". +The default value is "HTTP/1.1". + +A local copy of the _version_ is made in the request _req_. + +NOTE: No validation of the version supplied is performed. + +NOTE: The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". +Specifying any other version may result in unspecified behavior. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_add_header.3http.adoc b/external/nng/docs/man/nng_http_res_add_header.3http.adoc new file mode 100644 index 0000000..eb2a79c --- /dev/null +++ b/external/nng/docs/man/nng_http_res_add_header.3http.adoc @@ -0,0 +1,65 @@ += nng_http_res_add_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_add_header - add HTTP response header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_add_header(nng_http_res *res, const char *key, + const char *val); +---- + +== DESCRIPTION + +The `nng_http_res_add_header()` adds an HTTP header for the response +_res_ and the _key_ to the _val_. +The _key_ and _val_ are copied. + +If a header with the value of _key_ already exists, then a comma +and whitespace separate are appended to it, followed by _val_. + +If no such header already exists, then one is created with the value _val_. + +TIP: The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. + +TIP: See xref:nng_http_res_set_header.3http.adoc[`nng_http_res_set_header()`] if +replacement of an existing header rather than appending to it is desired. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], +xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], +xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_alloc.3http.adoc b/external/nng/docs/man/nng_http_res_alloc.3http.adoc new file mode 100644 index 0000000..f546d15 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_alloc.3http.adoc @@ -0,0 +1,68 @@ += nng_http_res_alloc(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_alloc - allocate HTTP response structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_alloc(nng_http_res **resp); +---- + +== DESCRIPTION + +The `nng_http_res_alloc()` function allocates a new HTTP response structure +and stores a pointer to it in __resp__. +The response will be initialized +with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `OK`, +and HTTP protocol version `HTTP/1.1`. + +TIP: When an error response is needed, consider using +xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res(3http)], +xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], +xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], +xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], +xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], +xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], +xref:nng_http_res_free.3http.adoc[nng_http_res_free(3http)], +xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], +xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason(3http)], +xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status(3http)], +xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version(3http)], +xref:nng_http_res_reset.3http.adoc[nng_http_res_reset(3http)], +xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], +xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], +xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], +xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_alloc_error.3http.adoc b/external/nng/docs/man/nng_http_res_alloc_error.3http.adoc new file mode 100644 index 0000000..2c8d729 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_alloc_error.3http.adoc @@ -0,0 +1,58 @@ += nng_http_res_alloc_error(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_alloc_error - allocate HTTP error response + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_alloc_error(nng_http_res **resp, uint16_t status); +---- + +== DESCRIPTION + +The `nng_http_res_alloc_error()` function allocates a new HTTP response structure +and stores a pointer to it in __resp__. +The response will be initialized +with the status code _status_, a corresponding reason phrase, and +a simple HTML page containing the same information will be generated and +attached to the response. +(Relevant HTTP headers will be set as well, such as `Content-Type` +and `Content-Length`.) +The HTTP protocol version is also set to "HTTP/1.1". + +TIP: This is the simplest way to generate an error response. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_free.3http.adoc[nng_http_res_free(3http)], +xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], +xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_copy_data.3http.adoc b/external/nng/docs/man/nng_http_res_copy_data.3http.adoc new file mode 100644 index 0000000..b2cea28 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_copy_data.3http.adoc @@ -0,0 +1,62 @@ += nng_http_res_copy_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_copy_data - copy HTTP response body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_copy_data(nng_http_res *res, const void *body, size_t size); +---- + +== DESCRIPTION + +The `nng_http_res_copy_data()` makes a copy of _body_ (of size __size__) +and sets the HTTP body for the response _res_ to it. +The copy will be deallocated automatically when _res_ is freed. + +The copied body data will be automatically sent with the response when it +is sent using xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`]. + +This also updates the relevant `Content-Length` header of _res_. + +NOTE: The current framework does not support sending data via chunked +transfer-encoding. + +TIP: To avoid copying data, the +xref:nng_http_res_set_data.3http.adoc[`nng_http_res_set_data()`] may be used instead. + +TIP: It is a good idea to also set the `Content-Type` header. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], +xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_del_header.3http.adoc b/external/nng/docs/man/nng_http_res_del_header.3http.adoc new file mode 100644 index 0000000..2a8500e --- /dev/null +++ b/external/nng/docs/man/nng_http_res_del_header.3http.adoc @@ -0,0 +1,52 @@ += nng_http_res_del_header(3http) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_del_header - delete HTTP response header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_del_header(nng_http_res *res, const char *key); +---- + +== DESCRIPTION + +The `nng_http_res_del_header()` removes all HTTP headers with the +associated _key_ from the response structure _res_. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: No header with the key _key_ was present. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], +xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], +xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_free.3http.adoc b/external/nng/docs/man/nng_http_res_free.3http.adoc new file mode 100644 index 0000000..c278648 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_free.3http.adoc @@ -0,0 +1,47 @@ += nng_http_res_free(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_free - free HTTP response structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_res_free(nng_http_res *req); +---- + +== DESCRIPTION + +The `nng_http_res_free()` function deallocates the HTTP response structure +_res_ entirely. + +TIP: Instead of freeing and reallocating response structures, it is possible +to reuse _res_ with xref:nng_http_res_reset.3http.adoc[`nng_http_res_reset()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_reset.3http.adoc[nng_http_res_reset(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_get_data.3http.adoc b/external/nng/docs/man/nng_http_res_get_data.3http.adoc new file mode 100644 index 0000000..374bce7 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_get_data.3http.adoc @@ -0,0 +1,50 @@ += nng_http_res_get_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_get_data - get HTTP response body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_res_get_data(nng_http_res *res, void **bodyp, size_t *sizep); +---- + +== DESCRIPTION + +The `nng_http_res_get_data()` gets the HTTP body associated with +the request _res_, storing a pointer to the buffer at the location referenced +by _bodyp_, and the length of the associated buffer at the location referenced +by _sizep_. + +NOTE: The buffer returned is owned by _res_, and will automatically freed +when the request is freed. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_req_alloc(3http)], +xref:nng_http_res_set_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng_http_res_copy_data.3http.adoc[nng_http_req_copy_data(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_get_header.3http.adoc b/external/nng/docs/man/nng_http_res_get_header.3http.adoc new file mode 100644 index 0000000..34c5b01 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_get_header.3http.adoc @@ -0,0 +1,52 @@ += nng_http_res_get_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_get_header - return HTTP response header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_res_get_header(nng_http_res *res, const char *key); +---- + +== DESCRIPTION + +The `nng_http_res_get_header()` looks for an HTTP header _key_ in +the response _res_, and returns the associated value if found, +or `NULL` if not found. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` will not find anything. + + +== RETURN VALUES + +HTTP header value for _key_, if it exists, or NULL otherwise. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], +xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_get_reason.3http.adoc b/external/nng/docs/man/nng_http_res_get_reason.3http.adoc new file mode 100644 index 0000000..a4167a0 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_get_reason.3http.adoc @@ -0,0 +1,48 @@ += nng_http_res_get_reason(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_get_reason - return HTTP response reason + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_res_get_reason(nng_http_res *res); +---- + +== DESCRIPTION + +The `nng_http_res_get_reason()` returns a string representing the +reason associated with the response _res_. +This is a human-readable explanation of the status code that +would be obtained from +xref:nng_http_res_get_status.3http.adoc[`nng_http_res_get_status()`]. + +== RETURN VALUES + +Reason as a string. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status(3http)], +xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_get_status.3http.adoc b/external/nng/docs/man/nng_http_res_get_status.3http.adoc new file mode 100644 index 0000000..0ad9092 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_get_status.3http.adoc @@ -0,0 +1,117 @@ += nng_http_res_get_status(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_get_status - return HTTP status code + +== SYNOPSIS + +[source, c] +---- +#include +#include + +uint16_t nng_http_res_get_status(nng_http_res *res); +---- + +== DESCRIPTION + +The `nng_http_res_get_status()` returns a numeric code corresponding to +the HTTP status of the response _res_. + +For convenience, a number of predefined symbols corresponding to well-known +HTTP status codes are available. + +[source, c] +---- +enum { + NNG_HTTP_STATUS_CONTINUE = 100, + NNG_HTTP_STATUS_SWITCHING = 101, + NNG_HTTP_STATUS_PROCESSING = 102, + NNG_HTTP_STATUS_OK = 200, + NNG_HTTP_STATUS_CREATED = 201, + NNG_HTTP_STATUS_ACCEPTED = 202, + NNG_HTTP_STATUS_NOT_AUTHORITATIVE = 203, + NNG_HTTP_STATUS_NO_CONTENT = 204, + NNG_HTTP_STATUS_RESET_CONTENT = 205, + NNG_HTTP_STATUS_PARTIAL_CONTENT = 206, + NNG_HTTP_STATUS_MULTI_STATUS = 207, + NNG_HTTP_STATUS_ALREADY_REPORTED = 208, + NNG_HTTP_STATUS_IM_USED = 226, + NNG_HTTP_STATUS_MULTIPLE_CHOICES = 300, + NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY = 301, + NNG_HTTP_STATUS_FOUND = 302, + NNG_HTTP_STATUS_SEE_OTHER = 303, + NNG_HTTP_STATUS_NOT_MODIFIED = 304, + NNG_HTTP_STATUS_USE_PROXY = 305, + NNG_HTTP_STATUS_TEMPORARY_REDIRECT = 307, + NNG_HTTP_STATUS_PERMANENT_REDIRECT = 308, + NNG_HTTP_STATUS_BAD_REQUEST = 400, + NNG_HTTP_STATUS_UNAUTHORIZED = 401, + NNG_HTTP_STATUS_PAYMENT_REQUIRED = 402, + NNG_HTTP_STATUS_FORBIDDEN = 403, + NNG_HTTP_STATUS_NOT_FOUND = 404, + NNG_HTTP_STATUS_METHOD_NOT_ALLOWED = 405, + NNG_HTTP_STATUS_NOT_ACCEPTABLE = 406, + NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED = 407, + NNG_HTTP_STATUS_REQUEST_TIMEOUT = 408, + NNG_HTTP_STATUS_CONFLICT = 409, + NNG_HTTP_STATUS_GONE = 410, + NNG_HTTP_STATUS_LENGTH_REQUIRED = 411, + NNG_HTTP_STATUS_PRECONDITION_FAILED = 412, + NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE = 413, + NNG_HTTP_STATUS_ENTITY_TOO_LONG = 414, + NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415, + NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE = 416, + NNG_HTTP_STATUS_EXPECTATION_FAILED = 417, + NNG_HTTP_STATUS_TEAPOT = 418, + NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY = 422, + NNG_HTTP_STATUS_LOCKED = 423, + NNG_HTTP_STATUS_FAILED_DEPENDENCY = 424, + NNG_HTTP_STATUS_UPGRADE_REQUIRED = 426, + NNG_HTTP_STATUS_PRECONDITION_REQUIRED = 428, + NNG_HTTP_STATUS_TOO_MANY_REQUESTS = 429, + NNG_HTTP_STATUS_HEADERS_TOO_LARGE = 431, + NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS = 451, + NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, + NNG_HTTP_STATUS_NOT_IMPLEMENTED = 501, + NNG_HTTP_STATUS_BAD_GATEWAY = 502, + NNG_HTTP_STATUS_SERVICE_UNAVAILABLE = 503, + NNG_HTTP_STATUS_GATEWAY_TIMEOUT = 504, + NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP = 505, + NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES = 506, + NNG_HTTP_STATUS_INSUFFICIENT_STORAGE = 507, + NNG_HTTP_STATUS_LOOP_DETECTED = 508, + NNG_HTTP_STATUS_NOT_EXTENDED = 510, + NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED = 511, +} +---- + +TIP: When displaying status information to users (or logging such information), +consider also including the reason obtained with +xref:nng_http_res_get_reason.3http.adoc[`nng_http_res_get_reason()`]. + +== RETURN VALUES + +HTTP status code. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason(3http)], +xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_get_version.3http.adoc b/external/nng/docs/man/nng_http_res_get_version.3http.adoc new file mode 100644 index 0000000..d69e387 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_get_version.3http.adoc @@ -0,0 +1,45 @@ += nng_http_res_get_version(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_get_version - return HTTP response protocol version + +== SYNOPSIS + +[source, c] +---- +#include +#include + +const char *nng_http_res_get_version(nng_http_res *res); +---- + +== DESCRIPTION + +The `nng_http_res_get_version()` returns a string representing the HTTP +protocol version associated with the request _res_, such as "HTTP/1.1". + + +== RETURN VALUES + +Response version as a string. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_reset.3http.adoc b/external/nng/docs/man/nng_http_res_reset.3http.adoc new file mode 100644 index 0000000..f78d29a --- /dev/null +++ b/external/nng/docs/man/nng_http_res_reset.3http.adoc @@ -0,0 +1,44 @@ += nng_http_res_reset(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_reset - reset HTTP response structure + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_res_reset(nng_http_res *res); +---- + +== DESCRIPTION + +The `nng_http_res_reset()` function resets the response __res__ so that it +is just as if it had been freshly allocated with +xref:nng_http_res_alloc.3http.adoc[`nng_http_res_alloc()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_set_data.3http.adoc b/external/nng/docs/man/nng_http_res_set_data.3http.adoc new file mode 100644 index 0000000..7c4c06b --- /dev/null +++ b/external/nng/docs/man/nng_http_res_set_data.3http.adoc @@ -0,0 +1,64 @@ += nng_http_res_set_data(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_set_data - set HTTP response body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_set_data(nng_http_res *res, const void *body, size_t size); +---- + +== DESCRIPTION + +The `nng_http_res_set_data()` sets the HTTP body associated with +the response _res_ to _body_, and the size of the body to _size_. +This body data will be automatically sent with the response when it +is sent using xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`]. + +This also updates the relevant `Content-Length` header of _res_. + +NOTE: The current framework does not support sending data via chunked +transfer-encoding. + +The _body_ is *not* copied, and the caller must ensure that it is available +until the _res_ is deallocated. + +TIP: To have a local copy allocated with _res_ that will be automatically +deallocated when _res_ is freed, +see xref:nng_http_res_copy_data.3http.adoc[`nng_http_res_copy_data()`]. + +TIP: It is a good idea to also set the `Content-Type` header. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], +xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_set_header.3http.adoc b/external/nng/docs/man/nng_http_res_set_header.3http.adoc new file mode 100644 index 0000000..2ad4282 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_set_header.3http.adoc @@ -0,0 +1,59 @@ += nng_http_res_set_header(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_set_header - set HTTP response header + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_set_header(nng_http_res *res, const char *key, + const char *val); +---- + +== DESCRIPTION + +The `nng_http_res_set_header()` sets the HTTP header for the response +_res_ and the _key_ to the _val_. +The _key_ and _val_ are copied. +Any previous header with the same _key_ is replaced. + +TIP: See xref:nng_http_res_add_header.3http.adoc[`nng_http_res_add_header()`] to +add additional headers with the same _key_ without replacing them. + +The value of _key_ is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying `Host` or `hOSt` are +equivalent, whereas the value `Host:` is not a legal header key. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], +xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], +xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_set_reason.3http.adoc b/external/nng/docs/man/nng_http_res_set_reason.3http.adoc new file mode 100644 index 0000000..50699de --- /dev/null +++ b/external/nng/docs/man/nng_http_res_set_reason.3http.adoc @@ -0,0 +1,56 @@ += nng_http_res_set_reason(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_set_reason - set HTTP response reason + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_set_reason(nng_http_res *res, const char *reason); +---- + +== DESCRIPTION + +The `nng_http_res_set_reason()` sets the human readable reason +associated with the response _res_ to _reason_. + +If the value of _reason_ is `NULL` (the default), then a default reason +phrase is supplied based upon the value of the status code (see +xref:nng_http_res_set_status.3http.adoc[`nng_http_res_set_status()`]). + +TIP: The _reason_ is never parsed automatically, but it can be a hint for humans + to help them understand the nature of any erroneous result. + +A local copy of the _reason_ is made in the response _res_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_get_reason.3http.adoc[nng_http_req_get_reason(3http)], +xref:nng_http_res_set_status.3http.adoc[nng_http_req_set_status(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_set_status.3http.adoc b/external/nng/docs/man/nng_http_res_set_status.3http.adoc new file mode 100644 index 0000000..e57764d --- /dev/null +++ b/external/nng/docs/man/nng_http_res_set_status.3http.adoc @@ -0,0 +1,124 @@ += nng_http_res_set_status(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_set_status - set HTTP response status + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_set_status(nng_http_res *res, uint16_t status); +---- + +== DESCRIPTION + +The `nng_http_res_set_status()` sets the numeric HTTP status code +associated with the response _res_ to _status_. +The default value for a newly allocated response is 200 (`NNG_HTTP_STATUS_OK`). + +The _status_ is not verified, so the caller should take care to ensure +that only a valid code is supplied. + +For convenience, a number of predefined symbols are available. + +[source, c] +---- +enum { + NNG_HTTP_STATUS_CONTINUE = 100, + NNG_HTTP_STATUS_SWITCHING = 101, + NNG_HTTP_STATUS_PROCESSING = 102, + NNG_HTTP_STATUS_OK = 200, + NNG_HTTP_STATUS_CREATED = 201, + NNG_HTTP_STATUS_ACCEPTED = 202, + NNG_HTTP_STATUS_NOT_AUTHORITATIVE = 203, + NNG_HTTP_STATUS_NO_CONTENT = 204, + NNG_HTTP_STATUS_RESET_CONTENT = 205, + NNG_HTTP_STATUS_PARTIAL_CONTENT = 206, + NNG_HTTP_STATUS_MULTI_STATUS = 207, + NNG_HTTP_STATUS_ALREADY_REPORTED = 208, + NNG_HTTP_STATUS_IM_USED = 226, + NNG_HTTP_STATUS_MULTIPLE_CHOICES = 300, + NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY = 301, + NNG_HTTP_STATUS_FOUND = 302, + NNG_HTTP_STATUS_SEE_OTHER = 303, + NNG_HTTP_STATUS_NOT_MODIFIED = 304, + NNG_HTTP_STATUS_USE_PROXY = 305, + NNG_HTTP_STATUS_TEMPORARY_REDIRECT = 307, + NNG_HTTP_STATUS_PERMANENT_REDIRECT = 308, + NNG_HTTP_STATUS_BAD_REQUEST = 400, + NNG_HTTP_STATUS_UNAUTHORIZED = 401, + NNG_HTTP_STATUS_PAYMENT_REQUIRED = 402, + NNG_HTTP_STATUS_FORBIDDEN = 403, + NNG_HTTP_STATUS_NOT_FOUND = 404, + NNG_HTTP_STATUS_METHOD_NOT_ALLOWED = 405, + NNG_HTTP_STATUS_NOT_ACCEPTABLE = 406, + NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED = 407, + NNG_HTTP_STATUS_REQUEST_TIMEOUT = 408, + NNG_HTTP_STATUS_CONFLICT = 409, + NNG_HTTP_STATUS_GONE = 410, + NNG_HTTP_STATUS_LENGTH_REQUIRED = 411, + NNG_HTTP_STATUS_PRECONDITION_FAILED = 412, + NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE = 413, + NNG_HTTP_STATUS_ENTITY_TOO_LONG = 414, + NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415, + NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE = 416, + NNG_HTTP_STATUS_EXPECTATION_FAILED = 417, + NNG_HTTP_STATUS_TEAPOT = 418, + NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY = 422, + NNG_HTTP_STATUS_LOCKED = 423, + NNG_HTTP_STATUS_FAILED_DEPENDENCY = 424, + NNG_HTTP_STATUS_UPGRADE_REQUIRED = 426, + NNG_HTTP_STATUS_PRECONDITION_REQUIRED = 428, + NNG_HTTP_STATUS_TOO_MANY_REQUESTS = 429, + NNG_HTTP_STATUS_HEADERS_TOO_LARGE = 431, + NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS = 451, + NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, + NNG_HTTP_STATUS_NOT_IMPLEMENTED = 501, + NNG_HTTP_STATUS_BAD_GATEWAY = 502, + NNG_HTTP_STATUS_SERVICE_UNAVAILABLE = 503, + NNG_HTTP_STATUS_GATEWAY_TIMEOUT = 504, + NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP = 505, + NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES = 506, + NNG_HTTP_STATUS_INSUFFICIENT_STORAGE = 507, + NNG_HTTP_STATUS_LOOP_DETECTED = 508, + NNG_HTTP_STATUS_NOT_EXTENDED = 510, + NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED = 511, +}; +---- + +Please see the relevant HTTP RFCs for the semantics and correct +use of these status codes. + +TIP: It is a good idea to also set the reason message with +xref:nng_http_res_set_reason.3http.adoc[`nng_http_set_reason()`]. +This will help any humans who may have to diagnose a failure. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_res_get_status.3http.adoc[nng_http_req_get_status(3http)], +xref:nng_http_res_set_reason.3http.adoc[nng_http_req_set_reason(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_res_set_version.3http.adoc b/external/nng/docs/man/nng_http_res_set_version.3http.adoc new file mode 100644 index 0000000..23c2531 --- /dev/null +++ b/external/nng/docs/man/nng_http_res_set_version.3http.adoc @@ -0,0 +1,58 @@ += nng_http_res_set_version(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_res_set_version - set HTTP response protocol version + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_res_set_version(nng_http_res *res, const char *version); +---- + +== DESCRIPTION + +The `nng_http_res_set_version()` sets the HTTP protocol version associated with +the response _res_ to _version_. +The _version_ must be a string containing +a valid HTTP protocol version, such as "HTTP/1.0". +The default value is "HTTP/1.1". + +A local copy of the _version_ is made in the response _res_. + +NOTE: No validation of the version supplied is performed. + +NOTE: The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". +Specifying any other version may result in unspecified behavior. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], +xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_add_handler.3http.adoc b/external/nng/docs/man/nng_http_server_add_handler.3http.adoc new file mode 100644 index 0000000..5b5c474 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_add_handler.3http.adoc @@ -0,0 +1,59 @@ += nng_http_server_add_handler(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_add_handler - add HTTP server handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_add_handler(nng_http_server *s, nng_http_handler *h); +---- + +== DESCRIPTION + +The `nng_http_server_add_handler()` adds the handler _h_ to the server +instance _s_. + +If another handler is already added to the server that would conflict +with handler _h_, then the operation will fail with `NNG_EADDRINUSE`. + +If a handler is added to a server, and the server is subsequently +deallocated, the handler and any of its resources will also be deallocated. + +Handlers that are added to a server may be subsequently removed using the +xref:nng_http_server_del_handler.3http.adoc[`nng_http_server_del_handler()`] function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: Handler conflicts with another handler. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + + +[.text-left] +xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], +xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler(3http)], +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_del_handler.3http.adoc b/external/nng/docs/man/nng_http_server_del_handler.3http.adoc new file mode 100644 index 0000000..4ff89f7 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_del_handler.3http.adoc @@ -0,0 +1,50 @@ += nng_http_server_del_handler(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_del_handler - delete HTTP server handler + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_del_handler(nng_http_server *s, nng_http_handler *h); +---- + +== DESCRIPTION + +The `nng_http_server_del_handler()` removes the handler _h_ from the server +instance _s_. + +Once a handler has been deleted from a server, it is the responsibility +of the caller to dispose of the handler, or add it to another server instance. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: Handler is not registered with server. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_handler_free.3http.adoc[nng_http_handler_free(3http)], +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_get_addr.3http.adoc b/external/nng/docs/man/nng_http_server_get_addr.3http.adoc new file mode 100644 index 0000000..dc69901 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_get_addr.3http.adoc @@ -0,0 +1,46 @@ += nng_http_server_get_addr(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_get_addr - get HTTP server address + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_get_addr(nng_http_server *server, nng_sockaddr *sap); +---- + +== DESCRIPTION + +`nng_http_server_get_addr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_ for the server _server_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EINVAL`:: Either _server_ or _sap_ parameter is NULL. +`NNG_ENOTSUP`:: HTTP not supported. + + +== SEE ALSO + +[.text-left] +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_get_tls.3http.adoc b/external/nng/docs/man/nng_http_server_get_tls.3http.adoc new file mode 100644 index 0000000..51bc721 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_get_tls.3http.adoc @@ -0,0 +1,59 @@ += nng_http_server_get_tls(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_get_tls - get HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_get_tls(nng_http_server *s, nng_tls_config **cfgp); +---- + +== DESCRIPTION + +The `nng_http_server_get_tls()` obtains the TLS configuration of server _s_ and +saves a pointer to it in the address referenced by _cfgp_. + +The object will be returned with an extra hold (see +xref:nng_tls_config_hold.3tls.adoc[`nng_tls_config_hold()`]) +placed on it on behalf of the caller. +The caller should free this hold by calling +xref:nng_tls_config_free.3tls.adoc[`nng_tls_config_free()`] with it is done +with the TLS configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: TLS not configured on server. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_set_tls.3http.adoc[nng_http_server_set_tls(3http)], +xref:nng_http_server_start.3http.adoc[nng_http_server_start(3http)], +xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], +xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free(3tls)], +xref:nng_tls_config_hold.3tls.adoc[nng_tls_config_hold(3tls)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_hold.3http.adoc b/external/nng/docs/man/nng_http_server_hold.3http.adoc new file mode 100644 index 0000000..0111d43 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_hold.3http.adoc @@ -0,0 +1,66 @@ += nng_http_server_hold(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_hold - get and hold HTTP server instance + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_hold(nng_http_server **serverp, const nng_url *url); +---- + +== DESCRIPTION + +The `nng_http_server_hold()` acquires an instance of an HTTP server suitable +for use in serving the URL identified by _url_, and stores a pointer to it +at the location pointed to by _serverp_. + +This function first looks to see if an existing HTTP server instance exists, +that is suitable for this. +If so, it increments the reference count on it and uses that. +Otherwise, it will attempt to create a new server instance +with an initial reference count of one (1). + +The server instance is not started, and can have additional configuration +applied to it before it is later started with +xref:nng_http_server_start.3http.adoc[`nng_http_server_start()`]. + +NOTE: The URL matching logic in determining servers is unable to distinguish +between different aliases for the same local IP address. +This may create problems when using URLs for virtual hosting. +It is recommended to use canonical IP addresses or names in the +_url_ to avoid confusion. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], +xref:nng_http_server_release.3http.adoc[nng_http_server_release(3http)], +xref:nng_http_server_stop.3http.adoc[nng_http_server_stop(3http)], +xref:nng_url_parse.3.adoc[nng_url_parse(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_release.3http.adoc b/external/nng/docs/man/nng_http_server_release.3http.adoc new file mode 100644 index 0000000..0d91919 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_release.3http.adoc @@ -0,0 +1,54 @@ += nng_http_server_release(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_release - release HTTP server instance + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_server_release(nng_http_server *server); +---- + +== DESCRIPTION + +The `nng_http_server_release()` releases an instance of an HTTP _server_ +that was previously held with +xref:nng_http_server_hold.3http.adoc[`nng_http_server_hold()`]. + +This effectively drops the reference count on the server instance. When +the reference count drops to zero, then the _server_ and all resources +associated with it (e.g. HTTP handlers, connections, etc.) are deallocated. +(If the server is "running" when this occurs, then the server is stopped.) + +IMPORTANT: It is an error to release an instance of a server that has +not previously been held, or to attempt to release an instance more +times than it has been held. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_stop.3http.adoc[nng_http_server_stop(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_res_error.3http.adoc b/external/nng/docs/man/nng_http_server_res_error.3http.adoc new file mode 100644 index 0000000..b669a06 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_res_error.3http.adoc @@ -0,0 +1,63 @@ += nng_http_server_res_error(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_res_error - use HTTP server error page + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_res_error(nng_http_server *server, + nng_http_res *response); +---- + +== DESCRIPTION + +The `nng_http_server_res_error()` sets the body of _response_ +to _server_'s error page, which may have been customized using the +xref:nng_http_server_set_error_file.3http.adoc[`nng_http_server_error_file()`] +or +xref:nng_http_server_set_error_page.3http.adoc[`nng_http_server_error_page()`] +functions. + +The status code of the _response_ should have already been set, either +implicitly by allocating it with +xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`], +or by calling +xref:nng_http_res_set_status.3http.adoc[`nng_http_res_set_status()`]. + +Any content body previously set for _response_ will be overridden by +this function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file(3http)], +xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_set_error_file.3http.adoc b/external/nng/docs/man/nng_http_server_set_error_file.3http.adoc new file mode 100644 index 0000000..ac38f6f --- /dev/null +++ b/external/nng/docs/man/nng_http_server_set_error_file.3http.adoc @@ -0,0 +1,73 @@ += nng_http_server_set_error_file(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_set_error_file - set custom HTTP error file + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_error_file(nng_http_server *server, + uint16_t code, const char *path); +---- + +== DESCRIPTION + +The `nng_http_server_set_error_file()` sets an error page to be used +for HTTP status _code_ on the server instance _server_. +The body content of the HTTP responses will contain the file contents of +the file located at _path_, which should be an HTML file. + +The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] +function. +This HTML content will also be used if the application calls the +xref:nng_http_server_res_error.3http.adoc[`nng_http_server_res_error()`]. +The last custom error page set for _code_ by either this function or +xref:`nng_http_server_set_error_page.3http.adoc[`nng_http_server_error_page()`] +will be used. + +NOTE: Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. + +NOTE: The file contents of _path_ are read when this function is called. +Therefore, if the file contents are changed, then this function should +be called again to update the error page. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: The file named by _path_ does not exist. +`NNG_EPERM`:: No permission to read the file named by _path_. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error(3http)], +xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_set_error_page.3http.adoc b/external/nng/docs/man/nng_http_server_set_error_page.3http.adoc new file mode 100644 index 0000000..d3b136d --- /dev/null +++ b/external/nng/docs/man/nng_http_server_set_error_page.3http.adoc @@ -0,0 +1,69 @@ += nng_http_server_set_error_page(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_set_error_page - set custom HTTP error page + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_error_page(nng_http_server *server, + uint16_t code, const char *html); +---- + +== DESCRIPTION + +The `nng_http_server_set_error_page()` sets an error page to be used +for HTTP status _code_ on the server instance _server_. +The body content of the HTTP responses will contain _html_. + +The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] +function. +This HTML content will also be used if the application calls the +xref:nng_http_server_res_error.3http.adoc[`nng_http_server_res_error()`]. +The last custom error page set for _code_ by either this function or +xref:nng_http_server_set_error_file.3http.adoc[`nng_http_server_error_file()`] +will be used. + +NOTE: Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. + +The supplied HTML content is copied by this function, and may be reused +after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error(3http)], +xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file(3http)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_set_tls.3http.adoc b/external/nng/docs/man/nng_http_server_set_tls.3http.adoc new file mode 100644 index 0000000..1fe8eaa --- /dev/null +++ b/external/nng/docs/man/nng_http_server_set_tls.3http.adoc @@ -0,0 +1,62 @@ += nng_http_server_set_tls(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_set_tls - set HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_tls(nng_http_server *s, nng_tls_config *cfg); +---- + +== DESCRIPTION + +The `nng_http_server_set_tls()` sets the TLS configuration of server _s_ to +_cfg_. + +This change overwrites any previous TLS configuration. + +IMPORTANT: This also invalidates any previously obtained values from +xref:nng_http_server_get_tls.3http.adoc[`nng_http_server_get_tls()`]. + +If the server is already running (i.e. it has been started with +xref:nng_http_server_start.3http.adoc[`nng_http_server_start()`]) then this will +fail with `NNG_EBUSY`. + +TIP: Generally, the _cfg_ must have a configured private key, set with +xref:nng_tls_config_own_cert.3tls.adoc[`nng_tls_config_own_cert()`] or similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBUSY`:: Server instance is running. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_get_tls.3http.adoc[nng_http_server_get_tls(3http)], +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_start.3http.adoc[nng_http_server_start(3http)], +xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_start.3http.adoc b/external/nng/docs/man/nng_http_server_start.3http.adoc new file mode 100644 index 0000000..31e0f32 --- /dev/null +++ b/external/nng/docs/man/nng_http_server_start.3http.adoc @@ -0,0 +1,52 @@ += nng_http_server_start(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_start - start HTTP server + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_start(nng_http_server *server); +---- + +== DESCRIPTION + +The `nng_http_server_start()` starts the HTTP server instance _server_. +This causes it to bind to the appropriate TCP port, and start accepting +connections and handling HTTP requests. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: The TCP port is unavailable. +`NNG_EADDRINVAL`:: The server is configured with an invalid address. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_release.3http.adoc[nng_http_server_release(3http)], +xref:nng_http_server_stop.3http.adoc[nng_http_server_stop(3http)], +xref:nng_url_parse.3.adoc[nng_url_parse(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_http_server_stop.3http.adoc b/external/nng/docs/man/nng_http_server_stop.3http.adoc new file mode 100644 index 0000000..098d7bd --- /dev/null +++ b/external/nng/docs/man/nng_http_server_stop.3http.adoc @@ -0,0 +1,60 @@ += nng_http_server_stop(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_http_server_stop - stop HTTP server + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_server_stop(nng_http_server *server); +---- + +== DESCRIPTION + +The `nng_http_server_stop()` undoes the effect of +xref:nng_http_server_start.3http.adoc[`nng_http_server_start()`]. + +Each call by +xref:nng_http_server_start.3http.adoc[`nng_http_server_start()`] acts as reference +count, and should be matched by a call to `nng_http_server_stop()`. +When the reference count drops to zero, then the server is actually stopped, +and existing open connections to it are closed. + +This function does not wait for the connections to close. + +NOTE: Once the server instance is actually stopped, it cannot be started again, +and any future calls to xref:nng_http_server_hold.3http.adoc[`nng_http_server_hold()`] +will return a new instance of the server. +It is expected that the caller will follow this function call with a call to +xref:nng_http_server_release.3http.adoc[`nng_http_server_release()`]. + + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], +xref:nng_http_server_release.3http.adoc[nng_http_server_release(3http)], +xref:nng_http_server_start.3http.adoc[nng_http_server_start(3http)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_id_map.3supp.adoc b/external/nng/docs/man/nng_id_map.3supp.adoc new file mode 100644 index 0000000..343c066 --- /dev/null +++ b/external/nng/docs/man/nng_id_map.3supp.adoc @@ -0,0 +1,100 @@ += nng_id_map(3supp) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_id_map - identifier based mapping table + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef struct nng_id_map_s nng_id_map; + +#define NNG_MAP_RANDOM 1 + +int nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags); +void nng_id_map_free(nng_id_map *map); +void *nng_id_get(nng_id_map *map, uint64_t id); +int nng_id_set(nng_id_map *map, uint64_t, void *value); +int nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value); +int nng_id_remove(nng_id_map *map, uint64_t id); + +---- + +== DESCRIPTION + +These functions provide support for managing tables of data based on +identifiers, ensuring that identifiers are allocated uniquely and within +specified range limits. + +The table stores data pointers (which must not be `NULL`) at a logical numeric index. +It does so efficiently, even if large gaps exist, and it provides a means to efficiently +allocate a numeric identifier from a pool of unused identifiers. + +Identifiers are allocated in increasing order, without reusing old identifiers until the +largest possible identifier is allocated. After wrapping, only identifiers that are no longer +in use will be considered. +No effort to order the availability of identifiers based on when they were freed is made. + +An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_, +and the largest legal identifier in _hi_. +The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. + +**** +As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed. +If identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the +exact values desired. +**** + +The _flags_ argument is a bit mask of flags for the table. +If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. +This is useful to reduce the odds of different instances of an application using the same identifiers at the same time. + +The `nng_id_get()` function returns the value previously stored with the given identifier. +If no value is currently associated with the identifer, it returns `NULL`. + +The `nng_id_set()` function sets the value with the associated identifier. +This can be used to replace a previously allocated identifier. +If the identifier was not previously allocated, then it is allocated as part of the call. +This function does not necessarily honor the identifier range limits set for the map when it was allocated. + +The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with +the supplied _value_. + +The `nng_id_remove()` function removes the identifier and its associated value from the table. + +NOTE: These functions are limited to storing at most 2^32^ identifiers, even though the identifers may +themselves be larger than 2^32^. + +IMPORTANT: These functions are *not* thread-safe. +Callers should use a xref:nng_mtx_lock.3supp[mutex] or similar approach when thread-safety is needed. + +== RETURN VALUES + +The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions +return 0 on success, or -1 on failure. + +The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: The _id_ does not exist in the table. +`NNG_ENOMEM`:: Insufficient memory is available, or the table is full. + +== SEE ALSO + +[.text-left] +xref:nng_mtx_lock.3supp.adoc[nng(7)] +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_inproc.7.adoc b/external/nng/docs/man/nng_inproc.7.adoc new file mode 100644 index 0000000..833ba35 --- /dev/null +++ b/external/nng/docs/man/nng_inproc.7.adoc @@ -0,0 +1,75 @@ += nng_inproc(7) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_inproc - intra-process transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_inproc_register(void); +---- + +== DESCRIPTION + +(((transport, _inproc_))) +(((intra-process))) +The ((_inproc_ transport)) provides communication support between +sockets within the same process. +This may be used as an alternative +to slower transports when data must be moved within the same process. + +This transport tries hard to avoid copying data, and thus is very +light-weight. + +=== Registration + +This transport is generally built-in to the core, so +no extra steps to use it should be necessary. + +=== URI Format +(((URI, `inproc://`))) +This transport uses URIs using the scheme `inproc://`, followed by +an arbitrary string of text, terminated by a `NUL` byte. + +Multiple URIs can be used within the +same application, and they will not interfere with one another. + +Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI. + +=== Socket Address + +When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, +the actual structure is of type +xref:nng_sockaddr_inproc.5.adoc[`nng_sockaddr_inproc`]. + +=== Transport Options + +The _inproc_ transport has no special options. + +NOTE: While _inproc_ accepts the option +xref:nng_options.5.adoc#NNG_OPT_RECVMAXSZ[`NNG_OPT_RECVMAXSZ`] for +compatibility, the value of the option is ignored with no enforcement. +As _inproc_ peers are in the same address space, they are implicitly trusted, +and thus it makes no sense to spend cycles protecting a program from itself. + +== SEE ALSO + +[.text-left] +xref:nng_inproc_register.3.adoc[nng_inproc_register(3)], +xref:nng_sockaddr_inproc.5.adoc[nng_sockaddr_inproc(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_inproc_register.3.adoc b/external/nng/docs/man/nng_inproc_register.3.adoc new file mode 100644 index 0000000..8379a4e --- /dev/null +++ b/external/nng/docs/man/nng_inproc_register.3.adoc @@ -0,0 +1,47 @@ += nng_inproc_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_inproc_register - register inproc transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_inproc_register(void); +---- + +== DESCRIPTION + +The `nng_inproc_register()` function registers the +((_inproc_ transport))(((transport, _inproc_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_inproc.7.adoc[nng_inproc(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_iov.5.adoc b/external/nng/docs/man/nng_iov.5.adoc new file mode 100644 index 0000000..5c3e3c4 --- /dev/null +++ b/external/nng/docs/man/nng_iov.5.adoc @@ -0,0 +1,55 @@ += nng_iov(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_iov - scatter/gather element + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct { + void * iov_buf; + size_t iov_len; +} nng_iov; +---- + +== DESCRIPTION + +An `nng_iov` structure represents a single element in a ((scatter/gather)) +array. +Some operations can use arrays of these to access different regions of +memory in a single operation. +For example, it may be useful to send a message with header data from +one part of memory, and a user payload from another. + +The operations that do this typically store an array of these in +an xref:nng_aio.5.adoc[`nng_aio`] structure using the +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function. + +The following structure members are present: + +`iov_buf`:: + This is a pointer to the first byte within the memory being + referenced by this scatter/gather element. + +`iov_len`:: + This is the size in bytes of this scatter/gather element. + +== SEE ALSO + +[.text-left] +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ipc.7.adoc b/external/nng/docs/man/nng_ipc.7.adoc new file mode 100644 index 0000000..c085e4d --- /dev/null +++ b/external/nng/docs/man/nng_ipc.7.adoc @@ -0,0 +1,126 @@ += nng_ipc(7) +// +// Copyright 2023 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ipc - IPC transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_ipc_register(void); +---- + +== DESCRIPTION + +(((IPC)))(((transport, _ipc_))) +The ((_ipc_ transport)) provides communication support between +sockets within different processes on the same host. +For POSIX platforms, this is implemented using ((UNIX domain sockets)). +For Windows, this is implemented using Windows ((Named Pipes)). +Other platforms may have different implementation strategies. + +// We need to insert a reference to the nanomsg RFC. + +=== Registration + +This transport is generally built-in to the core, so +no extra steps to use it should be necessary. + +=== URI Formats + +==== Traditional Names + +(((URI, `ipc://`))) +This transport uses URIs using the scheme `ipc://`, followed by a path +name in the file system where the socket or named pipe should be created. + +TIP: On Windows, all names are prefixed by `\\.\pipe\` and do not +reside in the normal file system. +On POSIX platforms, the path is taken literally, and is relative to +the current directory, unless it begins with `/`, in which case it is +relative to the root directory. + +NOTE: When using relative paths on POSIX systems, the address used and returned +in properties like `NNG_OPT_LOCADDR` and `NNG_OPT_URL` will also be relative. +Consequently, they will only be interpreted the same by processes that have +the same working directory. +To ensure maximum portability and safety, absolute paths are recommended +whenever possible. + +NOTE: If compatibility with legacy _nanomsg_ applications is required, +then path names must not be longer than 122 bytes, including the final +`NUL` byte. +This is because legacy versions of _nanomsg_ cannot express URLs +longer than 128 bytes, including the `ipc://` prefix. + +==== UNIX Aliases + +(((URI, `unix://`))) +The `unix://` scheme is an alias for `ipc://` and can be used inter-changeably, but only +on POSIX systems. + +The purpose of this scheme is to support a future transport making use of `AF_UNIX` +on Windows systems, at which time it will be necessary to discriminate between +the Named Pipes and the `AF_UNIX` based transports. + +==== Abstract Names + +(((URI, `abstract://`))) +On Linux, this transport also can support abstract sockets. +Abstract sockets use a URI-encoded name after the scheme, which allows arbitrary values to be conveyed +in the path, including embedded `NUL` bytes. +For example, the name `"a\0b"` would be represented as `abstract://a%00b`. + +TIP: An empty name may be used with a listener to request "`auto bind`" be used to select a name. +In this case the system will allocate a free name. +The name assigned may be retrieved using `NNG_OPT_LOCADDR`. + +NOTE: _NNG_ cannot represent an abstract socket with the empty name. + +NOTE: Abstract names do not include the leading `NUL` byte used in the low-level socket address. + +Abstract sockets do not have any representation in the file system, and are automatically freed by +the system when no longer in use. +Abstract sockets ignore socket permissions, but it is still possible to determine the credentials +of the peer with `NNG_OPT_PEER_UID`, etc. + +=== Socket Address + +When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, +the actual structure is of type xref:nng_sockaddr_ipc.5.adoc[`nng_sockaddr_ipc`], +except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_sockaddr_abstract`]. + +=== Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PERMISSIONS[`NNG_OPT_IPC_PERMISSIONS`] +* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_SECURITY_DESCRIPTOR[`NNG_OPT_IPC_SECURITY_DESCRIPTOR`] +* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] +* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`] +* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`] +* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`] +* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`] +* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`] +* xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`] + +== SEE ALSO + +[.text-left] +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_ipc_options.5.adoc b/external/nng/docs/man/nng_ipc_options.5.adoc new file mode 100644 index 0000000..516fbe8 --- /dev/null +++ b/external/nng/docs/man/nng_ipc_options.5.adoc @@ -0,0 +1,110 @@ += nng_ipc_options(5) +// +// Copyright 2023 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// 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_ipc_options - IPC-specific options + +== SYNOPSIS + +[source, c] +---- +#include + +#define NNG_OPT_IPC_PEER_GID "ipc:peer-gid" +#define NNG_OPT_IPC_PEER_PID "ipc:peer-pid" +#define NNG_OPT_IPC_PEER_UID "ipc:peer-uid" +#define NNG_OPT_IPC_PEER_ZONEID "ipc:peer-zoneid" +#define NNG_OPT_IPC_PERMISSIONS "ipc:permissions" +#define NNG_OPT_IPC_SECURITY_DESCRIPTOR "ipc:security-descriptor" +---- + +== DESCRIPTION + +This page documents the various standard options that can be set or +retrieved on objects using IPC. + +The option names should always be used by their symbolic definitions. + +In the following list of options, the name of the option is supplied, +along with the data type of the underlying value. + +Some options are only meaningful or supported in certain contexts, or may +have other access restrictions. +An attempt has been made to include details about such restrictions in the +description of the option. + +NOTE: The availability of the following options is platform-specific, +as the implementations of IPC are quite different on Windows and POSIX systems. + +[[NNG_OPT_IPC_PERMISSIONS]]((`NNG_OPT_IPC_PERMISSIONS`)):: +(`int`) +This write-only option may be applied to a listener to configure the +permissions that are used on the UNIX domain socket created by that listener. +This property is only supported on POSIX systems. +The value is of type `int`, representing the normal permission bits +on a file, such as `0600` (typically meaning read-write to the owner, and +no permissions for anyone else.) +The default is system-specific, most often `0644`. ++ +IMPORTANT: Not all systems validate these permissions. +In particular, illumos and Solaris are known to ignore these permission +settings when connecting. ++ +NOTE: Normally both read and write permission will be necessary for a +peer dialer to connect. +See your system documentation for UNIX domain sockets for more information. ++ +NOTE: The _umask_ of the process is *not* applied to these bits. ++ +TIP: The best practice for limiting access is to place the socket in a +directory writable only by the server, and only readable and searchable +by clients. +All mainstream POSIX systems will fail to permit a client to connect +to a socket located in a directory for which the client lacks search (execute) +permission. + +[[NNG_OPT_IPC_SECURITY_DESCRIPTOR]]((`NNG_OPT_IPC_SECURITY_DESCRIPTOR`)):: +(`PSECURITY_DESCRIPTOR`) +This write-only option may be used on listeners on Windows platforms to +configure the `SECURITY_DESCRIPTOR` that is used when creating the underlying +named pipe. +The value is a pointer, `PSECURITY_DESCRIPTOR`, and may only be +applied to listeners that have not been started yet. + +=== Common Platform Specific Options + +The following options are supported by this transport when the underlying platform supports them: + +* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`] (also available as `NNG_OPT_IPC_PEER_GID`) +* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`] (also available as `NNG_OPT_IPC_PEER_PID`) +* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`] (also available as `NNG_OPT_IPC_PEER_UID`) +* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`] (also available as `NNG_OPT_IPC_PEER_ZONEID`) + +=== Inherited Options + +Generally, the following option values are also available when appropriate for the context: + +* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] +* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`] + +== SEE ALSO + +[.text-left] +xref:nng_dialer_get.3.adoc[nng_dialer_get(3)], +xref:nng_dialer_set.3.adoc[nng_dialer_set(3)], +xref:nng_listener_get.3.adoc[nng_listener_get(3)], +xref:nng_listener_set.3.adoc[nng_listener_set(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], +xref:nng_options.5.adoc[nng_options(5)] +xref:nng.7.adoc[nng(7)], +xref:nng_ipc.7.adoc[nng_ipc(7)] diff --git a/external/nng/docs/man/nng_ipc_register.3.adoc b/external/nng/docs/man/nng_ipc_register.3.adoc new file mode 100644 index 0000000..64da4b0 --- /dev/null +++ b/external/nng/docs/man/nng_ipc_register.3.adoc @@ -0,0 +1,47 @@ += nng_ipc_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_ipc_register - register ipc transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_ipc_register(void); +---- + +== DESCRIPTION + +The `nng_ipc_register()` function registers the +((_ipc_ transport))(((transport, _ipc_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_ipc.7.adoc[nng_ipc(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listen.3.adoc b/external/nng/docs/man/nng_listen.3.adoc new file mode 100644 index 0000000..b62c5df --- /dev/null +++ b/external/nng/docs/man/nng_listen.3.adoc @@ -0,0 +1,78 @@ += nng_listen(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listen - create and start listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listen(nng_socket s, const char *url, nng_listener *lp, int flags); +---- + +== DESCRIPTION + +The `nng_listen()` function creates a newly initialized +xref:nng_listener.5.adoc[`nng_listener`] object, associated with socket _s_, +and configured to listen at the address specified by _url_, and starts it. +If the value of _lp_ is not `NULL`, then +the newly created listener is stored at the address indicated by _lp_. + +Listeners are used to accept connections initiated by remote dialers. +An incoming connection generally results in an +xref:nng_pipe.5.adoc[`nng_pipe`] object being created and attached to the socket _s_. +Unlike dialers, listeners generally can create many +pipes, which may be open concurrently. + +The _flags_ argument is ignored, but reserved for future use. + +TIP: While it is convenient to think of listeners as servers, the +relationship between the listener or dialer is orthogonal to any server or +client status that might be associated with a given protocol. +For example, a xref:nng_req.7.adoc[_req_] +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +Because the listener is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using xref:nng_listener_create.3.adoc[`nng_listener_create()`] and +xref:nng_listener_start.3.adoc[`nng_listener_start()`] instead. + +The created listener will continue to accept new connections, associating +their pipes with the socket, until either it or the socket _s_ is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: The address specified by _url_ is already in use. +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_EINVAL`:: An invalid set of _flags_ or an invalid _url_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +[.text-left] +xref:nng_dial.3.adoc[nng_dial(3)], +xref:nng_listener_close.3.adoc[nng_listener_close(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_start.3.adoc[nng_listener_start(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener.5.adoc b/external/nng/docs/man/nng_listener.5.adoc new file mode 100644 index 0000000..66eb736 --- /dev/null +++ b/external/nng/docs/man/nng_listener.5.adoc @@ -0,0 +1,77 @@ += nng_listener(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener - listener + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_listener_s nng_listener; +---- + +== DESCRIPTION + +(((listener))) +An `nng_listener` is a handle to a listener object, which is responsible for +creating xref:nng_pipe.5.adoc[`nng_pipe`] objects by accepting incoming connections. +A given listener object may create many pipes at the same time, much like an +HTTP server can have many connections to multiple clients simultaneously. + +Listener objects are created by the +xref:nng_listener_create.3.adoc[`nng_listener_create()`] +or xref:nng_listen.3.adoc[`nng_listen()`] functions, and are always associated +with a single xref:nng_socket.5.adoc[`nng_socket`]. + +IMPORTANT: The `nng_listener` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + +TIP: A given xref:nng_socket.5.adoc[`nng_socket`] may have multiple listener +objects, multiple xref:nng_dialer.5.adoc[dialer] objects, or even some +of both. + +TIP: The client/server relationship described by dialer/listener is +completely orthogonal to any similar relationship in the protocols. +For example, a xref:nng_rep.7.adoc[_rep_] socket may use a dialer +to connect to a listener on an xref:nng_req.7.adoc[_req_] socket. +This orthogonality can lead to innovative solutions to otherwise +challenging communications problems. + +Listener objects may be destroyed by the +xref:nng_listener_close.3.adoc[`nng_listener_close()`] function. +They are also closed when their associated socket is closed. + +[[NNG_LISTENER_INITIALIZER]] +=== Initialization + +A listener may be initialized using the macro `NNG_LISTENER_INITIALIZER` +before it is opened, to prevent confusion with valid open listener. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_close.3.adoc[nng_listener_close(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)], +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], +xref:nng_listener_id.3.adoc[nng_listener_id(3)], +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], +xref:nng_listener_start.3.adoc[nng_listener_start(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_pipe.5.adoc[nng_pipe(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_close.3.adoc b/external/nng/docs/man/nng_listener_close.3.adoc new file mode 100644 index 0000000..239fe26 --- /dev/null +++ b/external/nng/docs/man/nng_listener_close.3.adoc @@ -0,0 +1,56 @@ += nng_listener_close(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_close - close listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_close(nng_listener l); +---- + +== DESCRIPTION + +The `nng_listener_close()` function closes the listener _l_. +This also closes any pipes that have been created by the listener. + +Once this function returns, the listener _l_ and any of its resources +are deallocated. +Therefore it is an error to attempt to access _l_ +after this function has returned. +(Attempts to do so will result in `NNG_ECLOSED` errors.) + +Listeners are implicitly closed when the socket they are associated with +is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. + +== SEE ALSO + +[.text-left] +xref:nng_close.3.adoc[nng_close(3)], +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_create.3.adoc b/external/nng/docs/man/nng_listener_create.3.adoc new file mode 100644 index 0000000..edf19af --- /dev/null +++ b/external/nng/docs/man/nng_listener_create.3.adoc @@ -0,0 +1,77 @@ += nng_listener_create(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_create - create listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_create(nng_listener *listenerp, nng_socket s, const char *url); +---- + +== DESCRIPTION + +The `nng_listener_create()` function creates a newly initialized +xref:nng_listener.5.adoc[`nng_listener`] object, associated with socket _s_, +and configured to listen at the address specified by _url_, +and stores a pointer to at the location referenced by _listenerp_. + +Listeners are used to accept connections initiated by remote dialers. +An incoming connection generally results in a pipe being created and attached +to the socket _s_. +Unlike dialers, listeners generally can create many pipes, +which may be open concurrently. + +TIP: While it is convenient to think of listeners as servers, the +relationship between the listener or dialer is orthogonal to any server or +client status that might be associated with a given protocol. +For example, a xref:nng_req.7.adoc[_req_] socket might have associated dialers, +but might also have associated listeners. +It may even have some of each at the same time! + +The listener is not started, but may be further configured with +the xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] family of +functions. + +Once it is fully configured, the listener may be started using the +xref:nng_listener_start.3.adoc[`nng_listener_start()`] function. + +TIP: If no specific configuration is required, consider using the +simpler xref:nng_listen.3.adoc[`nng_listen()`] function instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_close.3.adoc[nng_listener_close(3)], +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], +xref:nng_listener_start.3.adoc[nng_listener_start(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_get.3.adoc b/external/nng/docs/man/nng_listener_get.3.adoc new file mode 100644 index 0000000..83ae698 --- /dev/null +++ b/external/nng/docs/man/nng_listener_get.3.adoc @@ -0,0 +1,146 @@ += nng_listener_get(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_get - get listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_get(nng_listener l, const char *opt, void *val, size_t *valszp); + +int nng_listener_get_bool(nng_listener l, const char *opt, bool *bvalp); + +int nng_listener_get_int(nng_listener l, const char *opt, int *ivalp); + +int nng_listener_get_ms(nng_listener l, const char *opt, nng_duration *durp); + +int nng_listener_get_ptr(nng_listener l, const char *opt, void **ptr); + +int nng_listener_get_size(nng_listener l, const char *opt, size_t *zp); + +int nng_listener_get_addr(nng_listener l, const char *opt, nng_sockaddr *sap); + +int nng_listener_get_string(nng_listener l, const char *opt, char **strp); + +int nng_listener_get_uint64(nng_listener l, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +(((options, listener))) +The `nng_listener_get()` functions are used to retrieve option values for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the listener _l_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_listener_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_listener_get_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_listener_get_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_listener_get_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. + +`nng_listener_get_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_listener_get_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_listener_get_addr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_listener_get_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_listener_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_set.3.adoc[nng_listener_set(3)] +xref:nng_socket_get.3.adoc[nng_socket_get(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_getopt.3.adoc b/external/nng/docs/man/nng_listener_getopt.3.adoc new file mode 100644 index 0000000..828f440 --- /dev/null +++ b/external/nng/docs/man/nng_listener_getopt.3.adoc @@ -0,0 +1,150 @@ += nng_listener_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_getopt - get listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); + +int nng_listener_getopt_bool(nng_listener l, const char *opt, bool *bvalp); + +int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); + +int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); + +int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); + +int nng_listener_getopt_size(nng_listener l, const char *opt, size_t *zp); + +int nng_listener_getopt_sockaddr(nng_listener l, const char *opt, nng_sockaddr *sap); + +int nng_listener_getopt_string(nng_listener l, const char *opt, char **strp); + +int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_listener_get.3.adoc[nng_listener_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, listener))) +The `nng_listener_getopt()` functions are used to retrieve option values for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options +are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the listener _l_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_listener_getopt()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. + + + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _valszp_. +If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_listener_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_listener_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_listener_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. + +`nng_listener_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_listener_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_listener_getopt_sockaddr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_listener_getopt_string()`:: +This function is used to retrieve a string into _strp_. +This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_listener_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] +xref:nng_getopt.3.adoc[nng_getopt(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_id.3.adoc b/external/nng/docs/man/nng_listener_id.3.adoc new file mode 100644 index 0000000..974a7f0 --- /dev/null +++ b/external/nng/docs/man/nng_listener_id.3.adoc @@ -0,0 +1,52 @@ += nng_listener_id(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_id - return numeric listener identifier + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_id(nng_listener l); +---- + +== DESCRIPTION + +The `nng_listener_id()` function returns a positive identifier for the +listener _l_, if it is valid. +Otherwise it returns `-1`. + +NOTE: A listener is considered valid if it was ever created with the +xref:nng_listener_create.3.adoc[`nng_listener_create()`] or +xref:nng_listen.3.adoc[`nng_listen()`] functions. +listeners that are allocated on the stack or statically should be +initialized with the macro +xref:nng_ctx.5.adoc#NNG_LISTENER_INITIALIZER[`NNG_LISTENER_INITIALIZER`] to ensure that +they cannot be confused with a valid listener before they are created properly. + +== RETURN VALUES + +This function returns the positive value for the listener identifier, or +`-1` if the listener is invalid. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_set.3.adoc b/external/nng/docs/man/nng_listener_set.3.adoc new file mode 100644 index 0000000..0cfd211 --- /dev/null +++ b/external/nng/docs/man/nng_listener_set.3.adoc @@ -0,0 +1,132 @@ += nng_listener_set(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_set - set listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_set(nng_listener l, const char *opt, const void *val, + size_t valsz); + +int nng_listener_set_bool(nng_listener l, const char *opt, bool bval); + +int nng_listener_set_int(nng_listener l, const char *opt, int ival); + +int nng_listener_set_ms(nng_listener l, const char *opt, nng_duration dur); + +int nng_listener_set_ptr(nng_listener l, const char *opt, void *ptr); + +int nng_listener_set_size(nng_listener l, const char *opt, size_t z); + +int nng_listener_set_string(nng_listener l, const char *opt, const char *str); + +int nng_listener_set_uint64(nng_listener l, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +(((options, listener))) +The `nng_listener_set()` functions are used to configure options for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +NOTE: Once a listener has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the listener _l_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_listener_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +`nng_listener_set_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_listener_set_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_listener_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_listener_set_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) +can be passed this way. + +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_listener_set_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_listener_set_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_listener_set_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_get.3.adoc[nng_listener_get(3)] +xref:nng_socket_set.3.adoc[nng_socket_set(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_setopt.3.adoc b/external/nng/docs/man/nng_listener_setopt.3.adoc new file mode 100644 index 0000000..25411ad --- /dev/null +++ b/external/nng/docs/man/nng_listener_setopt.3.adoc @@ -0,0 +1,136 @@ += nng_listener_setopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_setopt - set listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_setopt(nng_listener l, const char *opt, const void *val, + size_t valsz); + +int nng_listener_setopt_bool(nng_listener l, const char *opt, bool bval); + +int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); + +int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); + +int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); + +int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); + +int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); + +int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_listener_set.3.adoc[nng_listener_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, listener))) +The `nng_listener_setopt()` functions are used to configure options for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options +are documented with the transports themselves. + +NOTE: Once a listener has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the listener _l_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_listener_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +`nng_listener_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_listener_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_listener_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_listener_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) +can be passed this way. + +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_listener_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_listener_setopt_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_listener_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)] +xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_listener_start.3.adoc b/external/nng/docs/man/nng_listener_start.3.adoc new file mode 100644 index 0000000..b8f59ed --- /dev/null +++ b/external/nng/docs/man/nng_listener_start.3.adoc @@ -0,0 +1,57 @@ += nng_listener_start(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_listener_start - start listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_start(nng_listener l, int flags); +---- + +== DESCRIPTION + +The `nng_listener_start()` function starts the listener _l_. + +This causes the listener to bind to the address it was created with, +and to start accepting connections from remote +dialers. +Each new connection results in an xref:nng_pipe.5.adoc[`nng_pipe`] object, +which will be attached to the listener's socket. + +The _flags_ argument is ignored, but reserved for future use. + +Once a listener has started, it is generally not possible to change +its configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_log.3.adoc b/external/nng/docs/man/nng_log.3.adoc new file mode 100644 index 0000000..358264c --- /dev/null +++ b/external/nng/docs/man/nng_log.3.adoc @@ -0,0 +1,65 @@ += nng_log(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_log - log messages + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_log_err(const char *msgid, const char *msg, ...); +void nng_log_warn(const char *msgid, const char *msg, ...); +void nng_log_notice(const char *msgid, const char *msg, ...); +void nng_log_info(const char *msgid, const char *msg, ...); +void nng_log_debug(const char *msgid, const char *msg, ...); + +void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...); +---- + +== DESCRIPTION + +These functions are used to post a message to system or application logs. + +The first five forms all post a message at the severity indicated by the function name. +The _msgid_ should be a short message identifier that should indicate the message in question. +A `NULL` value for _msgid_ canbe used as well. + +Message identifiers can be used to assist in filtering logs. +These should uniquely identify the nature of the problem, whe possible, to assist in trouble-shooting. +They should also be short. +Eight characters or less is ideal, and more than sixteen is strongly discouraged. + +The message is formatting as if by `sprintf`, using `msg` as the format, and remaining arguments as arguments to the format. + +The final function, `nng_log_auth`, is used for posting authentication related messages which might be treated specially, such as be storing them in a separate secured log file. +It takes the severity as a level in _level_. +The severity can be one of the following values: + +* `NNG_LOG_ERR` +* `NNG_LOG_WARN` +* `NNG_LOG_NOTICE` +* `NNG_LOG_INFO` +* `NNG_LOG_DEBUG` + +The message itself is handled according to the logging facility set up with xref:nng_mg_set_logger.3.adoc[`nng_log_set_logger`]. +Message delivery is best effort, and messages may be suppressed based on the priority set with xref:nng_log_set_level.3.adoc[`nng_log_set_level`]. + +Note that in order to get log messages, a suitable logger must be set using `nng_log_set_logger`. +The default logger, `nng_null_logger` simply discards logged content. + +== SEE ALSO + +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)], +xref:nng_log_set_logger.3.adoc[nng_log_set_logger(3)] diff --git a/external/nng/docs/man/nng_log_get_level.3.adoc b/external/nng/docs/man/nng_log_get_level.3.adoc new file mode 100644 index 0000000..7ff9090 --- /dev/null +++ b/external/nng/docs/man/nng_log_get_level.3.adoc @@ -0,0 +1,42 @@ += nng_log_get_level(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_log_get_level - get minimum level for logging messagse + +== SYNOPSIS + +[source, c] +---- +#include + +typedef enum nng_log_level { + NNG_LOG_NONE = 0, // used for filters only, NNG suppresses these + NNG_LOG_ERR = 3, + NNG_LOG_WARN = 4, + NNG_LOG_NOTICE = 5, + NNG_LOG_INFO = 6, + NNG_LOG_DEBUG = 7 +} nng_log_level; + +nng_log_level nng_log_set_level(void); +---- + +== DESCRIPTION + +The `nng_log_get_level` function is used to get the minimum severity to _level_ for processing log messages. +The intended use case is to avoid expensive operations used solely to provide debugging information in logs, +if the logged content would merely be discarded. + +== SEE ALSO + +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)] diff --git a/external/nng/docs/man/nng_log_set_facility.3.adoc b/external/nng/docs/man/nng_log_set_facility.3.adoc new file mode 100644 index 0000000..ecd6ab7 --- /dev/null +++ b/external/nng/docs/man/nng_log_set_facility.3.adoc @@ -0,0 +1,47 @@ += nng_log_set_facility(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_log_set_facility - set facility used for log messages + +== SYNOPSIS + +[source, c] +---- +#include + +typedef enum nng_log_facility { + NNG_LOG_USER = 1, + NNG_LOG_DAEMON = 3, + NNG_LOG_AUTH = 10, + NNG_LOG_LOCAL0 = 16, + NNG_LOG_LOCAL1 = 17, + NNG_LOG_LOCAL2 = 18, + NNG_LOG_LOCAL3 = 19, + NNG_LOG_LOCAL4 = 20, + NNG_LOG_LOCAL5 = 21, + NNG_LOG_LOCAL6 = 22, + NNG_LOG_LOCAL7 = 23, +} nng_log_facility; + +void nng_log_set_facility(nng_log_facility facility); +---- + +== DESCRIPTION + +The `nng_log_set_facility` is used to set the _facility_ of the application posting logs. +This is used to assist with directing log content when handled by services such as `syslog`. + +Note that while the log levels used here overlap with common levels used by the syslog facility on POSIX systems, applications should not rely on this. + +== SEE ALSO + +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)] diff --git a/external/nng/docs/man/nng_log_set_level.3.adoc b/external/nng/docs/man/nng_log_set_level.3.adoc new file mode 100644 index 0000000..5501e9c --- /dev/null +++ b/external/nng/docs/man/nng_log_set_level.3.adoc @@ -0,0 +1,43 @@ += nng_log_set_level(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_log_set_level - set minimum level for logging messagse + +== SYNOPSIS + +[source, c] +---- +#include + +typedef enum nng_log_level { + NNG_LOG_NONE = 0, // used for filters only, NNG suppresses these + NNG_LOG_ERR = 3, + NNG_LOG_WARN = 4, + NNG_LOG_NOTICE = 5, + NNG_LOG_INFO = 6, + NNG_LOG_DEBUG = 7 +} nng_log_level; + +void nng_log_set_level(nng_log_level level); +---- + +== DESCRIPTION + +The `nng_log_set_level` function is used to set the minimum severity to _level_ for processing log messages. +Any messages with a less severe rating are not processed and simply are discarded. +Use `NNG_LOG_NONE` to suppress all log messages. +Use `NNG_LOG_DEBUG` to receive all log messages. + +== SEE ALSO + +xref:nng_log_get_level.3.adoc[nng_log_set_level(3)] +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)] diff --git a/external/nng/docs/man/nng_log_set_logger.3.adoc b/external/nng/docs/man/nng_log_set_logger.3.adoc new file mode 100644 index 0000000..eedbca4 --- /dev/null +++ b/external/nng/docs/man/nng_log_set_logger.3.adoc @@ -0,0 +1,53 @@ += nng_log_set_logger(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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_log_set_logger - set logging handler + +== SYNOPSIS + +[source, c] +---- +#include + +typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility, + const char *msgid, const char *msg); + +void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *); +void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *); +void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *); + +void nng_log_set_logger(nng_logger logger); +---- + +== DESCRIPTION + +The `nng_log_set_logger` is used to set the base logging function to _logger_. +The _logger_ may be a user defined function to process log messages. +Only a single logger may be registered at a time. +If needed, the logger should make copies of either _msgid_ or _msg_, as those may not be valid once the logger function returns. + +The `nng_null_logger` function is an implementation of `nng_logger` that simply discards the content. +This is the default logger, so logging is disabled by default. + +The `nng_stderr_logger` function is an implementation that logs messages to the standard error stream. +It will attempt to colorize messages by the severity, if the standard error is a terminal device. +This can be supressed by setting either the `NO_COLOR` or `NNG_LOG_NO_COLOR` environment variables. + +The `nng_system_logger` attempts to use an appropriate system facility to log messages. +For POSIX systems, this means using `syslog` to process the messages. +For other the `nng_stderr_log` may be used as a fallback. + +== SEE ALSO + +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)], +xref:nng_log.3.adoc[nng_log(3)] diff --git a/external/nng/docs/man/nng_msg.5.adoc b/external/nng/docs/man/nng_msg.5.adoc new file mode 100644 index 0000000..5044cf1 --- /dev/null +++ b/external/nng/docs/man/nng_msg.5.adoc @@ -0,0 +1,64 @@ += nng_msg(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg - message + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_msg nng_msg; +---- + +== DESCRIPTION + +An `nng_msg` represents a single ((message)) sent between Scalability Protocols +peers. +Messages internally have a ((body)), containing the application supplied +payload, and a ((header)), containing protocol specific routing and similar +related information. + +TIP: Using message-oriented functions is a good way to reduce the likelihood +of data copies and improve application performance. + +Messages are allocated using the xref:nng_msg_alloc.3.adoc[`nng_msg_alloc()`] +function, and are deallocated using the xref:nng_msg_free.3.adoc[`nng_msg_free()`] +function. + +In addition there are other functions used to access message contents, +including adding data to either the beginning or end of the message, +automatic data conversion, and removing data from the beginning or end. +These functions are designed to try to avoid copying message contents +by making use of scratch areas at the beginning and end of the message. + +== SEE ALSO + +[.text-left] +xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], +xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_dup.3.adoc[nng_msg_dup(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_recvmsg.3.adoc[nng_recvmsg(3)], +xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_alloc.3.adoc b/external/nng/docs/man/nng_msg_alloc.3.adoc new file mode 100644 index 0000000..2754b67 --- /dev/null +++ b/external/nng/docs/man/nng_msg_alloc.3.adoc @@ -0,0 +1,55 @@ += nng_msg_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_alloc - allocate a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_alloc(nng_msg **msgp, size_t size); +---- + +== DESCRIPTION + +The `nng_msg_alloc()` function allocates a new message with body length _size_ +and stores the result in __msgp__. +Messages allocated with this function contain a body and optionally a header. +They are used with receive and transmit functions. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_dup.3.adoc[nng_msg_dup(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_append.3.adoc b/external/nng/docs/man/nng_msg_append.3.adoc new file mode 100644 index 0000000..9ed3741 --- /dev/null +++ b/external/nng/docs/man/nng_msg_append.3.adoc @@ -0,0 +1,58 @@ += nng_msg_append(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_append - append to message body + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_append_u16(nng_msg *msg, uint16_t val16); +int nng_msg_append_u32(nng_msg *msg, uint32_t val32); +int nng_msg_append_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_append()` family of functions appends data to +the end of the body of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. +The remaining functions append the value specified (such as _val32_) in +network-byte order (big-endian). + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_body.3.adoc b/external/nng/docs/man/nng_msg_body.3.adoc new file mode 100644 index 0000000..ad0fa7b --- /dev/null +++ b/external/nng/docs/man/nng_msg_body.3.adoc @@ -0,0 +1,62 @@ += nng_msg_body(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_body - return message body + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_msg_body(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_body()` function returns a pointer to the start of the body +content of the message _msg_. + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message itself. +Such functions are +xref:nng_msg_free.3.adoc[`nng_msg_free()`], +xref:nng_msg_realloc.3.adoc[`nng_msg_realloc()`], +any of the xref:nng_msg_trim.3.adoc[`nng_msg_trim()`], +xref:nng_msg_chop.3.adoc[`nng_msg_chop()`], +xref:nng_msg_append.3.adoc[`nng_msg_append()`], +or xref:nng_msg_insert.3.adoc[`nng_msg_insert()`] variants. + +== RETURN VALUES + +Pointer to start of message body. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_capacity.3.adoc b/external/nng/docs/man/nng_msg_capacity.3.adoc new file mode 100644 index 0000000..ffc7f5d --- /dev/null +++ b/external/nng/docs/man/nng_msg_capacity.3.adoc @@ -0,0 +1,46 @@ += nng_msg_capacity(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_capacity - return message body length + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_msg_capacity(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_capacity()` returns the storage allocated for the body of message _msg_. +The capacity includes the current contents of the message and free space after it. +The message body may grow to capacity without performing any further allocations. + +== RETURN VALUES + +Allocated capacity for message body. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_chop.3.adoc b/external/nng/docs/man/nng_msg_chop.3.adoc new file mode 100644 index 0000000..b945f0b --- /dev/null +++ b/external/nng/docs/man/nng_msg_chop.3.adoc @@ -0,0 +1,61 @@ += nng_msg_chop(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_chop - remove data from end of message body + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_chop(nng_msg *msg, size_t size); +int nng_msg_chop_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_chop_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_chop()` family of functions removes data from +the end of the body of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native byte order. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_clear.3.adoc b/external/nng/docs/man/nng_msg_clear.3.adoc new file mode 100644 index 0000000..e5b3bf4 --- /dev/null +++ b/external/nng/docs/man/nng_msg_clear.3.adoc @@ -0,0 +1,41 @@ += nng_msg_clear(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_clear - clear message body content + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_clear(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the body length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_dup.3.adoc b/external/nng/docs/man/nng_msg_dup.3.adoc new file mode 100644 index 0000000..b985d5b --- /dev/null +++ b/external/nng/docs/man/nng_msg_dup.3.adoc @@ -0,0 +1,49 @@ += nng_msg_dup(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_dup - duplicate a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); +---- + +== DESCRIPTION + +The `nng_msg_dup()` makes a duplicate of the original message _orig_, and +saves the result in the location pointed by _dup_. +The actual message body and header content is copied, +but the duplicate may contain a +different amount of unused space than the original message. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_free.3.adoc b/external/nng/docs/man/nng_msg_free.3.adoc new file mode 100644 index 0000000..1ee045c --- /dev/null +++ b/external/nng/docs/man/nng_msg_free.3.adoc @@ -0,0 +1,43 @@ += nng_msg_free(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_free - free a message + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_free(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_free()` function deallocates the message _msg_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_get_pipe.3.adoc b/external/nng/docs/man/nng_msg_get_pipe.3.adoc new file mode 100644 index 0000000..154f4c4 --- /dev/null +++ b/external/nng/docs/man/nng_msg_get_pipe.3.adoc @@ -0,0 +1,60 @@ += nng_msg_get_pipe(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_get_pipe - get pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +nng_pipe nng_msg_get_pipe(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_get_pipe()` returns the xref:nng_pipe.5.adoc[`nng_pipe`] object +associated with message _msg_. +On receive, this is the pipe from which a message was received. +On transmit, this would be the pipe that the message should be delivered +to, if a specific peer is required. + +NOTE: Not all protocols support overriding the destination pipe. + +The most usual use case for this is to obtain information about the peer +from which the message was received. +This can be used to provide different behaviors for different peers, such as +a higher level of authentication for peers located on an untrusted network. +The xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function +is useful in this situation. + + +== RETURN VALUES + +This function returns the pipe associated with this message, which will +be a positive value. +If the pipe is non-positive, then that indicates that +no specific pipe is associated with the message. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header.3.adoc b/external/nng/docs/man/nng_msg_header.3.adoc new file mode 100644 index 0000000..eac45ff --- /dev/null +++ b/external/nng/docs/man/nng_msg_header.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header - return message header + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_msg_header(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_header()` function returns a pointer to the start of the header +content of the message _msg_. + +NOTE: The message header contains protocol-specific header content. Most +applications should not need to access this content, but it is available +for raw mode sockets (set with the +xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`] option.) + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message or the header content. + +== RETURN VALUES + +Pointer to start of message header. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)] +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_append.3.adoc b/external/nng/docs/man/nng_msg_header_append.3.adoc new file mode 100644 index 0000000..16badf0 --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_append.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_append(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_append - append to message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_append_u16(nng_msg *msg, uint16_t val16); +int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); +int nng_msg_header_append_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_header_append()` family of functions appends data to +the end of the headers of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. + +The remaining functions append the value (such as _val32_) in +network-byte order (big-endian). + + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_chop.3.adoc b/external/nng/docs/man/nng_msg_header_chop.3.adoc new file mode 100644 index 0000000..454e9e5 --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_chop.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_chop(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_chop - remove data from end of message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_chop(nng_msg *msg, size_t size); +int nng_msg_header_chop_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_header_chop_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_header_chop()` family of functions removes +data from the end of the header of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +These function return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_clear.3.adoc b/external/nng/docs/man/nng_msg_header_clear.3.adoc new file mode 100644 index 0000000..d00286e --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_clear.3.adoc @@ -0,0 +1,42 @@ += nng_msg_header_clear(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_clear - clear message header + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_header_clear(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the header length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_insert.3.adoc b/external/nng/docs/man/nng_msg_header_insert.3.adoc new file mode 100644 index 0000000..a2bf0d6 --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_insert.3.adoc @@ -0,0 +1,60 @@ += nng_msg_header_insert(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_insert - prepend to message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_insert_u16(nng_msg *msg, uint16_t val16); +int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); +int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_header_insert()` family of functions +prepends data to the front of the headers of message _msg_, reallocating +if necessary. +The first function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) in +network-byte order (big-endian). + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_len.3.adoc b/external/nng/docs/man/nng_msg_header_len.3.adoc new file mode 100644 index 0000000..0a7b361 --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_header_len(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_len - return message header length + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_msg_header_len(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_header_len()` returns the length of message header of _msg_. + +== RETURN VALUES + +Length of message header. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_header_trim.3.adoc b/external/nng/docs/man/nng_msg_header_trim.3.adoc new file mode 100644 index 0000000..6df504f --- /dev/null +++ b/external/nng/docs/man/nng_msg_header_trim.3.adoc @@ -0,0 +1,59 @@ += nng_msg_header_trim(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_trim - remove data from start of message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_trim(nng_msg *msg, size_t size); +int nng_msg_header_trim_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_header_trim()` family of functions remove +data from the start of the header of message _msg_. +The first function removes _size_ bytes. +The remaining functions removes 2, 4, or 8 bytes, and stores them in the +value (such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_insert.3.adoc b/external/nng/docs/man/nng_msg_insert.3.adoc new file mode 100644 index 0000000..25f98fc --- /dev/null +++ b/external/nng/docs/man/nng_msg_insert.3.adoc @@ -0,0 +1,63 @@ += nng_msg_insert(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_insert - prepend to message body + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); +int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); +int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_insert()` family of functions prepends data to +the front of the body of message _msg_, reallocating it if necessary. +The first function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) +in network-byte order (big-endian). + +TIP: These functions make use of space pre-allocated in front of the +message body if available, so they can often avoid performing any reallocation. +Applications should use these instead of reallocating and copying message +content themselves, in order to benefit from this capability. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_len.3.adoc b/external/nng/docs/man/nng_msg_len.3.adoc new file mode 100644 index 0000000..2a3dfe6 --- /dev/null +++ b/external/nng/docs/man/nng_msg_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_len(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_len - return message body length + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_msg_len(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_len()` returns the length of the body of message _msg_. + +== RETURN VALUES + +Length of message body. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_realloc.3.adoc b/external/nng/docs/man/nng_msg_realloc.3.adoc new file mode 100644 index 0000000..bf40728 --- /dev/null +++ b/external/nng/docs/man/nng_msg_realloc.3.adoc @@ -0,0 +1,66 @@ += nng_msg_realloc(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_realloc - reallocate a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_realloc(nng_msg *msg, size_t size); +---- + +== DESCRIPTION + +The `nng_msg_realloc()` function re-allocates a message so that it has +a body of length _size_. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. +When appending many small pieces of data to a message using xref:nng_msg_append.3.adoc[`nng_msg_append()`], +allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`] +to create sufficient space. +In any case, reallocating or appending to a message is guaranteed to succeed if the resulting +body length is less than xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. + +NOTE: Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message size is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_reserve.3.adoc b/external/nng/docs/man/nng_msg_reserve.3.adoc new file mode 100644 index 0000000..254c1e9 --- /dev/null +++ b/external/nng/docs/man/nng_msg_reserve.3.adoc @@ -0,0 +1,63 @@ += nng_msg_reserve(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_reserve - reserve storage for a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_reserve(nng_msg *msg, size_t capacity); +---- + +== DESCRIPTION + +The `nng_msg_reserve()` function ensures a message has allocated enough storage +to accommodate a body of the given length. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: Using this message before xref:nng_msg_append.3.adoc[`nng_msg_append()`] +will prevent additional memory allocations until the message's length exceeds +the alotted capacity. + +NOTE: Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message capacity is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_set_pipe.3.adoc b/external/nng/docs/man/nng_msg_set_pipe.3.adoc new file mode 100644 index 0000000..c95cc83 --- /dev/null +++ b/external/nng/docs/man/nng_msg_set_pipe.3.adoc @@ -0,0 +1,50 @@ += nng_msg_set_pipe(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_set_pipe - set pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); +---- + +== DESCRIPTION + +The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_. +This is most often useful when used with protocols that support directing +a message to a specific peer. +For example the xref:nng_pair.7.adoc[_pair_] version 1 protocol can do +this when `NNG_OPT_PAIR1_POLY` mode is set. + +NOTE: Not all protocols support overriding the destination pipe. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msg_trim.3.adoc b/external/nng/docs/man/nng_msg_trim.3.adoc new file mode 100644 index 0000000..aa48295 --- /dev/null +++ b/external/nng/docs/man/nng_msg_trim.3.adoc @@ -0,0 +1,60 @@ += nng_msg_trim(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_trim - remove data from start of message body + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_trim(nng_msg *msg, size_t size); +int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_trim()` family of functions removes data from +the start of the body of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_msleep.3supp.adoc b/external/nng/docs/man/nng_msleep.3supp.adoc new file mode 100644 index 0000000..57d3615 --- /dev/null +++ b/external/nng/docs/man/nng_msleep.3supp.adoc @@ -0,0 +1,49 @@ += nng_msleep(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msleep - sleep milliseconds + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_msleep(nng_duration msec); +---- + +== DESCRIPTION + +The `nng_msleep()` blocks the caller for at least _msec_ milliseconds. + +NOTE: This function may block for longer than requested. +The actual wait time is determined by the capabilities of the +underlying system. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_sleep_aio.3.adoc[nng_sleep_aio(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_clock.3supp.adoc[nng_clock(3supp)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_mtx_alloc.3supp.adoc b/external/nng/docs/man/nng_mtx_alloc.3supp.adoc new file mode 100644 index 0000000..45bbfac --- /dev/null +++ b/external/nng/docs/man/nng_mtx_alloc.3supp.adoc @@ -0,0 +1,58 @@ += nng_mtx_alloc(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_mtx_alloc - allocate mutex + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef struct nng_mtx nng_mtx; + +int nng_mtx_alloc(nng_mtx **mtxp); +---- + +== DESCRIPTION + +The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. + +The mutex objects created by this function are suitable only for +simple lock and unlock operations, and are not recursive. +Every effort has been made to use light-weight underlying primitives when available. + +Mutex (mutual exclusion) objects can be thought of as binary semaphores, +where only a single thread of execution is permitted to acquire the semaphore. + +Furthermore, a mutex can only be unlocked by the thread that locked it. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_mtx_free.3supp.adoc[nng_mtx_free(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_mtx_free.3supp.adoc b/external/nng/docs/man/nng_mtx_free.3supp.adoc new file mode 100644 index 0000000..2867afe --- /dev/null +++ b/external/nng/docs/man/nng_mtx_free.3supp.adoc @@ -0,0 +1,43 @@ += nng_mtx_free(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_mtx_free - free mutex + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_mtx_free(nng_mtx *mtx); +---- + +== DESCRIPTION + +The `nng_mtx_free()` function frees the mutex _mtx_. +The mutex must not be locked when this function is called. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_mtx_lock.3supp.adoc b/external/nng/docs/man/nng_mtx_lock.3supp.adoc new file mode 100644 index 0000000..91fd2ab --- /dev/null +++ b/external/nng/docs/man/nng_mtx_lock.3supp.adoc @@ -0,0 +1,65 @@ += nng_mtx_lock(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_mtx_lock - lock mutex + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_mtx_lock(nng_mtx *mtx); +---- + +== DESCRIPTION + +The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. +If the lock is already owned, this function will wait until the current +owner releases it with xref:nng_mtx_unlock.3supp.adoc[`nng_mtx_unlock()`]. + +If multiple threads are waiting for the lock, the order of acquisition +is not specified. + +NOTE: A mutex can _only_ be unlocked by the thread that locked it. + +IMPORTANT: Mutex locks are _not_ recursive; attempts to reacquire the +same mutex may result in deadlock or aborting the current program. +It is a programming error for the owner of a mutex to attempt to +reacquire it. + +**** +_NNG_ offers neither a non-blocking variant that can fail, +nor recursive mutexes. +This is by design, as _NNG_ itself does not use such things, +and most often the need for them is the result of poor design. +If such capabilities are needed, they may be synthesized fairly +easily from mutexes and condition variables. +**** + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_mtx_unlock.3supp.adoc b/external/nng/docs/man/nng_mtx_unlock.3supp.adoc new file mode 100644 index 0000000..d1b048e --- /dev/null +++ b/external/nng/docs/man/nng_mtx_unlock.3supp.adoc @@ -0,0 +1,48 @@ += nng_mtx_unlock(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_mtx_unlock - unlock mutex + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_mtx_unlock(nng_mtx *mtx); +---- + +== DESCRIPTION + +The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that +was previously acquired via xref:nng_mtx_lock.3supp.adoc[`nng_mtx_lock()`]. + +IMPORTANT: A mutex can _only_ be unlocked by the thread that locked it. +Attempting to unlock a mutex that is not owned by the caller will result +in undefined behavior. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], +xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_options.5.adoc b/external/nng/docs/man/nng_options.5.adoc new file mode 100644 index 0000000..94da37a --- /dev/null +++ b/external/nng/docs/man/nng_options.5.adoc @@ -0,0 +1,391 @@ += nng_options(5) +// +// Copyright 2024 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// 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_options - socket, dialer, listener, and pipe options + +== SYNOPSIS + +[source, c] +---- +#include + +#define NNG_OPT_SOCKNAME "socket-name" +#define NNG_OPT_RAW "raw" +#define NNG_OPT_PROTO "protocol" +#define NNG_OPT_PROTONAME "protocol-name" +#define NNG_OPT_PEER "peer" +#define NNG_OPT_PEERNAME "peer-name" +#define NNG_OPT_RECVBUF "recv-buffer" +#define NNG_OPT_SENDBUF "send-buffer" +#define NNG_OPT_RECVFD "recv-fd" +#define NNG_OPT_SENDFD "send-fd" +#define NNG_OPT_RECVTIMEO "recv-timeout" +#define NNG_OPT_SENDTIMEO "send-timeout" +#define NNG_OPT_LOCADDR "local-address" +#define NNG_OPT_REMADDR "remote-address" +#define NNG_OPT_URL "url" +#define NNG_OPT_MAXTTL "ttl-max" +#define NNG_OPT_RECVMAXSZ "recv-size-max" +#define NNG_OPT_RECONNMINT "reconnect-time-min" +#define NNG_OPT_RECONNMAXT "reconnect-time-max" +#define NNG_OPT_PEER_GID "ipc:peer-gid" +#define NNG_OPT_PEER_PID "ipc:peer-pid" +#define NNG_OPT_PEER_UID "ipc:peer-uid" +#define NNG_OPT_PEER_ZONEID "ipc:peer-zoneid" +---- + +== DESCRIPTION + +This page documents the various standard options that can be set or +retrieved on objects. + +Sockets (xref:nng_socket.5.adoc[`nng_socket`] objects) use the functions +xref:nng_socket_get.3.adoc[`nng_socket_get()`] +and xref:nng_socket_set.3.adoc[`nng_socket_set()`] to set and retrieve option values. + +Dialers (xref:nng_dialer.5.adoc[`nng_dialer`] objects) use the functions +xref:nng_dialer_get.3.adoc[`nng_dialer_get()`] and +xref:nng_dialer_set.3.adoc[`nng_dialer_set()`] to set and retrieve option +values. + +Listeners (xref:nng_listener.5.adoc[`nng_listener`] objects) use the functions +xref:nng_listener_get.3.adoc[`nng_listener_get()`] +and xref:nng_listener_set.3.adoc[`nng_listener_set()`] to set and +retrieve option values. + +Pipes (xref:nng_pipe.5.adoc[`nng_pipe`] objects) can only retrieve option values using +the xref:nng_pipe_get.3.adoc[`nng_pipe_get()`] function. + +Other object types may have additional methods to access these options. + +In addition to the options listed here, transports and protocols will generally +have some of their own options, which will be documented with the transport +or protocol. + +=== Generic Options + +In the following list of options, the name of the option is supplied, +along with the data type of the underlying value. + +Some options are only meaningful or supported in certain contexts; for +example there is no single meaningful address for a socket, since sockets +can have multiple dialers and endpoints associated with them. +An attempt has been made to include details about such restrictions in the +description of the option. + +[[NNG_OPT_LOCADDR]] +((`NNG_OPT_LOCADDR`)):: +(xref:nng_sockaddr.5.adoc[`nng_sockaddr`]) +This read-only option may be used on listeners, dialers and connected pipes, and +represents the local address used for communication. +NOTE: 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. + +[[NNG_OPT_RAW]] +((`NNG_OPT_RAW`)):: +(((raw mode))) +(((cooked mode))) +(`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 normal 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 normal mode a xref:nng_rep.7.adoc[_rep_] socket would +automatically copy message headers from a received message to the corresponding +reply, whereas in raw mode this is not done.) +See xref:nng.7.adoc#raw_mode[Raw Mode] for more details. + +[[NNG_OPT_RECONNMINT]] +((`NNG_OPT_RECONNMINT`)):: +(((reconnect time, minimum))) +(xref:nng_duration.5.adoc[`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 +dialer. +The option is irrelevant for listeners. + +[[NNG_OPT_RECONNMAXT]] +((`NNG_OPT_RECONNMAXT`)):: +(((`NNG_OPT_RECONNMAXT`))) +(((reconnect time, maximum))) +(xref:nng_duration.5.adoc[`nng_duration`]) +This is the maximum amount of time +(milliseconds) to wait before attempting to establish a connection after +a previous attempt has failed. +If this is non-zero, then the time between successive connection attempts +will start at the value of `NNG_OPT_RECONNMINT`, +and grow exponentially, until it reaches this value. +If this value is zero, then no exponential +back-off between connection attempts is done, and each attempt will wait +the time specified by `NNG_OPT_RECONNMINT`. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners. + +[[NNG_OPT_RECVBUF]] +((`NNG_OPT_RECVBUF`)):: +(((buffer, receive))) +(((receive, buffer))) +(`int`) +This is the depth of the socket's receive buffer as a number of messages. +Messages received by a transport may be buffered until the application +has accepted them for delivery. +This value must be an integer between 0 and 8192, inclusive. +NOTE: Not all protocols support buffering received messages. +For example xref:nng_req.7.adoc[_req_] can only deal with a single reply at a time. + +[[NNG_OPT_RECVFD]] +((`NNG_OPT_RECVFD`)):: +(((poll))) +(((select))) +(((receive, polling))) +(`int`) +This read-only option is used to obtain an integer file descriptor suitable +for use with +http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`], +http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`], +(or on Windows systems +https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`]) +and similar functions. +This descriptor will be *readable* when a message is available for receiving +on the socket. +When no message is ready for receiving, then this file descriptor will *not* +be readable. ++ +IMPORTANT: Applications should never attempt to read or write to the +returned file descriptor. ++ +IMPORTANT: This option is incompatible with +xref:nng_ctx.5.adoc[`nng_ctx`] contexts and should not be used on a socket +where they are in use. ++ +TIP: 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 xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`]. + +[[NNG_OPT_RECVMAXSZ]] +((`NNG_OPT_RECVMAXSZ`)):: +(((receive, maximum size))) +(`size_t`) +This is the maximum message size that the will be accepted from a remote peer. +If a peer attempts to send a message larger than this, then the message +will be discarded. +If the value of this is zero, then no limit on message sizes is enforced. +This option exists to prevent certain kinds of denial-of-service attacks, +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. ++ +IMPORTANT: Applications on hostile networks should set this to a non-zero +value to prevent denial-of-service attacks. ++ +IMPORTANT: This option should be set before any listeners or dialers are added. +Ideally this option should be set on specific dialers or listeners; setting it +on the socket globally is deprecated behavior, and might not work in a future release, +or might only work for endpoints that have not yet been created. +(Maximum receive sizes might be negotiated during connection establishment for +future transports, which means that the option needs to be set before any connections +are established.) ++ +NOTE: Some transports may have further message size restrictions. + +[[NNG_OPT_RECVTIMEO]] +((`NNG_OPT_RECVTIMEO`)):: +(((receive, timeout))) +(((timeout, receive))) +(xref:nng_duration.5.adoc[`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`. + +[[NNG_OPT_REMADDR]] +((`NNG_OPT_REMADDR`)):: +(xref:nng_sockaddr.5.adoc[`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. + +[[NNG_OPT_SENDBUF]] +((`NNG_OPT_SENDBUF`)):: +(((send, buffer))) +(((buffer, send))) +(`int`) +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. ++ +NOTE: Not all protocols support buffering sent messages. +For example, xref:nng_req.7.adoc[_req_] can only have a single request +outstanding at a time (per context). + +[[NNG_OPT_SENDFD]] +((`NNG_OPT_SENDFD`)):: +(((poll))) +(((select))) +(((send, polling))) +(`int`) +This read-only option is used to obtain an integer file descriptor suitable +for use with +http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`], +http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`], +(or on Windows systems +https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`]) +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. ++ +IMPORTANT: Applications should never attempt to read or write to the +returned file descriptor; use should be limited to polling system calls only. ++ +IMPORTANT: This option is incompatible with +xref:nng_ctx.5.adoc[`nng_ctx`] contexts and should not be used on a socket +where they are in use. ++ +TIP: 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 xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`]. + +[[NNG_OPT_SENDTIMEO]] +((`NNG_OPT_SENDTIMEO`)):: +(((send, timeout))) +(((timeout, send))) +(xref:nng_duration.5.adoc[`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 +return value of `NNG_ETIMEDOUT`. + +[[NNG_OPT_SOCKNAME]] +((`NNG_OPT_SOCKNAME`)):: +(((name, socket))) +(string) +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. +The value is intended for application use, and is not used for anything +in the library itself. + +[[NNG_OPT_MAXTTL]] +((`NNG_OPT_MAXTTL`)):: +(`int`) +(((time-to-live))) +This is the maximum number of times a message may traverse across +a xref:nng_device.3.adoc[`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. ++ +NOTE: Not all protocols support this option. +Those that do generally have a default value of 8. ++ +TIP: Each node along a forwarding path may have its own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. + +[[NNG_OPT_URL]] +((`NNG_OPT_URL`)):: +(((URI))) +(((URL))) +(string) +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. ++ +NOTE: Some transports will canonify URLs before returning them to the +application. + +[[NNG_OPT_PROTO]] +((`NNG_OPT_PROTO`)):: +(`int`) +This read-only option is used to obtain the 16-bit number for the socket's protocol. + +[[NNG_OPT_PEER]] +((`NNG_OPT_PEER`)):: +(`int`) +This read-only option is used to obtain the 16-bit number of the +peer protocol for the socket. + +[[NNG_OPT_PEER_GID]] +((`NNG_OPT_PEER_GID`)):: +(`uint64_t`) +This read-only option provides a connected peer's primary group id, when known. +This is the effective group id of the peer when either the underlying +`listen()` or `connect()` calls were made, and is not forgeable. +This option is generally only available on POSIX systems, only on certain transports. + +[[NNG_OPT_PEER_PID]] +((`NNG_OPT_PEER_PID`)):: +(`uint64_t`) +This read-only option provides the process id of the connected peer, when known. +This option is only available on certain platforms and transports. ++ +NOTE: Applications should not assume that the process ID does not change, +as it may be possible for a process to pass a file descriptor between processes. +However, it is not possible for a nefarious application to forge the identity +of a well-behaved one using this method. + +[[NNG_OPT_PEER_UID]] +((`NNG_OPT_PEER_UID`)):: +(`uint64_t`) +This read-only option provides a connected peer's user id. +This is the effective user id of the peer when either the underlying +`listen()` or `connect()` calls were made, and cannot be forged. +This option is generally only available on POSIX systems, on certain transports. + +[[NNG_OPT_PEER_ZONEID]] +((`NNG_OPT_PEER_ZONEID`)):: +(`uint64_t`) +This read-only option provides a connected peer's the zone id. +Zones (and this option) are only supported on Solaris and illumos systems, on select transports. + +[[NNG_OPT_PEERNAME]] +((`NNG_OPT_PEERNAME`)):: +(string) +This read-only option is used to obtain the name of the peer protocol for the socket. + +[[NNG_OPT_PROTONAME]] +((`NNG_OPT_PROTONAME`)):: +(string) +This read-only option is used to obtain the name of the socket's protocol. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_get.3.adoc[nng_dialer_get(3)], +xref:nng_dialer_set.3.adoc[nng_dialer_set(3)], +xref:nng_listener_get.3.adoc[nng_listener_get(3)], +xref:nng_listener_set.3.adoc[nng_listener_set(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], +xref:nng_socket_get.3.adoc[nng_socket_get(3)], +xref:nng_socket_set.3.adoc[nng_socket_set(3)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/external/nng/docs/man/nng_opts_parse.3supp.adoc b/external/nng/docs/man/nng_opts_parse.3supp.adoc new file mode 100644 index 0000000..beb9e1b --- /dev/null +++ b/external/nng/docs/man/nng_opts_parse.3supp.adoc @@ -0,0 +1,185 @@ += nng_opts_parse(3supp) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_opts_parse - parse command line options + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef struct nng_optspec { + const char *o_name; // Long style name (may be NULL for short only) + int o_short; // Short option (no clustering!) + int o_val; // Value stored on a good parse (>0) + bool o_arg; // Option takes an argument if true +} nng_optspec; + +int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx); +---- + +== DESCRIPTION + +The `nng_opts_parse()` is function is a supplemental function intended to +facilitate parsing command line arguments. +This function exists largely to stand in for `getopt()` from POSIX +systems, but it is available everywhere that _NNG_ is, and it includes +some capabilities missing from `getopt()`. + +The function parses arguments from `main()` (using _argc_ and _argv_), +starting at the index referenced by _idx_. +(New invocations typically set the value pointed to by _idx_ to 1.) + +Options are parsed as specified by _spec_ (see <