Socket Services
[CONNECT]

Collaboration diagram for Socket Services:

Classes
struct	SSOCK_Poll
struct	SPOLLABLE_Poll
class	CPollable
class	CTrigger
	CTrigger::. More...
class	CSocket
	CSocket::. More...
class	CDatagramSocket
	CDatagramSocket::. More...
class	CListeningSocket
	CListeningSocket::. More...
class	CSocketAPI
	CSocketAPI::. More...
class	CUNIXSocket
class	CUNIXListeningSocket
Defines
#define	SOCK_NetToHostLong   SOCK_HostToNetLong
#define	SOCK_NetToHostShort   SOCK_HostToNetShort
#define	NCBI_SOCK_DEPRECATED
#define	SOCK_ntohl   SOCK_htonl
#define	SOCK_ntohs   SOCK_htons
Typedefs
typedef LSOCK_tag *	LSOCK
typedef SOCK_tag *	SOCK
typedef TRIGGER_tag *	TRIGGER
typedef unsigned int	TSOCK_Flags
typedef SPOLLABLE_tag *	POLLABLE
typedef const struct SOCKSSL_struct *	SOCKSSL
typedef SOCKSSL(*	FSSLSetup )(void)
Enumerations
enum	ENH_ByteOrder { eNH_HostByteOrder, eNH_NetworkByteOrder }
	Network and host byte order enumeration type. More...
enum	ESOCK_Flags {   fSOCK_LogOff = eOff, fSOCK_LogOn = eOn, fSOCK_LogDefault = eDefault, fSOCK_BindAny = 0,   fSOCK_BindLocal = 0x10, fSOCK_KeepOnExec = 0x20, fSOCK_CloseOnExec = 0, fSOCK_Secure = 0x40,   fSOCK_KeepOnClose = 0x80, fSOCK_CloseOnClose = 0, fSOCK_ReadOnWrite = 0x100, fSOCK_InterruptOnSignal = 0x200 }
enum	ELSCE_Flags {   fLSCE_LogOff = fSOCK_LogOff, fLSCE_LogOn = fSOCK_LogOn, fLSCE_LogDefault = fSOCK_LogDefault, fLSCE_BindAny = fSOCK_BindAny,   fLSCE_BindLocal = fSOCK_BindLocal, fLSCE_CloseOnExec = fSOCK_CloseOnExec }
enum	ESCOT_OnClose { eSCOT_KeepOnClose = fSOCK_KeepOnClose, eSCOT_CloseOnClose = fSOCK_CloseOnClose }
	SOCK_Close behavior for SOCKs created on top of OS handles. More...
enum	ECopyTimeout { eCopyTimeoutsFromSOCK, eCopyTimeoutsToSOCK }
Functions
SOCKSSL	NcbiSetupGnuTls (void)
ESwitch	SOCK_SetDataLoggingAPI (ESwitch log)
	By default ("log" == eDefault, which is eOff), data are not logged.
ESwitch	SOCK_SetDataLogging (SOCK sock, ESwitch log)
	Control the data logging for socket "sock" individually.
ESwitch	SOCK_SetInterruptOnSignalAPI (ESwitch on_off)
	Control restartability of I/O interrupted by signals.
ESwitch	SOCK_SetInterruptOnSignal (SOCK sock, ESwitch on_off)
	Control restartability of I/O interrupted by signals on a per-socket basis.
ESwitch	SOCK_SetReuseAddressAPI (ESwitch on_off)
	Control address reuse for socket addresses taken by the API.
void	SOCK_SetReuseAddress (SOCK sock, int on_off)
	Control reuse of socket addresses on per-socket basis Note: only a boolean parameter value is can be used here.
const STimeout *	SOCK_SetSelectInternalRestartTimeout (const STimeout *timeout)
	This is a helper call that can improve I/O behavior.
void	SOCK_AllowSigPipeAPI (void)
	By default (on UNIX platforms) the SOCK API functions automagically call "signal(SIGPIPE, SIG_IGN)" on initialization.
EIO_Status	SOCK_InitializeAPI (void)
	Initialize all internal/system data & resources to be used by the SOCK API.
EIO_Status	SOCK_ShutdownAPI (void)
	Cleanup; destroy all internal/system data & resources used by the SOCK API.
EIO_Status	TRIGGER_Create (TRIGGER *trigger, ESwitch log)
	Create an event trigger.
EIO_Status	TRIGGER_Close (TRIGGER trigger)
	Close an event trigger.
EIO_Status	TRIGGER_Set (TRIGGER trigger)
	Set an event trigger.
EIO_Status	TRIGGER_IsSet (TRIGGER trigger)
	Check whether the trigger has been set.
EIO_Status	TRIGGER_Reset (TRIGGER trigger)
	Reset trigger.
EIO_Status	LSOCK_CreateEx (unsigned short port, unsigned short backlog, LSOCK *lsock, TSOCK_Flags flags)
	[SERVER-side] Create and initialize the server-side(listening) socket (socket() + bind() + listen())
EIO_Status	LSOCK_Create (unsigned short port, unsigned short backlog, LSOCK *lsock)
	[SERVER-side] Create and initialize the server-side(listening) socket Same as LSOCK_CreateEx called with the last argument provided as fSOCK_LogDefault.
EIO_Status	LSOCK_Accept (LSOCK lsock, const STimeout *timeout, SOCK *sock)
	[SERVER-side] Accept connection from a client.
EIO_Status	LSOCK_Close (LSOCK lsock)
	[SERVER-side] Close the listening socket, destroy relevant internal data.
EIO_Status	LSOCK_GetOSHandle (LSOCK lsock, void *handle_buf, size_t)
	Get an OS-dependent native socket handle to use by platform-specific API.
EIO_Status	SOCK_CreateEx (const char *host, unsigned short port, const STimeout *timeout, SOCK *sock, const void *init_data, size_t init_size, TSOCK_Flags flags)
	[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()])
EIO_Status	SOCK_Create (const char *host, unsigned short port, const STimeout *timeout, SOCK *sock)
	[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()]) Equivalent to SOCK_CreateEx(host, port, timeout, sock, 0, 0, fSOCK_LogDefault).
EIO_Status	SOCK_CreateOnTopEx (const void *handle, size_t handle_size, SOCK *sock, const void *init_data, size_t init_size, TSOCK_Flags flags)
	[SERVER-side] Create a socket on top of OS-dependent "handle" (file descriptor on Unix, SOCKET on MS-Windows).
EIO_Status	SOCK_CreateOnTop (const void *handle, size_t handle_size, SOCK *sock)
	[SERVER-side] Create a socket on top of OS-dependent "handle".
EIO_Status	SOCK_Reconnect (SOCK sock, const char *host, unsigned short port, const STimeout *timeout)
	[CLIENT-side] Close the socket referred to by "sock" and then connect it to another "host:port"; fail if it takes more than "timeout" (close() + connect() [+ select()])
EIO_Status	SOCK_Shutdown (SOCK sock, EIO_Event how)
	Shutdown the connection in only one direction (specified by "direction").
EIO_Status	SOCK_Close (SOCK sock)
	Close the connection, destroy relevant internal data.
EIO_Status	SOCK_CloseEx (SOCK sock, int destroy)
	Close the connection, and conditionally destroy relevant internal data.
EIO_Status	SOCK_Wait (SOCK sock, EIO_Event event, const STimeout *timeout)
	Block on the socket until either the specified "event" is available or "timeout" expires (if "timeout" is NULL then assume it infinite).
EIO_Status	SOCK_Poll (size_t n, SSOCK_Poll polls[], const STimeout *timeout, size_t *n_ready)
	Block until at least one of the sockets enlisted in "polls" array (of size "n") becomes available for requested operation (event), or until timeout expires (wait indefinitely if timeout is passed NULL).
EIO_Status	POLLABLE_Poll (size_t n, SPOLLABLE_Poll polls[], const STimeout *timeout, size_t *n_ready)
POLLABLE	POLLABLE_FromSOCK (SOCK)
POLLABLE	POLLABLE_FromLSOCK (LSOCK)
POLLABLE	POLLABLE_FromTRIGGER (TRIGGER)
SOCK	POLLABLE_ToSOCK (POLLABLE)
LSOCK	POLLABLE_ToLSOCK (POLLABLE)
TRIGGER	POLLABLE_ToTRIGGER (POLLABLE)
EIO_Status	SOCK_SetTimeout (SOCK sock, EIO_Event event, const STimeout *timeout)
	Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs).
const STimeout *	SOCK_GetTimeout (SOCK sock, EIO_Event event)
	Get the connection's i/o timeout (or NULL, if the timeout is infinite).
EIO_Status	SOCK_Read (SOCK sock, void *buf, size_t size, size_t *n_read, EIO_ReadMethod how)
	Read/peek up to "size" bytes from "sock" to the mem.buffer pointed by "buf".
EIO_Status	SOCK_ReadLine (SOCK sock, char *buf, size_t size, size_t *n_read)
	Read a line from SOCK.
