$ZSOCKET()
$ZSOCKET()
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 |
|---|---|---|
| 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 |
| 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] | 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: ` |
| 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: ` |
| 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: ` |