OpenEuphoria

8.34 Core Sockets

8.34.1 Error Information

8.34.1.1 error_code

include std/socket.e
namespace sockets
public function error_code()

Get the error code.

Returns:

Integer OK on no error, otherwise any one of the ERR_ constants to follow.

8.34.1.2 OK

include std/socket.e
namespace sockets
public constant OK

No error occurred.

8.34.1.3 ERR_ACCESS

include std/socket.e
namespace sockets
public constant ERR_ACCESS

Permission has been denied. This can happen when using a send_to call on a broadcast address without setting the socket option SO_BROADCAST. Another, possibly more common, reason is you have tried to bind an address that is already exclusively bound by another application.

May occur on a Unix Domain Socket when the socket directory or file could not be accessed due to security.

8.34.1.4 ERR_ADDRINUSE

include std/socket.e
namespace sockets
public constant ERR_ADDRINUSE

Address is already in use.

8.34.1.5 ERR_ADDRNOTAVAIL

include std/socket.e
namespace sockets
public constant ERR_ADDRNOTAVAIL

The specified address is not a valid local IP address on this computer.

8.34.1.6 ERR_AFNOSUPPORT

include std/socket.e
namespace sockets
public constant ERR_AFNOSUPPORT

Address family not supported by the protocol family.

8.34.1.7 ERR_AGAIN

include std/socket.e
namespace sockets
public constant ERR_AGAIN

Kernel resources to complete the request are temporarly unavailable.

8.34.1.8 ERR_ALREADY

include std/socket.e
namespace sockets
public constant ERR_ALREADY

Operation is already in progress.

8.34.1.9 ERR_CONNABORTED

include std/socket.e
namespace sockets
public constant ERR_CONNABORTED

Software has caused a connection to be aborted.

8.34.1.10 ERR_CONNREFUSED

include std/socket.e
namespace sockets
public constant ERR_CONNREFUSED

Connection was refused.

8.34.1.11 ERR_CONNRESET

include std/socket.e
namespace sockets
public constant ERR_CONNRESET

An incomming connection was supplied however it was terminated by the remote peer.

8.34.1.12 ERR_DESTADDRREQ

include std/socket.e
namespace sockets
public constant ERR_DESTADDRREQ

Destination address required.

8.34.1.13 ERR_FAULT

include std/socket.e
namespace sockets
public constant ERR_FAULT

Address creation has failed internally.

8.34.1.14 ERR_HOSTUNREACH

include std/socket.e
namespace sockets
public constant ERR_HOSTUNREACH

No route to the host specified could be found.

8.34.1.15 ERR_INPROGRESS

include std/socket.e
namespace sockets
public constant ERR_INPROGRESS

A blocking call is inprogress.

8.34.1.16 ERR_INTR

include std/socket.e
namespace sockets
public constant ERR_INTR

A blocking call was cancelled or interrupted.

8.34.1.17 ERR_INVAL

include std/socket.e
namespace sockets
public constant ERR_INVAL

An invalid sequence of command calls were made, for instance trying to accept before an actual listen was called.

8.34.1.18 ERR_IO

include std/socket.e
namespace sockets
public constant ERR_IO

An I/O error occurred while making the directory entry or allocating the inode. (Unix Domain Socket).

8.34.1.19 ERR_ISCONN

include std/socket.e
namespace sockets
public constant ERR_ISCONN

Socket is already connected.

8.34.1.20 ERR_ISDIR

include std/socket.e
namespace sockets
public constant ERR_ISDIR

An empty pathname was specified. (Unix Domain Socket).

8.34.1.21 ERR_LOOP

include std/socket.e
namespace sockets
public constant ERR_LOOP

Too many symbolic links were encountered. (Unix Domain Socket).

8.34.1.22 ERR_MFILE

include std/socket.e
namespace sockets
public constant ERR_MFILE

The queue is not empty upon routine call.

8.34.1.23 ERR_MSGSIZE

include std/socket.e
namespace sockets
public constant ERR_MSGSIZE

Message is too long for buffer size. This would indicate an internal error to Euphoria as Euphoria sets a dynamic buffer size.

8.34.1.24 ERR_NAMETOOLONG

include std/socket.e
namespace sockets
public constant ERR_NAMETOOLONG

Component of the path name exceeded 255 characters or the entire path exceeded 1023 characters. (Unix Domain Socket).

8.34.1.25 ERR_NETDOWN

