socket: sanitize LDoc and fix C99 declarations

Trim verbose LDoc in module header, send, receive, bind, listen,
connect, getsockname, getpeername, close, accept, and new to concise
descriptions.

Fix C99 issues: remove uninitialized size_t len from send/receive by
scoping it inside the else branch and using vec.iov_len directly in
the kernel calls; refactor pushaddr to use early returns and eliminate
int n; fix double semicolon in checkaddr AF_PACKET branch.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lneto

lib/luasocket.c

@@ -5,18 +5,10 @@
 
 /***
 * Low-level Lua interface for kernel networking sockets.
-* This library provides support for creating and managing various types of
-* sockets within the Linux kernel, enabling network communication directly
-* from Lua scripts running in kernel space. It is inspired by
-* [Chengzhi Tan](https://github.com/tcz717)'s
+* Inspired by [Chengzhi Tan](https://github.com/tcz717)'s
 * [GSoC project](https://summerofcode.withgoogle.com/archive/2018/projects/5993341447569408).
 *
-* It allows operations such as creating sockets, binding, listening, connecting,
-* sending, and receiving data. The library also exposes constants for address
-* families, socket types, IP protocols, and message flags.
-*
-* For higher-level IPv4 TCP/UDP socket operations with string-based IP addresses
-* (e.g., "127.0.0.1"), consider using the `socket.inet` library.
+* For higher-level IPv4 TCP/UDP socket operations, consider using the `socket.inet` library.
 *
 * @module socket
 * @see socket.inet
@@ -70,7 +62,7 @@ static size_t luasocket_checkaddr(lua_State *L, struct socket *socket, struct so
 	else if (addr->ss_family == AF_PACKET) {
 		struct sockaddr_ll *addr_ll = (struct sockaddr_ll *)addr;
 		addr_ll->sll_protocol = htons((u16)lunatik_checkinteger(L, ix, 0, U16_MAX));
-		addr_ll->sll_ifindex = (int)lunatik_checkinteger(L, ix + 1, 0, INT_MAX);;
+		addr_ll->sll_ifindex = (int)lunatik_checkinteger(L, ix + 1, 0, INT_MAX);
 		return sizeof(struct sockaddr_ll);
 	}
 	else {
@@ -84,25 +76,21 @@ static size_t luasocket_checkaddr(lua_State *L, struct socket *socket, struct so
 
 static int luasocket_pushaddr(lua_State *L, struct sockaddr_storage *addr)
 {
-	int n;
 	if (addr->ss_family == AF_INET) {
 		struct sockaddr_in *addr_in = (struct sockaddr_in *)addr;
 		lua_pushinteger(L, (lua_Integer)ntohl(addr_in->sin_addr.s_addr));
 		lua_pushinteger(L, (lua_Integer)ntohs(addr_in->sin_port));
-		n = 2;
+		return 2;
 	}
 #ifdef CONFIG_UNIX
 	else if (LUASOCKET_ISUNIX(addr->ss_family)) {
 		struct sockaddr_un *addr_un = (struct sockaddr_un *)addr;
 		lua_pushstring(L, addr_un->sun_path);
-		n = 1;
+		return 1;
 	}
 #endif
-	else {
-		lua_pushlstring(L, (const char *)addr->__data, LUASOCKET_ADDRMAX);
-		n = 1;
-	}
-	return n;
+	lua_pushlstring(L, (const char *)addr->__data, LUASOCKET_ADDRMAX);
+	return 1;
 }
 
 LUNATIK_PRIVATECHECKER(luasocket_check, struct socket *);
@@ -112,33 +100,17 @@ LUNATIK_PRIVATECHECKER(luasocket_check, struct socket *);
 /***
 * Sends a message through the socket.
 *
-* For connection-oriented sockets (`SOCK_STREAM`), `addr` and `port` are usually omitted
-* as the connection is already established.
-* For connectionless sockets (`SOCK_DGRAM`), `addr` and `port` (if applicable for the
-* address family) specify the destination.
-*
 * @function send
 * @tparam string|data message The message to send; a data object avoids string allocation.
-* @tparam[opt] integer|string addr The destination address.
-*
-* - For `AF_INET` (IPv4) sockets: An integer representing the IPv4 address (e.g., from `net.aton()`).
-* - For other address families (e.g., `AF_PACKET`): A packed string representing the destination address
-*   (e.g., MAC address for `AF_PACKET`). The exact format depends on the family.
-* @tparam[opt] integer port The destination port number (required if `addr` is an IPv4 address for `AF_INET`).
+* @tparam[opt] integer|string addr Destination address (family-dependent).
+* @tparam[opt] integer port Destination port (required for `AF_INET`).
 * @treturn integer The number of bytes sent.
-* @raise Error if the send operation fails or if address parameters are incorrect for the socket type.
-* @usage
-*   -- For a connected TCP socket:
-*   local bytes_sent = tcp_conn_sock:send("Hello, server!")
-*
-*   -- For a UDP socket (sending to 192.168.1.100, port 1234):
-*   local bytes_sent = udp_sock:send("UDP packet", net.aton("192.168.1.100"), 1234)
+* @raise Error if the send operation fails.
 * @see net.aton
 */
 static int luasocket_send(lua_State *L)
 {
 	struct socket *socket = luasocket_check(L, 1);
-	size_t len;
 	struct kvec vec;
 	struct msghdr msg;
 	struct sockaddr_storage addr;
@@ -151,18 +123,20 @@ static int luasocket_send(lua_State *L)
 		luadata_t *data = lunatik_checkclass(L, 2, "data", LUNATIK_OPT_SINGLE)->private;
 		lunatik_argchecknull(L, data->ptr, 2);
 		vec.iov_base = data->ptr;
-		len = data->size;
+		vec.iov_len = data->size;
 	}