EIO_Status	SOCK_PushBack (SOCK sock, const void *buf, size_t size)
	Push the specified data back to the socket input queue (in the socket's internal read buffer).
EIO_Status	SOCK_Status (SOCK sock, EIO_Event direction)
	Return low-level socket I/O status of *last* socket operation.
EIO_Status	SOCK_Write (SOCK sock, const void *buf, size_t size, size_t *n_written, EIO_WriteMethod how)
	Write "size" bytes from buffer "buf" to "sock".
EIO_Status	SOCK_Abort (SOCK sock)
	If there is outstanding connection or output data pending, cancel it.
unsigned short	SOCK_GetLocalPort (SOCK sock, ENH_ByteOrder byte_order)
	Get local port of the socket.
void	SOCK_GetPeerAddress (SOCK sock, unsigned int *host, unsigned short *port, ENH_ByteOrder byte_order)
	Get host and port of the socket's peer.
char *	SOCK_GetPeerAddressString (SOCK sock, char *buf, size_t buflen)
	Get textual representation of the socket's peer.
EIO_Status	SOCK_GetOSHandle (SOCK sock, void *handle_buf, size_t handle_size)
	Get an OS-dependent native socket handle to use by platform-specific API.
ESwitch	SOCK_SetReadOnWriteAPI (ESwitch on_off)
	By default ("on_off" == eDefault,eOff), sockets will not try to read data from inside SOCK_Write().
ESwitch	SOCK_SetReadOnWrite (SOCK sock, ESwitch on_off)
	Control the reading-while-writing feature for socket "sock" individually.
void	SOCK_DisableOSSendDelay (SOCK sock, int on_off)
	Control OS-defined send strategy by disabling/enabling TCP Nagle algorithm that packs multiple requests into a single frame and thus transferring data in fewer transactions, miminizing the network traffic and bursting the throughput.
EIO_Status	DSOCK_Create (SOCK *sock)
EIO_Status	DSOCK_CreateEx (SOCK *sock, TSOCK_Flags flags)
EIO_Status	DSOCK_Bind (SOCK sock, unsigned short port)
EIO_Status	DSOCK_Connect (SOCK sock, const char *host, unsigned short port)
EIO_Status	DSOCK_WaitMsg (SOCK sock, const STimeout *timeout)
EIO_Status	DSOCK_SendMsg (SOCK sock, const char *host, unsigned short port, const void *data, size_t datalen)
EIO_Status	DSOCK_RecvMsg (SOCK sock, void *buf, size_t buflen, size_t maxmsglen, size_t *msglen, unsigned int *sender_addr, unsigned short *sender_port)
EIO_Status	DSOCK_WipeMsg (SOCK sock, EIO_Event direction)
EIO_Status	DSOCK_SetBroadcast (SOCK sock, int broadcast)
int	SOCK_IsDatagram (SOCK sock)
	bool
int	SOCK_IsClientSide (SOCK sock)
	bool
int	SOCK_IsServerSide (SOCK sock)
	bool
int	SOCK_IsUNIX (SOCK sock)
	bool
int	SOCK_IsSecure (SOCK sock)
	bool
int	SOCK_gethostname (char *name, size_t namelen)
int	SOCK_ntoa (unsigned int addr, char *buf, size_t buflen)
int	SOCK_isipEx (const char *host, int fullquad)
int	SOCK_isip (const char *host)
	Equivalent of SOCK_isip(host, 0).
unsigned int	SOCK_HostToNetLong (unsigned int value)
	See man for the BSDisms, htonl() and htons().
unsigned short	SOCK_HostToNetShort (unsigned short value)
unsigned int	SOCK_htonl (unsigned int)
unsigned short	SOCK_htons (unsigned short)
unsigned int	SOCK_gethostbyname (const char *hostname)
char *	SOCK_gethostbyaddr (unsigned int addr, char *name, size_t namelen)
	Take INET host address (in network byte order) and fill out the the provided buffer with the name, which the address corresponds to (in case of multiple names the primary name is used).
unsigned int	SOCK_GetLoopbackAddress (void)
unsigned int	SOCK_GetLocalHostAddress (ESwitch reget)
	Get (and cache for faster follow-up retrievals) the address of local host.
const char *	SOCK_StringToHostPort (const char *str, unsigned int *host, unsigned short *port)
	Read (skipping leading blanks) "[host][:port]" from a string.
size_t	SOCK_HostPortToString (unsigned int host, unsigned short port, char *buf, size_t buflen)
	Print host:port into provided buffer string, not to exceed 'buflen' size.
void	SOCK_SetupSSL (FSSLSetup setup)
EIO_Status	LSOCK_CreateUNIX (const char *path, unsigned short backlog, LSOCK *lsock, TSOCK_Flags flags)
EIO_Status	SOCK_CreateUNIX (const char *path, const STimeout *timeout, SOCK *sock, const void *init_data, size_t init_size, TSOCK_Flags flags)

---

Define Documentation

#define NCBI_SOCK_DEPRECATED

Definition at line 1567 of file ncbi_socket.h.

#define SOCK_NetToHostLong   SOCK_HostToNetLong

Definition at line 1552 of file ncbi_socket.h. Referenced by CSocketAPI::NetToHostLong().

#define SOCK_NetToHostShort   SOCK_HostToNetShort

Definition at line 1562 of file ncbi_socket.h. Referenced by CSocketAPI::NetToHostShort().

#define SOCK_ntohl   SOCK_htonl

Definition at line 1573 of file ncbi_socket.h.

#define SOCK_ntohs   SOCK_htons

Definition at line 1576 of file ncbi_socket.h.

---

Typedef Documentation

typedef SOCKSSL(* FSSLSetup)(void)

Definition at line 1688 of file ncbi_socket.h.

typedef struct LSOCK_tag* LSOCK

Definition at line 170 of file ncbi_socket.h.

typedef struct SPOLLABLE_tag* POLLABLE

Definition at line 863 of file ncbi_socket.h.

typedef struct SOCK_tag* SOCK

Definition at line 173 of file ncbi_socket.h.

typedef const struct SOCKSSL_struct* SOCKSSL

Definition at line 1685 of file ncbi_socket.h.

typedef struct TRIGGER_tag* TRIGGER

Definition at line 176 of file ncbi_socket.h.

typedef unsigned int TSOCK_Flags

Definition at line 462 of file ncbi_socket.h.

---

Enumeration Type Documentation

enum ECopyTimeout

Enumerator: eCopyTimeoutsFromSOCK  eCopyTimeoutsToSOCK  Definition at line 55 of file ncbi_socket.hpp.

enum ELSCE_Flags

Enumerator: fLSCE_LogOff  fLSCE_LogOn  fLSCE_LogDefault  fLSCE_BindAny  fLSCE_BindLocal  fLSCE_CloseOnExec  Definition at line 469 of file ncbi_socket.h.

enum ENH_ByteOrder

Network and host byte order enumeration type. Enumerator: eNH_HostByteOrder  eNH_NetworkByteOrder  Definition at line 160 of file ncbi_socket.h.

enum ESCOT_OnClose

SOCK_Close behavior for SOCKs created on top of OS handles. See also: SOCK_Close, SOCK_CreateOnTop, SOCK_CreateOnTopEx Enumerator: eSCOT_KeepOnClose  eSCOT_CloseOnClose  Definition at line 634 of file ncbi_socket.h.

enum ESOCK_Flags

Enumerator: fSOCK_LogOff  fSOCK_LogOn  logging is inherited in Accept()ed SOCKs fSOCK_LogDefault  fSOCK_BindAny  fSOCK_BindLocal  bind to 0.0.0.0 (i.e. any), default fSOCK_KeepOnExec  bind to 127.0.0.1 only fSOCK_CloseOnExec  can be applied to all sockets fSOCK_Secure  can be applied to all sockets fSOCK_KeepOnClose  subsumes CloseOnExec regardless of Keep fSOCK_CloseOnClose  do not close OS handle on SOCK_Close[Ex] fSOCK_ReadOnWrite  do close OS handle on SOCK_Close[Ex] fSOCK_InterruptOnSignal  Definition at line 448 of file ncbi_socket.h.

---

Function Documentation

EIO_Status DSOCK_Bind (  SOCK  sock, unsigned short  port )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() port  [in] port to bind to (!=0) Definition at line 5051 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, CORE_LOGF_X, eDatagram, eDefault, eIO_Closed, eIO_InvalidArg, eIO_Open, eIO_Success, eIO_Unknown, eLOG_Trace, eOn, SOCK_tag::log, SOCK_tag::myport, s_DoLog(), s_ID(), s_Log, SOCK_tag::sock, SOCK_EADDRINUSE, and SOCK_tag::type. Referenced by CDatagramSocket::Bind().

EIO_Status DSOCK_Connect (  SOCK  sock, const char *  host, unsigned short  port )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() host  [in] peer host port  [in] peer port Definition at line 5096 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, CORE_LOGF_X, eDatagram, eDefault, eIO_Closed, eIO_InvalidArg, eIO_Open, eIO_Success, eIO_Unknown, eOn, SOCK_tag::host, SOCK_tag::id, SOCK_tag::log, SOCK_tag::port, s_DoLog(), s_ID(), s_Log, s_WipeRBuf(), s_WipeWBuf(), SOCK_tag::sock, SOCK_gethostbyname(), SOCK_HostPortToString(), and SOCK_tag::type. Referenced by CDatagramSocket::Connect().

EIO_Status DSOCK_Create (  SOCK *  sock  )

Parameters: sock  [out] socket created Definition at line 4930 of file ncbi_socket.c. References DSOCK_CreateEx(), and fSOCK_LogDefault.

EIO_Status DSOCK_CreateEx (  SOCK *  sock, TSOCK_Flags  flags )

Parameters: sock  [out] socket created flags  [in] additional socket properties Definition at line 4936 of file ncbi_socket.c. References BUF_SetChunkSize(), CORE_LOGF_ERRNO_EXX, eDatagram, eDefault, eIO_NotSupported, eIO_Open, eIO_Success, eIO_Unknown, eLOG_Warning, eOn, eSOCK_Client, FALSE, fSOCK_InterruptOnSignal, fSOCK_KeepOnClose, fSOCK_KeepOnExec, fSOCK_Secure, s_DoLog(), s_ID(), s_ID_Counter, s_InitAPI(), s_Log, s_SetNonblock(), SOCK_BUF_CHUNK_SIZE, and TRUE. Referenced by CDatagramSocket::CDatagramSocket(), and DSOCK_Create().

EIO_Status DSOCK_RecvMsg (  SOCK  sock, void *  buf, size_t  buflen, size_t  maxmsglen, size_t *  msglen, unsigned int *  sender_addr, unsigned short *  sender_port )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() buf  [in] buf to store msg at,m.b.NULL buflen  [in] buf length provided maxmsglen  [in] maximal expected message len msglen  [out] actual msg size, may be NULL sender_addr  [out] net byte order, may be NULL sender_port  [out] host byte order, may be NULL Definition at line 5322 of file ncbi_socket.c. References BUF_Write(), CORE_LOGF_ERRNO_EXX, CORE_LOGF_X, eDatagram, eDefault, eIO_Close, eIO_Closed, eIO_Interrupt, eIO_InvalidArg, eIO_Open, eIO_Success, eIO_Unknown, eLOG_Trace, eOn, SSOCK_Poll::event, SOCK_tag::i_on_sig, SOCK_tag::log, SOCK_tag::n_in, SOCK_tag::n_read, SOCK_tag::r_buf, SOCK_tag::r_status, SOCK_tag::r_timeout, SSOCK_Poll::revent, s_DoLog(), s_ID(), s_InterruptOnSignal, s_Log, s_Select(), s_WipeRBuf(), SOCK_tag::sock, SSOCK_Poll::sock, SOCK_EAGAIN, SOCK_EINTR, SOCK_EWOULDBLOCK, and SOCK_tag::type. Referenced by CDatagramSocket::Recv().

EIO_Status DSOCK_SendMsg (  SOCK  sock, const char *  host, unsigned short  port, const void *  data, size_t  datalen )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() host  [in] hostname or dotted IP port  [in] port number, host byte order data  [in] additional data to send datalen  [in] size of additional data (bytes) Definition at line 5180 of file ncbi_socket.c. References BUF_Peek(), BUF_Size(), CORE_LOGF_X, eDatagram, eDefault, eIO_Closed, eIO_InvalidArg, eIO_Unknown, eIO_Write, SOCK_tag::eof, eOn, SOCK_tag::host, SOCK_tag::log, SOCK_tag::port, s_DoLog(), s_ID(), s_Log, s_Write(), SOCK_tag::sock, SOCK_gethostbyname(), SOCK_tag::type, verify, and SOCK_tag::w_buf. Referenced by CDatagramSocket::Send().

EIO_Status DSOCK_SetBroadcast (  SOCK  sock, int  broadcast )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() broadcast  [in] set(1)/unset(0) bcast capab Parameters: broadcast  bool Definition at line 5523 of file ncbi_socket.c. References BOOL, CORE_LOGF_ERRNO_EXX, CORE_LOGF_X, eDatagram, eIO_Closed, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_Unknown, s_ID(), SOCK_tag::sock, and SOCK_tag::type. Referenced by CDatagramSocket::SetBroadcast().

EIO_Status DSOCK_WaitMsg (  SOCK  sock, const STimeout *  timeout )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() timeout  [in] time to wait for message Definition at line 5453 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_Close, eIO_Closed, eIO_InvalidArg, eIO_Open, eIO_Success, eIO_Unknown, SSOCK_Poll::event, SSOCK_Poll::revent, s_ID(), s_Select(), s_to2tv(), SOCK_tag::sock, SSOCK_Poll::sock, and SOCK_tag::type. Referenced by CDatagramSocket::Wait().

EIO_Status DSOCK_WipeMsg (  SOCK  sock, EIO_Event  direction )

Parameters: sock  [in] SOCK from DSOCK_Create[Ex]() direction  [in] either of eIO_Read|eIO_Write Definition at line 5485 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_Closed, eIO_InvalidArg, eIO_Write, SOCK_tag::r_status, s_ID(), s_WipeRBuf(), s_WipeWBuf(), SOCK_tag::sock, SOCK_tag::type, and SOCK_tag::w_status. Referenced by CDatagramSocket::Clear().

EIO_Status LSOCK_Accept (  LSOCK  lsock, const STimeout *  timeout, SOCK *  sock )

[SERVER-side] Accept connection from a client. Parameters: lsock  [in] handle of a listening socket timeout  [in] timeout (infinite if NULL) NOTE: the provided "timeout" is for this accept() only. To set I/O timeout on the resulted socket use SOCK_SetTimeout(); all I/O timeouts are infinite by default. sock  [out] handle of the accepted socket See also: SOCK_Create, SOCK_Close Definition at line 3753 of file ncbi_socket.c. References fSOCK_LogDefault, and s_Accept(). Referenced by CListeningSocket::Accept().

EIO_Status LSOCK_Close (  LSOCK  lsock  )

[SERVER-side] Close the listening socket, destroy relevant internal data. Parameters: lsock  [in] listening socket handle to close The call invalidates the handle, so its further is not allowed. See also: LSOCK_Create Definition at line 3770 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, CORE_LOGF_X, eDefault, eIO_Success, eIO_Unknown, eLOG_Trace, eOn, LSOCK_tag::id, LSOCK_tag::keep, LSOCK_tag::log, LSOCK_tag::n_accept, LSOCK_tag::port, s_Initialized, s_Log, s_SetNonblock(), LSOCK_tag::sock, SOCK_EINTR, and SOCK_HostPortToString(). Referenced by CListeningSocket::Close().

EIO_Status LSOCK_Create (  unsigned short  port, unsigned short  backlog, LSOCK *  lsock )

[SERVER-side] Create and initialize the server-side(listening) socket Same as LSOCK_CreateEx called with the last argument provided as fSOCK_LogDefault. Parameters: port  [in] the port to listen at backlog  [in] maximal # of pending connections NOTE: on some systems, "backlog" can be silently limited down to 128 (or 5), or completely ignored whatsoever. lsock  [out] handle of the created listening socket See also: LSOCK_CreateEx, LSOCK_Close Definition at line 3497 of file ncbi_socket.c. References fSOCK_LogDefault, and s_CreateListening().

EIO_Status LSOCK_CreateEx (  unsigned short  port, unsigned short  backlog, LSOCK *  lsock, TSOCK_Flags  flags )

[SERVER-side] Create and initialize the server-side(listening) socket (socket() + bind() + listen()) Parameters: port  [in] the port to listen at backlog  [in] maximal # of pending connections NOTE: on some systems, "backlog" can be silently limited down to 128 (or 5), or completely ignored whatsoever. lsock  [out] handle of the created listening socket flags  [in] special modifiers See also: LSOCK_Create, LSOCK_Close Definition at line 3505 of file ncbi_socket.c. References s_CreateListening(). Referenced by CListeningSocket::CListeningSocket(), and CListeningSocket::Listen().

EIO_Status LSOCK_CreateUNIX (  const char *  path, unsigned short  backlog, LSOCK *  lsock, TSOCK_Flags  flags )

Definition at line 3514 of file ncbi_socket.c. References s_CreateListening(). Referenced by CUNIXListeningSocket::CUNIXListeningSocket(), and CUNIXListeningSocket::Listen().

EIO_Status LSOCK_GetOSHandle (  LSOCK  lsock, void *  handle_buf, size_t  )

Get an OS-dependent native socket handle to use by platform-specific API. FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int". Parameters: lsock  [in] socket handle handle_buf  [in] pointer to a memory location to store the OS-dependent handle at handle_size  The exact(!) size of the expected OS handle See also: SOCK_GetOSHandle Definition at line 3855 of file ncbi_socket.c. References CORE_LOGF_X, eIO_Closed, eIO_InvalidArg, eIO_Success, LSOCK_tag::id, and LSOCK_tag::sock. Referenced by CListeningSocket::GetOSHandle().

SOCKSSL NcbiSetupGnuTls (  void   )

Definition at line 454 of file ncbi_gnutls.c.

POLLABLE POLLABLE_FromLSOCK (  LSOCK   )

Definition at line 4405 of file ncbi_socket.c. References eListening, and LSOCK_tag::type.

POLLABLE POLLABLE_FromSOCK (  SOCK   )

Returns: Return 0 if conversion cannot be made; otherwise converted handle Definition at line 4412 of file ncbi_socket.c. References eSocket, and SOCK_tag::type.

POLLABLE POLLABLE_FromTRIGGER (  TRIGGER   )

Definition at line 4398 of file ncbi_socket.c. References eTrigger, and TRIGGER_tag::type. Referenced by CSocketAPI::Poll().

EIO_Status POLLABLE_Poll (  size_t  n, SPOLLABLE_Poll  polls[], const STimeout *  timeout, size_t *  n_ready )

Parameters: n  polls[]  timeout  n_ready  Definition at line 4389 of file ncbi_socket.c. References SOCK_Poll().

LSOCK POLLABLE_ToLSOCK (  POLLABLE   )

Definition at line 4426 of file ncbi_socket.c. References eListening, and LSOCK_tag::type.

SOCK POLLABLE_ToSOCK (  POLLABLE   )

Definition at line 4433 of file ncbi_socket.c. References eSocket, and SOCK_tag::type.

TRIGGER POLLABLE_ToTRIGGER (  POLLABLE   )

Definition at line 4419 of file ncbi_socket.c. References eTrigger, and TRIGGER_tag::type.

EIO_Status SOCK_Abort (  SOCK  sock  )

If there is outstanding connection or output data pending, cancel it. Mark the socket as if it has been shut down for both reading and writing. Break actual connection if any was established. Do not attempt to send anything upon SOCK_Close(). This call is available for stream sockets only. NB: Even though the underlying OS socket handle may have been marked for preservation via fSOCK_KeepOnClose, this call always and unconditially closes and destroys the actual OS handle. Parameters: sock  Socket handle Definition at line 4735 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_Closed, eIO_InvalidArg, eLOG_Warning, SOCK_tag::eof, SOCK_tag::pending, s_Close(), s_ID(), SOCK_tag::sock, SOCK_tag::type, and SOCK_tag::w_len. Referenced by CSocket::Abort(), s_FTPAbort(), s_FTPRetrieve(), and s_VT_Close().

void SOCK_AllowSigPipeAPI (  void   )

By default (on UNIX platforms) the SOCK API functions automagically call "signal(SIGPIPE, SIG_IGN)" on initialization. To prohibit this feature, you must call SOCK_AllowSigPipeAPI() before you call any other function from the SOCK API. Definition at line 605 of file ncbi_socket.c. Referenced by CSocketAPI::AllowSigPipe().

EIO_Status SOCK_Close (  SOCK  sock  )

Close the connection, destroy relevant internal data. The "sock" handle goes invalid after this function call, regardless of whether the call was successful or not. If eIO_Close timeout was specified (or NULL) then it blocks until either all unsent data are sent, error flagged, or the timeout expires; if there is any output pending, that output will be flushed. Parameters: sock  [in] socket handle to close See also: SOCK_Create, SOCK_CreateOnTop, DSOCK_Create, SOCK_SetTimeout Definition at line 4234 of file ncbi_socket.c. References SOCK_CloseEx(). Referenced by CUNIXSocket::Connect(), CSocket::Connect(), CORE_SendMailEx(), CNetBVSServer::ProcessOverflow(), CThreadedServer::ProcessOverflow(), CSocket::Reset(), s_Create(), s_DropConnection(), s_FTPAbort(), s_FTPReply(), s_VT_Close(), s_VT_Open(), s_VT_Read(), SOCK_CreateOnTopEx(), and CSocket::~CSocket().

EIO_Status SOCK_CloseEx (  SOCK  sock, int  destroy )

Close the connection, and conditionally destroy relevant internal data. If eIO_Close timeout was specified (or NULL) then it blocks until either all unsent data are sent, error flagged, or the timeout expires; if there is any output pending, that output will be flushed. NOTE SOCK_CloseEx(sock, 1) is equivalent to SOCK_Close(sock); Parameters: sock  [in] handle of the socket to close destroy  [in] =1 to destroy handle; =0 to keep handle See also: SOCK_Close, SOCK_Create, SOCK_CreateOnTop, DSOCK_Create, SOCK_SetTimeout Parameters: destroy  bool Definition at line 4214 of file ncbi_socket.c. References BUF_Destroy(), eIO_Closed, eIO_Success, SOCK_tag::r_buf, s_Close(), s_Initialized, SOCK_tag::sock, and SOCK_tag::w_buf. Referenced by CListeningSocket::Accept(), CSocket::Close(), and SOCK_Close().

EIO_Status SOCK_Create (  const char *  host, unsigned short  port, const STimeout *  timeout, SOCK *  sock )

[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()]) Equivalent to SOCK_CreateEx(host, port, timeout, sock, 0, 0, fSOCK_LogDefault). Parameters: host  [in] host to connect to port  [in] port to connect to timeout  [in] the connect timeout (infinite if NULL) sock  [out] handle of the created socket See also: SOCK_CreateEx, SOCK_Reconnect, SOCK_Close Definition at line 3880 of file ncbi_socket.c. References eDefault, eIO_InvalidArg, and s_Create(). Referenced by CORE_SendMailEx().