include std/socket.e
namespace sockets
public constant ERR_NETDOWN

The network subsystem is down or has failed

8.34.1.26 ERR_NETRESET

include std/socket.e
namespace sockets
public constant ERR_NETRESET

Network has dropped it's connection on reset.

8.34.1.27 ERR_NETUNREACH

include std/socket.e
namespace sockets
public constant ERR_NETUNREACH

Network is unreachable.

8.34.1.28 ERR_NFILE

include std/socket.e
namespace sockets
public constant ERR_NFILE

Not a file. (Unix Domain Sockets).

8.34.1.29 ERR_NOBUFS

include std/socket.e
namespace sockets
public constant ERR_NOBUFS

No buffer space is available.

8.34.1.30 ERR_NOENT

include std/socket.e
namespace sockets
public constant ERR_NOENT

Named socket does not exist. (Unix Domain Socket).

8.34.1.31 ERR_NOTCONN

include std/socket.e
namespace sockets
public constant ERR_NOTCONN

Socket is not connected.

8.34.1.32 ERR_NOTDIR

include std/socket.e
namespace sockets
public constant ERR_NOTDIR

Component of the path prefix is not a directory. (Unix Domain Socket).

8.34.1.33 ERR_NOTINITIALISED

include std/socket.e
namespace sockets
public constant ERR_NOTINITIALISED

Socket system is not initialized (Windows only)

8.34.1.34 ERR_NOTSOCK

include std/socket.e
namespace sockets
public constant ERR_NOTSOCK

The descriptor is not a socket.

8.34.1.35 ERR_OPNOTSUPP

include std/socket.e
namespace sockets
public constant ERR_OPNOTSUPP

Operation is not supported on this type of socket.

8.34.1.36 ERR_PROTONOSUPPORT

include std/socket.e
namespace sockets
public constant ERR_PROTONOSUPPORT

Protocol not supported.

8.34.1.37 ERR_PROTOTYPE

include std/socket.e
namespace sockets
public constant ERR_PROTOTYPE

Protocol is the wrong type for the socket.

8.34.1.38 ERR_ROFS

include std/socket.e
namespace sockets
public constant ERR_ROFS

The name would reside on a read-only file system. (Unix Domain Socket).

8.34.1.39 ERR_SHUTDOWN

include std/socket.e
namespace sockets
public constant ERR_SHUTDOWN

The socket has been shutdown. Possibly a send/receive call after a shutdown took place.

8.34.1.40 ERR_SOCKTNOSUPPORT

include std/socket.e
namespace sockets
public constant ERR_SOCKTNOSUPPORT

Socket type is not supported.

8.34.1.41 ERR_TIMEDOUT

include std/socket.e
namespace sockets
public constant ERR_TIMEDOUT

Connection has timed out.

8.34.1.42 ERR_WOULDBLOCK

include std/socket.e
namespace sockets
public constant ERR_WOULDBLOCK

The operation would block on a socket marked as non-blocking.

8.34.2 Socket Backend Constants

These values are used by the Euphoria backend to pass information to this library. The TYPE constants are used to identify to the info function which family of constants are being retrieved (AF protocols, socket types, and socket options, respectively).

8.34.2.1 ESOCK_UNDEFINED_VALUE

include std/socket.e
namespace sockets
public constant ESOCK_UNDEFINED_VALUE

when a particular constant was not defined by C,the backend returns this value

8.34.2.2 ESOCK_UNKNOWN_FLAG

include std/socket.e
namespace sockets
public constant ESOCK_UNKNOWN_FLAG

if the backend doesn't recognize the flag in question

8.34.2.3 ESOCK_TYPE_AF

include std/socket.e
namespace sockets
public constant ESOCK_TYPE_AF

8.34.2.4 ESOCK_TYPE_TYPE

include std/socket.e
namespace sockets
public constant ESOCK_TYPE_TYPE

8.34.2.5 ESOCK_TYPE_OPTION

include std/socket.e
namespace sockets
public constant ESOCK_TYPE_OPTION

8.34.3 Socket Type Euphoria Constants

These values are used to retrieve the known values for family and sock_type parameters of the create function from the Euphoria backend. (The reason for doing it this way is to retrieve the values defined in C, instead of duplicating them here.) These constants are guarranteed to never change, and to be the same value across platforms.

8.34.3.1 EAF_UNSPEC

