---
name: "Socket"
section: "3cc"
platform: "linux"
package: "libcommoncpp2-dev"
version: "1.0.13-5"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/Socket"
---

# Socket(3cc)

The Socket is used as the base for all Internet protocol services under Common C++. base class of all sockets.

## NAME

Socket - The Socket is used as the base for all Internet protocol services under Common C++. base class of all sockets.

## SYNOPSIS

`#include <socket.h>`

Inherited by **SocketPort**, **TCPSocket**` [protected]`, **TCPStream**, **UDPSocket**, **UnixSocket**` [protected]`, and **UnixStream**.

### Public Types

typedef enum Error **Error**\
 typedef enum Tos **Tos**\
 typedef enum Pending **Pending**\
 enum **Error** { **errSuccess** =  0, **errCreateFailed**, **errCopyFailed**, **errInput**, **errInputInterrupt**, **errResourceFailure**, **errOutput**, **errOutputInterrupt**, **errNotConnected**, **errConnectRefused**, **errConnectRejected**, **errConnectTimeout**, **errConnectFailed**, **errConnectInvalid**, **errConnectBusy**, **errConnectNoRoute**, **errBindingFailed**, **errBroadcastDenied**, **errRoutingDenied**, **errKeepaliveDenied**, **errServiceDenied**, **errServiceUnavailable**, **errMulticastDisabled**, **errTimeout**, **errNoDelay**, **errExtended** }\
 enum **Tos** { **tosLowDelay** =  0, **tosThroughput**, **tosReliability**, **tosMinCost**, **tosInvalid** }\
 enum **Pending** { **pendingInput**, **pendingOutput**, **pendingError** }\

### Public Methods

virtual **~Socket** ()\
 *The socket base class may be 'thrown' as a result of an error, and the 'catcher' may then choose to destroy the object.* Socket & **operator=** (const Socket &from)\
 *Sockets may also be duplicated by the assignment operator.* **InetHostAddress** **getSender** (**tpport\_t** \*port=NULL) const\
 *May be used to examine the origin of data waiting in the socket receive queue.* **InetHostAddress** **getPeer** (**tpport\_t** \*port=NULL) const\
 *Get the host address and port of the socket this socket is connected to.* **InetHostAddress** **getLocal** (**tpport\_t** \*port=NULL) const\
 *Get the local address and port number this socket is currently bound to.* void **setCompletion** (bool immediate)\
 *Used to specify blocking mode for the socket.* **Error** **setLinger** (bool **linger**)\
 *Enable lingering sockets on close.* **Error** **setKeepAlive** (bool enable)\
 *Set the keep-alive status of this socket and if keep-alive messages will be sent.* **Error** **setTypeOfService** (**Tos** service)\
 *Set packet scheduling on platforms which support ip quality of service conventions.* bool **isConnected** (void) const\
 *Can test to see if this socket is 'connected', and hence whether a 'catch' can safely call* **getPeer()***.* bool **isActive** (void) const\
 *Test to see if the socket is at least operating or if it is mearly initialized.* bool **operator!** () const\
 *Operator based testing to see if a socket is currently active.* bool **isBroadcast** (void) const\
 *Return if broadcast has been enabled for the specified socket.* bool **isRouted** (void) const\
 *Return if socket routing is enabled.* **Error** **getErrorNumber** (void) const\
 *Often used by a 'catch' to fetch the last error of a thrown socket.* const char \* **getErrorString** (void) const\
 *Often used by a 'catch' to fetch the user set error string of a thrown socket, but only if EXTENDED error codes are used.* virtual bool **isPending** (**Pending** pend, **timeout\_t** timeout=TIMEOUT\_INF)\
 *Get the status of pending operations.*

### Protected Types

typedef enum State **State**\
 enum **State** { **INITIAL**, **AVAILABLE**, **BOUND**, **CONNECTED**, **CONNECTING**, **STREAM** }\

### Protected Methods

