1= nng_getopt(3)
2//
3// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
4// Copyright 2018 Capitar IT Group BV <info@capitar.com>
5//
6// This document is supplied under the terms of the MIT License, a
7// copy of which should be located in the distribution where this
8// file was obtained (LICENSE.txt).  A copy of the license may also be
9// found online at https://opensource.org/licenses/MIT.
10//
11
12== NAME
13
14nng_getopt - get socket option
15
16== SYNOPSIS
17
18[source, c]
19----
20#include <nng/nng.h>
21
22int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp);
23
24int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp);
25
26int nng_getopt_int(nng_socket s, const char *opt, int *ivalp);
27
28int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp);
29
30int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr);
31
32int nng_getopt_size(nng_socket s, const char *opt, size_t *zp);
33
34int nng_getopt_string(nng_socket s, const char *opt, char **strp);
35
36int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p);
37
38----
39
40== DESCRIPTION
41
42IMPORTANT: These functions are deprecated.  Please see xref:nng_socket_get.3.adoc[nng_socket_get].
43They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
44
45(((options, socket)))
46The `nng_getopt()` functions are used to retrieve option values for
47the xref:nng_socket.5.adoc[socket] _s_.
48The actual options that may be retrieved in this way vary.
49A number of them are documented in xref:nng_options.5.adoc[nng_options(5)].
50
51Additionally transport-specific options and protocol-specific options are
52documented with the transports and protocols themselves.
53
54=== Forms
55
56In all of these forms, the option _opt_ is retrieved from the socket _s_.
57The forms vary based on the type of the option they take.
58
59The details of the type, size, and semantics of the option will depend
60on the actual option, and will be documented with the option itself.
61
62`nng_getopt()`::
63This function is untyped and can be used to retrieve the value of any option.
64The caller must store a pointer to a buffer to receive the value in _val_,
65and the size of the buffer shall be stored at the location referenced by
66_valszp_.
67+
68When the function returns, the actual size of the data copied (or that
69would have been copied if sufficient space were present) is stored at
70the location referenced by _valszp_.
71If the caller's buffer is not large enough to hold the entire object,
72then the copy is truncated.
73Therefore the caller should check for truncation by verifying that the
74returned size in _valszp_ does not exceed the original buffer size.
75+
76It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero.
77This can be used to determine the size of the buffer needed to receive
78the object.
79+
80TIP: It may be easier to use one of the typed forms of this function.
81
82`nng_getopt_bool()`::
83This function is for options which take a Boolean (`bool`).
84The value will be stored at _bvalp_.
85
86`nng_getopt_int()`::
87This function is for options which take an integer (`int`).
88The value will be stored at _ivalp_.
89
90`nng_getopt_ms()`::
91This function is used to retrieve time xref:nng_duration.5.adoc[durations]
92(such as timeouts), stored in _durp_ as a number of milliseconds.
93(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and
94the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.)
95
96`nng_getopt_ptr()`::
97This function is used to retrieve a pointer, _ptr_, to structured data.
98The data referenced by _ptr_ is generally managed using other functions.
99Note that this form is somewhat special in that the object is generally
100not copied, but instead the *pointer* to the object is copied.
101
102`nng_getopt_size()`::
103This function is used to retrieve a size into the pointer _zp_,
104typically for buffer sizes, message maximum sizes, and similar options.
105
106`nng_getopt_string()`::
107This function is used to retrieve a string into _strp_.
108This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`]
109and consequently must be freed by the caller using
110xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed.
111
112`nng_getopt_uint64()`::
113This function is used to retrieve a 64-bit unsigned value into the value
114referenced by _u64p_.
115This is typically used for options related to identifiers, network
116numbers, and similar.
117
118== RETURN VALUES
119
120These functions return 0 on success, and non-zero otherwise.
121
122== ERRORS
123
124[horizontal]
125`NNG_EBADTYPE`:: Incorrect type for option.
126`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
127`NNG_EINVAL`:: Size of destination _val_ too small for object.
128`NNG_ENOMEM`:: Insufficient memory exists.
129`NNG_ENOTSUP`:: The option _opt_ is not supported.
130`NNG_EWRITEONLY`:: The option _opt_ is write-only.
131
132== SEE ALSO
133
134[.text-left]
135xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)],
136xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
137xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
138xref:nng_setopt.3.adoc[nng_setopt(3)],
139xref:nng_strdup.3.adoc[nng_strdup(3)],
140xref:nng_strerror.3.adoc[nng_strerror(3)],
141xref:nng_strfree.3.adoc[nng_strfree(3)],
142xref:nng_duration.5.adoc[nng_duration(5)],
143xref:nng_options.5.adoc[nng_options(5)],
144xref:nng_socket.5.adoc[nng_socket(5)],
145xref:nng.7.adoc[nng(7)]
146