ZLUOPEN (3X)

NAME

zluopen - Open a ZLU file

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int zluopen (zap, mode, fd)
 
zaddr_type         *zap;
int                mode;
int                *fd;

DESCRIPTION

Routine zluopen opens the device file associated with a program ZLU for use with the standard HP-UX file access routines. The zap parameter points to the program ZLU to be accessed. If successful, a file descriptor for the opened program ZLU device file is returned through the fd pointer. The mode parameter is intended for a future enhancement and is not used at this time. For future compatibility, mode should be set to zero.

The zluopen routine only allows opening the device files for the range of program ZLUs in the local system. If zap specifies a terminal ZLU, or a ZLU on remote node, the request will also be rejected with an error.

In the current implementation of ZCOM, only the select and close functions are allowed on the returned file descriptor. Other operations (such as read and write) will result in error ENOSYS (Function is not available). A select for read on the returned file descriptor is to check whether input data is available on a program ZLU. A select on write on the returned file descriptor will always return TRUE, while a select on exception always returns FALSE.

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).

PARAMETERS

zap	ZCOM address (checksum is not used). Node must be zero or contain the local node as defined in the TTGEN configuration file.
mode	Open mode. Parameter is not used and should be specified as zero.
fd (Return Param)	Returned file descriptor. If zluopen is returned with error, this return parameter is undefined.

RETURN VALUE

Routine zluopen 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;
int                    mode;
int                    fd;
 
if (ierr = zluopen (&zaddr, mode, &fd)) {
       /* error return code */
}
else {
       /* good return code */
}

NOTES

The ZLU associated device files are kept in the /dev/zcom directory, and should only be opened by zluopen. If they are opened and accessed directly, incorrect results may be returned.

Currently, only device files for program ZLUs are required for the system. They are named as pzluNNNNN, where NNNNN is a number ranging from 00001 to 99999. The first program ZLU is associated with pzlu00001, the second one is associated with pzlu00002, etc. (E.g. in a system with 2000 terminal ZLUs, the first program ZLU, i.e. 2001, is associated with the device file /dev/zcom/pzlu00001.)

Note that these device files are created automatically by the ZCOM subsystem on an as needed basis.

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).
/dev/zcom/pzlu*	Device files associated with program ZLUs.