EPICS Base
7.0.7.0
|
Platform independent socket support library API. More...
Go to the source code of this file.
Classes | |
union | osiSockAddr |
Union to switch between sockaddr_in and sockaddr. More... | |
struct | osiSockAddrNode |
Stores a list of socket addresses. More... | |
Enumerations | |
enum | epicsSocketSystemCallInterruptMechanismQueryInfo { esscimqi_socketCloseRequired, esscimqi_socketBothShutdownRequired, esscimqi_socketSigAlarmRequired } |
Enum specifying how to interrupt a blocking socket system call. More... | |
Functions | |
LIBCOM_API SOCKET epicsStdCall | epicsSocketCreate (int domain, int type, int protocol) |
Create a socket object. More... | |
LIBCOM_API int epicsStdCall | epicsSocketAccept (int sock, struct sockaddr *pAddr, osiSocklen_t *addrlen) |
Accept a connection on a listening stream socket. More... | |
LIBCOM_API void epicsStdCall | epicsSocketDestroy (SOCKET) |
Close and free resources held by a SOCKET object. More... | |
LIBCOM_API void epicsStdCall | epicsSocketEnableAddressReuseDuringTimeWaitState (SOCKET s) |
Allows a socket to bind ignoring other sockets in TIME_WAIT state. More... | |
LIBCOM_API void epicsStdCall | epicsSocketEnableAddressUseForDatagramFanout (SOCKET s) |
Allows multiple sockets to use the same family, local address, and local port. More... | |
LIBCOM_API enum epicsSocketSystemCallInterruptMechanismQueryInfo | epicsSocketSystemCallInterruptMechanismQuery () |
Query what approach to use to interrupt blocking socket calls. More... | |
LIBCOM_API unsigned epicsStdCall | sockAddrToA (const struct sockaddr *paddr, char *pBuf, unsigned bufSize) |
Convert socket address to ASCII. More... | |
LIBCOM_API unsigned epicsStdCall | ipAddrToA (const struct sockaddr_in *pInetAddr, char *pBuf, unsigned bufSize) |
Convert IP address to ASCII. More... | |
LIBCOM_API unsigned epicsStdCall | sockAddrToDottedIP (const struct sockaddr *paddr, char *pBuf, unsigned bufSize) |
Convert to raw dotted IP address with trailing port. More... | |
LIBCOM_API unsigned epicsStdCall | ipAddrToDottedIP (const struct sockaddr_in *paddr, char *pBuf, unsigned bufSize) |
Convert to raw dotted IP address with trailing port. More... | |
LIBCOM_API unsigned epicsStdCall | ipAddrToHostName (const struct in_addr *pAddr, char *pBuf, unsigned bufSize) |
Convert inet address to a host name string. More... | |
LIBCOM_API int epicsStdCall | aToIPAddr (const char *pAddrString, unsigned short defaultPort, struct sockaddr_in *pIP) |
Attempt to convert ASCII string to an IP address. More... | |
LIBCOM_API int epicsStdCall | hostToIPAddr (const char *pHostName, struct in_addr *pIPA) |
Attempt to convert ASCII host name string with optional port to an IP address. More... | |
LIBCOM_API int epicsStdCall | osiSockAttach (void) |
attach to BSD socket library More... | |
LIBCOM_API void epicsStdCall | osiSockRelease (void) |
release BSD socket library More... | |
LIBCOM_API void | epicsSocketConvertErrorToString (char *pBuf, unsigned bufSize, int error) |
convert socket error numbers to a string More... | |
LIBCOM_API void | epicsSocketConvertErrnoToString (char *pBuf, unsigned bufSize) |
Convert the currently set errno to a string. More... | |
LIBCOM_API int epicsStdCall | sockAddrAreIdentical (const osiSockAddr *plhs, const osiSockAddr *prhs) |
Compares two osiSockAddrs. More... | |
LIBCOM_API void epicsStdCall | osiSockDiscoverBroadcastAddresses (ELLLIST *pList, SOCKET socket, const osiSockAddr *pMatchAddr) |
Add available broadcast addresses to a list. More... | |
LIBCOM_API osiSockAddr epicsStdCall | osiLocalAddr (SOCKET socket) |
osiSock library contains platform independent APIs for creating sockets, converting between socket address structures and human readable strings, and configuring sockets.
Definition in file osiSock.h.
This enum specifies how to interrupt a blocking socket system call. Fortunately, on most systems the combination of a shutdown of both directions and/or a signal is sufficent to interrupt a blocking send, receive, or connect call. For odd ball systems this is stubbed out in the osi area.
LIBCOM_API SOCKET epicsStdCall epicsSocketCreate | ( | int | domain, |
int | type, | ||
int | protocol | ||
) |
Ask the operating system to create a socket and return its file descriptor.
domain | The socket domain, e.g. PF_INET |
type | The type of socket, e.g. SOCK_STREAM (tcp) or SOCK_DGRAM (udp) |
protocol | Typically unused and set to 0. |
LIBCOM_API int epicsStdCall epicsSocketAccept | ( | int | sock, |
struct sockaddr * | pAddr, | ||
osiSocklen_t * | addrlen | ||
) |
epicsSocketAccept is used with connection-based sockets. It takes the next connection request in the queue and returns a new socket that can be used to communicate with the listener.
sock | socket with pending connections to accept | |
pAddr | If not NULL, this socket contains the address of the peer whose connection is being accepted | |
[in,out] | addrlen | Caller must initialize this to the length of the structure pointed to by pAddr , or set to NULL if pAddr is NULL. This function will update the value of this parameter to the actual size of the peer address. |
LIBCOM_API void epicsStdCall epicsSocketDestroy | ( | SOCKET | ) |
Close and free resources held by a SOCKET object.
LIBCOM_API void epicsStdCall epicsSocketEnableAddressReuseDuringTimeWaitState | ( | SOCKET | s | ) |
Allows a socket to bind while other sockets hold the same address and port but are in the TIME_WAIT state. TIME_WAIT is a state where a socket has closed locally, but is waiting to be closed on the remote end. If the remote end doesn't respond, this can block another socket from binding to that address:port for a long time (possibly minutes). This option allows the socket to bind to an address:port combo, even if there's another socket with the same address:port that's waiting for the remote side to close its connection.
See also: Linux's SO_REUSEADDR in setsockopt.
s | The socket to ignore other TIME_WAIT sockets when binding |
LIBCOM_API void epicsStdCall epicsSocketEnableAddressUseForDatagramFanout | ( | SOCKET | s | ) |
Allows multiple sockets to use the same family, local address, and port. By having multiple sockets open with this setting enabled, the OS will distribute the datagrams (for UDP sockets) or connection requests (for TCP/stream sockets) among the sockets with this option set. Note that all sockets binding to the same address and port must have this option set.
As an example, this option could be a way to implement a form of load balancing between multiple threads or processes with sockets bound to the same address:port.
s | The socket to put in "Fanout" mode (aka REUSEPORT mode) |
LIBCOM_API enum epicsSocketSystemCallInterruptMechanismQueryInfo epicsSocketSystemCallInterruptMechanismQuery | ( | ) |
This function tells you what approach to use to interrupt calls blocked on socket operations.
LIBCOM_API unsigned epicsStdCall sockAddrToA | ( | const struct sockaddr * | paddr, |
char * | pBuf, | ||
unsigned | bufSize | ||
) |
Converts a socket address to an ASCII string. Conversion occurs in this order:
paddr | sockaddr structure to convert to ascii address:port | |
[out] | pBuf | Pointer to the output buffer contantaining the address:port string |
bufSize | Length of pBuf array |
LIBCOM_API unsigned epicsStdCall ipAddrToA | ( | const struct sockaddr_in * | pInetAddr, |
char * | pBuf, | ||
unsigned | bufSize | ||
) |
Convert an IP address to an ASCII string. Conversion occurs in this order: 1) look for matching host name and add trailing port 2) convert to raw dotted IP address with trailing port
pInetAddr | sockaddr_in structure to convert to address string | |
[out] | pBuf | Pointer to the char array where the address string will be stored |
bufSize | Length of the array to which pBuf points |
LIBCOM_API unsigned epicsStdCall sockAddrToDottedIP | ( | const struct sockaddr * | paddr, |
char * | pBuf, | ||
unsigned | bufSize | ||
) |
Convert an address to a raw dotted IP address. Compared to sockAddrToA(), this call will always convert to a raw dotted IP (e.g. 192.168.0.1) and not use host names (e.g. localhost) when available
paddr | sockaddr structure containing the node and service info to convert to strings | |
[out] | pBuf | Pointer to a character buffer where the output string will be placed. |
bufSize | Size of the array pointed to by pBuf |
LIBCOM_API unsigned epicsStdCall ipAddrToDottedIP | ( | const struct sockaddr_in * | paddr, |
char * | pBuf, | ||
unsigned | bufSize | ||
) |
Convert a sockaddr_in to a raw dotted IP address string with trailing port. Similar to sockAddrToDottedIP but takes a sockaddr_in structure.
paddr | sockaddr_in structure containing the node and service info to convert to strings | |
[out] | pBuf | Pointer to a character buffer where the output string will be placed |
bufSize | Size of the array pointed to by pBuf |
LIBCOM_API unsigned epicsStdCall ipAddrToHostName | ( | const struct in_addr * | pAddr, |
char * | pBuf, | ||
unsigned | bufSize | ||
) |
Convert an inet address to a host name string. There are many OS specific implementation stubs for this routine
pAddr | sockaddr_in structure containing the node and service info to convert to strings | |
[out] | pBuf | Pointer to a character buffer where the output string will be placed |
bufSize | Size of the array pointed to by pBuf |
LIBCOM_API int epicsStdCall aToIPAddr | ( | const char * | pAddrString, |
unsigned short | defaultPort, | ||
struct sockaddr_in * | pIP | ||
) |
Attempt to convert ASCII string to an IP address. Conversion occurs this order:
pAddrString | IP address string to convert to a sockaddr_in (e.g. "192.168.0.1:80") | |
defaultPort | The default port (service) to use if not specified in pAddrString | |
[out] | pIP | Pointer to a sockaddr_in where the converted address info will be stored |
LIBCOM_API int epicsStdCall hostToIPAddr | ( | const char * | pHostName, |
struct in_addr * | pIPA | ||
) |
Convert an in_addr struct to a human readable hostname.
pHostName | ASCII host name to convert | |
[out] | pIPA | Pointer to the in_addr structure where the hostname information will be stored |
LIBCOM_API int epicsStdCall osiSockAttach | ( | void | ) |
Attach to the BSD socket library in preparation for using sockets. If the OS does not require attaching to the socket library, this function does nothing.
LIBCOM_API void epicsStdCall osiSockRelease | ( | void | ) |
Release the BSD socket library if the OS requires it. For platforms that do not require attaching and releasing to use the socket library, this function does nothing.
LIBCOM_API void epicsSocketConvertErrorToString | ( | char * | pBuf, |
unsigned | bufSize, | ||
int | error | ||
) |
There are several system functions which set errno on failure. This function converts that error number into a string describing the error.
[out] | pBuf | Pointer to char array where the error string will be stored |
bufSize | Length of the array pointed to by pBuf | |
error | The error number to describe in string form |
LIBCOM_API void epicsSocketConvertErrnoToString | ( | char * | pBuf, |
unsigned | bufSize | ||
) |
errno is a global integer that gets set when certain functions return an error. This function converts that error value into a string describing the error.
[out] | pBuf | Pointer to char array where the error string will be stored |
bufSize | Length of the array pointed to by pBuf |
LIBCOM_API int epicsStdCall sockAddrAreIdentical | ( | const osiSockAddr * | plhs, |
const osiSockAddr * | prhs | ||
) |
Compares two osiSockAddrs
LIBCOM_API void epicsStdCall osiSockDiscoverBroadcastAddresses | ( | ELLLIST * | pList, |
SOCKET | socket, | ||
const osiSockAddr * | pMatchAddr | ||
) |
Add available broadcast addresses to a list. This routine is provided with the address of an ELLLIST, a socket, and a match address. When the routine returns there will be one additional entry in the list for each network interface found that is up and isn't a loop back interface (match addr is INADDR_ANY), or only the interfaces that match the specified addresses (match addr is other than INADDR_ANY). If the interface supports broadcasting then add its broadcast address to the list. If the interface is a point to point link then add the destination address of the point to point link to the list.
Any mutex locking required to protect pList is applied externally.
[out] | pList | Pointer to a list where network interfaces will be added as new osiSockAddrNode's |
socket | (May be unused) | |
pMatchAddr | Only add addresses that match this address. Use match.ia.sin_addr.s_addr = htonl(INADDR_ANY) to match any address. |
LIBCOM_API osiSockAddr epicsStdCall osiLocalAddr | ( | SOCKET | socket | ) |
Returns the osiSockAddr of the first non-loopback interface found that is operational (up flag is set). If no valid address can be located then return an osiSockAddr with the address family set to unspecified (AF_UNSPEC).
Unfortunately in EPICS 3.13 beta 11 and before the CA repeater would not always allow the loopback address as a local client address so current clients alternate between the address of the first non-loopback interface found and the loopback address when subscribing with the CA repeater until all CA repeaters have been updated to current code.