$ZSOCKET()

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

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

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] 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