HPlogo X25/9000: X.25/9000 Programmer's Guide > Chapter 6 Extended Features

Obtaining programmatic diagnostics and status
» 

Technical documentation

Complete book in PDF

 » Table of Contents

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

Diagnostics and status information on applications that use X.25 programmatic access can be obtained via the following features:

  • Error codes and log messages.

  • The ioctl(X25_RD_CTI) call (to get the circuit table index entry associated with a particular socket).

  • The ioctl(X25_RD_LCI) call (to get the logical channel identifier associated with a particular virtual circuit).

  • The ioctl(X25_RD_HOSTADR) call (to get the X.121 address of the interface).

  • The ioctl(X25_GET_IFSTATE) call (to get the condition/state of the interface).

  • Remote and local address information (getpeername(2) and getsockname(2))

Each feature is described below.

Error codes and log messages

The most commonly-used programmatic diagnostic is the value returned by errno. Possible errno values returned for each call are listed in the man pages for this command.

In addition to the error codes returned, X.25 maintains a log which describes the activities of the interface and all active virtual circuits. For details on logging, refer to your X.25/9000 User's Guide.

The ioctl (X25_RD_CTI) Call

The ioctl(X25_RD_CTI) c all returns the circuit table index (cti) entry associated with a particular socket. This identifies one connection regardless of the interface that is used. The circuit table index entry is a sub-identification number (sid) which is also logged in strace output (see your man pages for strace). Once you know the cti entry for a socket, you can use that information when examining the X.25 log file for information concerning the VC. The cti is also useful for network logging. EINVAL is returned if the circuit is not connected or if the socket is no longer bound to a circuit. For details on logging, see your X.25/9000 User's Guide.

Syntax for ioctl (X25_RD_CTI)

#include <x25/x25ioctls.h>
#include <x25/x25str.h>
int err;
int sd, cti;
err = ioctl(sd, X25_RD_CTI, &cti);
sd

Is a socket descriptor for a connected SVC socket.

X25_RD_CTI

Is the definition for the request.

cti

Contains the circuit table index for the socket.

A programming example is shown below.

int error, s, cti;
/*
 * Assume at this point that s is a socket
 */
error = ioctl (s, X25_RD_CTI, &cti);
if (error 0) {
   perror("X25_RD_CTI");
   exit(1);
   }

The ioctl (X25_RD_LCI) Call

The ioctl(X25_RD_LCI) call returns the logical channel identifier (lci) associated with a particular virtual circuit. Once you know the lci entry for a circuit, you can use that information when examining statistics for a virtual circuit, with network logging and the corresponding data from a protocol-analyzer trace. The lci is the value written into the header of most CCITT X.25 packets.

Syntax for ioctl (X25_RD_LCI)

#include <x25/x25ioctls.h>
#include <x25/x25str.h>
int err;
int sd, lci;
err = ioctl(sd, X25_RD_LCI, &lci);
sd

Is a socket descriptor for a connected SVC socket.

X25_RD_LCI

Is the definition for the request.

lci

Contains the logical channel indicator for the socket.

err

Is set to 0 if the call was successful; otherwise, contains -1 and errno contains the cause of the error. If EINVAL is returned, the circuit is not connected or the socket is no longer bound to a circuit.

A programming example is shown below. 

int error, s, lci;
/*
 * Assume at this point that s is a socket
 */
error = ioctl (s, X25_RD_LCI, &lci);
if (error < 0) {
perror("X25_RD_LCI");
exit(1);
}
/* Use the lci as the logical circuit indicator. */

The ioctl (X25_RD_HOSTADR) call

The ioctl(X25_RD_HOSTADR) call returns the X.121 address of the interface. This is the X.121 address of the interface (NOT the address inserted in the call packet)

Syntax for ioctl (X25_RD_HOSTADR)

The ioctl(X25_RD_HOSTADR) and its parameters are described below.

#include <x25/x25ioctls.h>
#include <x25/x25addrstr.h>
int error;
int sd;
struct x25addrstr addr;
error = ioctl(sd, X25_RD_HOSTADR, &addr);
sd

Is a socket descriptor for an X.25 socket. Note that this can be a completely new socket, a connected socket or a connected socket that has been shutdown

X25_RD_HOSTADR

Is the definition for the request.

addr

Indicates the X.25 interface name. x25_family must be set to AF_CCITT. x25ifname must be set to a name string (with "\0" at the end). The address is returned in x25hostl() and x25hostlen.