**Error** **error** (**Error** error, char \*errstr=NULL) const\
 *This service is used to throw all socket errors which usually occur during the socket constructor.* void **error** (char \*errstr) const\
 *This service is used to throw application defined socket errors where the application specific error code is a string.* void **setError** (bool enable)\
 *This service is used to turn the error handler on or off for 'throwing' exceptions by manipulating the thrown flag.* void **endSocket** (void)\
 *Used as the default destructor for ending a socket.* **Error** **connectError** (void)\
 *Used as a common handler for connection failure processing.* **Error** **setBroadcast** (bool enable)\
 *Set the subnet broadcast flag for the socket.* **Error** **setMulticast** (bool enable)\
 *Setting multicast binds the multicast interface used for the socket to the interface the socket itself has been implicitly bound to.* **Error** **setLoopback** (bool enable)\
 *Set the multicast loopback flag for the socket.* **Error** **setTimeToLive** (unsigned char **ttl**)\
 *Set the multicast time to live for a multicast socket.* **Error** **join** (const **InetMcastAddress** &ia)\
 *Join a multicast group.* **Error** **drop** (const **InetMcastAddress** &ia)\
 *Drop membership from a multicast group.* **Error** **setRouting** (bool enable)\
 *Set the socket routing to indicate if outgoing messages should bypass normal routing (set false).* **Error** **setNoDelay** (bool enable)\
 *Enable/disable delaying packets (Nagle algorithm).* **Socket** (int domain, int type, int protocol=0)\
 *An unconnected socket may be created directly on the local machine.* **Socket** (**SOCKET** fd)\
 *A socket object may be created from a file descriptor when that descriptor was created either through a socket() or accept() call.* **Socket** (const Socket &source)\
 *A socket can also be constructed from an already existing Socket object.* ssize\_t **readLine** (char \*buf, size\_t len, **timeout\_t** timeout=0)\
 **Process** *a logical input line from a socket descriptor directly.* virtual ssize\_t **readData** (void \*buf, size\_t len, char separator=0, **timeout\_t** t=0)\
 *Read in a block of len bytes with specific separator.* virtual ssize\_t **writeData** (const void \*buf, size\_t len, **timeout\_t** t=0)\
 *Write a block of len bytes to socket.*

### Protected Attributes

struct {\
    bool **thrown**: 1\
    bool **broadcast**: 1\
    bool **route**: 1\
    bool **keepalive**: 1\
    bool **loopback**: 1\
    bool **multicast**: 1\
    bool **completion**: 1\
    bool **linger**: 1\
    unsigned **ttl**: 8\
 } **flags**\
\
 **SOCKET** **so**\
 *the actual socket descriptor, in Windows, unlike posix it \*cannot\* be used as an file descriptor that way madness lies -- jfc* **State** **state**\

### Friends

**SOCKET** **dupSocket** (**SOCKET** s, **Socket::State** **state**)\

## DETAILED DESCRIPTION

The Socket is used as the base for all Internet protocol services under Common C++. base class of all sockets.

A socket is a system resource (or winsock descriptor) that occupies a specific port address (and may be bound to a specific network interface) on the local machine. The socket may also be directly connected to a specific socket on a remote internet host.

This base class is not directly used, but is provided to offer properties common to other Common C++ socket classes, including the socket exception model and the ability to set socket properties such as QoS, 'sockopts' properties like Dont-Route and Keep-Alive, etc.

**Author:**  David Sugar \<dyfet@ostel.com\>

## MEMBER TYPEDEF DOCUMENTATION

### typedef enum Error Socket::Error

Reimplemented in **URLStream**.

### typedef enum Pending Socket::Pending

### typedef enum State Socket::State` [protected]`

### typedef enum Tos Socket::Tos

## MEMBER ENUMERATION DOCUMENTATION

### enum Socket::Error

**Enumeration values:**

