NAME
Socket::Class - A class to communicate with sockets
SYNOPSIS
use Socket::Class;DESCRIPTION
Socket::Class provides a simple, fast and efficient way to communicate with sockets. It operates outside of Perl IO and socket layer. It can be used as a replacement to IO::Socket. Little parts of Bluetooth technology has been integrated. Please see below.
Bluetooth
The standard build includes Bluetooth protocols for RFCOMM (stream) and L2CAP (datagram). Bluetooth adapters on a MS-Windows operation system must be compatible with the Windows Bluetooth API to get it working. More specific Bluetooth support could be added in the future.
Functions by Category
Main Functions
Sending and Receiving
Address Functions
get_hostaddr, get_hostname, getaddrinfo, getnameinfo, local_addr, local_path, local_port, pack_addr, remote_addr, remote_path, remote_port, unpack_addr
Socket Options
get_blocking, get_broadcast, get_option, get_rcvbuf_size, get_reuseaddr, get_sndbuf_size, get_timeout, get_tcp_nodelay, set_blocking, set_broadcast, set_option, set_rcvbuf_size, set_reuseaddr, set_sndbuf_size, set_timeout, set_tcp_nodelay
Miscellaneous Functions
available, fileno, handle, is_readable, is_writable, select, sleep, state, to_string, wait
Error Handling
EXAMPLES
Simple Internet Server
use Socket::Class qw(SOMAXCONN);
# create a new socket on port 9999 and listen for clients
$server = Socket::Class->new(
'local_port' => 9999,
'listen' => SOMAXCONN,
) or die Socket::Class->error;
# wait for clients
while( $client = $server->accept() ) {
# somebody connected to us (we are local, client's address is remote)
print 'Incoming connection from '
. $client->remote_addr . ' port ' . $client->remote_port . "\n";
# do something with the client
$client->say( 'hello client' );
...
$client->wait( 100 );
# close the client connection and free its resources
$client->free();
}Simple Internet Client
use Socket::Class;
# create a new socket and connect to the server at localhost on port 9999
$client = Socket::Class->new(
'remote_addr' => 'localhost',
'remote_port' => 9999,
) or die Socket::Class->error;
# do something with the socket
$str = $client->readline();
print $str, "\n";
# close the client connection and free its resources
$client->free();Simple HTTP Client
use Socket::Class;
# create a new socket and connect to www.perl.org
$sock = Socket::Class->new(
'remote_addr' => 'www.perl.org',
'remote_port' => 'http',
) or die Socket::Class->error;
# request the main site
$sock->write(
"GET / HTTP/1.0\r\n" .
"User-Agent: Not Mozilla\r\n" .
"Host: www.perl.org\r\n" .
"Connection: Close\r\n" .
"\r\n"
) or die $sock->error;
# read the response (1MB max)
$sock->read( $buf, 1048576 )
or die $sock->error;
# do something with the response
print $buf;
# close the socket an free its resources
$sock->free();Bluetooth RFCOMM Client
use Socket::Class;
# create a new socket and connect to a bluetooth device
$sock = Socket::Class->new(
'domain' => 'bluetooth',
'type' => 'stream',
'proto' => 'rfcomm',
'remote_addr' => '00:16:20:66:F2:6C',
'remote_port' => 1, # channel
) or die Socket::Class->error;
# do something with the socket
$sock->send( "bluetooth works" );
...
# close the connection and free its resources
$sock->free();METHODS
Constructing
- new ( [%arg] )
-
Creates a Socket::Class object, which is a reference to a newly created socket handle. new() optionally takes arguments, these arguments must set as key-value pairs.
remote_addr Remote host address <hostname> | <hostaddr> remote_port Remote port or service <service> | <number> remote_path Remote path for unix sockets "/tmp/mysql.sock" local_addr Local host bind address <hostname> | <hostaddr> local_port Local host bind port <service> | <number> local_path Local path for unix sockets "/tmp/myserver.sock" domain Socket domain name (or number) "inet" | "inet6" | ... proto Protocol name (or number) "tcp" | "udp" | ... type Socket type name (or number) "stream" | "dgram" | ... listen Put socket into listen state with a specified maximal number of connections in the queue broadcast Set SO_BROADCAST before binding reuseaddr Set SO_REUSEADDR before binding blocking Enable or disable blocking mode; default is enabled timeout Timeout value for various operations as floating point number; defaults to 15000 (15 seconds); currently used by connectIf local_addr, local_port or local_path is defined, then the socket will bind a local address. If listen is defined, then the socket will put into listen state. If remote_addr, remote_port or remote_path is defined then connect() is called.
Standard domain is AF_INET. Standard socket type is SOCK_STREAM. Standard proto is IPPROTO_TCP. If local_path or remote_path is defined, then the standard domain becomes AF_UNIX and the standard protocol becomes 0.
Examples
Create a nonblocking listening inet socket on a random local port
$sock = Socket::Class->new( 'listen' => 5, 'blocking' => 0, ) or die Socket::Class->error; print "listen on local port ", $sock->local_port, "\n";Create a listening unix socket
$sock = Socket::Class->new( 'domain' => 'unix', 'local_path' => '/tmp/myserver.sock', 'listen' => 5, ) or die Socket::Class->error;Connect to smtp service (port 25) on localhost
$sock = Socket::Class->new( 'remote_addr' => 'localhost', 'remote_port' => 'smtp', ) or die Socket::Class->error;Create a broadcast socket
$sock = Socket::Class->new( 'remote_addr' => '255.255.255.255', 'remote_port' => 9999, 'proto' => 'udp', 'local_addr' => 'localhost', 'broadcast' => 1, ) or die Socket::Class->error;
Closing / Destructing / Freeing
Undefining all reference variables will free the socket and its resources.
You can also call free() to free the socket explicitly.
- shutdown ( [$how] )
-
Disables sends and receives on the socket.
Parameters
$how
One of the following values that specifies the operation that will no longer be allowed. Default is SD_SEND.
Num Const Description ---------------------------------------------------------------------- 0 SD_SEND Disable sending on the socket. 1 SD_RECEIVE Disable receiving on the socket. 2 SD_BOTH Disable both sending and receiving on the socket.Return Values
Returns a true value on sucess or undef on failure. Use errno() and error() to retrieve the error code and message.
Examples
use Socket::Class qw(SD_BOTH); $sock = Socket::Class->new( ... ); ... $sock->shutdown( SD_BOTH ); $sock->free(); - close ()
-
Closes the socket without freeing internal resources.
- free ()
-
Closes the socket and frees all internally allocated resources.
Bind, Listen and Accept
- bind ( [$addr [, $port]] )
- bind ( [$path] )
-
Binds the socket to a specified local address.
Parameters
$addr or $path
On 'inet' family sockets the $addr parameter can be an IP address in dotted-quad notation (e.g. 127.0.0.1) or a valid hostname.
On 'inet6' family sockets the $addr parameter can be an IPv6 address in hexadecimal notation (e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344) or a valid hostname.
On 'unix' family sockets the $path is the pathname of a Unix domain socket.
If $addr is not defined the address from last bind is used.
$port
The $port parameter designates the port or channel on the local host.
Return Values
Returns a true value on sucess or undef on failure. Use errno() and error() to retrieve the error code and message.
Examples
$sock->bind( '0.0.0.0', 9999 ) or die "can't bind: " . $sock->error; - listen ( [$backlog] )
-
Listens for a connection on a socket.
Parameters
$backlog
A maximum of backlog incoming connections will be queued for processing. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed.
Return Values
Returns a true value on sucess or undef on failure. Use errno() and error() to retrieve the error code and message.
Examples
use Socket::Class qw(SOMAXCONN); ... $sock->listen( SOMAXCONN ) or die $sock->error; - accept ()
-
Accepts a connection on a bound socket. Once a successful connection is made, a new socket resource is returned, which may be used for communication. If there are multiple connections queued on the socket, the first will be used. If there are no pending connections, accept() will block until a connection becomes present. If socket has been made non-blocking using set_blocking(), 0 will be returned.
Return Values
Returns a new socket class on sucess or 0 on non-blocking mode and no new connection becomes available or UNDEF on failure. Use errno() and error() to retrieve the error code and message.
Examples
Blocking mode (default)
while( $client = $sock->accept() ) { # do something with the connection print "Incoming connection: ", $client->to_string, "\n"; ... $client->free(); }Non blocking mode
while( 1 ) { $client = $sock->accept(); if( ! defined $client ) { # error die $sock->error; } elsif( ! $client ) { # no client, sleep for a while $sock->wait( 10 ); next; } # do something with the connection print "Incoming connection: ", $client->to_string, "\n"; ... $client->free(); }
Connect
- connect ( [$addr [, $port [, $timeout]]] )
- connect ( [$path [,$timeout]] )
-
Initiates a connection.
Parameters
$addr or $path
On 'inet' family sockets the $addr parameter can be an IP address in dotted-quad notation (e.g. 127.0.0.1) or a valid hostname.
On 'inet6' family sockets the $addr parameter can be an IPv6 address in hexadecimal notation (e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344) or a valid hostname.
On 'unix' family sockets the $path is the pathname of a Unix domain socket.
If $addr is not defined the address from last connect is used.
$port
The $port parameter designates the port or service on the remote host to which a connection should be made.
$timeout
Optionally timeout in milliseconds as floating point number.
Return Values
Returns a TRUE value on sucess or UNDEF on failure. Use errno() and error() to retrieve the error code and message.
Examples
$sock->connect( 'www.perl.org', 'http' ) or die "can't connect: " . $sock->error; - reconnect ( [$timeout] )
-
Closes the current connection, waits $timeout milliseconds and reconnects the socket to the connection previously made.
Return Values
Returns a true value on sucess or undef on failure. Use errno() and error() to retrieve the error code and message.
Examples
if( $sock->is_error ) { retry: print "socket error: ", $sock->error, "\n"; # try to reconnect $r = $sock->reconnect( 1000 ); if( ! $r ) { # can't connect goto retry; } }
Low level sending and receiving data
- send ( $buf [, $flags] )
-
Sends data to a connected socket.
Parameters
$buf
A buffer containing the data that will be sent to the remote host.
$flags
The value of $flags can be any combination of the following:
Number Constant Description ------------------------------------------------------------- 0x1 MSG_OOB Process OOB (out-of-band) data 0x2 MSG_PEEK Peek at incoming message 0x4 MSG_DONTROUTE Bypass routing, use direct interface 0x8 MSG_CTRUNC Data completes record 0x100 MSG_WAITALL Data completes transactionReturn Values
Returns the number of bytes sent or undef if an error occured. Use errno() and error() to retrieve the error code and message.
Examples
$r = $sock->send( "important message" ); if( ! defined $r ) { # error die "can't sent: " . $sock->error; } print "sent $r bytes\n";See Also
- recv ( $buf, $len [, $flags] )
-
Receives data from a connected socket.
Parameters
$buf
A variable to write the received bytes into.
$len
The number of bytes to receive.
$flags
The value of $flags can be any combination of the following:
Number Constant Description ---------------------------------------------------------------------- 0x01 MSG_OOB Process OOB (out-of-band) data 0x02 MSG_PEEK Peek at incoming message 0x04 MSG_DONTROUTE Bypass routing, use direct interface 0x08 MSG_CTRUNC Data completes record 0x20 MSG_TRUNC Return the real length of the packet, even when it was longer than the passed buffer. Only valid for packet sockets.Return Values
Returns the number of bytes received or undef on error. Use errno() and error() to retrieve the error code and message.
See Also
- sendto ( $buf [, $to [, $flags]] )
-
Sends a message to a socket, whether it is connected or not.
Parameters
$buf
A buffer containing the data that will be sent to the remote host.
$to
Packed address of the remote host. (See pack_addr function)
$flags
The value of $flags can be any combination of the following:
Number Constant Description ------------------------------------------------------------- 0x01 MSG_OOB Process OOB (out-of-band) data 0x02 MSG_PEEK Peek at incoming message 0x04 MSG_DONTROUTE Bypass routing, use direct interfaceReturn Values
Returns the bytes sent to the remote host or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
$sock = Socket::Class->new( 'proto' => 'udp' ); $paddr = $sock->pack_addr( 'localhost', 9999 ); $sock->sendto( 'PING', $paddr );OR
$sock = Socket::Class->new( 'proto' => 'udp', 'remote_addr' => 'localhost', 'remote_port' => 9999, ); $sock->sento( 'PING' );See Also
- recvfrom ( $buf, $len [, $flags] )
-
Receives data from a socket whether or not it is connection-oriented
Parameters
$buf
The data received will be fetched to the variable specified with buf.
$len
Up to len bytes will be fetched from remote host.
$flags
The following table contains the different flags that can be set using the $flags parameter. Use the OR logic operator (|) to use more than one flag.
Number Constant Description ----------------------------------------------------------------------- 0x001 MSG_OOB Process OOB (out-of-band) data 0x002 MSG_PEEK Receive data from the beginning of the receive queue without removing it from the queue. 0x040 MSG_DONTWAIT With this flag set, the function returns even if it would normally have blocked. 0x100 MSG_WAITALL Block until at least len are received. However, if a signal is caught or the remote host disconnects, the function may return less data.Return Values
Returns a packed address of the sender or 0 on non-blocking mode and no data becomes available or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
Blocking mode (default)
while( $paddr = $sock->recvfrom( $buf, 1024 ) ) { ($r_addr, $r_port) = $sock->unpack_addr( $paddr ); print "Incoming message from $r_addr port $r_port\n"; }Non blocking mode
while( 1 ) { $paddr = $sock->recvfrom( $buf, 1024 ); if( ! defined $paddr ) { # error die $sock->error; } elsif( ! $paddr ) { # no data, sleep for a while $sock->wait( 10 ); next; } ($r_addr, $r_port) = $sock->unpack_addr( $paddr ); print "Incoming message from $r_addr port $r_port\n"; }See Also
Higher level sending and receiving
- write ( $buffer [, $start [, $length]] )
-
Writes to the socket from the given buffer.
Parameters
$buffer
The buffer to be written.
$start
The optional parameter $start can specify an alternate offset in the buffer.
$length
The optional parameter $length can specify an alternate length of bytes written to the socket. If this length is greater then the buffer length, it is silently truncated to the length of the buffer.
Return Values
Returns the number of bytes successfully written to the socket or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Notes
Note: write () does not necessarily write all bytes from the given buffer. It's valid that, depending on the network buffers etc., only a certain amount of data, even one byte, is written though your buffer is greater. You have to watch out so you don't unintentionally forget to transmit the rest of your data.
Examples
# generate 1mb of data $data = '#' x 1048576; # send the data out $start = 0; $size = length( $data ); while( !$sock->is_error && $start < $size ) { if( $sock->is_writable( 100 ) ) { $start += $sock->write( $data, $start ); } } - read ( $buffer, $length )
-
Reads a maximum of length bytes from a socket.
Parameters
$buffer
A variable to write the read bytes into.
$length
The maximum number of bytes read is specified by the length parameter.
Return Values
Returns number of bytes read, or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
# read from socket until error $data = ''; while( !$sock->is_error ) { if( $sock->is_readable( 100 ) ) { $sock->read( $buffer, 4096 ) or last; $data .= $buffer; } } printf "received %d bytes\n", length( $data ); - print ( ... )
-
Writes to the socket from the given parameters. print maps to write
Return Values
Returns the number of bytes successfully written to the socket, or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
$sock->print( 'hello client', "\n" ); - printf ( $fmt, ... )
-
Writes formated string to the socket.
Parameters
$fmt
Defines the format of the string. See Perl printf and sprintf for more details
Return Values
Returns the number of bytes successfully written to the socket or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Examples
# round number to 3 digits after decimal point and send it $sock->printf( "%.3f", $number ); # does the same like above $sock->write( sprintf( "%.3f", $number ) ); - writeline ( ... )
- say ( ... )
-
Writes to the socket from the given string plus a carriage return and a newline char (\r\n). say is a synonym for writeline.
Return Values
Returns the number of bytes successfully written to the socket, or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
$sock->say( 'hello client' ); - readline ( [$separator [, $maxsize]] )
-
Reads characters from the socket and stops at \r\n, \n\r, \n, \r or \0 if no $separator has been specified.
Parameters
$separator
Alternative line separator string.
$maxsize
Stop reading at $maxsize bytes. Default is 0 for unlimited size.
Return Values
Returns a string value, or undef on error. Use errno() and error() to retrieve the error code and message.
- read_packet ( $separator [, $maxsize] )
-
Reads characters from the socket and stops at $separator.
Parameters
$separator
Packet separator string.
$maxsize
Stop reading at $maxsize bytes. Default is 0 for unlimited size.
Return Values
Returns a string value, or undef on error. Use errno() and error() to retrieve the error code and message.
Socket options
- set_blocking ( [$int] )
-
Changes the blocking mode of the socket.
Parameters
$int
1 - blocking mode 0 - non-blocking modeReturn Values
Returns a true value on success, or undef on error. Use errno() and error() to retrieve the error code and message.
- get_blocking ()
-
Returns the current blocking state.
Return Values
Returns TRUE value on blocking mode, or FALSE on non-blocking mode, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_reuseaddr ( [$int] )
-
Sets the SO_REUSEADDR socket option.
Parameters
$int
1 - enable reuseaddr 0 - disable reuseaddrReturn Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_reuseaddr ()
-
Returns the current value of SO_REUSEADDR.
Return Values
Returns the value of SO_REUSEADDR or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_broadcast ( [$int] )
-
Sets the SO_BROADCAST socket option.
Parameters
$int
1 - set SO_BROADCAST 0 - unset SO_BROADCASTReturn Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_broadcast ()
-
Returns the current value of SO_BROADCAST.
Return Values
Returns the value of SO_BROADCAST or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_rcvbuf_size ( [$size] )
-
Sets the SO_RCVBUF socket option.
Parameters
$size
The size of the receive buffer.
Return Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_rcvbuf_size ()
-
Returns the current value of SO_RCVBUF.
Return Values
Returns the value of SO_RCVBUF or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_sndbuf_size ( [$size] )
-
Sets the SO_SNDBUF socket option.
Parameters
$size
The size of the send buffer.
Return Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_sndbuf_size ()
-
Returns the current value of SO_SNDBUF.
Return Values
Returns the value of SO_SNDBUF or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_timeout ( [$ms] )
-
Sets the timeout for various operations.
Parameters
$ms
The timeout in milliseconds as floating point number.
Return Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_timeout ()
-
Returns the current timeout.
Return Values
Returns the timeout in milliseconds or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_tcp_nodelay ( [$int] )
-
Sets the TCP_NODELAY socket option.
Parameters
$int
On 1 disable the naggle algorithm, on 0 enable it.
Return Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- get_tcp_nodelay ()
-
Returns the current value of TCP_NODELAY.
Return Values
Returns the value of TCP_NODELAY or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- set_option ( $level, $optname, $optval, ... )
-
Sets socket options for the socket.
Parameters
$level
The level parameter specifies the protocol level at which the option resides. For example, to retrieve options at the socket level, a level parameter of SOL_SOCKET would be used. Other levels, such as TCP, can be used by specifying the protocol number of that level.
$optname
A valid socket option.
$optval ...
The value in packed or unpacked format. If $optval is an integer value it will be packed as int. For SO_LINGER, SO_RCVTIMEO and SO_SNDTIMEO one or two values are accepted. Please see examples below.
Return Values
Returns a TRUE value on sucess or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Examples
use Socket::Class qw(SOL_SOCKET SO_LINGER SO_RCVTIMEO); $sock = Socket::Class->new( ... ); # disable linger $sock->set_option( SOL_SOCKET, SO_LINGER, 0, 0 ); # same like $sock->set_option( SOL_SOCKET, SO_LINGER, pack( 'S!S!', 0, 0 ) ); # set rcv timeout to 0sec + 100000usec $sock->set_option( SOL_SOCKET, SO_RCVTIMEO, 0, 100000 ); # or in milliseconds $sock->set_option( SOL_SOCKET, SO_RCVTIMEO, 100 );See Also
- get_option ( $level, $optname )
-
Gets socket options for the socket.
Parameters
$level
The level parameter specifies the protocol level at which the option resides. For example, to retrieve options at the socket level, a level parameter of SOL_SOCKET would be used. Other levels, such as TCP, can be used by specifying the protocol number of that level.
$optname
A valid socket option.
Option Description ----------------------------------------------------------------------- SO_DEBUG Reports whether debugging information is being recorded. SO_ACCEPTCONN Reports whether socket listening is enabled. SO_BROADCAST Reports whether transmission of broadcast messages is supported. SO_REUSEADDR Reports whether local addresses can be reused. SO_KEEPALIVE Reports whether connections are kept active with periodic transmission of messages. If the connected socket fails to respond to these messages, the connection is broken and processes writing to that socket are notified with a SIGPIPE signal. SO_LINGER Reports whether the socket lingers on close() if data is present. SO_OOBINLINE Reports whether the socket leaves out-of-band data inline. SO_SNDBUF Reports send buffer size information. SO_RCVBUF Reports recieve buffer size information. SO_ERROR Reports information about error status and clears it. SO_TYPE Reports the socket type. SO_DONTROUTE Reports whether outgoing messages bypass the standard routing facilities. SO_RCVLOWAT Reports the minimum number of bytes to process for socket input operations. ( Defaults to 1 ) SO_RCVTIMEO Reports the timeout value for input operations. SO_SNDLOWAT Reports the minimum number of bytes to process for socket output operations. SO_SNDTIMEO Reports the timeout value specifying the amount of time that an output function blocks because flow control prevents data from being sent.Return Values
Returns the value of the given option, or UNDEF on error. If the size of the value equals the size of int the value will be unpacked into integer. For SO_LINGER, SO_RCVTIMEO and SO_SNDTIMEO the value is unpacked, too. Use errno() and error() to retrieve the error code and message.
Examples
use Socket::Class qw(SOL_SOCKET SO_LINGER SO_RCVTIMEO); $sock = Socket::Class->new( ... ); # get linger ($l_onoff, $l_linger) = $sock->get_option( SOL_SOCKET, SO_LINGER ); # get rcv timeout ($tv_sec, $tv_usec) = $sock->get_option( SOL_SOCKET, SO_RCVTIMEO ); # or in milliseconds $ms = $sock->get_option( SOL_SOCKET, SO_RCVTIMEO );See Also
Address Functions
- local_addr ()
-
Returns the local address of the socket
- local_port ()
-
Returns the local port of the socket
- local_path ()
-
Returns the local path of 'unix' family sockets
- remote_addr ()
-
Returns the remote address of the socket
- remote_port ()
-
Returns the remote port of the socket
- remote_path ()
-
Returns the remote path of 'unix' family sockets
- pack_addr ( $addr [, $port] )
-
Packs a given address and returns it.
Parameters
$addr
IP address on 'inet' family sockets or a unix path on 'unix' family sockets.
$port
Port number of the address.
Return Values
Returns the packed address.
Examples
$paddr = $sock->pack_addr( 'localhost', 9999 ); ($addr, $port) = $sock->unpack_addr( $paddr ); - unpack_addr ( $paddr )
-
Unpacks a given address and returns it.
Parameters
$paddr
A packed address.
Return Values
Returns the unpacked address.
Examples
$paddr = $sock->pack_addr( 'localhost', 9999 ); ($addr, $port) = $sock->unpack_addr( $paddr ); # in scalar context only the address part will return $addr = $sock->unpack_addr( $paddr ); - get_hostname ()
- get_hostname ( $addr )
- remote_name ()
-
Resolves the name of a given host address. remote_name is a synonym for get_hostname.
Parameters
$addr
The host address in plain (e.g. '192.168.0.1') or packed format. If no address is specified the remote address of the socket is used.
Return Values
Returns the first hostname found, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Examples
$str = $sock->get_hostname( '127.0.0.1' ); # -or- $paddr = $sock->pack_addr( '127.0.0.1', 9999 ); $str = $sock->get_hostname( $paddr ); # -or- $sock->connect( 'www.perl.org', 'http' ) or die $sock->error; print "conntected to ", $sock->remote_name || $sock->remote_addr, "\n"; - get_hostaddr ( $name )
-
Resolves the address of a given host name.
Parameters
$name
The host name as a string.
Return Values
Returns the host address, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Examples
$host = 'www.perl.org'; $addr = $sock->get_hostaddr( $host ); print "address of $host is $addr\n"; - getaddrinfo ( $node [, $service [, $family [, $proto [, $type [, $flags]]]]] )
-
The getaddrinfo function provides protocol-independent translation of host names to an address. The function can be exported.
Parameters
$node
A string that contains a host (node) name or a numeric host address string. For the internet protocol, the numeric host address string is a dotted-decimal IPv4 address or an IPv6 hex address.
$service
A service name or port number, or undef to get all services.
$family
The address family as name or number, or undef to get all families.
$proto
The protocol type as name or number, or undef to get all protocols.
$type
The socket type as name or number, or undef to get all socket types.
$flags
Flags that indicate options used. See getaddrinfo() flags in the Socket::Class::Const module
Return Values
Returns an array of hashes with address information, or undef on error. Use errno() and error() to retrieve the error code and message.
Address information structure:
'family' => address family as number 'socktype' => socket type as number 'protocol' => protocol type as number 'paddr' => address in packed format 'canonname' => [opt] canonical name for the host 'familyname' => [opt] name of address family (eg. 'INET') 'sockname' => [opt] name of socket type (eg. 'STREAM') 'protocolname' => [opt] name of protocol type (eg. 'TCP') 'addr' => [opt] readable version of IP v4/6 address 'port' => [opt] readable version of IP v4/6 portExamples
getaddrinfo() as global function
@list = Socket::Class->getaddrinfo( 'localhost' ) or die Socket::Class->error;getaddrinfo() with an object
$sock = Socket::Class->new(); @list = $sock->getaddrinfo( 'localhost' ) or die $sock->error;getaddrinfo() exported
use Socket::Class qw/getaddrinfo/; @list = getaddrinfo( 'localhost' ) or die $@; - getnameinfo ( $addr [, $service [, $flags]] )
- getnameinfo ( $paddr [, $flags] )
-
The getnameinfo function provides protocol-independent name resolution from an address to a host name and from a port number to the service name. The function can be exported.
Parameters
$addr
The host address in plain (e.g. '192.168.0.1') format.
$service
A service name or port number.
$paddr
A packed host address. See also pack_addr(), getaddrinfo()
$flags
A value used to customize processing of the getnameinfo function. See getnameinfo() flags in the Socket::Class::Const module
Return Values
Returns the hostname in scalar context, or hostname and service in array context, or undef on error. Use errno() and error() to retrieve the error code and message.
Examples
getnameinfo() as global function
($host, $service) = Socket::Class->getnameinfo( '127.0.0.1', 80 ) or die Socket::Class->error; print "host: $host, service: $service\n";getnameinfo() with an object
$sock = Socket::Class->new(); ($host, $service) = $sock->getnameinfo( '127.0.0.1', 80 ) or die $sock->error; print "host: $host, service: $service\n";getnameinfo() exported
use Socket::Class qw/getnameinfo/; ($host, $service) = getnameinfo( '127.0.0.1', 80 ) or die $@; print "host: $host, service: $service\n";
Miscellaneous Functions
- available ()
-
Gets the amount of data that is available to be read.
Return Values
Returns the number of bytes that is available to be read, or undef on error. Use errno() and error() to retrieve the error code and message.
Remarks
On blocking sockets the function can block infinitely. In this case you should call is_readable() before running the function.
Examples
while( ! $sock->is_error ) { if( $sock->is_readable( 1000 ) ) { $size = $sock->available or die $sock->error; print "bytes to read: $size\n"; $got = $sock->read( $buf, $size ); or die $sock->error; } } - is_readable ( [$timeout] )
-
Checks the socket for readability.
Parameters
$timeout
The timeout in milliseconds as a floating point value. If $timeout is initialized to 0, is_readable will return immediately; this is used to poll the readability of the socket. If the value is undef (no timeout), is_readable() can block indefinitely.
Return Values
Returns TRUE if the socket is readable, or FALSE if it is not, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- is_writable ( [$timeout] )
-
Checks the socket for writability.
Parameters
$timeout
The timeout in milliseconds as a floating point value. If $timeout is initialized to 0, is_writable will return immediately; this is used to poll the writability of the socket. If the value is undef (no timeout), is_writable() can block indefinitely.
Return Values
Returns TRUE if the socket is writable, or FALSE if it is not, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
- select ( [$read [, $write [, $except [, $timeout]]]] )
-
Runs the select() system call on the socket with a specified timeout.
Parameters
$read - [in/out]
If the $read parameter is set, the socket will be watched to see if characters become available for reading. Out: Indicates the state of readability.
$write - [in/out]
If the $write parameter is set, the socket will be watched to see if a write will not block. Out: Indicates the state of writability.
$except - [in/out]
If the $except parameter is set, the socket will be watched for exceptions. Out: Indicates a socket exception.
$timeout
The timeout in milliseconds as a floating point value. If $timeout is initialized to 0, select will return immediately; this is used to poll the state of the socket. If the value is undef (no timeout), select() can block indefinitely.
Return Values
Returns a number between 0 to 3 which indicates the parameters set to TRUE, or UNDEF on error. Use errno() and error() to retrieve the error code and message.
Remarks
In summary, the socket will be identified in a particular set when select returns if:
read:
If listen has been called and a connection is pending, accept will succeed.
Data is available for reading (includes OOB data if SO_OOBINLINE is enabled).
Connection has been closed/reset/terminated.
write:
If processing a connect call (nonblocking), connection has succeeded.
Data can be sent.
except:
If processing a connect call (nonblocking), connection attempt failed.
OOB data is available for reading (only if SO_OOBINLINE is disabled).
Examples
use Socket::Class qw(SOL_SOCKET SO_ERROR); ... # watch all states and return within 1000 milliseconds $v = $sock->select( $r = 1, $w = 1, $e = 1, 1000 ); unless( defined $v ) { die "select failed: " . $sock->error; } if( $e ) { # socket error $e = $sock->get_option( SOL_SOCKET, SO_ERROR ); die $sock->error( $e ); } if( $r ) { # socket is readable ... } if( $w ) { # socket is writable ... } - state ()
-
Returns the state of the socket.
Return Values
Number Constant Description --------------------------------------------------- 0 SC_STATE_INIT Socket is created 1 SC_STATE_BOUND Socket is bound 2 SC_STATE_LISTEN Socket is listening 3 SC_STATE_CONNECTED Socket is connected 4 SC_STATE_CLOSED Socket is closed 99 SC_STATE_ERROR Socket got an error on last send or receive - to_string ()
-
Returns a readable version of the socket.
- handle ()
- fileno ()
-
Returns the internal socket handle. fileno is a synonym for handle.
- wait ( $ms )
- sleep ( $ms )
-
Sleeps the given number of milliseconds. sleep is a synonym for wait.
Parameters
$ms
The number of milliseconds to sleep as floating point number.
Error handling
- is_error ()
-
Indicates a socket error. Returns TRUE on socket state SC_STATE_ERROR, or FALSE value on other state.
- errno ()
-
Returns the last error code.
- error ( [code] )
-
Returns the error message for the error code provided by the $code parameter, or for the last error occurred.
MORE EXAMPLES
Internet Server using threads
use threads;
use threads::shared;
use Socket::Class;
our $RUNNING : shared = 1;
our $Server = Socket::Class->new(
'local_addr' => '0.0.0.0',
'local_port' => 9999,
'listen' => 30,
'blocking' => 0,
'reuseaddr' => 1,
) or die Socket::Class->error;
# catch interrupt signals for a clean shutdown
$SIG{'INT'} = \&quit;
#$SIG{'TERM'} = \&quit;
# create the server thread
threads->create( \&server_thread, $Server );
while( $RUNNING ) {
# do other things here
# ...
# sleep for a while
$Server->wait( 100 );
}
1;
sub quit {
my( $thread );
$RUNNING = 0;
foreach $thread( threads->list ) {
eval {
$thread->join();
};
}
$Server->free();
exit( 0 );
}
sub server_thread {
my( $server ) = @_;
my( $client );
print 'Server running at ' . $server->local_addr .
' port ' . $server->local_port . "\n";
while( $RUNNING ) {
$client = $server->accept();
if( ! defined $client ) {
# server is closed
last;
}
elsif( ! $client ) {
# no connection available, sleep for a while
$server->wait( 10 );
next;
}
threads->create( \&client_thread, $client );
}
return 1;
}
sub client_thread {
my( $client ) = @_;
my( $buf, $got );
print 'Connection from ' . $client->remote_addr .
' port ' . $client->remote_port . "\n";
# do something with the client
$client->set_blocking( 0 );
while( $RUNNING ) {
$got = $client->read( $buf, 4096 );
if( ! defined $got ) {
# error
warn $client->error;
last;
}
elsif( ! $got ) {
# no data available, sleep for a while
$client->wait( 10 );
next;
}
print "Got $got bytes from client\n";
$client->write( 'thank you!' );
}
# close the client and free allocated resources
$client->wait( 50 );
$client->free();
# detach thread
threads->self->detach() if $RUNNING;
return 1;
}XS / C API
The module provides a C interface for extension writers.
Example XS
#include <mod_sc.h>
/* global pointer to the socket class interface */
mod_sc_t *g_mod_sc;
MODULE = MyModule PACKAGE = MyModule
BOOT:
{
SV **psv;
psv = hv_fetch(PL_modglobal, "Socket::Class", 13, 0);
if (psv == NULL)
croak("Socket::Class 2.0 or higher required");
g_mod_sc = INT2PTR(mod_sc_t *, SvIV(*psv));
}
void
test()
PREINIT:
sc_t *socket;
char *args[4];
int r;
SV *sv;
PPCODE:
args[0] = "local_port";
args[1] = "8080";
args[2] = "listen";
args[3] = "10";
r = g_mod_sc->sc_create(args, 4, &socket);
if (r != SC_OK)
croak(g_mod_sc->sc_get_error(NULL));
g_mod_sc->sc_create_class(socket, NULL, &sv);
ST(0) = sv_2mortal(sv);
XSRETURN(1);See mod_sc.h for the definition and the source code of Class.xs for an implementation.
Use Socket::Class::include_path() to get the path to mod_sc.h.
AUTHORS
Christian Mueller, http://www.alien-heads.org/
COPYRIGHT AND LICENSE
The Socket::Class module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.