include std/socket.e
namespace sockets
public constant EAF_UNSPEC

Address family is unspecified

8.34.3.2 EAF_UNIX

include std/socket.e
namespace sockets
public constant EAF_UNIX

Local communications

8.34.3.3 EAF_INET

include std/socket.e
namespace sockets
public constant EAF_INET

IPv4 Internet protocols

8.34.3.4 EAF_INET6

include std/socket.e
namespace sockets
public constant EAF_INET6

IPv6 Internet protocols

8.34.3.5 EAF_APPLETALK

include std/socket.e
namespace sockets
public constant EAF_APPLETALK

Appletalk

8.34.3.6 EAF_BTH

include std/socket.e
namespace sockets
public constant EAF_BTH

Bluetooth (currently Windows-only)

8.34.3.7 ESOCK_STREAM

include std/socket.e
namespace sockets
public constant ESOCK_STREAM

Provides sequenced, reliable, two-way, connection-based byte streams. An out-of-band data transmission mechanism may be supported.

8.34.3.8 ESOCK_DGRAM

include std/socket.e
namespace sockets
public constant ESOCK_DGRAM

Supports datagrams (connectionless, unreliable messages of a fixed maximum length).

8.34.3.9 ESOCK_RAW

include std/socket.e
namespace sockets
public constant ESOCK_RAW

Provides raw network protocol access.

8.34.3.10 ESOCK_RDM

include std/socket.e
namespace sockets
public constant ESOCK_RDM

Provides a reliable datagram layer that does not guarantee ordering.

8.34.3.11 ESOCK_SEQPACKET

include std/socket.e
namespace sockets
public constant ESOCK_SEQPACKET

Obsolete and should not be used in new programs

8.34.4 Socket Type Constants

These values are passed as the family and sock_type parameters of the create function. They are OS-dependent.

8.34.4.1 AF_UNSPEC

include std/socket.e
namespace sockets
public constant AF_UNSPEC

Address family is unspecified

8.34.4.2 AF_UNIX

include std/socket.e
namespace sockets
public constant AF_UNIX

Local communications

8.34.4.3 AF_INET

include std/socket.e
namespace sockets
public constant AF_INET

IPv4 Internet protocols

8.34.4.4 AF_INET6

include std/socket.e
namespace sockets
public constant AF_INET6

IPv6 Internet protocols

8.34.4.5 AF_APPLETALK

include std/socket.e
namespace sockets
public constant AF_APPLETALK

Appletalk

8.34.4.6 AF_BTH

include std/socket.e
namespace sockets
public constant AF_BTH

Bluetooth (currently Windows-only)

8.34.4.7 SOCK_STREAM

include std/socket.e
namespace sockets
public constant SOCK_STREAM

Provides sequenced, reliable, two-way, connection-based byte streams. An out-of-band data transmission mechanism may be supported.

8.34.4.8 SOCK_DGRAM

include std/socket.e
namespace sockets
public constant SOCK_DGRAM

Supports datagrams (connectionless, unreliable messages of a fixed maximum length).

8.34.4.9 SOCK_RAW

include std/socket.e
namespace sockets
public constant SOCK_RAW

Provides raw network protocol access.

8.34.4.10 SOCK_RDM

include std/socket.e
namespace sockets
public constant SOCK_RDM

Provides a reliable datagram layer that does not guarantee ordering.

8.34.4.11 SOCK_SEQPACKET

include std/socket.e
namespace sockets
public constant SOCK_SEQPACKET

Obsolete and should not be used in new programs

8.34.5 Select Accessor Constants

Use with the result of select.

8.34.5.1 SELECT_SOCKET

include std/socket.e
namespace sockets
public enum SELECT_SOCKET

The socket

8.34.5.2 SELECT_IS_READABLE

include std/socket.e
namespace sockets
public enum SELECT_IS_READABLE

Boolean (1/0) value indicating the readability.

8.34.5.3 SELECT_IS_WRITABLE

include std/socket.e
namespace sockets
public enum SELECT_IS_WRITABLE

Boolean (1/0) value indicating the writeability.

8.34.5.4 SELECT_IS_ERROR

include std/socket.e
namespace sockets
public enum SELECT_IS_ERROR

Boolean (1/0) value indicating the error state.

8.34.6 Shutdown Options

Pass one of the following to the method parameter of shutdown.

8.34.6.1 SD_SEND

include std/socket.e
namespace sockets
public constant SD_SEND

