nixio.Socket.lua 6.4 KB

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