ZINFO (3X)

NAME

zinfo - Get ZCOM table information

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
int32 zinfo (zap, mode, ibuf, len)
zaddr_type  *zap;
unit32      mode;
char        *ibuf;
int32       len;

DESCRIPTION

Routine zinfo is used to retrieve the contents of various ZCOM subsystem tables. Depending on the mode selected, it retrieves information such as the System Header, Interface Table, Logical and Physical Terminal Tables, ZLU descriptor table, or Node Entry table.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2). See the NOTES section below for more information on using this routine in a multi-threaded application.

PARAMETERS

zap	ZCOM address pointer. The node field is used to indicate from which node to retrieve the information. The uses of zlu and zcs depend on the specified mode.
mode	Type of information to return:
	ZcZLU_TBL	(0) - ZLU Descriptor information
	ZcLTT_TBL	(1) - Logical Terminal Table information
	ZcPTT_TBL	(2) - Physical Terminal Table information
	ZcHDR_TBL	(3) - Header information (zlu and zcs are not used)
	ZcIFT_TBL	(4) - Interface Table (zlu is the interface number, zcs is not used)
	ZcNODE_BYNUM	(5) - Node entry (zlu is the required node number, zcs is not used)
	ZcNODE_BYIDX	(6) - Node entry (zlu is the index within the node table, ranging from 0 to maximum-1, zcs is not used)
	Bit 15 - When this bit (ZCOM_ZINFO_NAVL) is set, zinfo will return the configured ZLU, Logical and Physical terminal information for non-available terminals. A non-available terminal ZLU would normally result in a "Terminal is not available" error (ZENAVL[-74]). This bit has no effect for modes ZcHDR_TBL, ZcIFT_TBL, ZcNODE_BYNUM or ZcNODE_BYIDX.
ibuf (Return Param)	Buffer for return data. The full description of the layout of the return buffer is contained in the Chapter 3, Tables and Data Structures section.
len	Maximum number of bytes to be returned in ibuf. If the specified length is smaller than the requested table size, a truncated section of the table is returned. If the specified length is larger, only the size of the requested table is returned.

NOTES

The returned logical terminal table (mode = ZcLTT_TBL) consists of the basic table and the logical terminal table extension (the extension size is configurable in the TTGEN configuration file). The size of this buffer should be large enough to hold the required information.

ATTENTION

Note that this call returns the contents of the internal tables used to implement the ZCOM subsystem. As such, these tables are subject to change from release-to-release and may require an application be recompiled in order to function correctly on a new release. The release notes for each new release will indicate whether a recomplilation is required.

RETURN VALUE

Routine zinfo returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

EXAMPLE

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h>
 
int32        ierr;
zaddr_type   zaddr;
uint32       mode;
char         ibuf[size]; /* "size" is user-determined, and is >= len */
int32        len;
 
if (ierr = zinfo (&zaddr, mode, ibuf, len)) {
          /* error return code */
}
else {
          /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).