EIO_Status SOCK_CreateEx (  const char *  host, unsigned short  port, const STimeout *  timeout, SOCK *  sock, const void *  init_data, size_t  init_size, TSOCK_Flags  flags )

[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()]) Parameters: host  [in] host to connect to port  [in] port to connect to timeout  [in] the connect timeout (infinite if NULL) sock  [out] handle of the created socket init_data  [in] initial output data segment (may be NULL) init_size  [in] size of initial data segment (may be 0) flags  [in] additional socket requirements See also: SOCK_Create, SOCK_Reconnect, SOCK_Close Definition at line 3891 of file ncbi_socket.c. References eIO_InvalidArg, and s_Create(). Referenced by CSocket::Connect(), CSocket::CSocket(), s_VT_Open(), and URL_ConnectEx().

EIO_Status SOCK_CreateOnTop (  const void *  handle, size_t  handle_size, SOCK *  sock )

[SERVER-side] Create a socket on top of OS-dependent "handle". Equivalent to SOCK_CreateOnTopEx(handle, handle_size, sock, 0, 0, fSOCK_LogDefault|fSOCK_CloseOnClose). Parameters: handle  [in] OS-dependent "handle" to be converted handle_size  [in] "handle" size sock  [out] SOCK built on top of OS "handle" See also: SOCK_CreateOnTopEx Definition at line 3922 of file ncbi_socket.c. References fSOCK_LogDefault, and SOCK_CreateOnTopEx().