-	else
+	else {
+		size_t len;
 		vec.iov_base = (void *)luaL_checklstring(L, 2, &len);
-	vec.iov_len = len;
+		vec.iov_len = len;
+	}
 
 	if (unlikely(nargs >= 3)) {
 		size_t size = luasocket_checkaddr(L, socket, &addr, 3);
 		luasocket_msgaddr(msg, addr, size);
 	}
 
-	lunatik_tryret(L, ret, kernel_sendmsg, socket, &msg, &vec, 1, len);
+	lunatik_tryret(L, ret, kernel_sendmsg, socket, &msg, &vec, 1, vec.iov_len);
 	lua_pushinteger(L, ret);
 	return 1;
 }
@@ -185,7 +159,6 @@ static int luasocket_receive(lua_State *L)
 {
 	struct socket *socket = luasocket_check(L, 1);
 	int isdata = lua_isuserdata(L, 2);
-	size_t len;
 	luaL_Buffer B;
 	struct kvec vec;
 	struct msghdr msg;
@@ -200,51 +173,31 @@ static int luasocket_receive(lua_State *L)
 		luadata_t *data = lunatik_checkclass(L, 2, "data", LUNATIK_OPT_SINGLE)->private;
 		lunatik_argchecknull(L, data->ptr, 2);
 		vec.iov_base = data->ptr;
-		len = data->size;
+		vec.iov_len = data->size;
 	}
 	else {
-		len = (size_t)luaL_checkinteger(L, 2);
+		size_t len = (size_t)luaL_checkinteger(L, 2);
 		vec.iov_base = (void *)luaL_buffinitsize(L, &B, len);
+		vec.iov_len = len;
 	}
-	vec.iov_len = len;
 
 	if (unlikely(from))
 		luasocket_msgaddr(msg, addr, sizeof(addr));
 
