$ZSOCKET()

$ZSOCKET()
Prev	Chapter 7. Functions	Next

Returns information about a SOCKET device and its attached sockets. The format of the $ZSOCKET() function is:

$ZSOCKET(expr1,expr2[,[expr3][,expr4]])

The first expression specifies the SOCKET device name; an empty string returns the same result as the current device ($IO). If the first expression is not specified, $ZSOCKET() returns information about sockets in the socketpool. Specifying a device other than a SOCKET device for the $ZSOCKET() function produces a ZSOCKETNOTSOCK error. When a GT.M process starts with different sockets for input and output on $PRINCIPAL, $ZSOCKET() accepts $ZPIN or $ZPOUT as its first argument and supplies information on the input or output side, respectively. The following is an example of getting the handles for the $PRINCIPAL input and output socket devices.
```
 set handlein=$ZSOCKET($ZPIN,"SOCKETHANDLE",0)
 set handleout=$ZSOCKET($ZPOUT,"SOCKETHANDLE",0)
```
For more information, refer to “$ZPIN” and “$ZPOUT”.
The second expression specifies a keyword identifying the type of information returned and the optional third expression usually specifies the index (starting at zero) of a socket attached to the device; if the index is outside the range of attached sockets, $ZSOCKET() returns an empty string. If the third expression is not specified, $ZSOCKET() returns information about the current socket. Using an invalid keyword produces a ZSOCKETATTR error. The fourth expression specifies an individual delimiter when the second expression specifies DELIMITER. For more information, see the following table. Note that changes to the socket collection for a SOCKET device using OPEN, CLOSE, USE :ATTACH, or USE :DETACH may change the index for a socket.

Keyword	Arguments	Returns
BLOCKING	index	1 (TRUE) for blocking otherwise 0 (FALSE) for non-blocking WRITEs
CURRENTINDEX		The index (starting at zero) of the current socket for the SOCKET device.
DELIMITER	index[, delimiter]	If only index is specified, the number of delimiters. If delimiter is also specified, selects which delimiter to return. The first delimiter is zero.
DESCRIPTOR	index	The OS socket descriptor for the socket.
HOWCREATED	index	LISTEN, CONNECT, ACCEPTED, PRINCIPAL, or PASSED ACCEPTED indicates a connection created from a LISTENing socket. PRINCIPAL indicates that the socket is the $PRINCIPAL of the process. PASSED indicates a socket passed by WRITE /ACCEPT.
INDEX	handle	The current index of the socket named by handle.
IOERROR	index	1 (TRUE) if IOERROR=TRAP otherwise 0 (FALSE).
KEEPALIVE	index	A non zero value if SO_KEEPALIVE is enabled.
KEEPCNT	index	The value of TCP_KEEPCNT.
KEEPIDLE	index	The value of TCP_KEEPIDLE in seconds.
KEEPINTVL	index	The value of TCP_KEEPINTVL in seconds.
LOCALADDRESS	index	The address of the local side of the socket. For TCP sockets: the IPv6 or IPv4 numeric address. For LOCAL sockets: the path.
LOCALPORT	index	The numeric port of the local side of a TCP socket.
MOREREADTIME	index	The value of the MOREREADTIME device parameter if it was specified, otherwise an empty string.
NUMBER		The number of sockets in the SOCKET device.
OPTIONS	index	a string of the “OPTIONS” previously specified for the selected socket. The string may not exactly match the string originally specified but has the same meaning.
PARENT	index	If the socket was created from a LISTENing socket: the handle of the LISTENing socket.
PROTOCOL	index	TCP, TCP6, or LOCAL
REMOTEADDRESS	index	The address of the remote side of the socket. For TCP sockets: the IPv6 or IPv4 numeric address. For LOCAL sockets: the path.
REMOTEPORT	index	The numeric port of the remote side of a TCP socket.
SNDBUF	index	Size of the OS send buffer in bytes (SO_SNDBUF).
SOCKETHANDLE	index	The handle for the selected socket.
STATE	index	One of LISTENING, CONNECTED, BOUND, or CONNECTINPROGRESS
TLS	index[,expr4]	If the selected socket is using TLS, a string of the form: 1,{SERVER\|CLIENT}[,tlsid], where the optional tlsid comes from the WRITE /TLS which enabled TLS on the socket; otherwise an empty string. See the following table for a description of all options for the fourth expression for the TLS keyword.
ZBFSIZE	index	Size of the GT.M buffer in bytes.
ZFF	index	The value of the ZFF device parameter.
ZIBFSIZE	index	Size of the OS buffer in bytes (SO_RCVBUF).
ZDELAY	index	1 if Nagle algorithm enabled, otherwise 0.

	Note
	The getsockopt() keywords (KEEPALIVE, KEEPCNT, KEEPIDLE, KEEPINTVL, SNDBUF, and ZIBFSIZE return two values if the value previously specified with the “OPTIONS” or "ZIBFSIZE" device parameter doesn't match the system's current value. The two values are separated by a semicolon (";"):"uservalue;systemvalue".

The following table describes the values for the fourth expression for the TLS keyword.

expr4 (TLS)	Description
SESSION	Returns information related to SSL sessions including information about renegotiations. Here is an example: `\|S:RENSEC:1,RENTOT:1,SESSID:<SESSID>, SESEXP:Thu Jun 4 21:07:11 2015` `"\|S:"` denotes this piece contains session information, `"RENSEC:"` indicates whether secure renegotiation is available (1) or not (0), `"RENTOT:"` gives the current total number of renegotiations done on this socket, `"SESSID:"` shows the session id in hexadecimal, and `"SESEXP:"` indicates when the session expires respresented as time in the local time zone.
OPTIONS	the hexadecimal representation of the ssl-options selected by the combination of the OpenSSL defaults, options set by the GT.M TLS plugin, and options specified in the gtmcrypt_config configuration file prefixed by "O:", a comma, and the verify mode as two hexadecimal digits. Here is an example: `\|O:0000000001520004,01` The values for the SSL_OP options and verify modes are defined in the include/openssl/ssl.h file provided by the OpenSSL development package. Note: the TLS reference implementation plug-in disables protocols prior to TLSv1.2.
CIPHER	The SSL protocol version prefixed by "P:" and the algorithm negotiated between the server and client prefixed by "C:". Here is an example: `\|P:TLSv1.2\|C:DHE-RSA-AES256-SHA`
ALL	returns all available information. Here is an example: `\|P:TLSv1.2\|C:AES256-GCM-SHA384\|O:0000000001020004,01\|S:RENSEC:1,RENTOT:0,SESEXP:Mon Jun 22 23:58:09 2015`

Prev	Up	Next
$ZREPLACE()	Home	$ZSYSLOG()