EIO_Status SOCK_CreateOnTopEx (  const void *  handle, size_t  handle_size, SOCK *  sock, const void *  init_data, size_t  init_size, TSOCK_Flags  flags )

[SERVER-side] Create a socket on top of OS-dependent "handle" (file descriptor on Unix, SOCKET on MS-Windows). Returned socket is not reopenable to its default peer (SOCK_Reconnect may not specify zeros for the connection point). All timeouts are set to default [infinite] values. SOCK_Close will close the "handle" only if the "close_on_close" parameter is passed non-zero (eSCOT_CloseOnClose). Parameters: handle  [in] OS-dependent "handle" to be converted handle_size  [in] "handle" size sock  [out] SOCK built on top of OS "handle" init_data  [in] initial output data segment (may be NULL) init_size  [in] size of the initial data segment (may be 0) flags  [in] additional socket requirements Returns: Return eIO_Success on success; otherwise: eIO_Closed if the "handle" does not refer to an open socket [but e.g. to a normal file or a pipe]; other error codes in case of other errors See also: SOCK_CreateOnTop, SOCK_Reconnect, SOCK_Close Definition at line 3930 of file ncbi_socket.c. References BUF_Destroy(), BUF_SetChunkSize(), BUF_Write(), CORE_LOGF_ERRNO_EXX, CORE_LOGF_ERRNO_X, CORE_LOGF_X, SOCKSSL_struct::Create, eDefault, eIO_Closed, eIO_InvalidArg, eIO_NotSupported, eIO_Open, eIO_Success, eIO_Unknown, eLOG_Warning, eOn, errno, eSOCK_Client, eSOCK_Server, eSocket, fSOCK_InterruptOnSignal, fSOCK_KeepOnClose, fSOCK_KeepOnExec, fSOCK_ReadOnWrite, fSOCK_Secure, NCBI_OS_DARWIN, s_DoLog(), s_ID(), s_ID_Counter, s_InitAPI(), s_Log, s_SetNonblock(), s_SSL, s_StrError(), SESSION_INVALID, SOCK_BUF_CHUNK_SIZE, and SOCK_Close(). Referenced by SOCK_CreateOnTop().

EIO_Status SOCK_CreateUNIX (  const char *  path, const STimeout *  timeout, SOCK *  sock, const void *  init_data, size_t  init_size, TSOCK_Flags  flags )

Definition at line 3905 of file ncbi_socket.c. References eIO_InvalidArg, eIO_NotSupported, and s_Create(). Referenced by CUNIXSocket::Connect(), and CUNIXSocket::CUNIXSocket().

void SOCK_DisableOSSendDelay (  SOCK  sock, int  on_off )

Control OS-defined send strategy by disabling/enabling TCP Nagle algorithm that packs multiple requests into a single frame and thus transferring data in fewer transactions, miminizing the network traffic and bursting the throughput. Some applications, however, may find it useful to disable this default behavior for the sake of their performance increase (like in case of short transactions otherwise held by the system to be possibly coalesced into larger chunks). Parameters: sock  [in] socket handle on_off  NB: use true to disable; false to enable Parameters: on_off  bool Definition at line 4910 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, eLOG_Warning, s_ID(), and SOCK_tag::sock. Referenced by CSocket::DisableOSSendDelay().