- *errSuccess*

  - *errCreateFailed*

  - *errCopyFailed*

  - *errInput*

  - *errInputInterrupt*

  - *errResourceFailure*

  - *errOutput*

  - *errOutputInterrupt*

  - *errNotConnected*

  - *errConnectRefused*

  - *errConnectRejected*

  - *errConnectTimeout*

  - *errConnectFailed*

  - *errConnectInvalid*

  - *errConnectBusy*

  - *errConnectNoRoute*

  - *errBindingFailed*

  - *errBroadcastDenied*

  - *errRoutingDenied*

  - *errKeepaliveDenied*

  - *errServiceDenied*

  - *errServiceUnavailable*

  - *errMulticastDisabled*

  - *errTimeout*

  - *errNoDelay*

  - *errExtended*

  *Reimplemented in* **URLStream***.*

### enum Socket::Pending

**Enumeration values:**

- *pendingInput*

  - *pendingOutput*

  - *pendingError*

  ### enum Socket::State` [protected]`

**Enumeration values:**

- *INITIAL*

  - *AVAILABLE*

  - *BOUND*

  - *CONNECTED*

  - *CONNECTING*

  - *STREAM*

  ### enum Socket::Tos

**Enumeration values:**

- *tosLowDelay*

  - *tosThroughput*

  - *tosReliability*

  - *tosMinCost*

  - *tosInvalid*

  ## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### Socket::Socket (int domain, int type, int protocol = 0)` [protected]`

*An unconnected socket may be created directly on the local machine.*

*Sockets can occupy both the internet domain (AF\_INET) and UNIX socket domain (AF\_UNIX) under unix. The socket type (SOCK\_STREAM, SOCK\_DGRAM) and protocol may also be specified. If the socket cannot be created, an exception is thrown.*

**Parameters:**

- *domain*

  *socket domain to use.*

- *type*

  *base type and protocol family of the socket.*

- *protocol*

  *specific protocol to apply.*

### Socket::Socket (SOCKET fd)` [protected]`

*A socket object may be created from a file descriptor when that descriptor was created either through a socket() or accept() call.*

*This constructor is mostly for internal use.*

**Parameters:**

- *fd*

  *file descriptor of an already existing socket.*

### Socket::Socket (const Socket & source)` [protected]`

*A socket can also be constructed from an already existing Socket object.*

*On POSIX systems, the socket file descriptor is dup()'d. On Win32, DuplicateHandle() is used.*

**Parameters:**

- *source*

  *of existing socket to clone.*

### virtual Socket::~Socket ()` [virtual]`

*The socket base class may be 'thrown' as a result of an error, and the 'catcher' may then choose to destroy the object.*

*By assuring the socket base class is a virtual destructor, we can assure the full object is properly terminated.*

## MEMBER FUNCTION DOCUMENTATION

### Error Socket::connectError (void)` [protected]`

*Used as a common handler for connection failure processing.*

**Returns:**  *correct failure code to apply.*

### Error Socket::drop (const InetMcastAddress & ia)` [protected]`

*Drop membership from a multicast group.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *ia*

  *address of multicast group to drop.*

*Reimplemented in* **UDPReceive***.*

### void Socket::endSocket (void)` [protected]`

*Used as the default destructor for ending a socket.*

*This will cleanly terminate the socket connection. It is provided for use in derived virtual destructors.*

### void Socket::error (char \* errstr) const` [inline, protected]`

*This service is used to throw application defined socket errors where the application specific error code is a string.*

**Parameters:**

- *errstr*

  *string or message to pass.*

### Error Socket::error (Error error, char \* errstr = NULL) const` [protected]`

*This service is used to throw all socket errors which usually occur during the socket constructor.*

**Parameters:**

- *error*

  *defined socket error id.*

- *errstr*

  *string or message to pass.*

### Error Socket::getErrorNumber (void) const` [inline]`

*Often used by a 'catch' to fetch the last error of a thrown socket.*

**Returns:**  *error number of Error error.*

### const char\* Socket::getErrorString (void) const` [inline]`

*Often used by a 'catch' to fetch the user set error string of a thrown socket, but only if EXTENDED error codes are used.*

**Returns:**  *string for error message.*

### InetHostAddress Socket::getLocal (tpport\_t \* port = NULL) const

*Get the local address and port number this socket is currently bound to.*