Shutdown the send operations.

8.34.6.2 SD_RECEIVE

include std/socket.e
namespace sockets
public constant SD_RECEIVE

Shutdown the receive operations.

8.34.6.3 SD_BOTH

include std/socket.e
namespace sockets
public constant SD_BOTH

Shutdown both send and receive operations.

8.34.7 Socket Options

Pass to the optname parameter of the functions get_option and set_option.

These options are highly OS specific and are normally not needed for most socket communication. They are provided here for your convenience. If you should need to set socket options, please refer to your OS reference material.

There may be other values that your OS defines and some defined here are not supported on all operating systems.

8.34.7.1 Socket Options In Common

8.34.7.2 SOL_SOCKET

include std/socket.e
namespace sockets
public constant SOL_SOCKET

8.34.7.3 SO_DEBUG

include std/socket.e
namespace sockets
public constant SO_DEBUG

8.34.7.4 SO_ACCEPTCONN

include std/socket.e
namespace sockets
public constant SO_ACCEPTCONN

8.34.7.5 SO_REUSEADDR

include std/socket.e
namespace sockets
public constant SO_REUSEADDR

8.34.7.6 SO_KEEPALIVE

include std/socket.e
namespace sockets
public constant SO_KEEPALIVE

8.34.7.7 SO_DONTROUTE

include std/socket.e
namespace sockets
public constant SO_DONTROUTE

8.34.7.8 SO_BROADCAST

include std/socket.e
namespace sockets
public constant SO_BROADCAST

8.34.7.9 SO_LINGER

include std/socket.e
namespace sockets
public constant SO_LINGER

8.34.7.10 SO_SNDBUF

include std/socket.e
namespace sockets
public constant SO_SNDBUF

8.34.7.11 SO_RCVBUF

include std/socket.e
namespace sockets
public constant SO_RCVBUF

8.34.7.12 SO_SNDLOWAT

include std/socket.e
namespace sockets
public constant SO_SNDLOWAT

8.34.7.13 SO_RCVLOWAT

include std/socket.e
namespace sockets
public constant SO_RCVLOWAT

8.34.7.14 SO_SNDTIMEO

include std/socket.e
namespace sockets
public constant SO_SNDTIMEO

8.34.7.15 SO_RCVTIMEO

include std/socket.e
namespace sockets
public constant SO_RCVTIMEO

8.34.7.16 SO_ERROR

include std/socket.e
namespace sockets
public constant SO_ERROR

8.34.7.17 SO_TYPE

include std/socket.e
namespace sockets
public constant SO_TYPE

8.34.7.18 SO_OOBINLINE

include std/socket.e
namespace sockets
public constant SO_OOBINLINE

8.34.7.19 Windows Socket Options

8.34.7.20 SO_USELOOPBACK

include std/socket.e
namespace sockets
public constant SO_USELOOPBACK

8.34.7.21 SO_DONTLINGER

include std/socket.e
namespace sockets
public constant SO_DONTLINGER

8.34.7.22 SO_REUSEPORT

include std/socket.e
namespace sockets
public constant SO_REUSEPORT

8.34.7.23 SO_CONNDATA

include std/socket.e
namespace sockets
public constant SO_CONNDATA

8.34.7.24 SO_CONNOPT

include std/socket.e
namespace sockets
public constant SO_CONNOPT

8.34.7.25 SO_DISCDATA

include std/socket.e
namespace sockets
public constant SO_DISCDATA

8.34.7.26 SO_DISCOPT

include std/socket.e
namespace sockets
public constant SO_DISCOPT

8.34.7.27 SO_CONNDATALEN

include std/socket.e
namespace sockets
public constant SO_CONNDATALEN

8.34.7.28 SO_CONNOPTLEN

include std/socket.e
namespace sockets
public constant SO_CONNOPTLEN

8.34.7.29 SO_DISCDATALEN

include std/socket.e
namespace sockets
public constant SO_DISCDATALEN

8.34.7.30 SO_DISCOPTLEN

include std/socket.e
namespace sockets
public constant SO_DISCOPTLEN

8.34.7.31 SO_OPENTYPE

include std/socket.e
namespace sockets
public constant SO_OPENTYPE

8.34.7.32 SO_MAXDG

include std/socket.e
namespace sockets
public constant SO_MAXDG

8.34.7.33 SO_MAXPATHDG

