12.7.8 Accessing the Diagnostic Code

The user may read the cause or diagnostic code in a Clear Indication or Reset Indication packet received from the remote end. The user may also write the cause or diagnostic code in Clear Request and Reset Request packets to be transmitted to the remote end.

typedef struct x25_cause_diag_s {
 u_char   flags;
 #   define RECV_DIAG    0
 #   define DIAG_TYPE   1
 #   define WAIT_CONFIRMATION 2
 /*  bit 0 (RECV_DIAG)=
  *  0: no cause and diagnostic codes
  *  1: receive cause and diagnostic codes.
  *  bit 1 (DIAG_TYPE)=
  *  0: reset cause and diagnostic codes in data array
  *  1: clear cause and diagnostic codes in data array
  *  bit 2 (WAIT_CONFIRMATION)=
  *  0: no wait after X25_WR_DIAG_CODE ioctl
  *  1: wait returned cause and diagnostic codes after
  *  X25_WR_DIAG_CODE ioctl.
  */
    u_char   datalen; /* byte count of data array */
    u_char   data[64];
 } X25_CAUSE_DIAG;
 X25_CAUSE_DIAG diag;
 int s, error; 

To read:

error = ioctl(s, X25_RD_CAUSE_DIAG, &diag);

To write:

error = ioctl(s, X25_WR_CAUSE_DIAG, &diag);

The data field in X25_CAUSE_DIAG contains the cause and diagnostic code.

Upon receiving a Clear Indication or Reset Indication packet, the X25_RD_CAUSE_DIAG ioctl may be issued to determine the cause and diagnostic associated with the packet. The datalen field contains the length in bytes of the information in data. When reading the diagnostic, if bit RECV_DIAG (that is, bit 0) is set, it indicates that the information in data is valid. If bit DIAG_TYPE (that is, bit 1) is set, it indicates that the diagnostic was received in a Clear Indication; otherwise, it was received in a Reset Indication.

The X25_WR_CAUSE_DIAG ioctl enables the user to send a Clear Request or Reset Request packet with the desired cause and diagnostic codes. If the user supplies only one byte in the data field, X.25 will use the cause code DTE_ORIGINATED, and use the provided byte as the diagnostic.

The X25_WR_CAUSE_DIAG ioctl call will send a Clear Request or Reset Request. To send a Clear Request, set bit DIAG_TYPE (that is, bit 1) in flags:

X25_CAUSE_DIAG diag;
 int s, error;
 diag.flags = 1 << DIAG_TYPE; /* Clear Request */
 diag.datalen = 2;
 diag.data[0] = 0;
 diag.data[1] = 67;
 error = ioctl(s, X25_WR_CAUSE_DIAG, &diag);

To send a Clear Request and wait for confirmation, set bit WAIT_CONFIRMATION (that is, bit 2) in flags:

X25_CAUSE_DIAG diag;
 int s, error;
 diag.flags = (1 << DIAG_TYPE) | (1 << WAIT_CONFIRMATION);
 diag.datalen = 2;
 diag.data[0] = 0;
 diag.data[1] = 67;
 error = ioctl(s, X25_WR_CAUSE_DIAG, &diag);

To send a Reset Request and wait for confirmation:

X25_CAUSE_DIAG diag;
 int s, error;
 diag.flags = 1 << WAIT_CONFIRMATION;
 diag.datalen = 2;
 diag.data[0] = 0;
 diag.data[1] = 0;   /* can be any valid diagnostic */
 error = ioctl(s, X25_WR_CAUSE_DIAG, &diag);

A close is still necessary to free all resources held by this socket and the associated virtual circuit after a Clear Indication or Clear Confirmation packet is received. After the DTE receives a Clear Indication packet, recv will return zero bytes after all unread data has been read. Calling send after the Clear Indication packet is received will not return an error. Note that this behavior is different from that of SunNet X.25 7.0, in which send does return an error.

To be notified when a Clear Indication packet is received, so that you can use the X25_RD_CAUSE_DIAG ioctl, you can use the following mechanism: Enable a third type of out-of-band data (see "12.5.4 Out-of-Band Data ") and receive the SIGURG signal when this type of out-of-band data arrives. To enable the signalling of Clear Indication packets, use the following ioctl:

error = ioctl(s, X25_OOB_ON_CLEAR, 0);

This will enable the reception of the following type of out-of-band data, which can be read with the X25_OOB_TYPE ioctl:

#define VC_CLEARED 31  /* virtual circuit cleared */

See "12.5.4 Out-of-Band Data " for a complete description of how to handle out-of-band data.

If an X25_WR_CAUSE_DIAG ioctl is not issued before close, X.25 fills an appropriate cause and diagnostic code in any Clear Request packet sent as a result (this will not happen if the connection is inactive at the time the call is issued).