**Parameters:**

- *port*

  *ptr to port number on local host.*

**Returns:**  *host address of interface this socket is bound to.*

*Reimplemented in* **TCPSocket***.*

### InetHostAddress Socket::getPeer (tpport\_t \* port = NULL) const

*Get the host address and port of the socket this socket is connected to.*

*If the socket is currently not in a connected state, then a host address of 0.0.0.0 is returned.*

**Parameters:**

- *port*

  *ptr to port number of remote socket.*

**Returns:**  *host address of remote socket.*

*Reimplemented in* **UDPSocket***.*

### InetHostAddress Socket::getSender (tpport\_t \* port = NULL) const

*May be used to examine the origin of data waiting in the socket receive queue.*

*This can tell a TCP server where pending 'connect' requests are coming from, or a UDP socket where it's next packet arrived from.*

**Parameters:**

- *port*

  *ptr to port number of sender.*

**Returns:**  *host address, test with 'isInetAddress()'.*

### bool Socket::isActive (void) const

*Test to see if the socket is at least operating or if it is mearly initialized.*

**Returns:**  *true if not in initial state.*

### bool Socket::isBroadcast (void) const` [inline]`

*Return if broadcast has been enabled for the specified socket.*

**Returns:**  *true if broadcast socket.*

### bool Socket::isConnected (void) const

*Can test to see if this socket is 'connected', and hence whether a 'catch' can safely call* **getPeer()***.*

*Of course, an unconnected socket will return a 0.0.0.0 address from* **getPeer()** *as well.*

**Returns:**  *true when socket is connected to a peer.*

### virtual bool Socket::isPending (Pending pend, timeout\_t timeout = TIMEOUT\_INF)` [virtual]`

*Get the status of pending operations.*

*This can be used to examine if input or output is waiting, or if an error has occured on the descriptor.*

**Returns:**  *true if ready, false on timeout.*

**Parameters:**

- *pend*

  *ready check to perform.*

- *timeout*

  *in milliseconds, inf. if not specified.*

*Reimplemented in* **TCPStream***, and* **UnixStream***.*

### bool Socket::isRouted (void) const` [inline]`

*Return if socket routing is enabled.*

**Returns:**  *true if routing enabled.*

### Error Socket::join (const InetMcastAddress & ia)` [protected]`

*Join a multicast group.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *ia*

  *address of multicast group to join.*

*Reimplemented in* **UDPReceive***.*

### bool Socket::operator! ()

*Operator based testing to see if a socket is currently active.*

*Reimplemented in* **tcpstream***, and* **unixstream***.*

### Socket& Socket::operator= (const Socket & from)

*Sockets may also be duplicated by the assignment operator.*

### virtual ssize\_t Socket::readData (void \* buf, size\_t len, char separator = 0, timeout\_t t = 0)` [protected, virtual]`

*Read in a block of len bytes with specific separator.*

*Can be zero, or any other char. If* \
\
  *or \\r, it's treated just like a* **readLine()***. Otherwise it looks for the separator.*

**Parameters:**

- *pointer*

  *to byte allocation.*

- *maximum*

  *length to read.*

- *timeout*

  *for pending data in milliseconds.*

- *separator*

  *for a particular ASCII character*

**Returns:**  *number of bytes actually read.*

### ssize\_t Socket::readLine (char \* buf, size\_t len, timeout\_t timeout = 0)` [protected]`

**Process** *a logical input line from a socket descriptor directly.*

**Parameters:**

- *buf*

  *pointer to string.*

- *len*

  *maximum length to read.*

- *timeout*

  *for pending data in milliseconds.*

**Returns:**  *number of bytes actually read.*

### Error Socket::setBroadcast (bool enable)` [protected]`

*Set the subnet broadcast flag for the socket.*

*This enables sending to a subnet and may require special image privileges depending on the operating system.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *enable*

  *when set to true.*

*Reimplemented in* **UDPTransmit***.*

### void Socket::setCompletion (bool immediate)

*Used to specify blocking mode for the socket.*