-	lunatik_tryret(L, ret, kernel_recvmsg, socket, &msg, &vec, 1, len, flags);
+	lunatik_tryret(L, ret, kernel_recvmsg, socket, &msg, &vec, 1, vec.iov_len, flags);
 	isdata ? lua_pushinteger(L, ret) : luaL_pushresultsize(&B, ret);
 
 	return unlikely(from) ? luasocket_pushaddr(L, (struct sockaddr_storage *)msg.msg_name) + 1 : 1;
 }
 
 /***
 * Binds the socket to a local address.
-* This is typically used on the server side before calling `listen()` or on
-* connectionless sockets to specify a local port/interface for receiving.
 *
 * @function bind
-* @tparam integer|string addr The local address to bind to. The interpretation depends on `socket.sk.sk_family`:
-*
-*   - `AF_INET` (IPv4): An integer representing the IPv4 address (e.g., from `net.aton()`).
-*     Use `0` (or `net.aton("0.0.0.0")`) to bind to all available interfaces.
-*     The `port` argument is also required.
-*   - `AF_PACKET`: An integer representing the ethernet protocol in host byte order
-*     (e.g., `0x0003` for `ETH_P_ALL`, `0x88CC` for `ETH_P_LLDP`)
-*     The `port` argument is also required.
-*   - Other families: A packed string directly representing parts of the family-specific address structure.
-*
-* @tparam[opt] integer port The local port or interface index.
-*   - `AF_INET`: TCP/UDP port number.
-*   - `AF_PACKET`: Network interface index (e.g., from `linux.ifindex("eth0")`).
-*
+* @tparam integer|string addr Local address to bind to (family-dependent).
+* @tparam[opt] integer port Local port or interface index (family-dependent).
 * @treturn nil
-* @raise Error if the bind operation fails (e.g., address already in use, invalid address).
-* @usage
-*   -- Bind TCP/IPv4 socket to localhost, port 8080
-*   tcp_server_sock:bind(net.aton("127.0.0.1"), 8080)
-*
-*   -- Bind AF_PACKET socket to protocol `ETH_P_LLDP` on a specific interface
-*   af_packet_sock:bind(0x88CC, linux.ifindex("eth0"))
+* @raise Error if the bind operation fails.
 * @see net.aton
 * @see linux.ifindex
 */
