home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / gnu / man / cat3 / vis.0 < prev   
Text File  |  1993-12-07  |  6KB  |  133 lines
  1.  
  2. VIS(3)                     UNIX Programmer's Manual                     VIS(3)
  3.  
  4. NNAAMMEE
  5.      vviiss - visually encode characters
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<vviiss..hh>>
  9.  
  10.      _c_h_a_r _*
  11.      vviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _c, _i_n_t _f_l_a_g, _c_h_a_r _n_e_x_t_c)
  12.  
  13.      _i_n_t
  14.      ssttrrvviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _f_l_a_g)
  15.  
  16.      _i_n_t
  17.      ssttrrvviissxx(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _l_e_n, _i_n_t _f_l_a_g)
  18.  
  19. DDEESSCCRRIIPPTTIIOONN
  20.      The vviiss() function copies into _d_s_t a string which represents the charac­
  21.      ter _c. If _c needs no encoding, it is copied in unaltered.  The string is
  22.      null terminated, and a pointer to the end of the string is returned.  The
  23.      maximum length of any encoding is four characters (not including the
  24.      trailing NULL); thus, when encoding a set of characters into a buffer,
  25.      the size of the buffer should be four times the number of characters en­
  26.      coded, plus one for the trailing NULL. The flag parameter is used for al­
  27.      tering the default range of characters considered for encoding and for
  28.      altering the visual representation.  The additional character, _n_e_x_t_c, is
  29.      only used when selecting the VIS_CSTYLE encoding format (explained be­
  30.      low).
  31.  
  32.      The ssttrrvviiss() and ssttrrvviissxx() functions copy into _d_s_t a visual representa­
  33.      tion of the string _s_r_c. The ssttrrvviiss() function encodes characters from _s_r_c
  34.      up to the first NULL. The ssttrrvviissxx() function encodes exactly _l_e_n charac­
  35.      ters from _s_r_c (this is useful for encoding a block of data that may con­
  36.      tain NULL's). Both forms NULL terminate _d_s_t. The size of _d_s_t must be four
  37.      times the number of characters encoded from _s_r_c (plus one for the NULL).
  38.      Both forms return the number of characters in dst (not including the
  39.      trailing NULL).
  40.  
  41.      The encoding is a unique, invertible representation comprised entirely of
  42.      graphic characters; it can be decoded back into the original form using
  43.      the unvis(3) or strunvis(3) functions.
  44.  
  45.      There are two parameters that can be controlled: the range of characters
  46.      that are encoded, and the type of representation used.  By default, all
  47.      non­graphic characters.  except space, tab, and newline are encoded.
  48.      (See isgraph(3).)  The following flags alter this:
  49.  
  50.      VIS_SP      Also encode space.
  51.  
  52.      VIS_TAB
  53.                  Also encode tab.
  54.  
  55.      VIS_NL      Also encode newline.
  56.  
  57.      VIS_WHITE   Synonym for VIS_SP | VIS_TAB | VIS_NL.
  58.  
  59.      VIS_SAFE    Only encode "unsafe" characters.  Unsafe means control char­
  60.                  acters which may cause common terminals to perform unexpected
  61.                  functions.  Currently this form allows space, tab, newline,
  62.                  backspace, bell, and return ­ in addition to all graphic
  63.                  characters ­ unencoded.
  64.  
  65.  
  66.      There are three forms of encoding.  All forms use the backslash character
  67.      `\' to introduce a special sequence; two backslashes are used to repre­
  68.      sent a real backslash.  These are the visual formats:
  69.  
  70.      (default)   Use an `M' to represent meta characters (characters with the
  71.                  8th bit set), and use carat `^' to represent control charac­
  72.                  ters see (iscntrl(3)).  The following formats are used:
  73.  
  74.                  \^C    Represents the control character `C'. Spans characters
  75.                         `\000' through `\037', and `\177' (as `\^?').
  76.  
  77.                  \M­C   Represents character `C' with the 8th bit set.  Spans
  78.                         characters `\241' through `\376'.
  79.  
  80.                  \M^C   Represents control character `C' with the 8th bit set.
  81.                         Spans characters `\200' through `\237', and `\377' (as
  82.                         `\M^?').
  83.  
  84.                  \040   Represents ASCII space.
  85.  
  86.                  \240   Represents Meta­space.
  87.  
  88.      VIS_CSTYLE  Use C­style backslash sequences to represent standard non­
  89.                  printable characters.  The following sequences are used to
  90.                  represent the indicated characters:
  91.  
  92.                        \a ­ BEL (007)
  93.                        \b ­ BS (010)
  94.                        \f ­ NP (014)
  95.                        \n ­ NL (012)
  96.                        \r ­ CR (015)
  97.                        \t ­ HT (011)
  98.                        \v ­ VT (013)
  99.                        \0 ­ NUL (000)
  100.  
  101.                  When using this format, the nextc parameter is looked at to
  102.                  determine if a NULL character can be encoded as `\0' instead
  103.                  of `\000'. If _n_e_x_t_c is an octal digit, the latter representa­
  104.                  tion is used to avoid ambiguity.
  105.  
  106.      VIS_OCTAL   Use a three digit octal sequence.  The form is `\ddd' where _d
  107.                  represents an octal digit.
  108.  
  109.      There is one additional flag, VIS_NOSLASH, which inhibits the doubling of
  110.      backslashes and the backslash before the default format (that is, control
  111.      characters are represented by `^C' and meta characters as `M­C'). With
  112.      this flag set, the encoding is ambiguous and non­invertible.
  113.  
  114. SSEEEE AALLSSOO
  115.      unvis(1),  unvis(3) strunvis(3)
  116.  
  117. HHIISSTTOORRYY
  118.      These functions are currently under development.
  119.  
  120. BSD Experimental                April 19, 1991                               2
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.