char* SOCK_gethostbyaddr (  unsigned int  addr, char *  name, size_t  namelen )

Take INET host address (in network byte order) and fill out the the provided buffer with the name, which the address corresponds to (in case of multiple names the primary name is used). Parameters: addr  [in] host address in network byte order name  [out] buffer to put the name to namelen  [in] size (bytes) of the buffer above Returns: Value 0 means error, while success is denoted by the 'name' argument returned. Note that on error the name returned emptied (name[0] == ''). Definition at line 5813 of file ncbi_socket.c. References CORE_LOCK_WRITE, CORE_LOGF_ERRNO_EXX, CORE_UNLOCK, DNS_BASE, EAI_BASE, eIO_Success, eLOG_Warning, eOn, s_InitAPI(), s_Log, SOCK_gethostbyname(), and SOCK_ntoa(). Referenced by ConnNetInfo_SetupStandardArgs(), CORE_SendMailEx(), CSocketAPI::gethostbyaddr(), s_MakeFrom(), and s_SetDefaultReferer().

unsigned int SOCK_gethostbyname (  const char *  hostname  )

Parameters: hostname  [in] return current host address if hostname is 0 Returns: INET host address (in network byte order) of the specified host (or local host, if hostname is passed as NULL), which can be either domain name or an IP address in dotted notation (e.g. "123.45.67.89\0"). Return 0 on error. NOTE: "0.0.0.0" and "255.255.255.255" are considered invalid. Definition at line 5714 of file ncbi_socket.c. References CORE_LOCK_WRITE, CORE_LOGF_ERRNO_EXX, CORE_UNLOCK, DNS_BASE, EAI_BASE, eIO_Success, eLOG_Warning, eOn, out(), s_InitAPI(), s_Log, and SOCK_gethostname(). Referenced by CNetCacheServer::CNetCacheServer(), DSOCK_Connect(), DSOCK_SendMsg(), CSocketAPI::gethostbyname(), s_ClientAddress(), s_Connect(), s_ParseHeader(), SOCK_gethostbyaddr(), and SOCK_GetLocalHostAddress().

int SOCK_gethostname (  char *  name, size_t  namelen )

Parameters: name  [out] (guaranteed to be ''-terminated) namelen  [in] max # of bytes allowed to put to "name" Returns: Zero on success, non-zero on error. See BSD gethostname(). On error "name" returned emptied (name[0] == ''). Definition at line 5601 of file ncbi_socket.c. References CORE_LOG_ERRNO_EXX, CORE_LOG_X, eIO_NotSupported, eIO_Success, and s_InitAPI(). Referenced by CNetBVSServer::CNetBVSServer(), CNetCacheServer::CNetCacheServer(), ConnNetInfo_SetupStandardArgs(), CORE_SendMailEx(), CSocketAPI::gethostname(), s_MakeFrom(), s_SetDefaultReferer(), and SOCK_gethostbyname().

unsigned int SOCK_GetLocalHostAddress (  ESwitch  reget  )

Get (and cache for faster follow-up retrievals) the address of local host. Parameters: reget  eOn to forcibly recache and return the address; eDefault to recache only if unknown, return the cached value; eOff not to recache even if unknown, return whatever is available. Returns: Local address (in network byte order). Definition at line 5943 of file ncbi_socket.c. References eDefault, eOff, eOn, SOCK_gethostbyname(), and SOCK_GetLoopbackAddress(). Referenced by g_NCBI_ConnectSrandAddend(), CSocketAPI::GetLocalHostAddress(), s_ClientAddress(), s_Open(), and SERV_ServerPort().

unsigned short SOCK_GetLocalPort (  SOCK  sock, ENH_ByteOrder  byte_order )

Get local port of the socket. Parameters: sock  [in] socket handle byte_order  [in] port byte order Returns: If "network_byte_order" is true(non-zero) then return the port in the network byte order; otherwise return it in the local host byte order. Definition at line 4779 of file ncbi_socket.c. References eNH_HostByteOrder, SOCK_tag::myport, SOCK_tag::sock, and x_GetLocalPort(). Referenced by CSocket::GetLocalPort().

unsigned int SOCK_GetLoopbackAddress (  void   )

Returns: Loopback address (in network byte order). Definition at line 5937 of file ncbi_socket.c. Referenced by CSocketAPI::GetLoopbackAddress(), and SOCK_GetLocalHostAddress().

EIO_Status SOCK_GetOSHandle (  SOCK  sock, void *  handle_buf, size_t  handle_size )

Get an OS-dependent native socket handle to use by platform-specific API. FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int". Parameters: sock  Socket handle handle_buf  pointer to a memory area to put the OS handle at handle_size  the exact(!) size of the expected OS handle Definition at line 4828 of file ncbi_socket.c. References CORE_LOGF_X, eIO_Closed, eIO_InvalidArg, eIO_Success, s_ID(), and SOCK_tag::sock. Referenced by CSocket::GetOSHandle().

void SOCK_GetPeerAddress (  SOCK  sock, unsigned int *  host, unsigned short *  port, ENH_ByteOrder  byte_order )

Get host and port of the socket's peer. Parameters: sock  [in] socket handle host  [out] the peer's host (can be NULL) port  [out] the peer's port (can be NULL) byte_order  [in] host/port byte order Returns: If "network_byte_order" is true(non-zero) then return the host/port in the network byte order; otherwise return them in the local host byte order. Definition at line 4796 of file ncbi_socket.c. References eNH_HostByteOrder, SOCK_tag::host, and SOCK_tag::port. Referenced by CSocket::GetPeerAddress(), and s_VT_Open().

char* SOCK_GetPeerAddressString (  SOCK  sock, char *  buf, size_t  buflen )

Get textual representation of the socket's peer. For INET domain sockets, the result is of the form "aaa.bbb.ccc.ddd:ppppp"; for UNIX domain socket, the result is the name of the socket's file. Parameters: sock  [in] socket handle buf  [out] pointer to provided buffer to store the text to buflen  [in] usable size of the buffer above Returns: On success, return its "buf" argument; return 0 on error. Definition at line 4812 of file ncbi_socket.c. References SOCK_tag::host, SOCK_tag::port, SOCK_HostPortToString(), and strncpy0(). Referenced by CSocket::GetPeerAddress().

const STimeout* SOCK_GetTimeout (  SOCK  sock, EIO_Event  event )

Get the connection's i/o timeout (or NULL, if the timeout is infinite). NOTE 1: the returned timeout is guaranteed to be pointing to a valid (and correct) structure in memory at least until the SOCK is closed or SOCK_SetTimeout is called for this "sock". NOTE 2: eIO_ReadWrite timeout is the least of eIO_Read and eIO_Write ones. Parameters: sock  [in] socket handle event  [in] one of: eIO_[Read/Write/Close] Definition at line 4471 of file ncbi_socket.c. References SOCK_tag::c_timeout, SOCK_tag::c_to, CORE_LOGF_X, eIO_Close, eIO_ReadWrite, eIO_Write, SOCK_tag::r_timeout, SOCK_tag::r_to, s_ID(), s_tv2to(), STimeout::sec, STimeout::usec, SOCK_tag::w_timeout, and SOCK_tag::w_to. Referenced by CSocket::Reset().

size_t SOCK_HostPortToString (  unsigned int  host, unsigned short  port, char *  buf, size_t  buflen )

Print host:port into provided buffer string, not to exceed 'buflen' size. Suppress printing host if parameter 'host' is zero. Parameters: host  port  buf  buflen  Returns: Number of bytes printed. Definition at line 5999 of file ncbi_socket.c. References SOCK_ntoa(). Referenced by DSOCK_Connect(), CSocketAPI::HostPortToString(), LSOCK_Close(), s_CreateListening(), s_DoLog(), SERV_WriteInfo(), SOCK_GetPeerAddressString(), and x_ConnPoint().

unsigned int SOCK_HostToNetLong (  unsigned int  value  )

See man for the BSDisms, htonl() and htons(). Parameters: value  Definition at line 5690 of file ncbi_socket.c. Referenced by CNetCacheServer::CNetCacheServer(), CSocketAPI::HostToNetLong(), s_ParseHeader(), and s_VT_Open().

unsigned short SOCK_HostToNetShort (  unsigned short  value  )

Parameters: value  Definition at line 5696 of file ncbi_socket.c. Referenced by CSocketAPI::HostToNetShort().

unsigned int SOCK_htonl (  unsigned  int  )

Definition at line 5702 of file ncbi_socket.c.

unsigned short SOCK_htons (  unsigned  short  )

Definition at line 5708 of file ncbi_socket.c.

EIO_Status SOCK_InitializeAPI (  void   )

Initialize all internal/system data & resources to be used by the SOCK API. NOTE: You can safely call it more than once; just, all calls after the first one will have no result. NOTE: Usually, SOCK API does not require an explicit initialization -- as it is guaranteed to initialize itself automagically, in one of API functions, when necessary. Yet, see the "Multi Thread safety" remark above. NOTE: This call, when used for the very first time in the application, enqueues SOCK_ShutdownAPI() to be called upon application exit on plaftorms that provide this functionality. In any case, the application can opt for explicit SOCK_ShutdownAPI() call when it is done with all sockets. See also: SOCK_ShutdownAPI Definition at line 711 of file ncbi_socket.c. References CORE_LOCK_WRITE, CORE_LOG_ERRNO_EXX, CORE_UNLOCK, eIO_NotSupported, eIO_Success, eLOG_Error, s_Initialized, and SOCK_ShutdownAPI(). Referenced by CNetScheduleDApp::Init(), CSocketAPI::Initialize(), and s_InitAPI().

