Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet.socket

The socket library provides an implementation of the standard Berkeley sockets on top of the ratchet library. Any methods that pause execution MUST be called from within a thread attached to a ratchet object. This library is also intended for use alongside calls to ratchet:resolve_dns(), see the manual for examples. Most of these functions can fail, see error handling section in manual for details.

Functions

accept (self) Pauses the current thread until a new connection to the socket is attempted.
bind (self, sockaddr) Binds the socket to the given sockaddr, corresponding to the bind() system call.
check_errors (self) Gets the current state of the socket.
close (self) Closes the socket internal file descriptor.
connect (self, sockaddr) Attempts a connection to the given sockaddr and pauses the thread until it is completed.
encrypt (self, context) Creates and attaches an encryption session to the socket, based on the given context.
from_fd (fd) Returns a new socket object, using the given file descriptor.
get_encryption (self) Returns the current encryption session for the socket.
get_fd (self) Returns the internal socket file descriptor.
get_timeout (self) Gets the current timeout for all socket methods that pause the thread.
gethostname () Gets the currently configured hostname of the machine using the gethostname(2) system call.
hton (inp) Converts a number into a byte-string ready to be sent over the network.
hton16 (inp) Converts a number into a byte-string ready to be sent over the network.
listen (self, backlog) Sets the socket to listen mode.
multi_recv (sockets, timeout) Waits for incoming data on several sockets, with a single timeout.
new (family, socktype, protocol) Returns a new socket object, with its own file descriptor.
new_pair () Returns two new socket objects, pre-connected to each other.
ntoh (inp) Converts a byte-string from network byte-order to host byte-order.
ntoh16 (inp) Converts a byte-string from network byte-order to host byte-order.
prepare_tcp (host, port, family) Prepares TCP socket information.
prepare_udp (host, port, family) Prepares UDP socket information.
prepare_unix (path) Prepares UNIX socket information.
recv (self, maxlen) Attempts to receive data from across the socket, pausing the thread until data is available.
send (self, data) Attempts to send the given data across the socket, pausing the thread until it is able to do so.
set_timeout (self, seconds) Sets the current timeout for all socket methods that pause the thread.
set_tracer (self, tracer) Sets a tracer function on the socket, which is called on the major events on the socket.
shutdown (self, what) Shuts down portions of the socket, corresponding to the system call of the same name.


Functions

accept (self)
Pauses the current thread until a new connection to the socket is attempted. The current socket MUST have called listen().

Parameters

  • self: the socket object.

Return value:

a new socket object for the connection, followed by the sockaddr userdata of the connecting host (convertible to an IP address with tostring()).
bind (self, sockaddr)
Binds the socket to the given sockaddr, corresponding to the bind() system call. This method must be used for sockets that call listen(), and may be used for sockets that call connect() when it is desired to connect from a specific network interface.

Parameters

  • self: the socket object.
  • sockaddr: a sockaddr userdata object.
check_errors (self)
Gets the current state of the socket. Returns true if the socket is connected and not in an error state, or returns nil and an error otherwise.

Parameters

  • self: the socket object.

Return value:

true if the socket is okay. See error handling section in manual.
close (self)
Closes the socket internal file descriptor. This is called automatically when the socket object is collected, for convenience.

Parameters

  • self: the socket object.
connect (self, sockaddr)
Attempts a connection to the given sockaddr and pauses the thread until it is completed.

Parameters

  • self: the socket object.
  • sockaddr: a sockaddr userdata object.

Return value:

true if the connection succeeded, false otherwise.
encrypt (self, context)
Creates and attaches an encryption session to the socket, based on the given context. Once this session is created, it handles all calls to the send()/recv() methods.

Parameters

  • self: the socket object.
  • context: a ratchet.ssl context object.

Return value:

the new encryption session for the socket. See ratchet.ssl.session for details.
from_fd (fd)
Returns a new socket object, using the given file descriptor. This is particularly useful when sockets are returned by the accept() system call.

Parameters

  • fd: an existing file descriptor of a socket.

Return value:

a new socket object.
get_encryption (self)
Returns the current encryption session for the socket.

Parameters

  • self: the socket object.

Return value:

the encryption session, or nil if unencrypted.
get_fd (self)
Returns the internal socket file descriptor.

Parameters

  • self: the socket object.

Return value:

a file descriptor.
get_timeout (self)
Gets the current timeout for all socket methods that pause the thread.

Parameters

  • self: the socket object.

Return value:

the current timeout in seconds.
gethostname ()
Gets the currently configured hostname of the machine using the gethostname(2) system call.
hton (inp)
Converts a number into a byte-string ready to be sent over the network. This is necessary only for binary socket protocols. See manpage byteorder(3).

