cursutil(3X) cursutil(3X)

NAME
       ddeellaayyoouuttppuutt, ffiilltteerr, fflluusshhiinnpp, ggeettwwiinn, kkeeyynnaammee, kkeeyynnaammee, ppuuttwwiinn,
       uunnccttrrll, uusseeeennvv, wwuunnccttrrll - miscellaneous ccuurrsseess utility routines

SYNOPSIS
       ##iinncclluuddee <>

       cchhaarr **uunnccttrrll((cchhttyyppee cc));;
       cchhaarr **wwuunnccttrrll((cccchhaarrtt **cc));;
       cchhaarr **kkeeyynnaammee((iinntt cc));;
       cchhaarr **kkeeyynnaammee((wwcchhaarrtt ww));;
       vvooiidd ffiilltteerr((vvooiidd));;
       vvooiidd uusseeeennvv((bbooooll ff));;
       iinntt ppuuttwwiinn((WWIINNDDOOWW **wwiinn,, FFIILLEE **ffiilleepp));;
       WWIINNDDOOWW **ggeettwwiinn((FFIILLEE **ffiilleepp));;
       iinntt ddeellaayyoouuttppuutt((iinntt mmss));;
       iinntt fflluusshhiinnpp((vvooiidd));;

DESCRIPTION
       The uunnccttrrll routine returns a character string which is a printable rep-
       resentation  of  the character c, ignoring attributes.  Control charac-
       ters are displayed in the ^^X notation.  Printing  characters  are  dis-
       played  as is.  The corresponding wwuunnccttrrll returns a printable represen-
       tation of a wide-character.

       The kkeeyynnaammee routine returns a character string corresponding to the key
       c.   Control characters are displayed in the ^^X notation.  Values above
       128 are either meta characters, shown in the MM-X notation, or the names
       of  function keys, or null.  The corresponding kkeeyynnaammee returns a char-
       acter string corresponding to the  wide-character  value  w.   The  two
       functions  do  not  return  the same set of strings; the latter returns
       null where the former would display a meta character.

       The ffiilltteerr routine, if used, must be called before iinniittssccrr  or  nneewwtteerrmm
       are called.  The effect is that, during those calls, LLIINNEESS is set to 1;
       the capabilities cclleeaarr, ccuupp, ccuudd, ccuudd11, ccuuuu11, ccuuuu,  vvppaa  are  disabled;
       and the hhoommee string is set to the value of ccrr.

       The  uusseeeennvv  routine, if used, is called before iinniittssccrr or nneewwtteerrmm are
       called.  When called with FFAALLSSEE as an argument, the values of lliinneess and
       ccoolluummnnss  specified in the terminfo database will be used, even if envi-
       ronment variables LLIINNEESS and CCOOLLUUMMNNSS (used by default) are  set,  or  if
       ccuurrsseess  is running in a window (in which case default behavior would be
       to use the window size if LLIINNEESS and CCOOLLUUMMNNSS are not  set).   Note  that
       setting  LLIINNEESS or CCOOLLUUMMNNSS overrides the corresponding size which may be
       obtained from the operating system.

       The ppuuttwwiinn routine writes all data associated with window win into  the
       file  to  which  filep points.  This information can be later retrieved
       using the ggeettwwiinn function.

       The ggeettwwiinn routine reads window related data  stored  in  the  file  by
       ppuuttwwiinn.   The  routine  then creates and initializes a new window using
       that data.  It returns a pointer to the new window.

       The ddeellaayyoouuttppuutt routine inserts an ms  millisecond  pause  in  output.
       This  routine should not be used extensively because padding characters
       are used rather than a CPU pause.  If no padding  character  is  speci-
       fied, this uses nnaappmmss to perform the delay.

       The  fflluusshhiinnpp  routine throws away any typeahead that has been typed by
       the user and has not yet been read by the program.

RREETTUURRNN VVAALLUUEE
       Except for fflluusshhiinnpp, routines that return an integer  return  EERRRR  upon
       failure  and OOKK (SVr4 specifies only "an integer value other than EERRRR")
       upon successful completion.

       Routines that return pointers return NNUULLLL on error.

       X/Open does not define any error conditions.  In this implementation

              fflluusshhiinnpp
                   returns an error if the terminal was not initialized.

              ppuuttwwiinn
                   returns an error if the associated ffwwrriittee calls  return  an
                   error.

PPOORRTTAABBIILLIITTYY
       The  XSI Curses standard, Issue 4 describes these functions.  It states
       that uunnccttrrll and wwuunnccttrrll will return a null pointer if unsuccessful, but
       does not define any error conditions.

       The  SVr4  documentation  describes  the  action  of ffiilltteerr only in the
       vaguest terms.  The description here is adapted  from  the  XSI  Curses
       standard (which erroneously fails to describe the disabling of ccuuuu).

       The strings returned by uunnccttrrll in this implementation are determined at
       compile time, showing C1 controls from the upper-128 codes with  a  `~'
       prefix rather than `^'.  Other implementations typically show both sets
       of control characters with `^', and may strip the parameter to 7  bits.
       This  implementation  uses 8 bits but does not modify the string to re-
       flect locale.

       The kkeeyynnaammee function may return the names of user-defined string  capa-
       bilities  which  are defined in the terminfo entry via the -xx option of
       ttiicc.

SEE ALSO
       ccuurrsseess(3X), ccuurrssiinniittssccrr(3X), ccuurrsskkeerrnneell(3X), ccuurrssssccrrdduummpp(3X).



                                                                 cursutil(3X)