From 4b25e091efe208f76802471e14452d59d10039b8 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sat, 9 Nov 2024 10:05:32 -0800
Subject: fixes #1914 Document nng_socket_proto_id, proto_name, peer_id,
 peer_name, and nng_socket_raw

---
 docs/ref/api/sock.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 docs/ref/api/sock.md

(limited to 'docs/ref/api/sock.md')

diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md
new file mode 100644
index 00000000..3851ca5e
--- /dev/null
+++ b/docs/ref/api/sock.md
@@ -0,0 +1,60 @@
+# Sockets
+
+Sockets {{hi:socket}} in Scalability Protocols provide the handle for communication
+between peers. Sockets also encapsulate protocol specific semantics, such as
+filtering subscriptions, or automatically retrying requests.
+
+## Socket Structure
+
+```c
+#define NNG_SOCKET_INITIALIZER // opaque value
+
+typedef struct nng_socket_s nng_socket;
+```
+
+The {{i:`nng_socket`}} structure represents socket. This is a handle, and
+the members of it are opaque. However, unlike a pointer, it is usually
+passed by value.
+
+A socket may be initialized statically with the `NNG_SOCKET_INITIALIZER` macro,
+to ensure that it cannot be confused with a valid open socket.
+
+## Socket Identity
+
+```c
+int nng_socket_id(nng_socket s);
+int nng_socket_raw(nng_socket s, bool *raw);
+int nng_socket_proto_id(nng_socket s, uint16_t *proto);
+int nng_socket_peer_id(nng_socket s, uint16_t *proto);
+int nng_socket_proto_name(nng_socket s, const char **name);
+int nng_socket_peer_name(nng_socket s, const char **name);
+```
+
+These functions are used to provide fundamental information about the socket _s_.
+Most applications will not need to use these functions.
+
+The {{i:`nng_socket_id`}} function returns the numeric id, which will be a non-negative
+value, associated with the socket. If the socket is uninitialized (has never been opened),
+then the return value may be `-1`.
+
+The {{i:`nng_socket_proto_id`}} and {{i:`nng_socket_peer_id`}} functions provide the 16-bit
+protocol identifier for the socket's protocol, and of the protocol peers will use when
+communicating with the socket.
+
+The {{i:`nng_socket_proto_name`}} and {{i:`nng_socket_peer_name`}} functions provide the ASCII
+names of the socket's protocol, and of the protocol peers of the socket use.
+The value stored in _name_ is a fixed string located in program text, and must not be freed
+or altered. It is guaranteed to remain valid while this library is present.
+
+The {{i:`nng_socket_raw`}} function determines whether the socket is in
+[raw mode][raw] or not, storing `true` in _raw_ if it is, or `false` if it is not.
+
+## Examples
+
+### Example 1: Initializing a Socket
+
+```c
+nng_socket s = NNG_SOCKET_INITIALIZER;
+```
+
+{{#include ../xref.md}}
-- 
cgit v1.2.3-70-g09d2