libwindows(3X)                                               libwindows(3X)


   NAME
         libwindows - windowing terminal function library

   SYNOPSIS
         cc [flag ...] file ...  -lwindows [library ...]

         int openagent (void);
         int New (int cntlfd, int originx, int originy,
           int cornerx, int cornery);
         int Newlayer (int cntlfd, int originx, int originy,
           int cornerx, int cornery);
         int openchan (int chan);
         int Runlayer (int chan, char *command);
         int Current (int cntlfd, int chan);
         int Delete (int cntlfd, int chan);
         int Top (int cntlfd, int chan);
         int Bottom (int cntlfd, int chan);
         int Move (int cntlfd, int chan, int originx, int originy);
         int Reshape (int cntlfd, int chan, int originx, int originy,
           int cornerx, int cornery);
         int Exit (int cntlfd);

   DESCRIPTION
         This library of routines enables a program running on a host UNIX
         system to perform windowing terminal functions [see layers(1)].

         The openagent routine opens the control channel of the xt(7) channel
         group to which the calling process belongs.  Upon successful
         completion, openagent returns a file descriptor that can be passed to
         any of the other libwindows routines except openchan and Runlayer.
         (The file descriptor can also be passed to the close system call.)
         Otherwise, the value -1 is returned.

         The New routine creates a new layer with a separate shell.  The
         origin_x, origin_y, corner_x, and corner_y arguments are the
         coordinates of the layer rectangle.  If all the coordinate arguments
         are 0, the user must define the layer's rectangle interactively.  The
         layer appears on top of any overlapping layers.  The layer is not
         made current (i.e., the keyboard is not attached to the new layer).
         Upon successful completion, New returns the xt(7) channel number
         associated with the layer.  Otherwise, the value -1 is returned.

         The Newlayer routine creates a new layer without executing a separate
         shell.  Otherwise it is identical to New, described above.

         The openchan routine opens the channel argument chan which is
         obtained from the New or Newlayer routine.  Upon successful
         completion, openchan returns a file descriptor that can be used as
         input to write(2) or close(2).  Otherwise, the value -1 is returned.




   7/91                                                                 Page 1

   libwindows(3X)                                               libwindows(3X)


         The Runlayer routine runs the specified command in the layer
         associated with the channel argument chan.  This layer is usually a
         layer previously created with Newlayer.  Any processes currently
         attached to this layer will be killed, and the new process will have
         the environment of the layers process.

         The Current routine makes the layer associated with the channel
         argument chan current (i.e., attached to the keyboard).

         The Delete routine deletes the layer associated with the channel
         argument chan and kills all host processes associated with the layer.

         The Top routine makes the layer associated with the channel argument
         chan appear on top of all overlapping layers.

         The Bottom routine puts the layer associated with the channel
         argument chan under all overlapping layers.

         The Move routine moves the layer associated with the channel argument
         chan from its current screen location to a new screen location at the
         origin point (origin_x, origin_y).  The size and contents of the
         layer are maintained.

         The Reshape routine reshapes the layer associated with the channel
         argument chan.  The arguments origin_x, origin_y, corner_x, and
         corner_y are the new coordinates of the layer rectangle.  If all the
         coordinate arguments are 0, the user is allowed to define the layer's
         rectangle interactively.

         The Exit routine causes the layers program to exit, killing all
         processes associated with it.

   FILES
         ULIBDIR/libwindows.a   windowing terminal function library
         ULIBDIR   usually /usr/lib

   SEE ALSO
         close(2), write(2), jagent(5).
         layers(1) in the User's Reference Manual.

   DIAGNOSTICS
         Upon successful completion, Runlayer, Current, Delete, Top, Bottom,
         Move, Reshape, and Exit return 0, while openagent, New, Newlayer, and
         openchan return values as described above under each routine.  If an
         error occurs, -1 is returned.

   NOTES
         The values of layer rectangle coordinates are dependent on the type
         of terminal.  This dependency affects the routines that pass layer
         rectangle coordinates:  Move, New, Newlayer, and Reshape.  Some
         terminals will expect these numbers to be passed as character


   Page 2                                                                 7/91

   libwindows(3X)                                               libwindows(3X)


         positions (bytes); others will expect the information to be in pixels
         (bits).

         It is recommended that applications use /dev/xt/??[0-7] instead of
         /dev/xt??[0-7] when accessing the xt driver.
















































   7/91                                                                 Page 3