int SOCK_IsClientSide (  SOCK  sock  )

bool Definition at line 5573 of file ncbi_socket.c. References eSOCK_Client, SOCK_tag::side, and SOCK_tag::sock. Referenced by CSocket::IsClientSide().

int SOCK_IsDatagram (  SOCK  sock  )

bool Definition at line 5567 of file ncbi_socket.c. References eDatagram, SOCK_tag::sock, and SOCK_tag::type. Referenced by CSocket::IsDatagram().

int SOCK_isip (  const char *  host  )

Equivalent of SOCK_isip(host, 0). Parameters: host  [in] ''-terminated string to check against being a plain IP address Returns: Non-zero (true) if given string is an IP address, zero (false) otherwise. Definition at line 5655 of file ncbi_socket.c. References SOCK_isipEx(). Referenced by CSocketAPI::isip(), and s_IsSufficientAddress().

int SOCK_isipEx (  const char *  host, int  fullquad )

Parameters: host  [in] ''-terminated string to check against being a plain IP address fullquad  [in] non-zero to only accept "host" if it is a full-quad IP notation Returns: Non-zero (true) if given string is an IP address, zero (false) otherwise. Definition at line 5661 of file ncbi_socket.c. References errno. Referenced by SOCK_isip().

int SOCK_IsSecure (  SOCK  sock  )

bool Definition at line 5585 of file ncbi_socket.c. References SOCK_tag::session, and SOCK_tag::sock. Referenced by CSocket::IsSecure().

int SOCK_IsServerSide (  SOCK  sock  )

bool Definition at line 5579 of file ncbi_socket.c. References eSOCK_Server, SOCK_tag::side, and SOCK_tag::sock. Referenced by CSocket::IsServerSide(), and s_Init().

int SOCK_IsUNIX (  SOCK  sock  )

bool Definition at line 5591 of file ncbi_socket.c. References SOCK_tag::sock. Referenced by CSocket::IsUNIX().

int SOCK_ntoa (  unsigned int  addr, char *  buf, size_t  buflen )

Parameters: addr  [in] must be in the network byte-order buf  [out] to be filled by smth. like "123.45.67.89\0" buflen  [in] max # of bytes to put to "buf" Returns: Zero on success, non-zero on error. Vaguely related to BSD's inet_ntoa(). On error "buf" returned emptied (buf[0] == ''). Definition at line 5633 of file ncbi_socket.c. References len, and verify. Referenced by CDatagramSocket::Connect(), CSocket::CSocket(), CSocketAPI::ntoa(), s_ClientAddress(), s_Open(), s_VT_Open(), SOCK_gethostbyaddr(), and SOCK_HostPortToString().

EIO_Status SOCK_Poll (  size_t  n, SSOCK_Poll  polls[], const STimeout *  timeout, size_t *  n_ready )

Block until at least one of the sockets enlisted in "polls" array (of size "n") becomes available for requested operation (event), or until timeout expires (wait indefinitely if timeout is passed NULL). Return eIO_Success if at least one socket was found ready; eIO_Timeout if timeout expired; eIO_Unknown if underlying system call(s) failed. NOTE 1: For a socket found not ready for an operation, eIO_Open is returned in its "revent"; for a failing socket, eIO_Close is returned; NOTE 2: This call may return eIO_InvalidArg if parameters to the call are inconsistent; a non-NULL socket polled with a bad "event" (eIO_Open, eIO_Close). With this return code, the calling program cannot rely on "revent" fields the "polls" array as they might not be properly updated. NOTE 3: If either both "n" and "polls" are NULL, or all sockets in "polls" are NULL, then the returned result is either eIO_Timeout (after the specified amount of time was spent idle), or eIO_Interrupted (if signal came while the waiting was in progress). NOTE 4: For datagram sockets, the readiness for reading is determined by message data latched since last message receive call (DSOCK_RecvMsg). NOTE 5: This call allows intermixture of stream and datagram sockets. NOTE 6: This call can cause some socket I/O in those sockets marked for read-on-write and those with pending connection or output data. Parameters: n  [in] # of SSOCK_Poll elems in "polls" polls[]  [in|out] array of query/result structures timeout  [in] max time to wait (infinite if NULL) n_ready  [out] # of ready sockets (may be NULL) Definition at line 4354 of file ncbi_socket.c. References BUF_Size(), eIO_Close, eIO_Closed, eIO_InvalidArg, eIO_Open, eSocket, and SSOCK_Poll::revent. Referenced by POLLABLE_Poll().

EIO_Status SOCK_PushBack (  SOCK  sock, const void *  buf, size_t  size )

