coap_startup: Make coap_startup() first function call in examples

This then makes sure that all things libcoap are properly initialized
before use, and coders realize they need to do this.

Note: coap_new_context() continues to make sure that coap_startup()
is invoked if not done previously, but this may be too late.

configure.ac

@@ -1100,6 +1100,7 @@ man/coap_encryption.txt
 man/coap_endpoint_client.txt
 man/coap_endpoint_server.txt
 man/coap_handler.txt
+man/coap_init.txt
 man/coap_io.txt
 man/coap_keepalive.txt
 man/coap_logging.txt

examples/coap-client.c

@@ -1606,6 +1606,9 @@ main(int argc, char **argv) {
   struct sigaction sa;
 #endif
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv,
                        "a:b:c:e:f:h:j:k:l:m:no:p:rs:t:u:v:wA:B:C:E:G:H:J:K:L:M:NO:P:R:T:UV:X:")) != -1) {
     switch (opt) {
@@ -1775,7 +1778,6 @@ main(int argc, char **argv) {
   sigaction(SIGPIPE, &sa, NULL);
 #endif
 
-  coap_startup();
   coap_set_log_level(log_level);
   coap_dtls_set_log_level(dtls_log_level);
 

examples/coap-rd.c

@@ -767,6 +767,9 @@ main(int argc, char **argv) {
   struct sigaction sa;
 #endif
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv, "A:c:C:g:G:h:k:n:R:p:v:T:V:w:")) != -1) {
     switch (opt) {
     case 'A' :
@@ -834,7 +837,6 @@ main(int argc, char **argv) {
     }
   }
 
-  coap_startup();
   coap_set_log_level(log_level);
   coap_dtls_set_log_level(dtls_log_level);
 

examples/coap-server.c

@@ -2734,6 +2734,9 @@ main(int argc, char **argv) {
   struct sigaction sa;
 #endif
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   clock_offset = time(NULL);
 
   while ((opt = getopt(argc, argv,
@@ -2910,7 +2913,6 @@ main(int argc, char **argv) {
   sigaction(SIGPIPE, &sa, NULL);
 #endif
 
-  coap_startup();
   coap_set_log_level(log_level);
   coap_dtls_set_log_level(dtls_log_level);
 

examples/contiki/server.c

@@ -162,6 +162,9 @@ struct etimer dirty_timer;
 PROCESS_THREAD(coap_server_process, ev, data) {
   PROCESS_BEGIN();
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   clock_offset = clock_time();
   init_coap_server(&coap_context);
 
@@ -182,6 +185,7 @@ PROCESS_THREAD(coap_server_process, ev, data) {
       etimer_reset(&dirty_timer);
     }
   }
+  coap_cleanup();
 
   PROCESS_END();
 }

examples/etsi_iot_01.c

@@ -582,6 +582,9 @@ main(int argc, char **argv) {
   coap_log_t log_level = COAP_LOG_WARN;
   struct sigaction sa;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv, "A:p:v:")) != -1) {
     switch (opt) {
     case 'A' :

examples/lwip/client-coap.c

@@ -119,6 +119,9 @@ client_coap_init(coap_lwip_input_wait_handler_t input_wait, void *input_arg,
   const char *use_id = "abc";
   coap_pdu_type_t pdu_type = COAP_MESSAGE_CON;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv, ":k:Nu:v:V:")) != -1) {
     switch (opt) {
     case 'k':
@@ -227,6 +230,7 @@ client_coap_finished(void) {
   coap_delete_optlist(optlist);
   coap_free_context(main_coap_context);
   main_coap_context = NULL;
+  coap_cleanup();
 }
 
 int

examples/lwip/server-coap.c

@@ -128,6 +128,9 @@ server_coap_init(coap_lwip_input_wait_handler_t input_wait,
   int have_ep = 0;
   coap_str_const_t node;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv, ":k:v:V:")) != -1) {
     switch (opt) {
     case 'k':
@@ -197,6 +200,7 @@ void
 server_coap_finished(void) {
   coap_free_context(main_coap_context);
   main_coap_context = NULL;
+  coap_cleanup();
 }
 
 void

examples/oscore-interop-server.c

@@ -593,6 +593,9 @@ main(int argc, char **argv) {
   struct sigaction sa;
 #endif
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   while ((opt = getopt(argc, argv, "g:G:l:p:rv:A:E:L:NX:")) != -1) {
     switch (opt) {
     case 'A' :
@@ -659,7 +662,6 @@ main(int argc, char **argv) {
   sigaction(SIGPIPE, &sa, NULL);
 #endif
 
-  coap_startup();
   coap_dtls_set_log_level(log_level);
   coap_set_log_level(log_level);
 

examples/riot/examples_libcoap_client/client-coap.c

@@ -133,7 +133,9 @@ client_coap_init(int argc, char **argv) {
   (void)argc;
   (void)argv;
 
+  /* Initialize libcoap library */
   coap_startup();
+
   coap_set_log_level(COAP_MAX_LOGGING_LEVEL);
 
   /* Parse the URI */

examples/riot/examples_libcoap_server/server-coap.c

@@ -191,6 +191,9 @@ void *
 server_coap_run(void *arg) {
   (void)arg;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   coap_set_log_level(COAP_MAX_LOGGING_LEVEL);
 
   if (!init_coap_context_endpoints(COAP_USE_PSK))

examples/tiny.c

@@ -141,6 +141,9 @@ main(int argc, char **argv) {
   struct sigaction sa;
   coap_context_t *ctx;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   if (argc > 1 && strncmp(argv[1], "-h", 2) == 0) {
     usage(argv[0]);
     exit(1);
@@ -180,6 +183,7 @@ main(int argc, char **argv) {
   }
 
   coap_free_context(ctx);
+  coap_cleanup();
 
   return 0;
 }

include/coap3/coap_net_internal.h

@@ -416,4 +416,6 @@ int coap_client_delay_first(coap_session_t *session);
 
 /** @} */
 
+extern int coap_started;
+
 #endif /* COAP_NET_INTERNAL_H_ */

man/Makefile.am

@@ -29,6 +29,7 @@ TXT3 = coap_address.txt \
 	coap_encryption.txt \
 	coap_endpoint_client.txt \
 	coap_handler.txt \
+	coap_init.txt \
 	coap_io.txt \
 	coap_keepalive.txt \
 	coap_logging.txt \

man/coap_block.txt.in

@@ -404,7 +404,8 @@ error:
 
 }
 
-int main(int argc, char *argv[]) {
+int
+main(int argc, char *argv[]) {
   coap_context_t *context = NULL;
   coap_session_t *session = NULL;
   unsigned char *data = NULL;
@@ -413,6 +414,9 @@ int main(int argc, char *argv[]) {
   (void)argc;
   (void)argv;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   /* ... Set up context, session etc. ... */
 
   /* Set up using libcoap to do the block work */
@@ -428,6 +432,7 @@ int main(int argc, char *argv[]) {
 
   /* ... Other code etc. ... */
 
+  coap_cleanup();
   return 0;
 }
 ----
@@ -494,12 +499,16 @@ const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
    */
 }
 
-int main(int argc, char *argv[]) {
+int
+main(int argc, char *argv[]) {
   coap_context_t *context = NULL;
   coap_resource_t *r;
   coap_resource_t *time_resource;
   int not_exit = 1;
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   (void)argc;
   (void)argv;
 
@@ -545,7 +554,7 @@ int main(int argc, char *argv[]) {
 
 SEE ALSO
 --------
-*coap_pdu_setup*(3), *coap_observe*(3), and *coap_resource*(3)
+*coap_init*(3) *coap_pdu_setup*(3), *coap_observe*(3), and *coap_resource*(3)
 
 FURTHER INFORMATION
 -------------------

man/coap_cache.txt.in

@@ -375,12 +375,16 @@ hnd_put_example_data(coap_context_t *ctx,
   coap_resource_notify_observers(resource, NULL);
 }
 
-int main(int argc, char* argv[]){
+int
+main(int argc, char* argv[]) {
   coap_context_t *ctx = NULL;  /* Set up as normal */
   /* ... */
   uint16_t cache_ignore_options[] = { COAP_OPTION_BLOCK1,
                                       COAP_OPTION_BLOCK2 };
 
+  /* Initialize libcoap library */
+  coap_startup();
+
   /* Remove (void) definition if variable is used */
   (void)argc;
   (void)argv;
@@ -392,13 +396,15 @@ int main(int argc, char* argv[]){
              sizeof(cache_ignore_options)/sizeof(cache_ignore_options[0]));
 
   /* ... */
+  coap_cleanup();
 
 }
 ----
 
 SEE ALSO
 --------
-*coap_block*(3), *coap_pdu_setup*(3), *coap_resource*(3) and *coap_string*(3)
+*coap_block*(3), *coap_init*(3), *coap_pdu_setup*(3), *coap_resource*(3)
+and *coap_string*(3)
 
 FURTHER INFORMATION
 -------------------

man/coap_init.txt.in

@@ -0,0 +1,72 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc tw=0
+
+coap_init(3)
+============
+:doctype: manpage
+:man source:   coap_init
+:man version:  @PACKAGE_VERSION@
+:man manual:   libcoap Manual
+
+NAME
+----
+coap_init,
+coap_startup,
+coap_cleanup
+- Work with CoAP initialization
+
+SYNOPSIS
+--------
+*#include <coap@LIBCOAP_API_VERSION@/coap.h>*
+
+*void coap_startup(void);*
+
+*void coap_cleanup(void);*
+
+For specific (D)TLS library support, link with
+*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
+*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
+or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*.   Otherwise, link with
+*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support.
+
+DESCRIPTION
+-----------
+
+The CoAP libcoap logic needs to be initialized before there is any use of the
+libcoap public API. This is done by calling *coap_startup*().
+
+FUNCTIONS
+---------
+
+*Function: coap_startup()*
+
+The *coap_startup*() function must be called before any other *coap_**()
+functions are called. It is used to initialize things like mutexes,
+random number gererators, clocks, TLS libraries etc.
+
+*NOTE:* This should be called after any other lower layer is initialized.
+For example, for LwIP, lwip_init() must be called before *coap_startup*().
+
+*Function: coap_cleanup()*
+
+The *coap_cleanup*() function is used to cleanup / free any information set
+up by the *coap_startup*() function and should be the last *coap_**() function
+called.
+
+FURTHER INFORMATION
+-------------------
+See
+
+"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
+
+for further information.
+
+BUGS
+----
+Please report bugs on the mailing list for libcoap:
+[email protected] or raise an issue on GitHub at
+https://github.com/obgm/libcoap/issues
+
+AUTHORS
+-------
+The libcoap project <[email protected]>