GETDEVICE (3X)

NAME

getdevice - Read ZCOM device definitions

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
     int getdevice (dfile, dpp)
     char                  *dfile;
zdev_type        **dpp;

DESCRIPTION

Routine getdevice reads the ZCOM device file specified by the dfile parameter and loads the device definition entries into a memory table. The pointer to the device definition table is returned (see zdev type definition below).

If dfile is NULL, it uses the default /opt/acc/cfg/zcomdevice. The ZCOM device file is a binary file created by the ZDGEN program, from a user-customizable ASCII file (usually /opt/acc/cfg/zcomdevice.txt). Refer to the section on zdgen in the Multiprotocol ACC Utilities Reference Guide for more details.

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

dfile	Pointer to the full path name of a binary zdgen device file. That is, the output file from the zdgen program. If a NULL is passed, it defaults to the file specified by the symbol ZCOM_DEVICE_FILE), which is currently defined as /opt/acc7cfg/zcomdevice in the include file /opt/acc/include/zcom/zcomsys.h
dpp (Return param)	Pointer to a data structure containing the full device table. The device table is an array of zdev_type elements.

RETURN VALUE

Routine getdevice, when successful, returns a non-negative value, indicating the number of device types. That is, it returns the number of zdev_type entries in the device table. Otherwise, it returns a negative value, and the user should check errno to determine why getdevice failed.

NOTES

On every call to getdevice, malloc(3C) is called to allocate dynamic memory for the returned device table. In case of error, this function will release the allocated memory internally to avoid memory leak. On successful return, the caller is responsible for freeing the allocated memory when it is no longer needed.
In a multi-threaded application, if thread cancellation occurs while calling this function, the allocated memory will be released before the thread terminates. Once this function returns, the calling thread is responsible for freeing the allocated memory during thread cancellation.

The following is the zdev_type data structure definition (from /opt/acc/include/zcom/zcomsys.h).

/*-- ZCOM Device Entries --*/
typedef struct {
    char dvname[16]; /* Device name */
    uint16 dptype;    /* Physical type (i.e., protocol number) */
    uint16 dltype;   /* Logical type (i.e., screen type) */
    uint16 dalen     /* Poll/Select address length (0,1,2) */
    uint16 damin;    /* Lower bound of address */
    uint16 damax;    /* Upper bound of address */
    uint16 doptn;    /* Protocol options */
    uint16 dlflag;   /* Logical terminal flags */
    char dpname[8];  /* Protocol module name */
} zdev_type;

EXAMPLE

        #include        <zcom/zcomsys.h>
        #include        <zcom/zcomcall.h> 
 
        int32        ierr;
        char         *dfile;
        zdev_type    *dp;
 
        ierr = getdevice (dfile, &dp);
        if (ierr < 0) {
        /* (error; user to check errno) */
        } 
        else {
        /* (success; ierr indicates number of device types) */
        }

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note: 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).
/opt/acc/cfg/zcomdevice.txt	User-customizable ASCII file used by ZDGEN to create the binary ZCOM device file, /opt/acc/cfg/zcomdevice. Refer to the section on ZDGEN in the Multiprotocol ACC Utilities Reference Guide for more details.
/opt/acc/cfg/zcomdevice	Binary ZCOM device file created by ZDGEN, using the user-customizable ASCII file, /opt/acc/cfg/zcomdevice.txt. Refer to the section on ZDGEN in the Multiprotocol ACC Utilities Reference Guide for more details.