@@ -263,16 +216,11 @@ static int luasocket_bind(lua_State *L)
 
 /***
 * Puts a connection-oriented socket into the listening state.
-* This is required for server sockets (e.g., `SOCK_STREAM`) to be able to
-* accept incoming connections.
 *
 * @function listen
-* @tparam[opt] integer backlog The maximum length of the queue for pending connections.
-*   If omitted, a system-dependent default (e.g., `SOMAXCONN`) is used.
+* @tparam[opt] integer backlog Maximum pending connection queue length (default: `SOMAXCONN`).
 * @treturn nil
-* @raise Error if the listen operation fails (e.g., socket not bound, invalid state).
-* @usage
-*   tcp_server_sock:listen(10)
+* @raise Error if the listen operation fails.
 */
 static int luasocket_listen(lua_State *L)
 {
@@ -285,23 +233,13 @@ static int luasocket_listen(lua_State *L)
 
 /***
 * Initiates a connection on a socket.
-* This is typically used by client sockets to establish a connection to a server.
-* For datagram sockets, this sets the default destination address for `send` and
-* the only address from which datagrams are received.
 *
 * @function connect
-* @tparam integer|string addr The destination address to connect to.
-*   Interpretation depends on `socket.sk.sk_family`:
-*
-*   - `AF_INET` (IPv4): An integer representing the IPv4 address (e.g., from `net.aton()`).
-*     The `port` argument is also required.
-*   - Other families: A packed string representing the family-specific destination address.
-* @tparam[opt] integer port The destination port number (required and used only if the family is `AF_INET`).
-* @tparam[opt=0] integer flags Optional connection flags.
+* @tparam integer|string addr Destination address (family-dependent).
+* @tparam[opt] integer port Destination port (required for `AF_INET`).
+* @tparam[opt=0] integer flags Connection flags.
 * @treturn nil
-* @raise Error if the connect operation fails (e.g., connection refused, host unreachable).
-* @usage
-*   tcp_client_sock:connect(net.aton("192.168.1.100"), 80)
+* @raise Error if the connect operation fails.
 */
 static int luasocket_connect(lua_State *L)
 {
@@ -332,43 +270,25 @@ static int luasocket_get##what(lua_State *L)					\
 * Gets the local address to which the socket is bound.
 *
 * @function getsockname
-* @treturn integer|string addr The local address.
-*
-* - For `AF_INET`: An integer representing the IPv4 address (can be converted with `net.ntoa()`).
-* - For other families: A packed string representing the local address.
-* @treturn[opt] integer port If the family is `AF_INET`, the local port number.
+* @treturn integer|string addr Local address (family-dependent).
+* @treturn[opt] integer port Local port for `AF_INET`.
 * @raise Error if the operation fails.
-* @usage
-*   local local_ip_int, local_port = my_socket:getsockname()
-*   if my_socket.sk.sk_family == socket.af.INET then print("Bound to " .. net.ntoa(local_ip_int) .. ":" .. local_port) end
 */
 LUASOCKET_NEWGETTER(sockname);
 
 /***
 * Gets the address of the peer to which the socket is connected.
-* This is typically used with connection-oriented sockets after a connection
-* has been established, or with connectionless sockets after `connect()` has
-* been called to set a default peer.
 *
 * @function getpeername
-* @treturn integer|string addr The peer's address.
-*
-* - For `AF_INET`: An integer representing the IPv4 address (can be converted with `net.ntoa()`).
-* - For other families: A packed string representing the peer's address.
-* @treturn[opt] integer port If the family is `AF_INET`, the peer's port number.
-* @raise Error if the operation fails (e.g., socket not connected).
-* @usage
-*   local peer_ip_int, peer_port = connected_socket:getpeername()
-*   if connected_socket.sk.sk_family == socket.af.INET then print("Connected to " .. net.ntoa(peer_ip_int) .. ":" .. peer_port) end
+* @treturn integer|string addr Peer address (family-dependent).
+* @treturn[opt] integer port Peer port for `AF_INET`.
+* @raise Error if the operation fails.
 */
 LUASOCKET_NEWGETTER(peername);
 
 /***
-* Closes the socket.
-* This shuts down the socket for both reading and writing and releases
-* associated kernel resources.
-* This method is also called automatically when the socket object is garbage collected
-* or via Lua 5.4's to-be-closed mechanism.
+* Closes the socket, shutting it down and releasing kernel resources.
+* Also called on garbage collection or via Lua 5.4's to-be-closed mechanism.
 *
 * @function close
 * @treturn nil
@@ -704,13 +624,9 @@ static const lunatik_class_t luasocket_class = {
 
 /***
 * Accepts a connection on a listening socket.
-* This function is used with connection-oriented sockets (e.g., `SOCK_STREAM`)
-* that have been put into the listening state by `sock:listen()`.
 *
 * @function accept
-* @tparam socket self The listening socket object.
-* @tparam[opt=0] integer flags Optional flags to apply to the newly accepted socket
-*   (e.g., `socket.sock.NONBLOCK`, `socket.sock.CLOEXEC`).
+* @tparam[opt=0] integer flags Flags for the new socket (e.g., `socket.sock.NONBLOCK`).
 * @treturn socket A new socket object representing the accepted connection.
 * @raise Error if the accept operation fails.
 */
@@ -726,19 +642,13 @@ static int luasocket_accept(lua_State *L)
 
 /***
 * Creates a new socket object.
-* This function is the primary way to create a socket.
 *
 * @function new
-* @tparam integer family The address family for the socket (e.g., `socket.af.INET`).
-* @tparam integer type The type of the socket (e.g., `socket.sock.STREAM`).
-* @tparam integer protocol The protocol to be used (e.g., `socket.ipproto.TCP`).
-*   For `AF_PACKET` sockets, `protocol` is typically an `ETH_P_*` value in network byte order
-*   (e.g., `linux.hton16(0x0003)` for `ETH_P_ALL`).
+* @tparam integer family Address family (e.g., `socket.af.INET`).
+* @tparam integer type Socket type (e.g., `socket.sock.STREAM`).
+* @tparam integer protocol Protocol (e.g., `socket.ipproto.TCP`).
 * @treturn socket A new socket object.
 * @raise Error if socket creation fails.
-* @usage
-*   -- TCP/IPv4 socket
-*   local tcp_sock = socket.new(socket.af.INET, socket.sock.STREAM, socket.ipproto.TCP)
 * @see socket.af
 * @see socket.sock
 * @see socket.ipproto