libs/luci-lib-nixio/docsrc/nixio.Socket.lua

   1 --- Socket Object.
   2 -- Supports IPv4, IPv6 and UNIX (POSIX only) families.
   3 -- @cstyle      instance
   4 module "nixio.Socket"
   5
   6 --- Get the local address of a socket.
   7 -- @class function
   8 -- @name Socket.getsockname
   9 -- @return      IP-Address
  10 -- @return      Port
  11
  12 --- Get the peer address of a socket.
  13 -- @class function
  14 -- @name Socket.getpeername
  15 -- @return      IP-Address
  16 -- @return      Port
  17
  18 --- Bind the socket to a network address.
  19 -- @class function
  20 -- @name Socket.bind
  21 -- @usage This function calls getaddrinfo() and bind() but NOT listen().
  22 -- @usage If <em>host</em> is a domain name it will be looked up and bind()
  23 -- tries the IP-Addresses in the order returned by the DNS resolver
  24 -- until the bind succeeds.
  25 -- @usage UNIX sockets ignore the <em>port</em>,
  26 -- and interpret <em>host</em> as a socket path.
  27 -- @param host  Host (optional, default: all addresses)
  28 -- @param port  Port or service description
  29 -- @return true
  30
  31 --- Connect the socket to a network address.
  32 -- @class function
  33 -- @name Socket.connect
  34 -- @usage This function calls getaddrinfo() and connect().
  35 -- @usage If <em>host</em> is a domain name it will be looked up and connect()
  36 -- tries the IP-Addresses in the order returned by the DNS resolver
  37 -- until the connect succeeds.
  38 -- @usage UNIX sockets ignore the <em>port</em>,
  39 -- and interpret <em>host</em> as a socket path.
  40 -- @param host  Hostname or IP-Address (optional, default: localhost)
  41 -- @param port  Port or service description
  42 -- @return true
  43
  44 --- Listen for connections on the socket.
  45 -- @class function
  46 -- @name Socket.listen
  47 -- @param       backlog Length of queue for pending connections
  48 -- @return      true
  49
  50 --- Accept a connection on the socket.
  51 -- @class function
  52 -- @name Socket.accept
  53 -- @return      Socket Object
  54 -- @return      Peer IP-Address
  55 -- @return  Peer Port
  56
  57 --- Send a message on the socket specifying the destination.
  58 -- @class function
  59 -- @name Socket.sendto
  60 -- @usage <strong>Warning:</strong> It is not guaranteed that all data
  61 -- in the buffer is written at once.
  62 -- You have to check the return value - the number of bytes actually written -
  63 -- or use the safe IO functions in the high-level IO utility module.
  64 -- @usage Unlike standard Lua indexing the lowest offset and default is 0.
  65 -- @param buffer        Buffer holding the data to be written.
  66 -- @param host          Target IP-Address
  67 -- @param port          Target Port
  68 -- @param offset        Offset to start reading the buffer from. (optional)
  69 -- @param length        Length of chunk to read from the buffer. (optional)
  70 -- @return number of bytes written
  71
  72 --- Send a message on the socket.
  73 -- This function is identical to sendto except for the missing destination
  74 -- parameters. See the sendto description for a detailed description.
  75 -- @class function
  76 -- @name Socket.send
  77 -- @param buffer        Buffer holding the data to be written.
  78 -- @param offset        Offset to start reading the buffer from. (optional)
  79 -- @param length        Length of chunk to read from the buffer. (optional)
  80 -- @see Socket.sendto
  81 -- @return number of bytes written
  82
  83 --- Send a message on the socket (This is an alias for send).
  84 -- See the sendto description for a detailed description.
  85 -- @class function
  86 -- @name Socket.write
  87 -- @param buffer        Buffer holding the data to be written.
  88 -- @param offset        Offset to start reading the buffer from. (optional)
  89 -- @param length        Length of chunk to read from the buffer. (optional)
  90 -- @see Socket.sendto
  91 -- @return number of bytes written
  92
  93 --- Receive a message on the socket including the senders source address.
  94 -- @class function
  95 -- @name Socket.recvfrom
  96 -- @usage <strong>Warning:</strong> It is not guaranteed that all requested data
  97 -- is read at once.
  98 -- You have to check the return value - the length of the buffer actually read -
  99 -- or use the safe IO functions in the high-level IO utility module.
 100 -- @usage The length of the return buffer is limited by the (compile time)
 101 -- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
 102 -- Any read request greater than that will be safely truncated to this value.
 103 -- @param length        Amount of data to read (in Bytes).
 104 -- @return buffer containing data successfully read
 105 -- @return host         IP-Address of the sender
 106 -- @return port         Port of the sender
 107
 108 --- Receive a message on the socket.
 109 -- This function is identical to recvfrom except that it does not return
 110 -- the sender's source address. See the recvfrom description for more details.
 111 -- @class function
 112 -- @name Socket.recv
 113 -- @param length        Amount of data to read (in Bytes).
 114 -- @see Socket.recvfrom
 115 -- @return buffer containing data successfully read
 116
 117 --- Receive a message on the socket (This is an alias for recv).
 118 -- See the recvfrom description for more details.
 119 -- @class function
 120 -- @name Socket.read
 121 -- @param length        Amount of data to read (in Bytes).
 122 -- @see Socket.recvfrom
 123 -- @return buffer containing data successfully read
 124
 125 --- Close the socket.
 126 -- @class function
 127 -- @name Socket.close
 128 -- @return true
 129
 130 --- Shut down part of a full-duplex connection.
 131 -- @class function
 132 -- @name Socket.shutdown
 133 -- @param how   (optional, default: rdwr) ["rdwr", "rd", "wr"]
 134 -- @return      true
 135
 136 --- Get the number of the filedescriptor.
 137 -- @class function
 138 -- @name Socket.fileno
 139 -- @return file descriptor number
 140
 141 --- Set the blocking mode of the socket.
 142 -- @class function
 143 -- @name Socket.setblocking
 144 -- @param       blocking        (boolean)
 145 -- @return true
 146
 147 --- Set a socket option.
 148 -- @class function
 149 -- @name Socket.setopt
 150 -- @param level Level ["socket", "tcp", "ip", "ipv6"]
 151 -- @param option Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf",
 152 -- "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute",
 153 -- "bindtodevice", "error", "oobinline", "cork" (TCP),  "nodelay" (TCP),
 154 -- "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop"
 155 -- (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops"
 156 -- (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]
 157 -- @param       value Value
 158 -- @return true
 159
 160 --- Get a socket option.
 161 -- @class function
 162 -- @name Socket.getopt
 163 -- @param level Level ["socket", "tcp", "ip", "ipv6"]
 164 -- @param option Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf",
 165 -- "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute",
 166 -- "bindtodevice", "error", "oobinline", "cork" (TCP),  "nodelay" (TCP),
 167 -- "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop"
 168 -- (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops"
 169 -- (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]
 170 -- @return Value