include std/socket.e
namespace sockets
public constant SO_MAXPATHDG

8.34.7.34 SO_SYNCHRONOUS_ALTERT

include std/socket.e
namespace sockets
public constant SO_SYNCHRONOUS_ALTERT

8.34.7.35 SO_SYNCHRONOUS_NONALERT

include std/socket.e
namespace sockets
public constant SO_SYNCHRONOUS_NONALERT

8.34.7.36 LINUX Socket Options

8.34.7.37 SO_SNDBUFFORCE

include std/socket.e
namespace sockets
public constant SO_SNDBUFFORCE

8.34.7.38 SO_RCVBUFFORCE

include std/socket.e
namespace sockets
public constant SO_RCVBUFFORCE

8.34.7.39 SO_NO_CHECK

include std/socket.e
namespace sockets
public constant SO_NO_CHECK

8.34.7.40 SO_PRIORITY

include std/socket.e
namespace sockets
public constant SO_PRIORITY

8.34.7.41 SO_BSDCOMPAT

include std/socket.e
namespace sockets
public constant SO_BSDCOMPAT

8.34.7.42 SO_PASSCRED

include std/socket.e
namespace sockets
public constant SO_PASSCRED

8.34.7.43 SO_PEERCRED

include std/socket.e
namespace sockets
public constant SO_PEERCRED

- Security levels - as per NRL IPv6 - don't actually do anything

8.34.7.44 SO_SECURITY_AUTHENTICATION

include std/socket.e
namespace sockets
public constant SO_SECURITY_AUTHENTICATION

8.34.7.45 SO_SECURITY_ENCRYPTION_TRANSPORT

include std/socket.e
namespace sockets
public constant SO_SECURITY_ENCRYPTION_TRANSPORT

8.34.7.46 SO_SECURITY_ENCRYPTION_NETWORK

include std/socket.e
namespace sockets
public constant SO_SECURITY_ENCRYPTION_NETWORK

8.34.7.47 SO_BINDTODEVICE

include std/socket.e
namespace sockets
public constant SO_BINDTODEVICE

8.34.7.48 LINUX Socket Filtering Options

8.34.7.49 SO_ATTACH_FILTER

include std/socket.e
namespace sockets
public constant SO_ATTACH_FILTER

8.34.7.50 SO_DETACH_FILTER

include std/socket.e
namespace sockets
public constant SO_DETACH_FILTER

8.34.7.51 SO_PEERNAME

include std/socket.e
namespace sockets
public constant SO_PEERNAME

8.34.7.52 SO_TIMESTAMP

include std/socket.e
namespace sockets
public constant SO_TIMESTAMP

8.34.7.53 SCM_TIMESTAMP

include std/socket.e
namespace sockets
public constant SCM_TIMESTAMP

8.34.7.54 SO_PEERSEC

include std/socket.e
namespace sockets
public constant SO_PEERSEC

8.34.7.55 SO_PASSSEC

include std/socket.e
namespace sockets
public constant SO_PASSSEC

8.34.7.56 SO_TIMESTAMPNS

include std/socket.e
namespace sockets
public constant SO_TIMESTAMPNS

8.34.7.57 SCM_TIMESTAMPNS

include std/socket.e
namespace sockets
public constant SCM_TIMESTAMPNS

8.34.7.58 SO_MARK

include std/socket.e
namespace sockets
public constant SO_MARK

8.34.7.59 SO_TIMESTAMPING

include std/socket.e
namespace sockets
public constant SO_TIMESTAMPING

8.34.7.60 SCM_TIMESTAMPING

include std/socket.e
namespace sockets
public constant SCM_TIMESTAMPING

8.34.7.61 SO_PROTOCOL

include std/socket.e
namespace sockets
public constant SO_PROTOCOL

8.34.7.62 SO_DOMAIN

include std/socket.e
namespace sockets
public constant SO_DOMAIN

8.34.7.63 SO_RXQ_OVFL

include std/socket.e
namespace sockets
public constant SO_RXQ_OVFL

8.34.8 Send Flags

Pass to the flags parameter of send and receive

8.34.8.1 MSG_OOB

include std/socket.e
namespace sockets
public constant MSG_OOB

Sends out-of-band data on sockets that support this notion (e.g., of type SOCK_STREAM); the underlying protocol must also support out-of-band data.

8.34.8.2 MSG_PEEK

include std/socket.e
namespace sockets
public constant MSG_PEEK

This flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data.

8.34.8.3 MSG_DONTROUTE

include std/socket.e
namespace sockets
public constant MSG_DONTROUTE

Don't use a gateway to send out the packet, only send to hosts on directly connected networks. This is usually used only by diagnostic or routing programs. This is only defined for protocol families that route; packet sockets don't.

8.34.8.4 MSG_TRYHARD

include std/socket.e
namespace sockets
public constant MSG_TRYHARD

8.34.8.5 MSG_CTRUNC

include std/socket.e
namespace sockets
public constant MSG_CTRUNC

indicates that some control data were discarded due to lack of space in the buffer for ancillary data.

8.34.8.6 MSG_PROXY

include std/socket.e
namespace sockets
public constant MSG_PROXY

8.34.8.7 MSG_TRUNC

include std/socket.e
namespace sockets
public constant MSG_TRUNC

indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.

8.34.8.8 MSG_DONTWAIT

include std/socket.e
namespace sockets
public constant MSG_DONTWAIT

Enables non-blocking operation; if the operation would block, EAGAIN or EWOULDBLOCK is returned.

8.34.8.9 MSG_EOR

include std/socket.e
namespace sockets
public constant MSG_EOR

Terminates a record (when this notion is supported, as for sockets of type SOCK_SEQPACKET).

8.34.8.10 MSG_WAITALL

include std/socket.e
namespace sockets
public constant MSG_WAITALL

This flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned.

8.34.8.11 MSG_FIN

include std/socket.e
namespace sockets
public constant MSG_FIN

8.34.8.12 MSG_SYN

include std/socket.e
namespace sockets
public constant MSG_SYN

8.34.8.13 MSG_CONFIRM

include std/socket.e
namespace sockets
public constant MSG_CONFIRM

Tell the link layer that forward progress happened: you got a successful reply from the other side. If the link layer doesn't get this it will regularly reprobe the neighbor (e.g., via a unicast ARP). Only valid on SOCK_DGRAM and SOCK_RAW sockets and currently only implemented for IPv4 and IPv6.

8.34.8.14 MSG_RST

include std/socket.e
namespace sockets
public constant MSG_RST

8.34.8.15 MSG_ERRQUEUE

include std/socket.e
namespace sockets
public constant MSG_ERRQUEUE

indicates that no data was received but an extended error from the socket error queue.

8.34.8.16 MSG_NOSIGNAL

include std/socket.e
namespace sockets
public constant MSG_NOSIGNAL

Requests not to send SIGPIPE on errors on stream oriented sockets when the other end breaks the connection. The EPIPE error is still returned.

8.34.8.17 MSG_MORE

include std/socket.e
namespace sockets
public constant MSG_MORE

The caller has more data to send. This flag is used with TCP sockets to obtain the same effect as the TCP_CORK socket option, with the difference that this flag can be set on a per-call basis.

8.34.9 Server and Client sides

8.34.9.1 SOCKET_SOCKET

include std/socket.e
namespace sockets
export enum SOCKET_SOCKET

Accessor index for socket handle of a socket type

8.34.9.2 SOCKET_SOCKADDR_IN

include std/socket.e
namespace sockets
export enum SOCKET_SOCKADDR_IN

Accessor index for the sockaddr_in pointer of a socket type

8.34.9.3 socket

include std/socket.e
namespace sockets
public type socket(object o)

Socket type

8.34.9.4 create

include std/socket.e
namespace sockets
public function create(integer family, integer sock_type, integer protocol)

Create a new socket

Parameters:

1. family: an integer
2. sock_type: an integer, the type of socket to create
3. protocol: an integer, the communication protocol being used

family options:

• AF_UNIX
• AF_INET
• AF_INET6
• AF_APPLETALK
• AF_BTH

sock_type options:

• SOCK_STREAM
• SOCK_DGRAM
• SOCK_RAW
• SOCK_RDM
• SOCK_SEQPACKET

Returns:

An object, an atom, representing an integer code on failure, else a sequence representing a valid socket id.

Comment:

On Windows, you must have Windows Sockets version 2.2 or greater installed. This means at least Windows 2000 Professional or Windows 2000 Server.

Example 1:

socket = create(AF_INET, SOCK_STREAM, 0)

8.34.9.5 close

include std/socket.e
namespace sockets
public function close(socket sock)

Closes a socket.

Parameters:

