fixes #1081 Use after free possible in stats

fixes #1080 Desire better way to access statistics for NNG objects

We've also added a test that uses some of this, in order to verify
that the req protocol rejects invalid peers.

7 files changed, 593 insertions, 361 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index ad397314..f357d60a 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -9,417 +9,421 @@
 # found online at https://opensource.org/licenses/MIT.
 
 # We default to off here.
-option (NNG_ENABLE_DOC "Enable building documentation." OFF)
+option(NNG_ENABLE_DOC "Enable building documentation." OFF)
 
 if (NNG_ENABLE_DOC)
-    find_program (ASCIIDOCTOR asciidoctor)
+    find_program(ASCIIDOCTOR asciidoctor)
     if (NOT ASCIIDOCTOR)
-        message (WARNING "Could not find asciidoctor: skipping docs")
-        set (NNG_ENABLE_DOC OFF)
+        message(WARNING "Could not find asciidoctor: skipping docs")
+        set(NNG_ENABLE_DOC OFF)
     else ()
-        message (STATUS "Using asciidoctor at ${ASCIIDOCTOR}")
+        message(STATUS "Using asciidoctor at ${ASCIIDOCTOR}")
     endif ()
 endif ()
 
 if (NNG_ENABLE_DOC)
-    set (NNG_DOCDIR ${CMAKE_CURRENT_SOURCE_DIR})
+    set(NNG_DOCDIR ${CMAKE_CURRENT_SOURCE_DIR})
 
-    set (NNG_A2M ${ASCIIDOCTOR} -b manpage -amanmanual='NNG Reference Manual')
-    set (NNG_A2H ${ASCIIDOCTOR} -a nofooter -atoc=left -aicons=font -d manpage -b html5)
+    set(NNG_A2M ${ASCIIDOCTOR} -b manpage -amanmanual='NNG Reference Manual')
+    set(NNG_A2H ${ASCIIDOCTOR} -a nofooter -atoc=left -aicons=font -d manpage -b html5)
 
-    macro (nng_man NAME SECT)
+    macro(nng_man NAME SECT)
 
-    add_custom_command (
-        OUTPUT ${NAME}.${SECT}
-        COMMAND ${NNG_A2M} -o ${NAME}.${SECT} ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
-        MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
-    )
+        add_custom_command(
+                OUTPUT ${NAME}.${SECT}
+                COMMAND ${NNG_A2M} -o ${NAME}.${SECT} ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
+                MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
+        )
 
-    add_custom_command (
-        OUTPUT ${NAME}.${SECT}.html
-        COMMAND ${NNG_A2H} -o ${NAME}.${SECT}.html ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
-        MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
-    )
+        add_custom_command(
+                OUTPUT ${NAME}.${SECT}.html
+                COMMAND ${NNG_A2H} -o ${NAME}.${SECT}.html ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
+                MAIN_DEPENDENCY ${NNG_DOCDIR}/${NAME}.${SECT}.adoc
+        )
 
-    set(NNG_MANS ${NNG_MANS} ${NAME}.${SECT})
-    set(NNG_HTMLS ${NNG_HTMLS} ${NAME}.${SECT}.html)
+        set(NNG_MANS ${NNG_MANS} ${NAME}.${SECT})
+        set(NNG_HTMLS ${NNG_HTMLS} ${NAME}.${SECT}.html)
 
-    install (
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT}.html
-        DESTINATION ${CMAKE_INSTALL_DOCDIR}
-    )
-    install (
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT}
-        DESTINATION ${CMAKE_INSTALL_MANDIR}/man${SECT}
-    )
+        install(
+                FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT}.html
+                DESTINATION ${CMAKE_INSTALL_DOCDIR}
+        )
+        install(
+                FILES ${CMAKE_CURRENT_BINARY_DIR}/${NAME}.${SECT}
+                DESTINATION ${CMAKE_INSTALL_MANDIR}/man${SECT}
+        )
 
-    endmacro (nng_man)
+    endmacro(nng_man)
 
-    set (NNG_MAN1
-	nngcat
-    )
+    set(NNG_MAN1
+            nngcat
+            )
 
