GSINIT(3g,L) AIX Technical Reference GSINIT(3g,L)
-------------------------------------------------------------------------------
gsinit
PURPOSE
Initializes the GSL subroutines.
C SYNTAX
int gsinit_ (buffer, size, save_restore, f_grant, f_retract, fildes)
int *buffer, *size, *save_restore;
int (*f_grant) ( ), (*f_retract) ( );
int *fildes;
FORTRAN SYNTAX
INTEGER function gsinit (buffer, size, save_restore, f_grant,
f_retract, fildes)
INTEGER buffer (*), size, save_restore, fildes
EXTERNAL f_grant, f_retract
PASCAL SYNTAX
FUNCTION gsinit_ (
VAR buffer: ARRAY [0..k] of INTEGER;
VAR size, save_restore, f_grant, f_retract, fildes: INTEGER
): INTEGER [PUBLIC];
DESCRIPTION
The gsinit subroutine initializes the GSL. It allocates any private storage
required, and sets attributes to the default values where necessary. It also
forces the virtual terminal of the application to Monitor Mode and sets up the
signal processing routines for the SIGRETRACT and SIGGRANT signals, and
optionally, the SIGMSG signal.
Parameters
buffer Defines the Monitor Mode input ring buffer to be used by the
GSL input functions. buffer must be word aligned and at
least 128 bytes long. For output to a printer or plotter
device, set the buffer parameter to -1. (In C, buffer is a
pointer to an integer containing the value -1. In Pascal, it
is a variable containing the value -1.)
size Defines the length of buffer in bytes. Depending on the
value of size, gsinit performs the following actions:
Processed November 7, 1990 GSINIT(3g,L) 1
GSINIT(3g,L) AIX Technical Reference GSINIT(3g,L)
size=0 The GSL ignores the buffer parameter and does not
provide input support. The application must provide a
means for receiving input events and can use the read
system call or set up its own ring buffer mechanism.
size<128 The gsinit subroutine does not initialize the GSL.
size=>128 The GSL establishes the virtual terminal linkage to
the input ring buffer provided by the application and
provides input support and sets up a SIGMSG signal
catcher.
save_restore Determines whether to save the display frame buffer and
adapter states.
If save_restore is nonzero, the GSL saves the current
contents of the display frame buffer as well as the current
adapter state when the virtual terminal must become inactive
and restores both the frame buffer contents and adapter state
when it becomes active.
If save_restore is 0, the GSL saves only the adapter state
and assumes that the application either saves the frame
buffer or reconstructs it in some fashion.
f_grant Sets up processing of the SIGGRANT signal. If f_grant is
nonzero, it is assumed to be the address of an application
supplied function, and the GSL calls the function as part of
the SIGGRANT signal handling. If save_restore is nonzero,
the application function is called before the frame buffer is
restored.
f_retract Sets up processing of the SIGRETRACT signal. If f_retract is
nonzero, it is assumed to be the address of an application
supplied function, and the GSL calls the function as part of
the SIGRETRACT signal handling.
fildes Determines where output is directed. The output device is
specified by one of the following:
o The value -1, which specifies standard output.
o A file descriptor returned by a creat, open, dup, or
fcntl system call.
o A null-terminated character string up to 11 characters
long, which names an environment variable defining a
printer or plotter device. In this case, the value of
the buffer parameter must be -1.
Processed November 7, 1990 GSINIT(3g,L) 2
GSINIT(3g,L) AIX Technical Reference GSINIT(3g,L)
(In C, fildes is a pointer to a file descriptor, an integer,
or a character string. In Pascal, it is a variable
containing one of these values.)
If the initialization process is unsuccessful, the virtual terminal is not
placed in Monitor Mode and invocation of any other GSL routines will cause
unpredictable results.
For printers or plotters, if initialization is unsuccessful, the application
can either terminate or re-drive the initialize function with a valid character
string as a means of correcting the problem.
For Pascal, the application must declare the arrays passed as being fixed
length and declare the routine as accepting arrays of that length; that is, the
k in the routine declaration must be a constant.
Pascal cannot directly provide the address of a routine. An assembler function
may be used to derive the address of a routine passed to the GSL.
The f_grant and f_retract routines supplied by the application are called on
the signal level and must return. These application routines must not use
either setjmp or longjmp subroutines.
The GSL supports use of the sdb symbolic debugger on the RT PC and the dbx
symbolic debugger on the PS/2 by redirection to a supplied file descriptor. If
two virtual terminals are open and the GSL application runs on one, the
application may get the file descriptor for the second and supply that
descriptor at GSL initialization. The GSL directs its output to the second
virtual terminal while sdb on the RT PC and dbx on the PS/2 directs its output
to the first; either is activated in the standard manner.
The user routine called at SIGGRANT can be called before gsinit returns to the
application.
RETURN VALUE
GS_SUCC Successful.
GS_HBUS Cannot access hardware bus.
GS_ADPT Invalid display type.
GS_FONT Cannot access default font.
GS_RING Buffer too small.
GS_HDCP Invalid file descriptor for hard copy output.
GS_HDLK Unable to create lock file.
GS_HDIM Insufficient memory.
GS_HDDB Device is busy.
GS_HDNA Physical device not attached.
GS_HDMG Maximum number of graphics devices open.
GS_HDIF No system interprocess communication buffers left.
GS_HDSF The fork system call failed.
GS_HDGO Specified graphics device already open.
GS_HDGN Specified graphics device does not exist.
GS_HDGU Specified graphics device driver is unknown.
Processed November 7, 1990 GSINIT(3g,L) 3