Push the specified data back to the socket input queue (in the socket's internal read buffer). These can be any data, not necessarily the data previously read from the socket. Parameters: sock  [in] socket handle buf  [in] data to push back to the socket's local buffer size  [in] # of bytes (starting at "buf") to push back Definition at line 4658 of file ncbi_socket.c. References CORE_LOGF_X, eIO_Closed, s_ID(), s_PushBack(), and SOCK_tag::sock. Referenced by CSocket::PushBack(), and s_SOCK_IO().

EIO_Status SOCK_Read (  SOCK  sock, void *  buf, size_t  size, size_t *  n_read, EIO_ReadMethod  how )

Read/peek up to "size" bytes from "sock" to the mem.buffer pointed by "buf". In "*n_read", return the number of successfully read bytes. Read method "how" can be either of the following: eIO_ReadPlain -- read as many as "size" bytes and return (eIO_Success); if no data are readily available then wait at most read timeout and return (eIO_Timeout) if no data still could be got; eIO_Success if some data were obtained. eIO_ReadPeek -- same as "eIO_ReadPlain" but do not extract the data from the socket (so that the next read operation will see the data again), with one important exception noted below. eIO_ReadPersist -- read exactly "size" bytes and return eIO_Success; if less data received then return an error condition (including eIO_Timeout). If there is no data available to read (also, if eIO_ReadPersist and cannot read exactly "size" bytes) and the timeout(see SOCK_SetTimeout) is expired then return eIO_Timeout. Both eIO_ReadPlain and eIO_ReadPeek return eIO_Success iff some data have been read (perhaps within the time allowance specified by eIO_Read timeout). Both mothods return any other code when no data at all were available. eIO_ReadPersist differs from the other two methods as it can return an error condition even if some data were actually obtained from the socket. Hence, as a rule of thumb, an application should always check the number of read bytes BEFORE checking the return status, which merely advises whether it is okay to read again. As a special case, "buf" may passed as NULL: eIO_ReadPeek -- read up to "size" bytes and store them in internal buffer; eIO_Read[Persist] -- discard up to "size" bytes from internal buffer and socket (check "*n_read" to know how many). NOTE 1: "Read" and "peek" methods differ: if "read" is performed and not enough but some data available immediately from the internal buffer, then the call completes with eIO_Success status. For "peek", if not all requested data were available, the real I/O occurs to pick up additional data (if any) from the system. Keep this difference in mind when programming loops that heavily use "peek"s without "read"s. NOTE 2: If on input "size" == 0, then "*n_read" is set to 0, and the return value can be either of eIO_Success, eIO_Closed or eIO_Unknown depending on connection status of the socket. Parameters: sock  [in] socket handle buf  [out] data buffer to read to size  [in] max # of bytes to read to "buf" n_read  [out] # of bytes read (can be NULL) how  [in] how to read the data Definition at line 4508 of file ncbi_socket.c. References CORE_LOGF_X, eIO_Closed, eIO_InvalidArg, eIO_ReadPeek, eIO_ReadPersist, eIO_ReadPlain, eIO_Success, s_ID(), s_Read(), and SOCK_tag::sock. Referenced by CSocket::Read(), s_FTPAbort(), s_Read(), s_SOCK_IO(), s_SockRead(), and s_VT_Read().

EIO_Status SOCK_ReadLine (  SOCK  sock, char *  buf, size_t  size, size_t *  n_read )

Read a line from SOCK. A line is terminated by either ' ' (with optional preceding '') or ''. Returned result is always ''- terminated and having ''(if any)' ' stripped. *n_read (if 'n_read' passed non-NULL) contains the numbed of characters written into 'buf' (not counting the terminating ''). If 'buf', whose size is specified via 'size' parameter, is not big enough to contain the line, all 'size' bytes will be filled, with *n_read == size upon return. Note that there will be no terminating '' in this (and the only) case, which the caller can easily distinguish. Parameters: sock  [in] socket handle buf  [out] data buffer to read to size  [in] max # of bytes to read to "buf" n_read  [out] # of bytes read (can be NULL) Returns: Return code eIO_Success upon successful completion, other - upon an error. Note that *n_read must be analyzed prior to return code, because the buffer could have received some contents before the indicated error occurred (especially when connection closed). Definition at line 4642 of file ncbi_socket.c. References CORE_LOGF_X, eIO_Closed, s_ID(), s_ReadLine(), and SOCK_tag::sock. Referenced by CSocket::ReadLine(), and s_ReadReply().

EIO_Status SOCK_Reconnect (  SOCK  sock, const char *  host, unsigned short  port, const STimeout *  timeout )

[CLIENT-side] Close the socket referred to by "sock" and then connect it to another "host:port"; fail if it takes more than "timeout" (close() + connect() [+ select()]) HINT: if "host" is NULL then connect to the same host address as before; if "port" is zero then connect to the same port # as before. NOTE 1: "new" socket inherits old I/O timeouts; NOTE 2: the call is only applicable to stream [not datagram] sockets. NOTE 3: "timeout"==NULL is infinite; "timeout"=={0,0} causes no wait for connection to be established and to return immediately. NOTE 4: UNIX sockets can only be reconnected to the same file thus both host and port have to be passed as 0s. Parameters: sock  [in] handle of the socket to reconnect host  [in] host to connect to (can be NULL) port  [in] port to connect to (can be 0) timeout  [in] the connect timeout (infinite if NULL) Definition at line 4163 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_InvalidArg, s_ID(), s_Reconnect(), and SOCK_tag::type. Referenced by CSocket::Reconnect(), and s_VT_Open().

ESwitch SOCK_SetDataLogging (  SOCK  sock, ESwitch  log )

Control the data logging for socket "sock" individually. Parameters: sock  [in] socket handle log  [in] requested data logging To reset to the global default behavior (as set by SOCK_SetDataLoggingAPI), call this function with "log" == eDefault. Returns: Prior setting See also: SOCK_SetDataLoggingAPI, SOCK_Create, DSOCK_Create Definition at line 591 of file ncbi_socket.c. References SOCK_tag::log. Referenced by CSocket::SetDataLogging().

ESwitch SOCK_SetDataLoggingAPI (  ESwitch  log  )

By default ("log" == eDefault, which is eOff), data are not logged. Parameters: log  To start logging the data, call this func with "log" == eOn. To stop logging the data, call this func with "log" == eOff. Returns: Prior setting See also: SOCK_SetDataLogging Definition at line 581 of file ncbi_socket.c. References eDefault, eOff, and s_Log. Referenced by CSocketAPI::SetDataLogging().

ESwitch SOCK_SetInterruptOnSignal (  SOCK  sock, ESwitch  on_off )

Control restartability of I/O interrupted by signals on a per-socket basis. eDefault causes the use of global API flag. Parameters: sock  [in] socket handle on_off  [in] per-socket I/O restart behavior on signals Returns: Prior setting. See also: SOCK_SetInterruptOnSignalAPI, SOCK_Create, DSOCK_Create Definition at line 4879 of file ncbi_socket.c. References SOCK_tag::i_on_sig. Referenced by CSocket::SetInterruptOnSignal().

ESwitch SOCK_SetInterruptOnSignalAPI (  ESwitch  on_off  )

Control restartability of I/O interrupted by signals. By default ("on_off" == eDefault,eOff), I/O is restartable if interrupted. Parameters: on_off  [in] eOn to cancel I/O on signals; eOff to restart Returns: Prior setting. See also: SOCK_SetInterruptOnSignal Definition at line 4869 of file ncbi_socket.c. References eDefault, eOff, and s_InterruptOnSignal. Referenced by CSocketAPI::SetInterruptOnSignal().

ESwitch SOCK_SetReadOnWrite (  SOCK  sock, ESwitch  on_off )

Control the reading-while-writing feature for socket "sock" individually. To reset to the global default behavior (as set by SOCK_SetReadOnWriteAPI), call this function with "on_off" == eDefault. Parameters: sock  [in] socket handle on_off  Returns: Prior setting. Definition at line 4858 of file ncbi_socket.c. References eDatagram, eDefault, SOCK_tag::r_on_w, and SOCK_tag::type. Referenced by CSocket::SetReadOnWrite().

ESwitch SOCK_SetReadOnWriteAPI (  ESwitch  on_off  )

By default ("on_off" == eDefault,eOff), sockets will not try to read data from inside SOCK_Write(). If you want to automagically upread the data (and cache it in the internal socket buffer) when the write operation is not immediately available, call this func with "on_off" == eOn. Parameters: on_off  Returns: Prior setting. Definition at line 4848 of file ncbi_socket.c. References eDefault, eOff, and s_ReadOnWrite. Referenced by CSocketAPI::SetReadOnWrite().

void SOCK_SetReuseAddress (  SOCK  sock, int  on_off )

Control reuse of socket addresses on per-socket basis Note: only a boolean parameter value is can be used here. Parameters: sock  [in] socket handle on_off  [in] whether to reuse the address (true, non-zero) or not (false, zero) See also: SOCK_SetReuseAddressAPI, SOCK_Create, DSOCK_Create Parameters: on_off  bool Definition at line 4895 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, eLOG_Warning, s_ID(), s_SetReuseAddress(), and SOCK_tag::sock. Referenced by CSocket::SetReuseAddress().

ESwitch SOCK_SetReuseAddressAPI (  ESwitch  on_off  )

Control address reuse for socket addresses taken by the API. By default ("on_off" == eDefault,eOff), address is not marked for reuse in SOCK, but is always reused for LSOCK. Parameters: on_off  [in] whether to turn on (eOn), turn off (eOff), or use default (eDefault) Returns: Prior setting. See also: SOCK_SetReuseAddress Definition at line 4887 of file ncbi_socket.c. References eOff, eOn, and s_ReuseAddress. Referenced by CSocketAPI::SetReuseAddress().

const STimeout* SOCK_SetSelectInternalRestartTimeout (  const STimeout *  timeout  )

This is a helper call that can improve I/O behavior. Parameters: timeout  [in] Break down long waits on I/O into smaller chunks of at most "timeout" duration each. This can help recover "hanging" sockets from indefinite wait and allow them to report an exceptional I/O condition. See also: SOCK_Wait, SOCK_Poll Definition at line 3019 of file ncbi_socket.c. References CORE_LOCK_WRITE, CORE_UNLOCK, s_SelectTimeout, s_to2tv(), and s_tv2to(). Referenced by CSocketAPI::SetSelectInternalRestartTimeout().

EIO_Status SOCK_SetTimeout (  SOCK  sock, EIO_Event  event, const STimeout *  timeout )

Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs). If "timeout" is NULL then set the timeout to be infinite; NOTE: the default timeout is infinite (wait "ad infinitum" on I/O). Parameters: sock  [in] socket handle event  [in] one of: eIO_[Read/Write/ReadWrite/Close] timeout  [in] new timeout value to set Definition at line 4440 of file ncbi_socket.c. References SOCK_tag::c_timeout, SOCK_tag::c_tv, CORE_LOGF_X, eIO_Close, eIO_InvalidArg, eIO_ReadWrite, eIO_Success, eIO_Write, SOCK_tag::r_timeout, SOCK_tag::r_tv, s_ID(), s_to2tv(), SOCK_tag::w_timeout, and SOCK_tag::w_tv. Referenced by CUNIXSocket::Connect(), CSocket::Connect(), CORE_SendMailEx(), CSocket::Reset(), s_DropConnection(), s_FTPAbort(), s_FTPExecute(), s_FTPLogin(), s_VT_Close(), s_VT_Read(), s_VT_Write(), CSocket::SetTimeout(), and URL_ConnectEx().

void SOCK_SetupSSL (  FSSLSetup  setup  )

Definition at line 6027 of file ncbi_socket.c. References s_SSLSetup.

EIO_Status SOCK_Shutdown (  SOCK  sock, EIO_Event  how )