-    set (NNG_MAN3
-	libnng
-	nng_aio_abort
-	nng_aio_alloc
-	nng_aio_begin
-	nng_aio_cancel
-	nng_aio_count
-	nng_aio_defer
-	nng_aio_finish
-	nng_aio_free
-	nng_aio_get_input
-	nng_aio_get_msg
-	nng_aio_get_output
-	nng_aio_result
-	nng_aio_set_input
-	nng_aio_set_iov
-	nng_aio_set_msg
-	nng_aio_set_output
-	nng_aio_set_timeout
-	nng_aio_stop
-	nng_aio_wait
-	nng_alloc
-	nng_bus_open
-	nng_close
-	nng_ctx_close
-	nng_ctx_get
-	nng_ctx_getopt
-	nng_ctx_id
-	nng_ctx_open
-	nng_ctx_recv
-	nng_ctx_send
-	nng_ctx_set
-	nng_ctx_setopt
-	nng_device
-	nng_dial
-	nng_dialer_close
-	nng_dialer_create
-	nng_dialer_get
-	nng_dialer_getopt
-	nng_dialer_id
-	nng_dialer_set
-	nng_dialer_setopt
-	nng_dialer_start
-	nng_free
-	nng_getopt
-	nng_inproc_register
-	nng_ipc_register
-	nng_listen
-	nng_listener_close
-	nng_listener_create
-	nng_listener_get
-	nng_listener_getopt
-	nng_listener_id
-	nng_listener_set
-	nng_listener_setopt
-	nng_listener_start
-	nng_msg_alloc
-	nng_msg_append
-	nng_msg_body
-	nng_msg_chop
-	nng_msg_clear
-	nng_msg_dup
-	nng_msg_free
-	nng_msg_get_pipe
-	nng_msg_header
-	nng_msg_header_append
-	nng_msg_header_chop
-	nng_msg_header_clear
-	nng_msg_header_insert
-	nng_msg_header_len
-	nng_msg_header_trim
-	nng_msg_insert
-	nng_msg_len
-	nng_msg_realloc
-	nng_msg_set_pipe
-	nng_msg_trim
-	nng_pair_open
-	nng_pipe_close
-	nng_pipe_dialer
-	nng_pipe_get
-	nng_pipe_getopt
-	nng_pipe_id
-	nng_pipe_listener
-	nng_pipe_notify
-	nng_pipe_socket
-	nng_pub_open
-	nng_pull_open
-	nng_push_open
-	nng_recv
-	nng_recv_aio
-	nng_recvmsg
-	nng_rep_open
-	nng_req_open
-	nng_respondent_open
-	nng_send
-	nng_send_aio
-	nng_sendmsg
-	nng_setopt
-	nng_sleep_aio
-	nng_socket_id
-	nng_socket_get
-	nng_socket_set
-	nng_stats_free
-	nng_stats_get
-	nng_stat_child
-	nng_stat_desc
-	nng_stat_name
-	nng_stat_next
-	nng_stat_string
-	nng_stat_timestamp
-	nng_stat_type
-	nng_stat_unit
-	nng_stat_value
-	nng_strdup
-	nng_strerror
-	nng_strfree
-	nng_sub_open
-	nng_surveyor_open
-	nng_tcp_register
-	nng_tls_register
-	nng_url_clone
-	nng_url_free
-	nng_url_parse
-	nng_version
-	nng_ws_register
-	nng_wss_register
-	nng_zt_register
-    )
+    set(NNG_MAN3
+            libnng
+            nng_aio_abort
+            nng_aio_alloc
+            nng_aio_begin
+            nng_aio_cancel
+            nng_aio_count
+            nng_aio_defer
+            nng_aio_finish
+            nng_aio_free
+            nng_aio_get_input
+            nng_aio_get_msg
+            nng_aio_get_output
+            nng_aio_result
+            nng_aio_set_input
+            nng_aio_set_iov
+            nng_aio_set_msg
+            nng_aio_set_output
+            nng_aio_set_timeout
+            nng_aio_stop
+            nng_aio_wait
+            nng_alloc
+            nng_bus_open
+            nng_close
+            nng_ctx_close
+            nng_ctx_get
+            nng_ctx_getopt
+            nng_ctx_id
+            nng_ctx_open
+            nng_ctx_recv
+            nng_ctx_send
+            nng_ctx_set
+            nng_ctx_setopt
+            nng_device
+            nng_dial
+            nng_dialer_close
+            nng_dialer_create
+            nng_dialer_get
+            nng_dialer_getopt
+            nng_dialer_id
+            nng_dialer_set
+            nng_dialer_setopt
+            nng_dialer_start
+            nng_free
+            nng_getopt
+            nng_inproc_register
+            nng_ipc_register
+            nng_listen
+            nng_listener_close
+            nng_listener_create
+            nng_listener_get
+            nng_listener_getopt
+            nng_listener_id
+            nng_listener_set
+            nng_listener_setopt
+            nng_listener_start
+            nng_msg_alloc
+            nng_msg_append
+            nng_msg_body
+            nng_msg_chop
+            nng_msg_clear
+            nng_msg_dup
+            nng_msg_free
+            nng_msg_get_pipe
+            nng_msg_header
+            nng_msg_header_append
+            nng_msg_header_chop
+            nng_msg_header_clear
+            nng_msg_header_insert
+            nng_msg_header_len
+            nng_msg_header_trim
+            nng_msg_insert
+            nng_msg_len
+            nng_msg_realloc
+            nng_msg_set_pipe
+            nng_msg_trim
+            nng_pair_open
+            nng_pipe_close
+            nng_pipe_dialer
+            nng_pipe_get
+            nng_pipe_getopt
+            nng_pipe_id
+            nng_pipe_listener
+            nng_pipe_notify
+            nng_pipe_socket
+            nng_pub_open
+            nng_pull_open
+            nng_push_open
+            nng_recv
+            nng_recv_aio
+            nng_recvmsg
+            nng_rep_open
+            nng_req_open
+            nng_respondent_open
+            nng_send
+            nng_send_aio
+            nng_sendmsg
+            nng_setopt
+            nng_sleep_aio
+            nng_socket_id
+            nng_socket_get
+            nng_socket_set
+            nng_stats_free
+            nng_stats_get
+            nng_stat_child
+            nng_stat_desc
+            nng_stat_find
+            nng_stat_find_dialer
+            nng_stat_find_listener
+            nng_stat_find_socket
+            nng_stat_name
+            nng_stat_next
+            nng_stat_string
+            nng_stat_timestamp
+            nng_stat_type
+            nng_stat_unit
+            nng_stat_value
+            nng_strdup
+            nng_strerror
+            nng_strfree
+            nng_sub_open
+            nng_surveyor_open
+            nng_tcp_register
+            nng_tls_register
+            nng_url_clone
+            nng_url_free
+            nng_url_parse
+            nng_version
+            nng_ws_register
+            nng_wss_register
+            nng_zt_register
+            )
 
     set(NNG_MAN3COMPAT
-	nn_allocmsg
-	nn_bind
-	nn_close
-	nn_cmsg
-	nn_connect
-	nn_device
-	nn_errno
-	nn_freemsg
-	nn_get_statistic
-	nn_getsockopt
-	nn_poll
-	nn_reallocmsg
-	nn_recv
-	nn_recvmsg
-	nn_send
-	nn_sendmsg
-	nn_setsockopt
-	nn_shutdown
-	nn_socket
-	nn_strerror
-	nn_term
-	nng_compat
-    )
+            nn_allocmsg
+            nn_bind
+            nn_close
+            nn_cmsg
+            nn_connect
+            nn_device
+            nn_errno
+            nn_freemsg
+            nn_get_statistic
+            nn_getsockopt
+            nn_poll
+            nn_reallocmsg
+            nn_recv
+            nn_recvmsg
+            nn_send
+            nn_sendmsg
+            nn_setsockopt
+            nn_shutdown
+            nn_socket
+            nn_strerror
+            nn_term
+            nng_compat
+            )
 
     set(NNG_MAN3HTTP
-	nng_http_client_alloc
-	nng_http_client_connect
-	nng_http_client_free
-	nng_http_client_get_tls
-	nng_http_client_set_tls
-	nng_http_client_transact
-	nng_http_conn_close
-	nng_http_conn_read
-	nng_http_conn_read_all
-	nng_http_conn_read_req
-	nng_http_conn_read_res
-	nng_http_conn_transact
-	nng_http_conn_write
-	nng_http_conn_write_all
-	nng_http_conn_write_req
-	nng_http_conn_write_res
-	nng_http_handler_alloc
-	nng_http_handler_free
-	nng_http_handler_get_data
-	nng_http_handler_set_data
-	nng_http_handler_set_host
-	nng_http_handler_set_method
-	nng_http_handler_set_tree
-	nng_http_hijack
-	nng_http_req_add_header
-	nng_http_req_alloc
-	nng_http_req_copy_data
-	nng_http_req_del_header
-	nng_http_req_free
-	nng_http_req_get_data
-	nng_http_req_get_header
-	nng_http_req_get_method
-	nng_http_req_get_uri
-	nng_http_req_get_version
-	nng_http_req_reset
-	nng_http_req_set_data
-	nng_http_req_set_header
-	nng_http_req_set_method
-	nng_http_req_set_uri
-	nng_http_req_set_version
-	nng_http_res_add_header
-	nng_http_res_alloc
-	nng_http_res_alloc_error
-	nng_http_res_copy_data
-	nng_http_res_del_header
-	nng_http_res_free
-	nng_http_res_get_data
-	nng_http_res_get_header
-	nng_http_res_get_reason
-	nng_http_res_get_status
-	nng_http_res_get_version
-	nng_http_res_reset
-	nng_http_res_set_data
-	nng_http_res_set_header
-	nng_http_res_set_reason
-	nng_http_res_set_status
-	nng_http_res_set_version
-	nng_http_server_add_handler
-	nng_http_server_del_handler
-	nng_http_server_get_addr
-	nng_http_server_get_tls
-	nng_http_server_hold
-	nng_http_server_release
-	nng_http_server_set_tls
-	nng_http_server_start
-	nng_http_server_stop
-    )
+            nng_http_client_alloc
+            nng_http_client_connect
+            nng_http_client_free
+            nng_http_client_get_tls
+            nng_http_client_set_tls
+            nng_http_client_transact
+            nng_http_conn_close
+            nng_http_conn_read
+            nng_http_conn_read_all
+            nng_http_conn_read_req
+            nng_http_conn_read_res
+            nng_http_conn_transact
+            nng_http_conn_write
+            nng_http_conn_write_all
+            nng_http_conn_write_req
+            nng_http_conn_write_res
+            nng_http_handler_alloc
+            nng_http_handler_free
+            nng_http_handler_get_data
+            nng_http_handler_set_data
+            nng_http_handler_set_host
+            nng_http_handler_set_method
+            nng_http_handler_set_tree
+            nng_http_hijack
+            nng_http_req_add_header
+            nng_http_req_alloc
+            nng_http_req_copy_data
+            nng_http_req_del_header
+            nng_http_req_free
+            nng_http_req_get_data
+            nng_http_req_get_header
+            nng_http_req_get_method
+            nng_http_req_get_uri
+            nng_http_req_get_version
+            nng_http_req_reset
+            nng_http_req_set_data
+            nng_http_req_set_header
+            nng_http_req_set_method
+            nng_http_req_set_uri
+            nng_http_req_set_version
+            nng_http_res_add_header
+            nng_http_res_alloc
+            nng_http_res_alloc_error
+            nng_http_res_copy_data
+            nng_http_res_del_header
+            nng_http_res_free
+            nng_http_res_get_data
+            nng_http_res_get_header
+            nng_http_res_get_reason
+            nng_http_res_get_status
+            nng_http_res_get_version
+            nng_http_res_reset
+            nng_http_res_set_data
+            nng_http_res_set_header
+            nng_http_res_set_reason
+            nng_http_res_set_status
+            nng_http_res_set_version
+            nng_http_server_add_handler
+            nng_http_server_del_handler
+            nng_http_server_get_addr
+            nng_http_server_get_tls
+            nng_http_server_hold
+            nng_http_server_release
+            nng_http_server_set_tls
+            nng_http_server_start
+            nng_http_server_stop
+            )
 
     set(NNG_MAN3SUPP
-	nng_clock
-	nng_cv_alloc
-	nng_cv_free
-	nng_cv_until
-	nng_cv_wait
-	nng_cv_wake
-	nng_cv_wake1
-	nng_msleep
-	nng_mtx_alloc
-	nng_mtx_free
-	nng_mtx_lock
-	nng_mtx_unlock
-	nng_opts_parse
-	nng_random
-	nng_thread_create
-	nng_thread_destroy
-    )
+            nng_clock
+            nng_cv_alloc
+            nng_cv_free
+            nng_cv_until
+            nng_cv_wait
+            nng_cv_wake
+            nng_cv_wake1
+            nng_msleep
+            nng_mtx_alloc
+            nng_mtx_free
+            nng_mtx_lock
+            nng_mtx_unlock
+            nng_opts_parse
+            nng_random
+            nng_thread_create
+            nng_thread_destroy
+            )
 
     set(NNG_MAN3STR
-        nng_stream_close
-	nng_stream_free
-	nng_stream_get
-	nng_stream_recv
-	nng_stream_send
-	nng_stream_set
-    	nng_stream_dialer_alloc
-	nng_stream_dialer_close
-	nng_stream_dialer_dial
-	nng_stream_dialer_free
-	nng_stream_dialer_get
-	nng_stream_dialer_set
-	nng_stream_listener_accept
-	nng_stream_listener_alloc
-	nng_stream_listener_close
-	nng_stream_listener_free
-	nng_stream_listener_get
-	nng_stream_listener_listen
-	nng_stream_listener_set
-    )
+            nng_stream_close
+            nng_stream_free
+            nng_stream_get
+            nng_stream_recv
+            nng_stream_send
+            nng_stream_set
+            nng_stream_dialer_alloc
+            nng_stream_dialer_close
+            nng_stream_dialer_dial
+            nng_stream_dialer_free
+            nng_stream_dialer_get
+            nng_stream_dialer_set
+            nng_stream_listener_accept
+            nng_stream_listener_alloc
+            nng_stream_listener_close
+            nng_stream_listener_free
+            nng_stream_listener_get
+            nng_stream_listener_listen
+            nng_stream_listener_set
+            )
 
     set(NNG_MAN3TLS
-	nng_tls_config_alloc
-	nng_tls_config_auth_mode
-	nng_tls_config_ca_chain
-	nng_tls_config_ca_file
-	nng_tls_config_cert_key_file
-	nng_tls_config_free
-	nng_tls_config_hold
-	nng_tls_config_own_cert
-	nng_tls_config_server_name
-    )
+            nng_tls_config_alloc
+            nng_tls_config_auth_mode
+            nng_tls_config_ca_chain
+            nng_tls_config_ca_file
+            nng_tls_config_cert_key_file
+            nng_tls_config_free
+            nng_tls_config_hold
+            nng_tls_config_own_cert
+            nng_tls_config_server_name
+            )
 
     set(NNG_MAN5
-	nng_aio
-	nng_ctx
-	nng_dialer
-	nng_duration
-	nng_iov
-	nng_listener
-	nng_msg
-	nng_options
-	nng_pipe
-	nng_sockaddr
-	nng_sockaddr_in
-	nng_sockaddr_in6
-	nng_sockaddr_inproc
-	nng_sockaddr_ipc
-	nng_sockaddr_zt
-	nng_socket
-	nng_stat
+            nng_aio
+            nng_ctx
+            nng_dialer
+            nng_duration
+            nng_iov
+            nng_listener
+            nng_msg
+            nng_options
+            nng_pipe
+            nng_sockaddr
+            nng_sockaddr_in
+            nng_sockaddr_in6
+            nng_sockaddr_inproc
+            nng_sockaddr_ipc
+            nng_sockaddr_zt
+            nng_socket
+            nng_stat
 
-	nng_stream
-	nng_stream_dialer
-	nng_stream_listener
+            nng_stream
+            nng_stream_dialer
+            nng_stream_listener
 
-	nng_tcp_options
-	nng_ipc_options
-	nng_tls_config
-	nng_tls_options
-    )
+            nng_tcp_options
+            nng_ipc_options
+            nng_tls_config
+            nng_tls_options
+            )
 
     set(NNG_MAN7
-	nng
-	nng_bus
-	nng_inproc
-	nng_ipc
-	nng_pair
-	nng_pub
-	nng_pull
-	nng_push
-	nng_rep
-	nng_req
-	nng_respondent
-	nng_sub
-	nng_surveyor
-	nng_tcp
-	nng_tls
-	nng_ws
-	nng_zerotier
-    )
+            nng
+            nng_bus
+            nng_inproc
+            nng_ipc
+            nng_pair
+            nng_pub
+            nng_pull
+            nng_push
+            nng_rep
+            nng_req
+            nng_respondent
+            nng_sub
+            nng_surveyor
+            nng_tcp
+            nng_tls
+            nng_ws
+            nng_zerotier
+            )
 