Parameters

  • inp: the number to be converted.

Return value:

a byte-string in network byte-order ready to be sent over the network. Any extra arguments passed are also returned in order.
hton16 (inp)
Converts a number into a byte-string ready to be sent over the network. This is necessary only for binary socket protocols. See manpage byteorder(3).

Parameters

  • inp: the number to be converted. This is the 16-bit version of hton().

Return value:

a byte-string in network byte-order ready to be sent over the network. Any extra arguments passed are also returned in order.
listen (self, backlog)
Sets the socket to listen mode. This socket will open the system port it was bind()ed to. Connections to this socket can be accepted by the accept() method.

Parameters

  • self: the socket object.
  • backlog: optional maximum length of pending connections queue.
multi_recv (sockets, timeout)
Waits for incoming data on several sockets, with a single timeout. A recv() call will be run on the first socket to signal incoming data, and the result will be returned by this function.

Parameters

  • sockets: Table array of sockets to wait for data on.
  • timeout: Seconds of inactivity before the function returns nil.

Return value:

The first data received on any of the sockets. If first return is nil, either a timeout occured or the nil will be followed by an error message.
new (family, socktype, protocol)
Returns a new socket object, with its own file descriptor.

Parameters

  • family: the protocol family which will be used for communication.
  • socktype: specifies the communication semantics.
  • protocol: specifies a particular protocol to be used.

Return value:

a new socket object.
new_pair ()
Returns two new socket objects, pre-connected to each other. This is done with the socketpair() system call, and does not open a port or create a server.

Return value:

Two socket objects connected to each other.
ntoh (inp)
Converts a byte-string from network byte-order to host byte-order. This is necessary only for binary socket protocols. Takes a 4-byte string from the socket and returns the regular number after conversion. See manpage byteorder(3).

Parameters

  • inp: the binary input string from the socket to convert to a number.

Return value:

the resulting number after conversion. Any extra arguments passed are also returned in order.
ntoh16 (inp)
Converts a byte-string from network byte-order to host byte-order. This is necessary only for binary socket protocols. Takes a 2-byte string from the socket and returns the regular number after conversion. See manpage byteorder(3). This is the 16-bit version of ntoh().

Parameters

  • inp: the binary input string from the socket to convert to a number.

Return value:

the resulting number after conversion. Any extra arguments passed are also returned in order.
prepare_tcp (host, port, family)
Prepares TCP socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details. If host is not an IP address, this call will pause the current thread to wait for a DNS lookup.

Parameters

  • host: queried by DNS for new TCP connection.
  • port: destination port number for new TCP connection.
  • family: optional string indicating socket family. Valid values are "AF_INET", "AF_INET6", or the default "AF_UNSPEC".

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
prepare_udp (host, port, family)
Prepares UDP socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details. If host is not an IP address, this call will pause the current thread to wait for a DNS lookup.

Parameters

  • host: queried by DNS for new UDP connection.
  • port: destination port number for new UDP connection.
  • family: string indicating socket family, default "AF_UNSPEC".

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
prepare_unix (path)
Prepares UNIX socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details.

Parameters

  • path: file-path to connect/create UNIX socket.

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
recv (self, maxlen)
Attempts to receive data from across the socket, pausing the thread until data is available. As in the system call, recv() will return an empty string if the other end has shut down.

Parameters

  • self: the socket object.
  • maxlen: optional maximum number of bytes to receive.

Return value:

string of data received on the socket.
send (self, data)
Attempts to send the given data across the socket, pausing the thread until it is able to do so. If the entire string of data cannot be sent at once, the portion that was not sent is returned.

Parameters

  • self: the socket object.
  • data: a string of data to send.

Return value:

a string of remaining data to still be sent, or nil if the entire string of data was sent.
set_timeout (self, seconds)
Sets the current timeout for all socket methods that pause the thread.

Parameters

  • self: the socket object.
  • seconds: the new timeout in seconds.
set_tracer (self, tracer)
Sets a tracer function on the socket, which is called on the major events on the socket. The first argument to the tracer function will be an event type, such as "accept" or "recv". A second argument is passed for those events that have associated data, such as "recv". Tracer functions can be useful for verbose logging or debugging.

Parameters

  • self: the socket object.
  • tracer: Function to call as tracer, or none or nil to clear current tracer.
shutdown (self, what)
Shuts down portions of the socket, corresponding to the system call of the same name. You can shut down reads, writes, or both.

Parameters

  • self: the socket object.
  • what: either "read", "write", or "both". Default "both".