Shutdown the connection in only one direction (specified by "direction"). Later attempts to I/O (or to wait) in the shutdown direction will do nothing, and immediately return with "eIO_Closed" status. Pending data output can cause data transfer to the remote end (subject for eIO_Close timeout as previously set by SOCK_SetTimeout). Cannot be applied to datagram sockets (eIO_InvalidArg results). Parameters: sock  [in] handle of the socket to shutdown how  [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite See also: SOCK_SetTimeout Definition at line 4193 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_Closed, eIO_InvalidArg, s_ID(), s_Shutdown(), SOCK_tag::sock, SOCK_tag::type, and SOCK_tag::w_timeout. Referenced by CSocket::Shutdown().

EIO_Status SOCK_ShutdownAPI (  void   )

Cleanup; destroy all internal/system data & resources used by the SOCK API. ATTENTION: no function from the SOCK API should be called after this call! NOTE: You can safely call it more than once; just, all calls after the first one will have no result. See also: SOCK_InitializeAPI Definition at line 801 of file ncbi_socket.c. References CORE_LOCK_WRITE, CORE_LOG_ERRNO_EXX, CORE_UNLOCK, eIO_NotSupported, eIO_Success, eLOG_Warning, SOCKSSL_struct::Exit, s_Initialized, s_SSL, and s_SSLSetup. Referenced by CId2FetchApp::Exit(), CId1FetchApp::Exit(), CSocketAPI::Shutdown(), and SOCK_InitializeAPI().

EIO_Status SOCK_Status (  SOCK  sock, EIO_Event  direction )

Return low-level socket I/O status of *last* socket operation. This call does not perform any I/O or socket related system calls. Parameters: sock  [in] socket handle direction  [in] one of: eIO_Open, eIO_Read, eIO_Write Returns: eIO_Closed -- if connection has either been shut down / closed (in corresponding direction for eIO_Read or eIO_Write), or not yet been attempted (for eIO_Open); eIO_Timeout -- if connection request has been submitted but not completed (i.e. it was still pending during last I/O); eIO_Interrupt -- if last data I/O was interrupted by a signal (applicable only to eIO_Read or eIO_Write); eIO_Unknown -- if an error has been detected during last data I/O (applicable only to eIO_Read or eIO_Write); eIO_InvalidArg -- if "direction" is not one of the allowed above; eIO_Success -- otherwise (also covers eIO_Timeout in last data I/O). NOTE: SOCK_Read(eIO_ReadPeek) and SOCK_Wait(eIO_Read) will not return any error as long as there is unread buffered data left. Thus, when you are "peeking" data (instead of reading it out), then the only "non-destructive" way to check whether an EOF or an error has actually occurred, it is to use this call. Definition at line 4758 of file ncbi_socket.c. References eIO_Closed, eIO_InvalidArg, eIO_Open, eIO_Success, eIO_Timeout, eIO_Write, SOCK_tag::pending, s_Status(), and SOCK_tag::sock. Referenced by CUNIXSocket::Connect(), CSocket::Connect(), CSocket::GetStatus(), s_FTPAbort(), s_Read(), and s_VT_Status().

const char* SOCK_StringToHostPort (  const char *  str, unsigned int *  host, unsigned short *  port )

Read (skipping leading blanks) "[host][:port]" from a string. Parameters: str  must not be NULL host  must not be NULL port  must not be NULL Returns: On success, return the advanced pointer past the host/port read. If no host/port detected, return 'str'. On format error, return 0. If host and/or port fragments are missing, then corresponding 'host'/'port' value returned as 0. Note that 'host' returned is in network byte order, unlike 'port', which always comes out in host (native) byte order. Definition at line 5955 of file ncbi_socket.c. Referenced by SERV_ReadInfoEx(), and CSocketAPI::StringToHostPort().

EIO_Status SOCK_Wait (  SOCK  sock, EIO_Event  event, const STimeout *  timeout )

Block on the socket until either the specified "event" is available or "timeout" expires (if "timeout" is NULL then assume it infinite). eIO_Open (as "event") can be used to check whether the socket has been connected. When eIO_Read is requested as an "event" for a datagram socket, then eIO_Closed results if the internally latched message has been entirely read out. Either of eIO_Open, eIO_Write and eIO_ReadWrite always succeed immediately for the datagram socket. Parameters: sock  [in] socket handle event  [in] one of: eIO_Open, eIO_Read, eIO_Write, eIO_ReadWrite timeout  [in] maximal time to wait for the event to occur Returns: eIO_Closed -- if the socket has been closed (in the specified direction when a read/write "event" requested); eIO_Success -- if the socket is ready; eIO_Unknown -- if partially closed with eIO_Open requested, or an I/O error occurred; eIO_Timeout -- if socket is not ready for the "event" and the allotted timeout has expired (for eIO_Open means the socket is still connecting); eIO_Interrupt -- if the call had been interrupted by a signal before any other verifiable status was available; eIO_InvalidArg -- if the "event" is not one of those mentioned above. NOTE: It is allowed to use a non-NULL zeroed STimeout to poll on the socket for the immediately available event and return it (or eIO_Timeout, otherwise) without blocking. Definition at line 4240 of file ncbi_socket.c. References BUF_Size(), CORE_LOGF_X, eDatagram, eIO_Close, eIO_Closed, eIO_InvalidArg, eIO_Open, eIO_ReadWrite, eIO_Success, eIO_Unknown, eIO_Write, eLOG_Note, eLOG_Warning, SOCK_tag::eof, eSocket, SOCK_tag::pending, SOCK_tag::r_buf, SOCK_tag::r_status, s_ID(), s_IsConnected(), s_SelectStallsafe(), s_to2tv(), SOCK_tag::sock, SOCK_tag::type, and SOCK_tag::w_status. Referenced by CORE_SendMailEx(), s_VT_Wait(), and CSocket::Wait().

EIO_Status SOCK_Write (  SOCK  sock, const void *  buf, size_t  size, size_t *  n_written, EIO_WriteMethod  how )

Write "size" bytes from buffer "buf" to "sock". Parameters: sock  [in] socket handle buf  [in] data to write to the socket size  [in] # of bytes (starting at "buf") to write n_written  [out] # of written bytes (can be NULL) how  [in] eIO_WritePlain | eIO_WritePersist Returns: In "*n_written", return the number of bytes actually written. eIO_WritePlain -- write as many bytes as possible at once and return immediately; if no bytes can be written then wait at most WRITE timeout, try again and return. eIO_WritePersist -- write all data (doing an internal retry loop if necessary); if any single write attempt times out or fails then stop writing and return (error code). Return status: eIO_Success -- some bytes were written successfully [Plain] -- all bytes were written successfully [Persist] other code denotes an error, but some bytes might have been sent nevertheless (always check *n_written to know). NOTE 1: With eIO_WritePlain the call returns eIO_Success iff some data were actually written to the socket. If no data could be written (and perhaps timeout expired) this call always returns an error. NOTE 2: eIO_WritePlain and eIO_WritePersist differs that the latter can flag an error condition even if some data were actually written (see "the rule of thumb" in the comments for SOCK_Read() above). NOTE 3: if "size"==0, return value can be eIO_Success if no pending data left in the socket, or eIO_Timeout if there are still data pending. In either case, "*n_written" is set to 0 on return. Definition at line 4673 of file ncbi_socket.c. References CORE_LOGF_X, eDatagram, eIO_Closed, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_WriteOutOfBand, eIO_WritePersist, eIO_WritePlain, s_ID(), s_Write(), SOCK_tag::sock, and SOCK_tag::type. Referenced by CNetBVSServer::ProcessOverflow(), s_FTPAbort(), s_SockWrite(), s_VT_Write(), s_WriteCommand(), and CSocket::Write().

EIO_Status TRIGGER_Close (  TRIGGER  trigger  )

Close an event trigger. Parameters: trigger  [in] a handle returned by TRIGGER_Create Returns: eIO_Success on success; other status on error See also: TRIGGER_Create Definition at line 3144 of file ncbi_socket.c. References CORE_LOGF_X, eDefault, eIO_NotSupported, eIO_Success, eLOG_Trace, eOn, TRIGGER_tag::fd, TRIGGER_tag::id, TRIGGER_tag::log, and s_Log. Referenced by CTrigger::~CTrigger().

EIO_Status TRIGGER_Create (  TRIGGER *  trigger, ESwitch  log )

Create an event trigger. Parameters: trigger  [in|out] a pointer to a location where to store handle of the new trigger Returns: eIO_Success on success; other status on error See also: TRIGGER_Close, TRIGGER_Set Definition at line 3037 of file ncbi_socket.c. References CORE_LOGF_ERRNO_EXX, CORE_LOGF_ERRNO_X, CORE_LOGF_X, CORE_TRACEF, eDefault, eIO_Closed, eIO_NotSupported, eIO_Success, eIO_Unknown, eLOG_Trace, eLOG_Warning, eOn, errno, eTrigger, FALSE, s_ID_Counter, s_InitAPI(), s_Log, s_SetNonblock(), and TRUE. Referenced by CTrigger::CTrigger().

EIO_Status TRIGGER_IsSet (  TRIGGER  trigger  )

Check whether the trigger has been set. Should not be used from multiple threads concurrently at a time. Parameters: trigger  [in] a handle returned by TRIGGER_Create Returns: eIO_Success if the trigger has been set; eIO_Closed if the trigger has not yet been set; other status on error See also: TRIGGER_Create, TRIGGER_Set, TRIGGER_Reset Definition at line 3210 of file ncbi_socket.c. References eIO_Closed, eIO_Success, eIO_Unknown, TRIGGER_tag::fd, and TRIGGER_tag::isset. Referenced by CTrigger::IsSet(), and TRIGGER_Reset().

EIO_Status TRIGGER_Reset (  TRIGGER  trigger  )

Reset trigger. Should not be used from multiple threads concurently. Parameters: trigger  [in] a handle returned by TRIGGER_Create Returns: eIO_Success if the trigger has been set; other status on error See also: TRIGGER_Create, TRIGGER_Set Definition at line 3262 of file ncbi_socket.c. References eIO_Closed, eIO_Success, eIO_Unknown, TRIGGER_tag::fd, TRIGGER_tag::isset, and TRIGGER_IsSet(). Referenced by CTrigger::Reset().

EIO_Status TRIGGER_Set (  TRIGGER  trigger  )

Set an event trigger. Can be used from many threads concurrently. Parameters: trigger  [in] a handle returned by TRIGGER_Create Returns: eIO_Success on success; other status on error See also: TRIGGER_Create, TRIGGER_IsSet Definition at line 3177 of file ncbi_socket.c. References CORE_LOG_X, eIO_NotSupported, eIO_Success, eIO_Unknown, errno, TRIGGER_tag::fd, TRIGGER_tag::isset, and NCBI_SwapPointers(). Referenced by CTrigger::Set().

---