ne_sock_init(3) [centos man page]
NE_SOCK_INIT(3) neon API reference NE_SOCK_INIT(3) NAME
ne_sock_init, ne_sock_exit - perform library initialization SYNOPSIS
#include <ne_socket.h> int ne_sock_init(void); void ne_sock_exit(void); DESCRIPTION
In some platforms and configurations, neon may be using some socket or SSL libraries which require global initialization before use. To perform this initialization, the ne_sock_init function must be called before any other library functions are used. Once all use of neon is complete, ne_sock_exit can be called to perform de-initialization of socket or SSL libraries, if necessary. Uses of ne_sock_init and ne_sock_exit are "reference counted"; if N calls to ne_sock_init are made, only the Nth call to ne_sock_exit will have effect. ne_sock_init will set the disposition of the SIGPIPE signal to ignored. No change is made to the SIGPIPE disposition by ne_sock_exit. Both the SSL libraries supported by neon -- OpenSSL and GnuTLS -- require callbacks to be registered to allow thread-safe use of SSL. These callbacks are stored as global variables and so their state persists for as long as the library in question is loaded into the process. If multiple users of the SSL library exist within the process, this can be problematic, particularly if one is dynamically loaded (and may subsequently be unloaded). If neon is configured using the --enable-threadsafe-ssl flag, thread-safe SSL support will be enabled automatically, as covered in the following section. Otherwise, it is not safe to use neon with SSL in a multi-threaded process. The ne_has_support function can be used to determine whether neon is built to enable thread-safety support in the SSL library. Thread-safe SSL with OpenSSL neon follows two simple rules when dealing with the OpenSSL locking callbacks: o ne_sock_init will set thread-safety locking callbacks if and only if no locking callbacks are already registered. o ne_sock_exit will unset the thread-safety locking callbacks if and only if the locking callbacks registered are those registered by ne_sock_init. Applications and libraries should be able to co-operate to ensure that SSL use is always thread-safe if similar rules are always followed. Thread-safe SSL with GnuTLS The cryptography library used by GnuTLS, libgcrypt, only supports an initialization operation to register thread-safety callbacks. ne_sock_init will register the thread-safe locking callbacks on first use; ne_sock_exit cannot unregister them. If multiple users of GnuTLS are present within the process, it is unsafe to dynamically unload neon from the process if neon is configured with thread-safe SSL support enabled (since the callbacks would be left pointing at unmapped memory once neon is unloaded). RETURN VALUE
ne_sock_init returns zero on success, or non-zero on error. If an error occurs, no further use of the neon library should be attempted. SEE ALSO
neon(3), ne_has_support(3) AUTHOR
Joe Orton <neon@lists.manyfish.co.uk> Author. COPYRIGHT
neon 0.30.0 31 July 2013 NE_SOCK_INIT(3)
Check Out this Related Man Page
NEON(3) neon API reference NEON(3) NAME
neon - HTTP and WebDAV client library DESCRIPTION
neon is an HTTP and WebDAV client library. The major abstractions exposed are the HTTP session, created by ne_session_create; and the HTTP request, created by ne_request_create. HTTP authentication is handled transparently for server and proxy servers, see ne_set_server_auth; complete SSL/TLS support is also included, see ne_ssl_set_verify. CONVENTIONS
Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below. Thread-safeness and global initialization neon itself is implemented to be thread-safe (avoiding any use of global state), but relies on the operating system providing a thread-safe resolver interface. Modern operating systems offer the thread-safe getaddrinfo interface, which neon supports; some others implement gethostbyname using thread-local storage. To allow thread-safe use of SSL in the OpenSSL and GnuTLS libraries neon must be configured using the --enable-threadsafe-ssl; if this is done, locking callbacks will be registered by ne_sock_init; note that care must be exercised if neon is used in conjunction with another library which uses OpenSSL or GnuTLS. Some platforms and libraries used by neon require global initialization before use; notably: o The SIGPIPE signal disposition must be set to ignored or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer. o OpenSSL and GnuTLS require global initialization to load shared lookup tables. o The Win32 socket library requires initialization before use. The ne_sock_init function should be called before any other use of neon to perform any necessary initialization needed for the particular platform. Applications wishing to perform all the necessary process-global initialization steps themselves may omit to call ne_sock_init (and ne_sock_exit); neon neither checks whether these functions are called nor calls them itself. For some applications and configurations it may be necessary to call ne_i18n_init to initialize the support for internationalization in neon. Asynchronous signal safety No function in neon is defined to be "async-signal safe" - that is, no function is safe to call from a signal handler. Any call into the neon library from a signal handler will have undefined behaviour - in other words, it may crash the process. Functions using global state Any function in neon may modify the errno global variable as a side-effect. Except where explicitly documented, the value of errno is unspecified after any neon function call. Other than in the use of errno, the only functions which use or modify process-global state in neon are as follows: o ne_sock_init, ne_i18n_init, and ne_sock_exit, as described above o ne_debug_init and ne_debug, if enabled at compile time; for debugging output o ne_oom_callback for installing a process-global callback to be invoked on malloc failure Namespaces To avoid possible collisions between names used for symbols and preprocessor macros by an application and the libraries it uses, it is good practice for each library to reserve a particular namespace prefix. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions. The neon library reserves the use of the namespace prefixes ne_ and NE_. The libraries used by neon may also reserve certain namespaces; collisions between these libraries and a neon-based application will not be detected at compile time, since the underlying library interfaces are not exposed through the neon header files. Such collisions can only be detected at link time, when the linker attempts to resolve symbols. The following list documents some of the namespaces claimed by libraries used by neon; this list may be incomplete. SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_ Some of the many prefixes used by the OpenSSL library; little attempt has been made to keep exported symbols within any particular prefixes for this library. gnutls_, gcry_, gpg_ Namespaces used by the GnuTLS library (and dependencies thereof) XML_, Xml[A-Z] Namespaces used by the expat library. xml[A-Z], html[A-Z], docb[A-Z] Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes. inflate, deflate, crc32, compress, uncompres, adler32, zlib Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes. krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes. pakchois_ Namespace used by the pakchois library. px_ Namespace used by the libproxy library. Argument validation neon does not attempt to validate that the parameters passed to functions conform to the API (for instance, checking that pointer arguments are not NULL). Any use of the neon API which is not documented to produce a certain behaviour results is said to produce undefined behaviour; it is likely that neon will segfault under these conditions. URI paths, WebDAV metadata The path strings passed to any function must be URI-encoded by the application; neon never performs any URI encoding or decoding internally. WebDAV property names and values must be valid UTF-8 encoded Unicode strings. User interaction As a pure library interface, neon will never produce output on stdout or stderr; all user interaction is the responsibilty of the application. Memory handling neon does not attempt to cope gracefully with an out-of-memory situation; instead, by default, the abort function is called to immediately terminate the process. An application may register a custom function which will be called before abort in such a situation; see ne_oom_callback. Callbacks and userdata Whenever a callback is registered, a userdata pointer is also used to allow the application to associate a context with the callback. The userdata is of type void *, allowing any pointer to be used. Large File Support Since version 0.27.0, neon transparently uses the "LFS transitional" interfaces in places where file-backed file descriptors are manipulated. This means files larger than 2GiB can be handled on platforms with a native 32-bit off_t type, where LFS support is available. Some interfaces use the ne_off_t type, which is defined to be either off_t or off64_t according to whether LFS support is detected at build time. neon does not use or require the -D_FILE_OFFSET_BITS=64 macro definition. SEE ALSO
ne_session_create(3), ne_oom_callback AUTHOR
Joe Orton <neon@lists.manyfish.co.uk> Author. COPYRIGHT
neon 0.30.0 31 July 2013 NEON(3)