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