pax_global_header00006660000000000000000000000064145703652100014515gustar00rootroot0000000000000052 comment=85fbe7f9e4642b554d0d97f2e3ff2aa12978691a nng-1.7.3/000077500000000000000000000000001457036521000123075ustar00rootroot00000000000000nng-1.7.3/.clang-format000066400000000000000000000007021457036521000146610ustar00rootroot00000000000000BasedOnStyle: 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 nng-1.7.3/.codecov.yml000066400000000000000000000001301457036521000145240ustar00rootroot00000000000000ignore: - "tests" - "src/testing" - "perf" - "**/*_test.c" coverage: range: 50..95 nng-1.7.3/.gitattributes000066400000000000000000000000231457036521000151750ustar00rootroot00000000000000*.sh text eol=lf nng-1.7.3/.github/000077500000000000000000000000001457036521000136475ustar00rootroot00000000000000nng-1.7.3/.github/FUNDING.yml000066400000000000000000000002501457036521000154610ustar00rootroot00000000000000# These are supported funding model platforms github: gdamore patreon: gedamore custom: [ "https://staysail.tech/support/" ] custom: [ "https://leanpub.com/nngref2e" ] nng-1.7.3/.github/ISSUE_TEMPLATE/000077500000000000000000000000001457036521000160325ustar00rootroot00000000000000nng-1.7.3/.github/ISSUE_TEMPLATE/bug_report.md000066400000000000000000000011551457036521000205260ustar00rootroot00000000000000--- 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. nng-1.7.3/.github/ISSUE_TEMPLATE/feature_request.md000066400000000000000000000011231457036521000215540ustar00rootroot00000000000000--- 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. nng-1.7.3/.github/pull_request_template.md000066400000000000000000000004121457036521000206050ustar00rootroot00000000000000fixes # 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. nng-1.7.3/.github/workflows/000077500000000000000000000000001457036521000157045ustar00rootroot00000000000000nng-1.7.3/.github/workflows/codeql-analysis.yml000066400000000000000000000046631457036521000215300ustar00rootroot00000000000000# 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 nng-1.7.3/.github/workflows/coverage.yml000066400000000000000000000030401457036521000202170ustar00rootroot00000000000000name: 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 nng-1.7.3/.github/workflows/darwin.yml000066400000000000000000000010141457036521000177070ustar00rootroot00000000000000name: 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 nng-1.7.3/.github/workflows/linux.yml000066400000000000000000000010231457036521000175620ustar00rootroot00000000000000name: 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-failurenng-1.7.3/.github/workflows/sanitizer.yml000066400000000000000000000014741457036521000204450ustar00rootroot00000000000000name: 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 nng-1.7.3/.github/workflows/windows.yml000066400000000000000000000012411457036521000201170ustar00rootroot00000000000000name: 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 nng-1.7.3/.gitignore000066400000000000000000000002201457036521000142710ustar00rootroot00000000000000build lxbuild winbuild wbuild .cache .vs .vscode/.cmaketools.json .vscode .idea .DS_Store etc/nng.sublime-workspace cmake-build-* docs/**/*.htmlnng-1.7.3/.gitmodules000066400000000000000000000001531457036521000144630ustar00rootroot00000000000000[submodule "extern/nng-wolfssl"] path = extern/nng-wolfssl url = https://github.com/staysail/nng-wolfssl nng-1.7.3/.grcov.yml000066400000000000000000000001371457036521000142310ustar00rootroot00000000000000branch: true ignore-not-existing: true filter: covered output-type: lcov output-file: lcov.infonng-1.7.3/CMakeLists.txt000066400000000000000000000271021457036521000150510ustar00rootroot00000000000000# # 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) nng-1.7.3/CODE_OF_CONDUCT.adoc000066400000000000000000000061161457036521000154200ustar00rootroot00000000000000= 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 nng-1.7.3/LICENSE.txt000066400000000000000000000022021457036521000141260ustar00rootroot00000000000000The 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. nng-1.7.3/README.adoc000066400000000000000000000175671457036521000141140ustar00rootroot00000000000000ifdef::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.]. nng-1.7.3/RELEASE_NOTES.adoc000066400000000000000000000115251457036521000151730ustar00rootroot00000000000000ifdef::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. nng-1.7.3/UKRAINE.adoc000066400000000000000000000124141457036521000142370ustar00rootroot00000000000000# 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 mean 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, 2022nng-1.7.3/cmake/000077500000000000000000000000001457036521000133675ustar00rootroot00000000000000nng-1.7.3/cmake/CheckSanitizer.cmake000066400000000000000000000022461457036521000173030ustar00rootroot00000000000000# # 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 () nng-1.7.3/cmake/FindMbedTLS.cmake000066400000000000000000000105101457036521000164210ustar00rootroot00000000000000# # 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}) nng-1.7.3/cmake/NNGHelpers.cmake000066400000000000000000000142351457036521000163430ustar00rootroot00000000000000# # 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) nng-1.7.3/cmake/NNGOptions.cmake000066400000000000000000000120471457036521000163730ustar00rootroot00000000000000# # 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() nng-1.7.3/cmake/nng-config.cmake.in000066400000000000000000000014331457036521000170240ustar00rootroot00000000000000# 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@) nng-1.7.3/demo/000077500000000000000000000000001457036521000132335ustar00rootroot00000000000000nng-1.7.3/demo/async/000077500000000000000000000000001457036521000143505ustar00rootroot00000000000000nng-1.7.3/demo/async/CMakeLists.txt000066400000000000000000000016071457036521000171140ustar00rootroot00000000000000# # 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) nng-1.7.3/demo/async/README.adoc000066400000000000000000000034101457036521000161330ustar00rootroot00000000000000= 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.) nng-1.7.3/demo/async/client.c000066400000000000000000000043251457036521000157760ustar00rootroot00000000000000// 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); } nng-1.7.3/demo/async/run.sh000077500000000000000000000006511457036521000155150ustar00rootroot00000000000000#!/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 nng-1.7.3/demo/async/server.c000066400000000000000000000107621457036521000160300ustar00rootroot00000000000000// 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); } nng-1.7.3/demo/http_client/000077500000000000000000000000001457036521000155505ustar00rootroot00000000000000nng-1.7.3/demo/http_client/CMakeLists.txt000066400000000000000000000012741457036521000203140ustar00rootroot00000000000000# # 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) nng-1.7.3/demo/http_client/README.adoc000066400000000000000000000026421457036521000173410ustar00rootroot00000000000000= 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 ---- nng-1.7.3/demo/http_client/http_client.c000066400000000000000000000073761457036521000202460ustar00rootroot00000000000000// // 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); } nng-1.7.3/demo/pubsub_forwarder/000077500000000000000000000000001457036521000166065ustar00rootroot00000000000000nng-1.7.3/demo/pubsub_forwarder/CMakeLists.txt000066400000000000000000000011611457036521000213450ustar00rootroot00000000000000# 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) nng-1.7.3/demo/pubsub_forwarder/README.adoc000066400000000000000000000027121457036521000203750ustar00rootroot00000000000000= 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 ---- nng-1.7.3/demo/pubsub_forwarder/pubsub_forwarder.c000066400000000000000000000052101457036521000223230ustar00rootroot00000000000000// // 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; }nng-1.7.3/demo/raw/000077500000000000000000000000001457036521000140245ustar00rootroot00000000000000nng-1.7.3/demo/raw/CMakeLists.txt000066400000000000000000000012731457036521000165670ustar00rootroot00000000000000# # 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}) nng-1.7.3/demo/raw/README.adoc000066400000000000000000000032751457036521000156200ustar00rootroot00000000000000= 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 & ---- nng-1.7.3/demo/raw/raw.c000066400000000000000000000117451457036521000147710ustar00rootroot00000000000000// 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); } nng-1.7.3/demo/reqrep/000077500000000000000000000000001457036521000145315ustar00rootroot00000000000000nng-1.7.3/demo/reqrep/CMakeLists.txt000066400000000000000000000012741457036521000172750ustar00rootroot00000000000000# # 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) nng-1.7.3/demo/reqrep/README.adoc000066400000000000000000000027151457036521000163230ustar00rootroot00000000000000= 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 ---- nng-1.7.3/demo/reqrep/reqrep.c000066400000000000000000000136531457036521000162030ustar00rootroot00000000000000// // 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); } nng-1.7.3/demo/rest/000077500000000000000000000000001457036521000142105ustar00rootroot00000000000000nng-1.7.3/demo/rest/CMakeLists.txt000066400000000000000000000012021457036521000167430ustar00rootroot00000000000000# # 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) nng-1.7.3/demo/rest/README.adoc000066400000000000000000000022201457036521000157710ustar00rootroot00000000000000= 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 ---- nng-1.7.3/demo/rest/server.c000066400000000000000000000235331457036521000156700ustar00rootroot00000000000000// // 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); } nng-1.7.3/demo/stream/000077500000000000000000000000001457036521000145265ustar00rootroot00000000000000nng-1.7.3/demo/stream/CMakeLists.txt000066400000000000000000000015211457036521000172650ustar00rootroot00000000000000# # 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) nng-1.7.3/demo/stream/platform/000077500000000000000000000000001457036521000163525ustar00rootroot00000000000000nng-1.7.3/demo/stream/platform/posix/000077500000000000000000000000001457036521000175145ustar00rootroot00000000000000nng-1.7.3/demo/stream/platform/posix/server.c000066400000000000000000000025121457036521000211660ustar00rootroot00000000000000// 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; } nng-1.7.3/demo/stream/platform/windows/000077500000000000000000000000001457036521000200445ustar00rootroot00000000000000nng-1.7.3/demo/stream/platform/windows/server.c000066400000000000000000000037401457036521000215220ustar00rootroot00000000000000// 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; } nng-1.7.3/demo/stream/stream.c000066400000000000000000000054031457036521000161670ustar00rootroot00000000000000// 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; } nng-1.7.3/docs/000077500000000000000000000000001457036521000132375ustar00rootroot00000000000000nng-1.7.3/docs/BUILD_ANDROID.adoc000066400000000000000000000052471457036521000160760ustar00rootroot00000000000000ifdef::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. nng-1.7.3/docs/BUILD_CROSSCOMPILE.adoc000066400000000000000000000037431457036521000167170ustar00rootroot00000000000000ifdef::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. nng-1.7.3/docs/BUILD_IOS.adoc000066400000000000000000000033321457036521000154410ustar00rootroot00000000000000ifdef::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.) nng-1.7.3/docs/BUILD_TLS.adoc000066400000000000000000000034301457036521000154500ustar00rootroot00000000000000ifdef::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 ---- nng-1.7.3/docs/BUILD_ZEROTIER.adoc000066400000000000000000000040711457036521000162530ustar00rootroot00000000000000ifdef::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 ---- nng-1.7.3/docs/CONTRIBUTING.adoc000066400000000000000000000127351457036521000160060ustar00rootroot00000000000000= 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. nng-1.7.3/docs/LICENSE.adoc000066400000000000000000000022061457036521000151510ustar00rootroot00000000000000= 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. nng-1.7.3/docs/RATIONALE.adoc000066400000000000000000000402601457036521000154070ustar00rootroot00000000000000= 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_. nng-1.7.3/docs/README.txt000066400000000000000000000010121457036521000147270ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/000077500000000000000000000000001457036521000140125ustar00rootroot00000000000000nng-1.7.3/docs/man/CMakeLists.txt000066400000000000000000000274651457036521000165700ustar00rootroot00000000000000# # Copyright 2020 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_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_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 () nng-1.7.3/docs/man/libnng.3.adoc000066400000000000000000000616731457036521000162710ustar00rootroot00000000000000= 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 |=== === 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)] nng-1.7.3/docs/man/man1.desc000066400000000000000000000001271457036521000155060ustar00rootroot00000000000000This section documents utilities and programs that are included with the distribution. nng-1.7.3/docs/man/man1.sect000066400000000000000000000000271457036521000155250ustar00rootroot00000000000000Commands and Utilities nng-1.7.3/docs/man/man3.desc000066400000000000000000000003771457036521000155170ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3.sect000066400000000000000000000000221457036521000155220ustar00rootroot00000000000000Library Functions nng-1.7.3/docs/man/man3compat.desc000066400000000000000000000011631457036521000167150ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3compat.sect000066400000000000000000000000351457036521000167320ustar00rootroot00000000000000Compatible Library Functions nng-1.7.3/docs/man/man3http.desc000066400000000000000000000010451457036521000164100ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3http.sect000066400000000000000000000000341457036521000164250ustar00rootroot00000000000000Supplemental HTTP Functions nng-1.7.3/docs/man/man3str.desc000066400000000000000000000005211457036521000162370ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3str.sect000066400000000000000000000000331457036521000162550ustar00rootroot00000000000000Supplemental TCP Functions nng-1.7.3/docs/man/man3supp.desc000066400000000000000000000005571457036521000164270ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3supp.sect000066400000000000000000000000271457036521000164370ustar00rootroot00000000000000Supplemental Functions nng-1.7.3/docs/man/man3tls.desc000066400000000000000000000015261457036521000162370ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man3tls.sect000066400000000000000000000000331457036521000162470ustar00rootroot00000000000000Supplemental TLS Functions nng-1.7.3/docs/man/man5.desc000066400000000000000000000002411457036521000155070ustar00rootroot00000000000000This section documents core macros and types that are available. These are the core types and macros that most Scalabilty Protocols applications need will use. nng-1.7.3/docs/man/man5.sect000066400000000000000000000000211457036521000155230ustar00rootroot00000000000000Macros and Types nng-1.7.3/docs/man/man7.desc000066400000000000000000000011201457036521000155060ustar00rootroot00000000000000This 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. nng-1.7.3/docs/man/man7.sect000066400000000000000000000000311457036521000155260ustar00rootroot00000000000000Protocols and Transports nng-1.7.3/docs/man/nn_allocmsg.3compat.adoc000066400000000000000000000040101457036521000204760ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_bind.3compat.adoc000066400000000000000000000041251457036521000176200ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_close.3compat.adoc000066400000000000000000000023611457036521000200110ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_cmsg.3compat.adoc000066400000000000000000000051451457036521000176400ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_connect.3compat.adoc000066400000000000000000000040121457036521000203300ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_device.3compat.adoc000066400000000000000000000032231457036521000201410ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_errno.3compat.adoc000066400000000000000000000046071457036521000200360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_freemsg.3compat.adoc000066400000000000000000000022641457036521000203360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_get_statistic.3compat.adoc000066400000000000000000000017441457036521000215560ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_getsockopt.3compat.adoc000066400000000000000000000175001457036521000210670ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_poll.3compat.adoc000066400000000000000000000065431457036521000176600ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_reallocmsg.3compat.adoc000066400000000000000000000031361457036521000210350ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_recv.3compat.adoc000066400000000000000000000047761457036521000176570ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_recvmsg.3compat.adoc000066400000000000000000000060511457036521000203520ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_send.3compat.adoc000066400000000000000000000046271457036521000176440ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_sendmsg.3compat.adoc000066400000000000000000000066431457036521000203530ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_setsockopt.3compat.adoc000066400000000000000000000155341457036521000211100ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_shutdown.3compat.adoc000066400000000000000000000027571457036521000205700ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_socket.3compat.adoc000066400000000000000000000044251457036521000201770ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_strerror.3compat.adoc000066400000000000000000000021401457036521000205610ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nn_term.3compat.adoc000066400000000000000000000031351457036521000176530ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng.7.adoc000066400000000000000000000204251457036521000155740ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio.5.adoc000066400000000000000000000046351457036521000164270ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_abort.3.adoc000066400000000000000000000025231457036521000176060ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_alloc.3.adoc000066400000000000000000000065411457036521000175750ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_begin.3.adoc000066400000000000000000000035501457036521000175640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_busy.3.adoc000066400000000000000000000025471457036521000174670ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_cancel.3.adoc000066400000000000000000000027201457036521000177230ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_count.3.adoc000066400000000000000000000033451457036521000176320ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_defer.3.adoc000066400000000000000000000050421457036521000175630ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_finish.3.adoc000066400000000000000000000031471457036521000177620ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_free.3.adoc000066400000000000000000000027161457036521000174240ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_get_input.3.adoc000066400000000000000000000026341457036521000205000ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_get_msg.3.adoc000066400000000000000000000022241457036521000201220ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_get_output.3.adoc000066400000000000000000000027701457036521000207020ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_result.3.adoc000066400000000000000000000030421457036521000200120ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_set_input.3.adoc000066400000000000000000000033741457036521000205160ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_set_iov.3.adoc000066400000000000000000000036101457036521000201450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_set_msg.3.adoc000066400000000000000000000021001457036521000201270ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_set_output.3.adoc000066400000000000000000000031661457036521000207160ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_set_timeout.3.adoc000066400000000000000000000044701457036521000210430ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_stop.3.adoc000066400000000000000000000031631457036521000174650ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_aio_wait.3.adoc000066400000000000000000000024631457036521000174460ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_alloc.3.adoc000066400000000000000000000027621457036521000167460ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_bus.7.adoc000066400000000000000000000056751457036521000164570ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_bus_open.3.adoc000066400000000000000000000024451457036521000174640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_clock.3supp.adoc000066400000000000000000000027431457036521000176560ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_close.3.adoc000066400000000000000000000031061457036521000167520ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_compat.3compat.adoc000066400000000000000000000206031457036521000203350ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx.5.adoc000066400000000000000000000131051457036521000164450ustar00rootroot00000000000000= 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 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(ec[i].ctx, rep_socket) nng_aio_alloc(ec[i].aio, echo, &e[i]); ec[i].state = INIT; echo(&ec[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)] nng-1.7.3/docs/man/nng_ctx_close.3.adoc000066400000000000000000000025601457036521000176330ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_get.3.adoc000066400000000000000000000106771457036521000173150ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_getopt.3.adoc000066400000000000000000000112441457036521000200270ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_id.3.adoc000066400000000000000000000023621457036521000171220ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_open.3.adoc000066400000000000000000000041321457036521000174640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_recv.3.adoc000066400000000000000000000044611457036521000174670ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_recvmsg.3.adoc000066400000000000000000000035511457036521000201750ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_send.3.adoc000066400000000000000000000061701457036521000174600ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_sendmsg.3.adoc000066400000000000000000000055011457036521000201640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_set.3.adoc000066400000000000000000000067131457036521000173250ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ctx_setopt.3.adoc000066400000000000000000000071171457036521000200470ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_alloc.3supp.adoc000066400000000000000000000032511457036521000203400ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_free.3supp.adoc000066400000000000000000000014571457036521000201750ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_until.3supp.adoc000066400000000000000000000046661457036521000204140ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_wait.3supp.adoc000066400000000000000000000042251457036521000202140ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_wake.3supp.adoc000066400000000000000000000033151457036521000201760ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_cv_wake1.3supp.adoc000066400000000000000000000032301457036521000202530ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_device.3.adoc000066400000000000000000000105121457036521000171030ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dial.3.adoc000066400000000000000000000067731457036521000165730ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer.5.adoc000066400000000000000000000053261457036521000171150ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_close.3.adoc000066400000000000000000000026571457036521000203040ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_create.3.adoc000066400000000000000000000051621457036521000204340ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_get.3.adoc000066400000000000000000000122421457036521000177450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_getopt.3.adoc000066400000000000000000000126411457036521000204730ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_id.3.adoc000066400000000000000000000025061457036521000175640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_set.3.adoc000066400000000000000000000102471457036521000177640ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_setopt.3.adoc000066400000000000000000000106271457036521000205110ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_dialer_start.3.adoc000066400000000000000000000046061457036521000203300ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_duration.5.adoc000066400000000000000000000023731457036521000175010ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_free.3.adoc000066400000000000000000000024031457036521000165650ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_getopt.3.adoc000066400000000000000000000122221457036521000171460ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_alloc.3http.adoc000066400000000000000000000024361457036521000222410ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_connect.3http.adoc000066400000000000000000000055371457036521000226050ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_free.3http.adoc000066400000000000000000000021701457036521000220630ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_get_tls.3http.adoc000066400000000000000000000035131457036521000226050ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_set_tls.3http.adoc000066400000000000000000000032631457036521000226230ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_client_transact.3http.adoc000066400000000000000000000055361457036521000227720ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_close.3http.adoc000066400000000000000000000022001457036521000217200ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_read.3http.adoc000066400000000000000000000050501457036521000215340ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_read_all.3http.adoc000066400000000000000000000051631457036521000223710ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_read_req.3http.adoc000066400000000000000000000040071457036521000224040ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_read_res.3http.adoc000066400000000000000000000046421457036521000224130ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_transact.3http.adoc000066400000000000000000000064601457036521000224460ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_write.3http.adoc000066400000000000000000000050641457036521000217600ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_write_all.3http.adoc000066400000000000000000000072641457036521000226140ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_write_req.3http.adoc000066400000000000000000000045641457036521000226330ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_conn_write_res.3http.adoc000066400000000000000000000053251457036521000226310ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_alloc.3http.adoc000066400000000000000000000171471457036521000224050ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_collect_body.3http.adoc000066400000000000000000000052231457036521000237450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_free.3http.adoc000066400000000000000000000022031457036521000222170ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_get_data.3http.adoc000066400000000000000000000022311457036521000230470ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_set_data.3http.adoc000066400000000000000000000031731457036521000230710ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_set_host.3http.adoc000066400000000000000000000033541457036521000231360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_set_method.3http.adoc000066400000000000000000000035651457036521000234450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_handler_set_tree.3http.adoc000066400000000000000000000045031457036521000231150ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_hijack.3http.adoc000066400000000000000000000040251457036521000210360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_add_header.3http.adoc000066400000000000000000000040371457036521000225170ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_alloc.3http.adoc000066400000000000000000000047711457036521000215560ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_copy_data.3http.adoc000066400000000000000000000035561457036521000224270ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_del_header.3http.adoc000066400000000000000000000030001457036521000225200ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_free.3http.adoc000066400000000000000000000021121457036521000213700ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_get_data.3http.adoc000066400000000000000000000024241457036521000222250ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_get_header.3http.adoc000066400000000000000000000025561457036521000225520ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_get_method.3http.adoc000066400000000000000000000020341457036521000225710ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_get_uri.3http.adoc000066400000000000000000000022461457036521000221150ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_get_version.3http.adoc000066400000000000000000000020541457036521000230000ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_reset.3http.adoc000066400000000000000000000022571457036521000216030ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_set_data.3http.adoc000066400000000000000000000037241457036521000222450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_set_header.3http.adoc000066400000000000000000000033621457036521000225620ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_set_method.3http.adoc000066400000000000000000000026071457036521000226130ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_set_uri.3http.adoc000066400000000000000000000032001457036521000221200ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_req_set_version.3http.adoc000066400000000000000000000031131457036521000230110ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_add_header.3http.adoc000066400000000000000000000040411457036521000225140ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_alloc.3http.adoc000066400000000000000000000047741457036521000215630ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_alloc_error.3http.adoc000066400000000000000000000033631457036521000227650ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_copy_data.3http.adoc000066400000000000000000000035611457036521000224250ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_del_header.3http.adoc000066400000000000000000000030031457036521000225250ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_free.3http.adoc000066400000000000000000000021151457036521000213750ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_get_data.3http.adoc000066400000000000000000000024251457036521000222300ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_get_header.3http.adoc000066400000000000000000000025601457036521000225470ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_get_reason.3http.adoc000066400000000000000000000023241457036521000226040ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_get_status.3http.adoc000066400000000000000000000106051457036521000226410ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_get_version.3http.adoc000066400000000000000000000020561457036521000230040ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_reset.3http.adoc000066400000000000000000000017211457036521000216000ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_set_data.3http.adoc000066400000000000000000000037271457036521000222520ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_set_header.3http.adoc000066400000000000000000000033641457036521000225660ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_set_reason.3http.adoc000066400000000000000000000032051457036521000226170ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_set_status.3http.adoc000066400000000000000000000113311457036521000226520ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_res_set_version.3http.adoc000066400000000000000000000031161457036521000230160ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_add_handler.3http.adoc000066400000000000000000000033521457036521000234220ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_del_handler.3http.adoc000066400000000000000000000025211457036521000234330ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_get_addr.3http.adoc000066400000000000000000000021421457036521000227420ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_get_tls.3http.adoc000066400000000000000000000035021457036521000226330ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_hold.3http.adoc000066400000000000000000000041551457036521000221250ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_release.3http.adoc000066400000000000000000000027531457036521000226210ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_res_error.3http.adoc000066400000000000000000000036211457036521000231760ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_set_error_file.3http.adoc000066400000000000000000000050341457036521000241770ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_set_error_page.3http.adoc000066400000000000000000000044111457036521000241720ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_set_tls.3http.adoc000066400000000000000000000035401457036521000226510ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_start.3http.adoc000066400000000000000000000027001457036521000223260ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_http_server_stop.3http.adoc000066400000000000000000000033411457036521000221600ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_id_map.3supp.adoc000066400000000000000000000076531457036521000200210ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_inproc.7.adoc000066400000000000000000000042131457036521000171430ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_inproc_register.3.adoc000066400000000000000000000021561457036521000210470ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_iov.5.adoc000066400000000000000000000026521457036521000164510ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ipc.7.adoc000066400000000000000000000111601457036521000164230ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ipc_options.5.adoc000066400000000000000000000103641457036521000202010ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_ipc_register.3.adoc000066400000000000000000000021151457036521000203230ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listen.3.adoc000066400000000000000000000054031457036521000171450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener.5.adoc000066400000000000000000000053711457036521000175020ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_close.3.adoc000066400000000000000000000026561457036521000206700ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_create.3.adoc000066400000000000000000000051071457036521000210200ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_get.3.adoc000066400000000000000000000122471457036521000203370ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_getopt.3.adoc000066400000000000000000000126421457036521000210610ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_id.3.adoc000066400000000000000000000025561457036521000201560ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_set.3.adoc000066400000000000000000000105221457036521000203450ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_setopt.3.adoc000066400000000000000000000111021457036521000210630ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_listener_start.3.adoc000066400000000000000000000027341457036521000207150ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg.5.adoc000066400000000000000000000042141457036521000164360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_alloc.3.adoc000066400000000000000000000030021457036521000176000ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_append.3.adoc000066400000000000000000000032331457036521000177630ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_body.3.adoc000066400000000000000000000032571457036521000174570ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_capacity.3.adoc000066400000000000000000000021461457036521000203130ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_chop.3.adoc000066400000000000000000000034441457036521000174510ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_clear.3.adoc000066400000000000000000000014001457036521000175740ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_dup.3.adoc000066400000000000000000000023221457036521000173020ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_free.3.adoc000066400000000000000000000015151457036521000174360ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_get_pipe.3.adoc000066400000000000000000000032541457036521000203130ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header.3.adoc000066400000000000000000000031321457036521000177420ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_append.3.adoc000066400000000000000000000032631457036521000212760ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_chop.3.adoc000066400000000000000000000033401457036521000207540ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_clear.3.adoc000066400000000000000000000015101457036521000211060ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_insert.3.adoc000066400000000000000000000035231457036521000213320ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_len.3.adoc000066400000000000000000000016051457036521000206030ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_header_trim.3.adoc000066400000000000000000000034051457036521000210000ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_insert.3.adoc000066400000000000000000000036771457036521000200340ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_len.3.adoc000066400000000000000000000015431457036521000172740ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_realloc.3.adoc000066400000000000000000000042021457036521000201320ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_reserve.3.adoc000066400000000000000000000036021457036521000201670ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_set_pipe.3.adoc000066400000000000000000000023001457036521000203160ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msg_trim.3.adoc000066400000000000000000000033041457036521000174660ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_msleep.3supp.adoc000066400000000000000000000020751457036521000200460ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_mtx_alloc.3supp.adoc000066400000000000000000000031011457036521000205320ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_mtx_free.3supp.adoc000066400000000000000000000015311457036521000203660ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_mtx_lock.3supp.adoc000066400000000000000000000033511457036521000203770ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_mtx_unlock.3supp.adoc000066400000000000000000000021371457036521000207430ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_options.5.adoc000066400000000000000000000350671457036521000173550ustar00rootroot00000000000000= 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)] nng-1.7.3/docs/man/nng_opts_parse.3supp.adoc000066400000000000000000000134701457036521000207410ustar00rootroot00000000000000= 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 <