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)
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 |
---|---|---|
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). |
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. |
|
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. |
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. |
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:
|
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:
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 SSLv3 by default. |
CIPHER |
The SSL protocol version prefixed by "P:" and the algorithm negotiated between the server and client prefixed by "C:". Here is an example:
|
ALL |
returns all available information. Here is an example:
|