-    foreach(F ${NNG_MAN1})
+    foreach (F ${NNG_MAN1})
         nng_man(${F} 1)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3})
+    foreach (F ${NNG_MAN3})
         nng_man(${F} 3)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3COMPAT})
+    foreach (F ${NNG_MAN3COMPAT})
         nng_man(${F} 3compat)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3HTTP})
+    foreach (F ${NNG_MAN3HTTP})
         nng_man(${F} 3http)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3STR})
+    foreach (F ${NNG_MAN3STR})
         nng_man(${F} 3str)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3SUPP})
+    foreach (F ${NNG_MAN3SUPP})
         nng_man(${F} 3supp)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN3TLS})
+    foreach (F ${NNG_MAN3TLS})
         nng_man(${F} 3tls)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN5})
+    foreach (F ${NNG_MAN5})
         nng_man(${F} 5)
-    endforeach()
+    endforeach ()
 
-    foreach(F ${NNG_MAN7})
+    foreach (F ${NNG_MAN7})
         nng_man(${F} 7)
-    endforeach()
+    endforeach ()
 
-    add_custom_target (man ALL DEPENDS ${NNG_MANS})
-    add_custom_target (html ALL DEPENDS ${NNG_HTMLS})
+    add_custom_target(man ALL DEPENDS ${NNG_MANS})
+    add_custom_target(html ALL DEPENDS ${NNG_HTMLS})
 endif ()
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 35c9b0f4..4e59890f 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -240,6 +240,10 @@ to observe program behaviors and as an aid in troubleshooting.
 |===
 |xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic
 |xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description
