From c3e062661388f70386d6766e3ce648030af340ee Mon Sep 17 00:00:00 2001 From: Jake Woltersdorf Date: Mon, 4 Mar 2019 12:35:19 +0800 Subject: fixes #901 shorter option get/set functions for all types - Renamed internal nng_*_getx/setx methods with "nni" prefix - Moved stream get/set option definition macros to options.h and added "NNI_" prefix - "_PTR" variant of get/set option definition macros is for when first arg is passed as pointer (`nng_stream *s` vs `nng_pipe s`) - New get/set option functions for `nng_socket` are `nng_socket_get_X` eschewing the previous `nng_getopt` pattern - Macro-fy legacy getopt/setopt and implement in terms of "new" API - nng_setopt* use "new" shorter API. Add missing uint64 set functions. - Shorter get/set option functions get own man page and old getopt/setopt link to them - Built with -DNNG_ENABLE_DOC=ON and part of central libnng index - Update copyright --- docs/man/nng_ctx_set.3.adoc | 113 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/man/nng_ctx_set.3.adoc (limited to 'docs/man/nng_ctx_set.3.adoc') diff --git a/docs/man/nng_ctx_set.3.adoc b/docs/man/nng_ctx_set.3.adoc new file mode 100644 index 00000000..8c9c5095 --- /dev/null +++ b/docs/man/nng_ctx_set.3.adoc @@ -0,0 +1,113 @@ += nng_ctx_set(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_ctx_set - set context option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_ctx_set(nng_ctx ctx, const char *opt, const void *val, size_t valsz); + +int nng_ctx_set_bool(nng_ctx ctx, const char *opt, int bval); + +int nng_ctx_set_int(nng_ctx ctx, const char *opt, int ival); + +int nng_ctx_set_ms(nng_ctx ctx, const char *opt, nng_duration dur); + +int nng_ctx_set_size(nng_ctx ctx, const char *opt, size_t z); + +int nng_ctx_set_string(nng_ctx ctx, const char *opt, const char *str); + +int nng_ctx_set_uint64(nng_ctx ctx, const char *opt, uint64_t u64); +---- + +== DESCRIPTION + +NOTE: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. + +(((options, context))) +The `nng_ctx_set()` functions are used to configure options for +the context _ctx_. +The actual options that may be configured in this way vary, and are +specified by _opt_. + +NOTE: Context options are protocol specific. +The details will be documented with the protocol. + +=== Forms + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_ctx_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_ctx_set_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_ctx_set_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_ctx_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +type `<>`. +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] +<>, +<>, +<>, +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2