UNVIS(3)                       Library Routines                       UNVIS(3)




NAME

       unvis, strunvis - decode a visual representation of characters


SYNOPSIS

       #include <vis.h>

       int unvis (char *cp, int c, int *astate, int flag)
       int strunvis (char *dst, const char *src)


DESCRIPTION

       The  unvis and strunvis functions are used to decode a visual represen-
       tation of characters, as produced by the vis(3) function, back into the
       original form.  Unvis is called with successive characters in c until a
       valid sequence is recognized, at which time the  decoded  character  is
       available  at  the  character  pointed  to by cp.  Strunvis decodes the
       characters pointed to by src into the buffer pointed to by dst.

       The strunvis function simply copies src to  dst,  decoding  any  escape
       sequences  along  the  way, and returns the number of characters placed
       into dst, or -1 if an invalid escape sequence was detected.   The  size
       of  dst should be equal to the size of src (that is, no expansion takes
       place during decoding).

       The unvis function implements a state  machine  that  can  be  used  to
       decode  an  arbitrary  stream  of bytes.  All state associated with the
       bytes being decoded is stored outside the unvis function  (that  is,  a
       pointer to the state is passed in), so calls decoding different streams
       can be freely intermixed.  To start decoding a stream of  bytes,  first
       initialize  an  integer to zero.  Call unvis with each successive byte,
       along with a pointer to this integer, and a pointer  to  a  destination
       character.   The  unvis  function has several return codes that must be
       handled properly.  They are:

       0 (zero)
              Another character is necessary; nothing has been recognized yet.

       UNVIS_VALID
              A  valid  character  has been recognized and is available at the
              location pointed to by cp.

       UNVIS_VALIDPUSH
              A valid character has been recognized and is  available  at  the
              location  pointed  to  by  cp;  however, the character currently
              passed in should be passed in again.

       UNVIS_NOCHAR
              A valid sequence was detected, but no  character  was  produced.
              This  return  code  is  necessary  to  indicate  a logical break
              between characters.

       UNVIS_SYNBAD
              An invalid escape sequence was detected, or the decoder is in an
              unknown state.  The decoder is placed into the starting state.

       When  all  bytes in the stream have been processed, call unvis one more
       time with flag set to UNVIS_END to extract any remaining character (the
       character passed in is ignored).

       The following code fragment illustrates a proper use of unvis.

       int state = 0;
       char out;

       while ((ch = getchar()) != EOF) {
       again:
            switch(unvis(&out, ch, &state, 0)) {
            case 0:
            case UNVIS_NOCHAR:
                 break;
            case UNVIS_VALID:
                 (void) putchar(out);
                 break;
            case UNVIS_VALIDPUSH:
                 (void) putchar(out);
                 goto again;
            case UNVIS_SYNBAD:
                 (void)fprintf(stderr, "bad sequence!0);
            exit(1);
            }
       }
       if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
            (void) putchar(out);


SEE ALSO

       vis(1)


HISTORY

       The unvis function first appeared in 4.4BSD.



GNO                             3 January 1999                        UNVIS(3)

Man(1) output converted with man2html