+|xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name
+|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics
+|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics
+|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics
 |xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name
 |xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic
 |xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value
diff --git a/docs/man/nng_stat.5.adoc b/docs/man/nng_stat.5.adoc
index 4382e4b0..0b649308 100644
--- a/docs/man/nng_stat.5.adoc
+++ b/docs/man/nng_stat.5.adoc
@@ -68,6 +68,10 @@ xref:nng_stats_free.3.adoc[nng_stats_free(3)],
 xref:nng_stats_get.3.adoc[nng_stats_get(3)],
 xref:nng_stat_child.3.adoc[nng_stat_child(3)],
 xref:nng_stat_desc.3.adoc[nng_stat_desc(3)],
+xref:nng_stat_find.3.adoc[nng_stat_find(3)],
+xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
+xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
+xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
 xref:nng_stat_name.3.adoc[nng_stat_name(3)],
 xref:nng_stat_next.3.adoc[nng_stat_next(3)],
 xref:nng_stat_string.3.adoc[nng_stat_string(3)],
diff --git a/docs/man/nng_stat_find.adoc b/docs/man/nng_stat_find.adoc
new file mode 100644
index 00000000..4f4103ea
--- /dev/null
+++ b/docs/man/nng_stat_find.adoc
@@ -0,0 +1,52 @@
+= nng_stat_find(3)
+//
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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_stat_find - find statistic by name
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+nng_stat *nng_stat_find(nng_stat *stat, const char *name);
+----
+
+== DESCRIPTION
+
+The `nng_stat_find()` function searches the statistics tree _stat_, looking for a statistic whose name is _name_.
+If it finds one, it returns it.
+Otherwise `NULL` is returned.
+
+NOTE: If multiple statistics have that name, then only the first match is returned.
+
+== RETURN VALUES
+
+The matching statistic, or NULL if no match is found.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:libnng.3.adoc[libnng(3)],
+xref:nng_stat_child.3.adoc[nng_stat_child(3)],
+xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
+xref:nng_stat_find_listener.3.adoc[nng_stat_find_listner(3)],
+xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
+xref:nng_stats_get.3.adoc[nng_stats_get(3)],
+xref:nng_stat.5.adoc[nng_stat(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_dialer.adoc b/docs/man/nng_stat_find_dialer.adoc
new file mode 100644
index 00000000..b0df247a
--- /dev/null
+++ b/docs/man/nng_stat_find_dialer.adoc
@@ -0,0 +1,56 @@
+= nng_stat_find_socket(3)
+//
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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_stat_find_dialer - find dialer statistics
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+typedef struct nng_dialer nng_dialer;
+
+nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer);
+----
+
+== DESCRIPTION
+
+The `nng_stat_find_dialer()` function returns the statistics tree within _stat_ associated with the dialer _dialer_, if such a tree exists.
+Otherwise `NULL` is returned.
+
+Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
+These can be further scanned using either
+xref:nng_stat_find.3.adoc[nng_stat_find(3)]
+or by walking the tree with
+xref:nng_stat_child.3.adoc[nng_stat_child(3)].
+
+== RETURN VALUES
+
+The matching statistic, or NULL if no match is found.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:libnng.3.adoc[libnng(3)],
+xref:nng_stat_child.3.adoc[nng_stat_child(3)],
+xref:nng_stat_find.3.adoc[nng_stat_find(3)],
+xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
+xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
+xref:nng_stats_get.3.adoc[nng_stats_get(3)],
+xref:nng_stat.5.adoc[nng_stat(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_listener.adoc b/docs/man/nng_stat_find_listener.adoc
new file mode 100644
index 00000000..2a099b1b
--- /dev/null
+++ b/docs/man/nng_stat_find_listener.adoc
@@ -0,0 +1,56 @@
+= nng_stat_find_listener(3)
+//
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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_stat_find_listener - find listener statistics
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+typedef struct nng_listener nng_listener;
+
+nng_stat *nng_stat_find_listener(nng_stat *stat, nng_listener listener);
+----
+
+== DESCRIPTION
+
+The `nng_stat_find_listener()` function returns the statistics tree within _stat_ associated with the listener _listener_, if such a tree exists.
+Otherwise `NULL` is returned.
+
+Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
+These can be further scanned using either
+xref:nng_stat_find.3.adoc[nng_stat_find(3)]
+or by walking the tree with
+xref:nng_stat_child.3.adoc[nng_stat_child(3)].
+
+== RETURN VALUES
+
+The matching statistic, or NULL if no match is found.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:libnng.3.adoc[libnng(3)],
+xref:nng_stat_child.3.adoc[nng_stat_child(3)],
+xref:nng_stat_find.3.adoc[nng_stat_find(3)],
+xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
+xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
+xref:nng_stats_get.3.adoc[nng_stats_get(3)],
+xref:nng_stat.5.adoc[nng_stat(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_socket.adoc b/docs/man/nng_stat_find_socket.adoc
new file mode 100644
index 00000000..eb03d5ea
--- /dev/null
+++ b/docs/man/nng_stat_find_socket.adoc
@@ -0,0 +1,56 @@
+= nng_stat_find_socket(3)
+//
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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_stat_find_socket - find socket statistics
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+typedef struct nng_socket nng_socket;
+
+nng_stat *nng_stat_find_socket(nng_stat *stat, nng_socket socket);
+----
+
+== DESCRIPTION
+
+The `nng_stat_find_socket()` function returns the statistics tree within _stat_ associated with the socket _socket_, if such a tree exists.
+Otherwise `NULL` is returned.
+
+Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
+These can be further scanned using either
+xref:nng_stat_find.3.adoc[nng_stat_find(3)]
+or by walking the tree with
+xref:nng_stat_child.3.adoc[nng_stat_child(3)].
+
+== RETURN VALUES
+
+The matching statistic, or NULL if no match is found.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:libnng.3.adoc[libnng(3)],
+xref:nng_stat_child.3.adoc[nng_stat_child(3)],
+xref:nng_stat_find.3.adoc[nng_stat_find(3)],
+xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
+xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
+xref:nng_stats_get.3.adoc[nng_stats_get(3)],
+xref:nng_stat.5.adoc[nng_stat(5)],
+xref:nng.7.adoc[nng(7)]