From f73cd76f54b8aead38689e0ea805d5d805dfbe96 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 23:07:20 -0700 Subject: Staging work. converted nng_ipc. --- docs/man/nng_pipe_getopt.3.adoc | 155 ---------------------------------------- 1 file changed, 155 deletions(-) delete mode 100644 docs/man/nng_pipe_getopt.3.adoc (limited to 'docs/man/nng_pipe_getopt.3.adoc') diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc deleted file mode 100644 index 648abbcc..00000000 --- a/docs/man/nng_pipe_getopt.3.adoc +++ /dev/null @@ -1,155 +0,0 @@ -= nng_pipe_getopt(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_pipe_getopt - get pipe option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp); - -int nng_pipe_getopt_bool(nng_pipe p, const char *opt, bool *bvalp); - -int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp); - -int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp); - -int nng_pipe_getopt_ptr(nng_pipe p, const char *opt, void **ptr); - -int nng_pipe_getopt_sockaddr(nng_pipe p, const char *opt, nng_sockaddr *sap); - -int nng_pipe_getopt_string(nng_pipe p, const char *opt, char **strp); - -int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp); - -int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -NOTE: These functions are deprecated. Please see xref:nng_pipe_get.3.adoc[nng_pipe_get]. - -(((options, pipe))) -The `nng_pipe_getopt()` functions are used to retrieve option values for -the xref:nng_pipe.5.adoc[pipe] _p_. -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 and protocol-specific options are -documented with the transports and protocols themselves. - -NOTE: All options on a pipe are read-only values. -Modification of options may be done before the pipe is created using -xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] or -xref:nng_dialer_getopt.3.adoc[`nng_dialer_setopt()`]. - -Any option that is set on a dialer or listener will normally be retrievable -from pipes created by that dialer or listener. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the pipe _p_. - -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_pipe_getopt()`:: -This is untyped, and can be used to retrieve the value of any option. -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 -size returned 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_pipe_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_pipe_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_pipe_getopt_ms()`:: -This function is used to retrieve time durations -(xref:nng_duration.5.adoc[`nng_duration`]) in milliseconds, which are stored in -_durp_. - -`nng_pipe_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_pipe_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_pipe_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into _sap_. - -`nng_pipe_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_pipe_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 _p_ does not refer to an open pipe. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(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_pipe.5.adoc[nng_pipe(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] -- cgit v1.2.3-70-g09d2