1. sock: the socket to close

Returns:

An integer, 0 on success and -1 on error.

Comments:

It may take several minutes for the OS to declare the socket as closed.

8.34.9.6 shutdown

include std/socket.e
namespace sockets
public function shutdown(socket sock, atom method = SD_BOTH)

Partially or fully close a socket.

Parameters:

1. sock : the socket to shutdown
2. method : the method used to close the socket

Returns:

An integer, 0 on success and -1 on error.

Comments:

Three constants are defined that can be sent to method:

• SD_SEND - shutdown the send operations.
• SD_RECEIVE - shutdown the receive operations.
• SD_BOTH - shutdown both send and receive operations.

It may take several minutes for the OS to declare the socket as closed.

8.34.9.7 select

include std/socket.e
namespace sockets
public function select(object sockets_read, object sockets_write, object sockets_err,
        integer timeout = 0, integer timeout_micro = 0)

Determine the read, write and error status of one or more sockets.

Using select, you can check to see if a socket has data waiting and is read to be read, if a socket can be written to and if a socket has an error status.

select allows for fine-grained control over your sockets, allow you to specify that a given socket only be checked for reading or for only reading and writing, etc.

Parameters:

1. sockets_read : either one socket or a sequence of sockets to check for reading.
2. sockets_write : either one socket or a sequence of sockets to check for writing.
3. sockets_err : either one socket or a sequence of sockets to check for errors.
4. timeout : maximum time to wait to determine a sockets status, seconds part
5. timeout_micro : maximum time to wait to determine a sockets status, microsecond part

Returns:

A sequence, of the same size of all unique sockets containing { socket, read_status, write_status, error_status } for each socket passed 2 to the function. Note that the sockets returned are not guaranteed to be in any particular order.

8.34.9.8 send

include std/socket.e
namespace sockets
public function send(socket sock, sequence data, atom flags = 0)

Send TCP data to a socket connected remotely.

Parameters:

1. sock : the socket to send data to
2. data : a sequence of atoms, what to send
3. flags : flags (see Send Flags)

Returns:

An integer, the number of characters sent, or -1 for an error.

8.34.9.9 receive

include std/socket.e
namespace sockets
public function receive(socket sock, atom flags = 0)

Receive data from a bound socket.

Parameters:

1. sock : the socket to get data from
2. flags : flags (see Send Flags)

Returns:

A sequence, either a full string of data on success, or an atom indicating the error code.

Comments:

This function will not return until data is actually received on the socket, unless the flags parameter contains MSG_DONTWAIT.

MSG_DONTWAIT only works on Linux kernels 2.4 and above. To be cross-platform you should use select to determine if a socket is readable, i.e. has data waiting.

8.34.9.10 get_option

include std/socket.e
namespace sockets
public function get_option(socket sock, integer level, integer optname)

Get options for a socket.

Parameters:

1. sock : the socket
2. level : an integer, the option level
3. optname : requested option (See Socket Options)

Returns:

An object, either:

• On error, {"ERROR",error_code}.
• On success, either an atom or a sequence containing the option value, depending on the option.

Comments:

Primarily for use in multicast or more advanced socket applications. Level is the option level, and option_name is the option for which values are being sought. Level is usually SOL_SOCKET.

Returns:

An atom, On error, an atom indicating the error code.
A sequence or atom, On success, either an atom or a sequence containing the option value.

See also:

get_option

8.34.9.11 set_option

include std/socket.e
namespace sockets
public function set_option(socket sock, integer level, integer optname, object val)

Set options for a socket.

Parameters:

1. sock : an atom, the socket id
2. level : an integer, the option level
3. optname : requested option (See Socket Options)
4. val : an object, the new value for the option

Returns:

An integer, 0 on success, -1 on error.

Comments:

Primarily for use in multicast or more advanced socket applications. Level is the option level, and option_name is the option for which values are being set. Level is usually SOL_SOCKET.

See Also:

get_option

8.34.10 Client side only

8.34.10.1 connect

include std/socket.e
namespace sockets
public function connect(socket sock, sequence address, integer port = - 1)

Establish an outgoing connection to a remote computer. Only works with TCP sockets.

Parameters:

1. sock : the socket
2. address : ip address to connect, optionally with :PORT at the end
3. port : port number

Returns:

An integer, 0 for success and non-zero on failure. See the ERR_* constants for supported values.

Comments:

