From 11769408e539e1a5d36215e954b2a4758717f0b5 Mon Sep 17 00:00:00 2001 From: auronandace Date: Wed, 3 Jun 2026 12:32:28 +0100 Subject: [PATCH] add descriptions to sys_socket constants and structs --- src/header/sys_socket/constants.rs | 153 +++++++++++++++++++++++++++-- src/header/sys_socket/mod.rs | 20 ++++ 2 files changed, 167 insertions(+), 6 deletions(-) diff --git a/src/header/sys_socket/constants.rs b/src/header/sys_socket/constants.rs index ec42889bf5..f043163a74 100644 --- a/src/header/sys_socket/constants.rs +++ b/src/header/sys_socket/constants.rs @@ -1,77 +1,218 @@ use crate::platform::types::c_int; -pub const SOCK_STREAM: c_int = 1; -pub const SOCK_DGRAM: c_int = 2; -pub const SOCK_RAW: c_int = 3; -pub const SOCK_NONBLOCK: c_int = 0o4_000; -pub const SOCK_CLOEXEC: c_int = 0o2_000_000; +// Socket types -// Other constants +/// Byte-stream socket. +pub const SOCK_STREAM: c_int = 1; +/// Datagram socket. +pub const SOCK_DGRAM: c_int = 2; +/// Raw Protocol Interface. +pub const SOCK_RAW: c_int = 3; +/// Non-POSIX, see . +/// +/// Provides a reliable datagram layer that does not guarantee ordering. pub const SOCK_RDM: c_int = 4; +/// Sequenced-packet socket. pub const SOCK_SEQPACKET: c_int = 5; +// End of socket types + +// Socket creation flags (for use in `socket()`, `socketpair()` and `accept4()`) + +/// Create a socket file descriptor with the `O_NONBLOCK` flag atomically set +/// on the new open file description. +pub const SOCK_NONBLOCK: c_int = 0o4_000; +/// Create a socket file descriptor wit the `FD_CLOEXEC` flag atomically set +/// on that file descriptor. +pub const SOCK_CLOEXEC: c_int = 0o2_000_000; + +// End of socket creation flags + +// `level` argument of `getsockopt()` and `setsockopt()` + +/// Options to be accessed at socket level, not protocol level. pub const SOL_SOCKET: c_int = 1; +// End of `level` argument + +// `option_name` argument for `getsockopt()` and `setsockopt()` + +/// Debugging information is recorded. pub const SO_DEBUG: c_int = 1; +/// Reuse of local addresses is supported. pub const SO_REUSEADDR: c_int = 2; +/// Socket type. pub const SO_TYPE: c_int = 3; +/// Socket error status. pub const SO_ERROR: c_int = 4; +/// Bypass normal routing. pub const SO_DONTROUTE: c_int = 5; +/// Transmission of broadcast messages is supported. pub const SO_BROADCAST: c_int = 6; +/// Send buffer size. pub const SO_SNDBUF: c_int = 7; +/// Receive buffer size. pub const SO_RCVBUF: c_int = 8; +/// Connections are kept alive with periodic messages. pub const SO_KEEPALIVE: c_int = 9; +/// Out-of-band data is transmitted inline. pub const SO_OOBINLINE: c_int = 10; +/// Non-POSIX, found in LwIP. +/// +/// Don't create UDP checksum. pub const SO_NO_CHECK: c_int = 11; +/// Non-POSIX, see . +/// +/// Set the protocol-defined priority for all packets to be sent on this +/// socket. pub const SO_PRIORITY: c_int = 12; +/// Socket lingers on close. pub const SO_LINGER: c_int = 13; +/// Non-POSIX, see . +/// +/// Enable BSD bug-to-bug compatibility. pub const SO_BSDCOMPAT: c_int = 14; +/// Non-POSIX, see . +/// +/// Permits multiple `AF_INET` or `AF_INET6` sockets to be bound to an +/// identical socket address. pub const SO_REUSEPORT: c_int = 15; +/// Non-POSIX, see . +/// +/// Enable or disable the receiving of the `SCM_CREDENTIALS` control message. pub const SO_PASSCRED: c_int = 16; +/// Non-POSIX, see . +/// +/// Return the credentials of the peer process connected to this socket. pub const SO_PEERCRED: c_int = 17; +/// Receive "low water mark". pub const SO_RCVLOWAT: c_int = 18; +/// Send "low water mark". pub const SO_SNDLOWAT: c_int = 19; +/// Receive timeout. pub const SO_RCVTIMEO: c_int = 20; +/// Send timeout. pub const SO_SNDTIMEO: c_int = 21; +/// Socket is accepting connections. pub const SO_ACCEPTCONN: c_int = 30; +/// Non-POSIX, see . +/// +/// Get the security context of a peer socket. pub const SO_PEERSEC: c_int = 31; +/// Non-POSIX, see . +/// +/// A privileged (`CAP_NET_ADMIN`) process can perform the same task as +/// `SO_SNDBUF`, but the `wmem_max` limit can be overridden. pub const SO_SNDBUFFORCE: c_int = 32; +/// Non-POSIX, see . +/// +/// A privileged (`CAP_NET_ADMIN`) process can perform the same task as +/// `SO_RCVBUF`, but the `rmem_max` limit can be overridden. pub const SO_RCVBUFFORCE: c_int = 33; +/// Socket protocol. pub const SO_PROTOCOL: c_int = 38; +/// Socket domain. pub const SO_DOMAIN: c_int = 39; +// End of `option_name` argument + +/// The maximum backlog queue length. pub const SOMAXCONN: c_int = 128; +// `msg_flags` + +/// Control data truncated. pub const MSG_CTRUNC: c_int = 8; +/// Send without using routing tables. pub const MSG_DONTROUTE: c_int = 4; +/// Terminates a record (if supported by the protocol). pub const MSG_EOR: c_int = 128; +/// Out-of-band data. pub const MSG_OOB: c_int = 1; +/// Leave received data in queue. pub const MSG_PEEK: c_int = 2; +/// Normal data truncated. pub const MSG_TRUNC: c_int = 32; +/// Non-POSIX, see . +/// +/// Enables nonblocking operation. pub const MSG_DONTWAIT: c_int = 64; +/// Attempt to fill the read buffer. pub const MSG_WAITALL: c_int = 256; +/// Atomically set the `FD_CLOEXEC` flag on any file descriptors created via +/// `SCM_RIGHTS` during `recvmsg()`. pub const MSG_CMSG_CLOEXEC: c_int = 0x40000000; +// End of `mag_flags` + +/// Non-POSIX, see . +/// +/// Join a multicast group and allow receiving data only from a specified +/// source. pub const IP_ADD_SOURCE_MEMBERSHIP: c_int = 70; +/// Non-POSIX, see . +/// +/// Leave a source-specific multicast group. pub const IP_DROP_SOURCE_MEMBERSHIP: c_int = 71; +/// Non-POSIX, see . +/// +/// Join a source-specific group. pub const MCAST_JOIN_SOURCE_GROUP: c_int = 46; +/// Non-POSIX, see . +/// +/// Leave a source-specific group. pub const MCAST_LEAVE_SOURCE_GROUP: c_int = 47; +// Address family constants (AF) + +/// Internet domain sockets for use with IPv4 sockets. pub const AF_INET: c_int = 2; +/// Internet domain sockets for use with IPv6 sockets. pub const AF_INET6: c_int = 10; +/// Non-POSIX, see . +/// +/// Alias for `AF_UNIX`. pub const AF_LOCAL: c_int = AF_UNIX; +/// UNIX domain sockets. pub const AF_UNIX: c_int = 1; +/// Unspecified. pub const AF_UNSPEC: c_int = 0; +// End of AF constants + +// Protocol family constants (PF) +// Constants historically used by BSDs, identical to AF constants. +// Recommended to use AF constants everywhere instead. +// See . + +/// See `AF_INET`. pub const PF_INET: c_int = 2; +/// See `AF_INET6`. pub const PF_INET6: c_int = 10; +/// See `AF_LOCAL`. pub const PF_LOCAL: c_int = PF_UNIX; +/// See `AF_UNIX`. pub const PF_UNIX: c_int = 1; +/// See `AF_UNSPEC`. pub const PF_UNSPEC: c_int = 0; +// End of PF constants + +/// Disables further receive operations. pub const SHUT_RD: c_int = 0; +/// Disables further send and receive operations. pub const SHUT_RDWR: c_int = 2; +/// Disables further send operations. pub const SHUT_WR: c_int = 1; +// `cmsg_type` value when `cmsg_level` is `SOL_SOCKET` + +/// Indicates that the data array contains the access rights to be sent or +/// received. pub const SCM_RIGHTS: c_int = 1; +/// Non-POSIX, see . +/// +/// Send or receive UNIX credentials. pub const SCM_CREDENTIALS: c_int = 2; + +// End of `cmsg_type` value diff --git a/src/header/sys_socket/mod.rs b/src/header/sys_socket/mod.rs index 1cc72a6025..49f25ff3fb 100644 --- a/src/header/sys_socket/mod.rs +++ b/src/header/sys_socket/mod.rs @@ -23,7 +23,9 @@ pub mod constants; #[repr(C)] #[derive(Default, CheckVsLibcCrate)] pub struct linger { + /// Indicates whether linger option is enabled. pub l_onoff: c_int, + /// Linger time, in seconds. pub l_linger: c_int, } @@ -31,12 +33,19 @@ pub struct linger { #[repr(C)] #[derive(Debug, CheckVsLibcCrate)] pub struct msghdr { + /// Optional address. pub msg_name: *mut c_void, + /// Size of address. pub msg_namelen: socklen_t, + /// Scatter/gather array. pub msg_iov: *mut iovec, + /// Members in `msg_iov`. pub msg_iovlen: size_t, + /// Ancilliary data. pub msg_control: *mut c_void, + /// Ancilliary data buffer length. pub msg_controllen: size_t, + /// Flags on received message. pub msg_flags: c_int, } @@ -44,19 +53,27 @@ pub struct msghdr { #[repr(C)] #[derive(Debug, CheckVsLibcCrate)] pub struct cmsghdr { + /// Data byte count, including the `cmsghdr`. pub cmsg_len: size_t, + /// Originating protocol. pub cmsg_level: c_int, + /// Protocol-specific type. pub cmsg_type: c_int, } // TODO: `ucred` should be behind _GNU_SOURCE include guard /// Non-POSIX, see . +/// +/// Represents UNIX credentials. #[repr(C)] #[derive(Clone, Debug)] // FIXME: CheckVsLibcCrate pub struct ucred { + /// Process ID of the sending process. pub pid: pid_t, + /// User ID of the sending process. pub uid: uid_t, + /// Group ID of the sending process. pub gid: gid_t, } @@ -64,7 +81,9 @@ pub struct ucred { #[repr(C)] #[derive(Default, CheckVsLibcCrate)] pub struct sockaddr { + /// Address family. pub sa_family: sa_family_t, + /// Socket address. pub sa_data: [c_char; 14], } @@ -89,6 +108,7 @@ const _SS_PADDING: usize = _SS_MAXSIZE - mem::size_of::() - mem::si #[repr(C)] //#[derive(CheckVsLibcCrate)] FIXME: can't ignore private fields yet pub struct sockaddr_storage { + /// Address family. pub ss_family: sa_family_t, __ss_pad2: [u8; _SS_PADDING], __ss_align: usize,