x25ifname can be an empty string, but this is only advised when there is only one interface on the system; the interface address returned is unpredictable when there are several interfaces.

error

Is set to 0 if the call was successful; otherwise, contains -1 and errno contains the cause of the error.

A programming example is shown below. 

/* Get X.25 parameters used for binding an address */
result = ioctl( call_soc, X25_RD_HOSTADR, &locl_addr);
if (result == -1) {
perror("ioctl(X25_RD_HOSTADR) call");
exit(1);
}

The ioctl (X25_GET_IFSTATE) call

The ioctl(X25_GET_IFSTATE) call returns the interface state.

Syntax for ioctl (X25_GET_IFSTATE)

#include <x25/x25ioctls.h>
#include <x25/x25str.h>
#include <x25/x25.h>
/*
 * Define data structure for X25_GET_IFSTATE
 */
/* struct x25_state_str {
 * char ifname[X25_MAX_IFNAMELEN+1];/* Name of X.25 
interface to use */
 * int ifstate; /* Status of the X.25 interface */
 * };
 */
int error;
int sd;
struct x25_state_str state_str;
error = ioctl(sd, X25_GET_IFSTATE, &state_str);
sd

Is a socket descriptor for an X.25 socket. Note that this can be a completely new socket, a connected socket or a connected socket that has been shutdown.

X25_GET_IFSTATE

Is the definition for the request.

state_str

Contains the state of the interface.

The state of the interface is returned in ifstate and can take the following values:

IFSTATE_UNINI T The interface has been stopped IFSTATE_INIT Level 3 is up (R1) IFSTATE_L2DOWN Level 3 is down (not R1)

error

Is set to 0 if the call was successful; otherwise, contains -1 and errno contains the cause of the error.

A programming example is shown below. 

/* Get if state */
result = ioctl( call_soc, X25_GET_IFSTATE, &if_state);
if (result == -1) {
perror("ioctl(X25_GET_IFSTATE) call");
exit(1);
}

Obtaining Status Information Programmatically

X.25 uses two system calls that return information regarding the status of a circuit. They are getpeername() to obtain the address of the remote DTE, and getsockname() to obtain the address of the local DTE.

Using getpeername() after a call has been established, a process can obtain the caller's address from the calling address field of the CALL ACCEPTED/INDICATION packet.

Using getsockname() after a call has been established, a process can obtain the called address from the CALL ACCEPTED/INDICATION packet. getsockname() can be used to obtain the actual called address when wildcard addressing is being used.

Syntax for getpeername()

The getpeername() and its parameters are described below.

#include <sys/types.h>
#include <sys/socket.h>
#include <x25/x25addrstr.h>
	 
int error;
int sd, addrlen;
struct x25addrstr addr;
addrlen = sizeof(struct x25addrstr);
error = getpeername(sd, &addr, addrlen);
sd

Is the socket descriptor for the socket whose peer address will be obtained.

addr

Upon successful completion, this x25addrstr structure will contain the X.121 address of the remote DTE. This information is useful when using wildcard addressing and when reestablishing a terminated connection.

addrlen

Upon successful completion, this integer will contain the length in bytes of the x25addrstr structure pointed to by addr. Before calling getpeername(), this field must be initialized with the size of the x25addrstr structure.

error

If the call successfully completes, error contains a 0; otherwise, -1 is returned, and errno contains the cause of the error.

Refer to the getpeername(2) entry in man pages for more information on this command.

Syntax for getsockname()

The getsockname() and its parameters are described below.

#include <sys/types.h>
#include <sys/socket.h>
#include <x25/x25addrstr.h>
	 
int error;
int sd, addrlen;
struct x25addrstr addr;
addrlen = sizeof(struct x25addrstr);
error = getsockname(sd, &addr, &addrlen);
sd

Is the socket descriptor for the socket whose addressing information is being obtained.

addr

Upon successful completion, this x25addrstr structure will contain the X.121 address specified by the remote process to make the connection. This information is useful when using wildcard addressing.

addrlen

Upon successful completion, this integer will contain the length in bytes of the x25addrstr structure pointed to by addr. Before calling getpeername(), this field must be initialized with the size of the x25addrstr structure.

error

If the call successfully completes, error contains a 0; otherwise, -1 is returned, and errno contains the cause of the error.

Refer to the getsockname(2) entry in your man pages for more information.



Reestablishing Terminated Connections
  		 


Appendix A  X.25 Packet Formats