---@meta socket.core

--------------------------------------------------------------------------------
-- LuaSocket C core module
--------------------------------------------------------------------------------

---@alias socket_core_timeout number|nil
---@alias socket_shutdown_mode 'receive'|'send'|'both'

---@class socket_core_tcp*: socket_tcp_client*
local socket_core_tcp = {}

---@class socket_core_udp*: socket_udp_client*
local socket_core_udp = {}

---@class socket_core_dns*: socket_dns*
local socket_core_dns = {}

---@class socket_core*
---@field _VERSION string version
---@field _DEBUG? boolean debug flag
---@field _DATAGRAMSIZE integer UDP Default datagram size
---@field _SETSIZE integer select fd set size
---@field _SOCKETINVALID integer Invalid socket fd
---@field dns socket_core_dns* DNS Tools
---@type socket_core*
local M = {}

--- Create a TCP socket.
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg error message
function M.tcp() end

--- Create an IPv4 TCP socket.
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg error message
function M.tcp4() end

--- Create an IPv6 TCP socket.
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg error message
function M.tcp6() end

--- Create UDP socket.
---@return socket_core_udp*? client UDP socket
---@return string? errMsg error message
function M.udp() end

--- Create an IPv4 UDP socket.
---@return socket_core_udp*? client UDP socket
---@return string? errMsg error message
function M.udp4() end

--- Create an IPv6 UDP socket.
---@return socket_core_udp*? client UDP socket
---@return string? errMsg error message
function M.udp6() end

--- Connect to TCP service.
---@param address string remote address
---@param port integer remote port
---@param laddress? string local address
---@param lport? integer local port
---@param family? 'inet'|'inet6' address family
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg error message
function M.connect(address, port, laddress, lport, family) end

--- Wait for the socket to be readable or writable.
---@param recvt? table Readable socket list
---@param sendt? table Writable socket list
---@param timeout? number Timeout seconds
---@return table readable readable list
---@return table writable writable list
---@return string? errMsg error message
function M.select(recvt, sendt, timeout) end

--- current time.
---@return number time seconds time
function M.gettime() end

--- Delay for the specified number of seconds.
---@param seconds number seconds
function M.sleep(seconds) end

--- Create error protection functions.
---@param finalizer? function closing function
---@return function try try function
function M.newtry(finalizer) end

--- Protect function calls.
---@param func function function
---@return function protected Protected function
function M.protect(func) end

--- Skip the first n return values.
---@param count integer skip quantity
---@param ... any value
---@return any ... residual value
function M.skip(count, ...) end

--- Uninstall the underlying socket library.
function M.__unload() end

--- Query the host name.
---@return string hostname hostname
function socket_core_dns.gethostname() end

--- Hostname to IP.
---@param name string hostname
---@return string? ip IP address
---@return table|string? resolved Parse information or error messages
function socket_core_dns.toip(name) end

--- IP to hostname.
---@param address string IP address
---@return string? name hostname
---@return table|string? resolved Parse information or error messages
function socket_core_dns.tohostname(address) end

--- Query address information.
---@param host string Hostname or IP address
---@return table? info Address information list
---@return string? errMsg error message
function socket_core_dns.getaddrinfo(host) end

--- Check the address and service name.
---@param address string IP address
---@param port? integer port
---@return string? host hostname
---@return string? service Service name
function socket_core_dns.getnameinfo(address, port) end

--- Get the socket address family.
---@return 'inet'|'inet6'|string family address family
function socket_core_tcp:getfamily() end

--- Get the underlying fd.
---@return integer fd file descriptor
function socket_core_tcp:getfd() end

--- Replace underlying fd.
---@param fd integer file descriptor
---@return integer? ok Returns 1 on success
---@return string? errMsg error message
function socket_core_tcp:setfd(fd) end

--- Check whether there is unread data in the buffer.
---@return boolean dirty Is there any unread data?
function socket_core_tcp:dirty() end

--- Get the timeout setting.
---@return number? block Single operation timeout
---@return number? total total timeout
function socket_core_tcp:gettimeout() end

--- Get transfer statistics.
---@return integer received Number of bytes received
---@return integer sent Number of bytes sent
---@return number age seconds after creation
function socket_core_tcp:getstats() end

--- Set transfer statistics.
---@param received? integer Number of bytes received
---@param sent? integer Number of bytes sent
---@param age? number seconds after creation
---@return integer? ok Returns 1 on success
function socket_core_tcp:setstats(received, sent, age) end

--- Turn off one-way or two-way transmission.
---@param mode? socket_shutdown_mode Close direction
---@return integer? ok Returns 1 on success
---@return string? errMsg error message
function socket_core_tcp:shutdown(mode) end

--- Get the socket address family.
---@return 'inet'|'inet6'|string family address family
function socket_core_udp:getfamily() end

--- Get the underlying fd.
---@return integer fd file descriptor
function socket_core_udp:getfd() end

--- Replace underlying fd.
---@param fd integer file descriptor
---@return integer? ok Returns 1 on success
---@return string? errMsg error message
function socket_core_udp:setfd(fd) end

--- Check whether the socket has unread data.
---@return boolean dirty Is there any unread data?
function socket_core_udp:dirty() end

--- Get the timeout setting.
---@return number? block Single operation timeout
---@return number? total total timeout
function socket_core_udp:gettimeout() end

--- Get socket options.
---@param option string option name
---@return any value option value
---@return string? errMsg error message
function socket_core_udp:getoption(option) end

return M
