*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> unvis (3)              



NAME    [Toc]    [Back]

     unvis, strunvis - decode a visual representation of  characters

SYNOPSIS    [Toc]    [Back]

     #include <vis.h>

     unvis(char *cp, char c, int *astate, int flag);

     strunvis(char *dst, char *src);

DESCRIPTION    [Toc]    [Back]

     The  unvis()  and  strunvis() functions are used to decode a
visual representation
 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
     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

     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

     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).

EXAMPLES    [Toc]    [Back]

     The  following  code  fragment  illustrates  a proper use of

           int state = 0;
           char out;

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

SEE ALSO    [Toc]    [Back]

     unvis(1), vis(1), vis(3)

HISTORY    [Toc]    [Back]

     The unvis() function first appeared in 4.4BSD.

OpenBSD     3.6                        December     11,      1993
[ Back ]
 Similar pages
Name OS Title
unvis OpenBSD revert a visual representation of data back to original form
unvis FreeBSD revert a visual representation of data back to original form
vis FreeBSD display non-printable characters in a visual format
vis OpenBSD display non-printable characters in a visual format
XmRepTypeGetId Tru64 A representation type manager function that retrieves the identification number of a representation ...
acl_from_text Tru64 Converts the textual representation of an ACL to an internal representation
crypt Tru64 encode/decode
crypt IRIX encode/decode
_leb128_unsigned_decode64 IRIX decode leb128 integers
crypt HP-UX encode/decode files
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service