address can contain a port number. If it does not, it has to be supplied to the port parameter.

Example 1:

success = connect(sock, "11.1.1.1") -- uses default port 80
success = connect(sock, "11.1.1.1:110") -- uses port 110
success = connect(sock, "11.1.1.1", 345) -- uses port 345

8.34.11 Server side only

8.34.11.1 bind

include std/socket.e
namespace sockets
public function bind(socket sock, sequence address, integer port = - 1)

Joins a socket to a specific local internet address and port so later calls only need to provide the socket.

Parameters:

1. sock : the socket
2. address : the address to bind the socket to
3. port : optional, if not specified you must include :PORT in the address parameter.

Returns:

An integer, 0 on success and -1 on failure.

Example 1:

-- Bind to all interfaces on the default port 80.
success = bind(socket, "0.0.0.0")
-- Bind to all interfaces on port 8080.
success = bind(socket, "0.0.0.0:8080")
-- Bind only to the 243.17.33.19 interface on port 345.
success = bind(socket, "243.17.33.19", 345)

8.34.11.2 listen

include std/socket.e
namespace sockets
public function listen(socket sock, integer backlog)

Start monitoring a connection. Only works with TCP sockets.

Parameters:

1. sock : the socket
2. backlog : the number of connection requests that can be kept waiting before the OS refuses to hear any more.

Returns:

An integer, 0 on success and an error code on failure.

Comments:

Once the socket is created and bound, this will indicate to the operating system that you are ready to being listening for connections.

The value of backlog is strongly dependent on both the hardware and the amount of time it takes the program to process each connection request.

This function must be executed after bind().

8.34.11.3 accept

include std/socket.e
namespace sockets
public function accept(socket sock)

Produces a new socket for an incoming connection.

Parameters:

1. sock: the server socket

Returns:

An atom, on error
A sequence, {socket client, sequence client_ip_address} on success.

Comments:

Using this function allows communication to occur on a "side channel" while the main server socket remains available for new connections.

accept() must be called after bind() and listen().

8.34.12 UDP only

8.34.12.1 send_to

include std/socket.e
namespace sockets
public function send_to(socket sock, sequence data, sequence address, integer port = - 1,
        atom flags = 0)

Send a UDP packet to a given socket

Parameters:

1. sock: the server socket
2. data: the data to be sent
3. ip: the ip where the data is to be sent to (ip:port) is acceptable
4. port: the port where the data is to be sent on (if not supplied with the ip)
5. flags : flags (see Send Flags)

Returns:

An integer status code.

See Also:

receive_from

8.34.12.2 receive_from

include std/socket.e
namespace sockets
public function receive_from(socket sock, atom flags = 0)

Receive a UDP packet from a given socket

Parameters:

1. sock: the server socket
2. flags : flags (see Send Flags)

Returns:

A sequence containing { client_ip, client_port, data } or an atom error code.

See Also:

send_to

8.34.13 Information

8.34.13.1 service_by_name

include std/socket.e
namespace sockets
public function service_by_name(sequence name, object protocol = 0)

Get service information by name.

Parameters:

1. name : service name.
2. protocol : protocol. Default is not to search by protocol.

Returns:

A sequence, containing { official protocol name, protocol, port number } or an atom indicating the error code.

Example 1:

object result = getservbyname("http")
-- result = { "http", "tcp", 80 }

See Also:

service_by_port

8.34.13.2 service_by_port

include std/socket.e
namespace sockets
public function service_by_port(integer port, object protocol = 0)

Get service information by port number.

Parameters:

1. port : port number.
2. protocol : protocol. Default is not to search by protocol.

Returns:

A sequence, containing { official protocol name, protocol, port number } or an atom indicating the error code.

Example 1:

object result = getservbyport(80)
-- result = { "http", "tcp", 80 }

See Also:

service_by_name

8.34.13.3 info

include std/socket.e
namespace sockets
public function info(integer Type)

Get constant definitions from the backend.

Parameters:

1. type : The type of information requested.

Returns:

A sequence, containing the list of definitions from the backend. The resulting list can be indexed into using the Euphoria constants. Or an atom indicating an error.

Example 1:

object result = info(ESOCK_TYPE_AF)
-- result = { AF_UNIX, AF_INET, AF_INET6, AF_APPLETALK, AF_BTH, AF_UNSPEC }

See Also:

Socket Options, Socket Backend Constants, Socket Type Euphoria Constants