*A socket can be made non-blocking by setting setCompletion(false) or set to block on all access with setCompletion(true). I do not believe this form of non-blocking socket I/O is supported in winsock, though it provides an alternate asynchronous set of socket services.*

**Parameters:**

- *immediate*

  *mode specify socket I/O call blocking mode.*

### void Socket::setError (bool enable)` [inline, protected]`

*This service is used to turn the error handler on or off for 'throwing' exceptions by manipulating the thrown flag.*

**Parameters:**

- *enable*

  *true to enable handler.*

### Error Socket::setKeepAlive (bool enable)

*Set the keep-alive status of this socket and if keep-alive messages will be sent.*

**Returns:**  *0 on success.*

**Parameters:**

- *enable*

  *keep alive messages.*

### Error Socket::setLinger (bool linger)

*Enable lingering sockets on close.*

**Parameters:**

- *linger*

  *specify linger enable.*

### Error Socket::setLoopback (bool enable)` [protected]`

*Set the multicast loopback flag for the socket.*

*Loopback enables a socket to hear what it is sending.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *enable*

  *when set to true.*

### Error Socket::setMulticast (bool enable)` [protected]`

*Setting multicast binds the multicast interface used for the socket to the interface the socket itself has been implicitly bound to.*

*It is also used as a check flag to make sure multicast is enabled before multicast operations are used.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *enable*

  *when set to true.*

*Reimplemented in* **UDPTransmit***, and* **UDPReceive***.*

### Error Socket::setNoDelay (bool enable)` [protected]`

*Enable/disable delaying packets (Nagle algorithm).*

**Returns:**  *0 on success.*

**Parameters:**

- *enable*

  *disable Nagle algorithm when set to true.*

### Error Socket::setRouting (bool enable)` [protected]`

*Set the socket routing to indicate if outgoing messages should bypass normal routing (set false).*

**Returns:**  *0 on success.*

**Parameters:**

- *enable*

  *normal routing when set to true.*

*Reimplemented in* **UDPTransmit***, and* **UDPReceive***.*

### Error Socket::setTimeToLive (unsigned char ttl)` [protected]`

*Set the multicast time to live for a multicast socket.*

**Returns:**  *0 (errSuccess) on success, else error code.*

**Parameters:**

- *ttl*

  *time to live.*

*Reimplemented in* **UDPTransmit***.*

### Error Socket::setTypeOfService (Tos service)

*Set packet scheduling on platforms which support ip quality of service conventions.*

*This effects how packets in the queue are scheduled through the interface.*

**Returns:**  *0 on success, error code on failure.*

**Parameters:**

- *service*

  *type of service enumerated type.*

*Reimplemented in* **UDPTransmit***.*

### virtual ssize\_t Socket::writeData (const void \* buf, size\_t len, timeout\_t t = 0)` [protected, virtual]`

*Write a block of len bytes to socket.*

**Parameters:**

- *pointer*

  *to byte allocation.*

- *maximum*

  *length to write.*

- *timeout*

  *for pending data in milliseconds.*

**Returns:**  *number of bytes actually read.*

## FRIENDS AND RELATED FUNCTION DOCUMENTATION

### SOCKET dupSocket (SOCKET s, Socket::State state)` [friend]`

## MEMBER DATA DOCUMENTATION

### bool Socket::broadcast` [protected]`

### bool Socket::completion` [protected]`

### struct { ... } Socket::flags` [protected]`

### bool Socket::keepalive` [protected]`

### bool Socket::linger` [protected]`

### bool Socket::loopback` [protected]`

### bool Socket::multicast` [protected]`

### bool Socket::route` [protected]`

### SOCKET Socket::so` [protected]`

*the actual socket descriptor, in Windows, unlike posix it \*cannot\* be used as an file descriptor that way madness lies -- jfc*

### State Socket::state` [protected]`

### bool Socket::thrown` [protected]`

### unsigned Socket::ttl` [protected]`

## AUTHOR

*Generated automatically by Doxygen for CommonC++ from the source code.*