[BACK]Return to vis.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/vis.3, Revision 1.12.6.5

1.12.6.4  nathanw     1: .\"    $NetBSD$
1.6       cgd         2: .\"
                      3: .\" Copyright (c) 1989, 1991, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
                     14: .\" 3. All advertising materials mentioning features or use of this software
                     15: .\"    must display the following acknowledgement:
                     16: .\"    This product includes software developed by the University of
                     17: .\"    California, Berkeley and its contributors.
                     18: .\" 4. Neither the name of the University nor the names of its contributors
                     19: .\"    may be used to endorse or promote products derived from this software
                     20: .\"    without specific prior written permission.
                     21: .\"
                     22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     25: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     32: .\" SUCH DAMAGE.
                     33: .\"
1.6       cgd        34: .\"     @(#)vis.3      8.1 (Berkeley) 6/9/93
1.1       cgd        35: .\"
1.6       cgd        36: .Dd June 9, 1993
1.1       cgd        37: .Dt VIS 3
                     38: .Os
                     39: .Sh NAME
1.8       mrg        40: .Nm vis ,
                     41: .Nm strvis ,
1.12      wennmach   42: .Nm strvisx ,
                     43: .Nm svis ,
                     44: .Nm strsvis ,
                     45: .Nm strsvisx
1.1       cgd        46: .Nd visually encode characters
1.10      perry      47: .Sh LIBRARY
                     48: .Lb libc
1.1       cgd        49: .Sh SYNOPSIS
1.12.6.2  nathanw    50: .Fd #include \*[Lt]vis.h\*[Gt]
1.1       cgd        51: .Ft char *
1.12      wennmach   52: .Fn vis "char *dst" "int c" "int flag" "int nextc"
1.12.6.1  nathanw    53: .Ft int
1.12      wennmach   54: .Fn strvis "char *dst" "const char *src" "int flag"
1.12.6.1  nathanw    55: .Ft int
1.12      wennmach   56: .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
                     57: .Ft char *
                     58: .Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
1.12.6.1  nathanw    59: .Ft int
1.12      wennmach   60: .Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
1.12.6.1  nathanw    61: .Ft int
1.12      wennmach   62: .Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
1.1       cgd        63: .Sh DESCRIPTION
                     64: The
                     65: .Fn vis
                     66: function
                     67: copies into
                     68: .Fa dst
                     69: a string which represents the character
                     70: .Fa c .
                     71: If
                     72: .Fa c
1.12.6.5! nathanw    73: needs no encoding, it is copied in unaltered.
        !            74: The string is null terminated, and a pointer to the end of the string is
        !            75: returned.
        !            76: The maximum length of any encoding is four
1.1       cgd        77: characters (not including the trailing
1.12.6.1  nathanw    78: .Dv NUL ) ;
1.1       cgd        79: thus, when
                     80: encoding a set of characters into a buffer, the size of the buffer should
                     81: be four times the number of characters encoded, plus one for the trailing
1.12.6.1  nathanw    82: .Dv NUL .
1.1       cgd        83: The flag parameter is used for altering the default range of
                     84: characters considered for encoding and for altering the visual
                     85: representation.
                     86: The additional character,
                     87: .Fa nextc ,
                     88: is only used when selecting the
                     89: .Dv VIS_CSTYLE
                     90: encoding format (explained below).
                     91: .Pp
                     92: The
                     93: .Fn strvis
                     94: and
                     95: .Fn strvisx
                     96: functions copy into
                     97: .Fa dst
                     98: a visual representation of
                     99: the string
                    100: .Fa src .
                    101: The
                    102: .Fn strvis
                    103: function encodes characters from
                    104: .Fa src
                    105: up to the
                    106: first
1.12.6.1  nathanw   107: .Dv NUL .
1.1       cgd       108: The
                    109: .Fn strvisx
                    110: function encodes exactly
                    111: .Fa len
                    112: characters from
                    113: .Fa src
                    114: (this
                    115: is useful for encoding a block of data that may contain
1.12.6.1  nathanw   116: .Dv NUL Ns 's ) .
1.1       cgd       117: Both forms
1.5       mycroft   118: .Dv NUL
1.1       cgd       119: terminate
                    120: .Fa dst .
                    121: The size of
                    122: .Fa dst
                    123: must be four times the number
                    124: of characters encoded from
                    125: .Fa src
                    126: (plus one for the
1.12.6.1  nathanw   127: .Dv NUL ) .
1.1       cgd       128: Both
                    129: forms return the number of characters in dst (not including
                    130: the trailing
1.12.6.1  nathanw   131: .Dv NUL ) .
1.1       cgd       132: .Pp
1.12      wennmach  133: The functions
                    134: .Fn svis ,
                    135: .Fn strsvis ,
                    136: and
1.12.6.1  nathanw   137: .Fn strsvisx
1.12      wennmach  138: correspond to
                    139: .Fn vis ,
                    140: .Fn strvis ,
                    141: and
1.12.6.1  nathanw   142: .Fn strvisx
1.12      wennmach  143: but have an additional argument
                    144: .Fa extra ,
                    145: pointing to a
                    146: .Dv NUL
1.12.6.5! nathanw   147: terminated list of characters.
        !           148: These characters will be copied encoded or backslash-escaped into
1.12      wennmach  149: .Fa dst .
1.12.6.5! nathanw   150: These functions are useful e.g. to remove the special meaning
1.12      wennmach  151: of certain characters to shells.
                    152: .Pp
1.7       scottr    153: The encoding is a unique, invertible representation composed entirely of
1.12.6.1  nathanw   154: graphic characters; it can be decoded back into the original form using
1.1       cgd       155: the
                    156: .Xr unvis 3
                    157: or
                    158: .Xr strunvis 3
                    159: functions.
                    160: .Pp
                    161: There are two parameters that can be controlled: the range of
1.12      wennmach  162: characters that are encoded (applies only to
                    163: .Fn vis ,
                    164: .Fn strvis ,
                    165: and
                    166: .Fn strvisx ) ,
1.12.6.1  nathanw   167: and the type of representation used.
1.12      wennmach  168: By default, all non-graphic characters,
1.1       cgd       169: except space, tab, and newline are encoded.
                    170: (See
                    171: .Xr isgraph 3 . )
                    172: The following flags
                    173: alter this:
                    174: .Bl -tag -width VIS_WHITEX
                    175: .It Dv VIS_SP
                    176: Also encode space.
1.12.6.1  nathanw   177: .It Dv VIS_TAB
1.1       cgd       178: Also encode tab.
                    179: .It Dv VIS_NL
                    180: Also encode newline.
1.12.6.1  nathanw   181: .It Dv VIS_WHITE
1.1       cgd       182: Synonym for
                    183: .Dv VIS_SP
                    184: \&|
                    185: .Dv VIS_TAB
                    186: \&|
                    187: .Dv VIS_NL .
1.12.6.1  nathanw   188: .It Dv VIS_SAFE
1.12.6.5! nathanw   189: Only encode "unsafe" characters.
        !           190: Unsafe means control characters which may cause common terminals to perform
        !           191: unexpected functions.
        !           192: Currently this form allows space, tab, newline, backspace, bell, and
        !           193: return - in addition to all graphic characters - unencoded.
1.1       cgd       194: .El
                    195: .Pp
1.12      wennmach  196: (The above flags have no effect for
                    197: .Fn svis ,
                    198: .Fn strsvis ,
                    199: and
                    200: .Fn strsvisx .
                    201: When using these functions, place all graphic characters to be
                    202: encoded in an array pointed to by
                    203: .Fa extra .
                    204: In general, the backslash character should be included in this array, see the
                    205: warning on the use of the
                    206: .Dv VIS_NOSLASH
                    207: flag below).
                    208: .Pp
1.12.6.4  nathanw   209: There are four forms of encoding.
1.1       cgd       210: All forms use the backslash character
                    211: .Ql \e
                    212: to introduce a special
1.12.6.4  nathanw   213: sequence; two backslashes are used to represent a real backslash,
                    214: except
                    215: .Dv VIS_HTTPSTYLE
                    216: that uses
                    217: .Ql $ .
1.1       cgd       218: These are the visual formats:
                    219: .Bl -tag -width VIS_CSTYLE
                    220: .It (default)
                    221: Use an
                    222: .Ql M
                    223: to represent meta characters (characters with the 8th
1.4       jtc       224: bit set), and use caret
1.1       cgd       225: .Ql ^
                    226: to represent control characters see
                    227: .Pf ( Xr iscntrl 3 ) .
                    228: The following formats are used:
                    229: .Bl -tag -width xxxxx
                    230: .It Dv \e^C
                    231: Represents the control character
                    232: .Ql C .
                    233: Spans characters
                    234: .Ql \e000
                    235: through
                    236: .Ql \e037 ,
                    237: and
                    238: .Ql \e177
                    239: (as
                    240: .Ql \e^? ) .
                    241: .It Dv \eM-C
                    242: Represents character
                    243: .Ql C
                    244: with the 8th bit set.
                    245: Spans characters
                    246: .Ql \e241
                    247: through
                    248: .Ql \e376 .
                    249: .It Dv \eM^C
                    250: Represents control character
                    251: .Ql C
                    252: with the 8th bit set.
                    253: Spans characters
                    254: .Ql \e200
                    255: through
                    256: .Ql \e237 ,
                    257: and
                    258: .Ql \e377
                    259: (as
                    260: .Ql \eM^? ) .
                    261: .It Dv \e040
                    262: Represents
                    263: .Tn ASCII
                    264: space.
                    265: .It Dv \e240
                    266: Represents Meta-space.
                    267: .El
                    268: .Pp
                    269: .It Dv VIS_CSTYLE
                    270: Use C-style backslash sequences to represent standard non-printable
                    271: characters.
                    272: The following sequences are used to represent the indicated characters:
                    273: .Bd -unfilled -offset indent
                    274: .Li \ea Tn  - BEL No (007)
                    275: .Li \eb Tn  - BS No (010)
                    276: .Li \ef Tn  - NP No (014)
                    277: .Li \en Tn  - NL No (012)
                    278: .Li \er Tn  - CR No (015)
                    279: .Li \et Tn  - HT No (011)
                    280: .Li \ev Tn  - VT No (013)
                    281: .Li \e0 Tn  - NUL No (000)
                    282: .Ed
                    283: .Pp
                    284: When using this format, the nextc parameter is looked at to determine
                    285: if a
1.5       mycroft   286: .Dv NUL
1.1       cgd       287: character can be encoded as
                    288: .Ql \e0
                    289: instead of
                    290: .Ql \e000 .
                    291: If
                    292: .Fa nextc
                    293: is an octal digit, the latter representation is used to
                    294: avoid ambiguity.
                    295: .It Dv VIS_OCTAL
1.12.6.5! nathanw   296: Use a three digit octal sequence.
        !           297: The form is
1.1       cgd       298: .Ql \eddd
                    299: where
                    300: .Em d
                    301: represents an octal digit.
1.12.6.4  nathanw   302: .It Dv VIS_HTTPSTYLE
                    303: Use URI encoding as described in RFC 1808.
                    304: The form is
                    305: .Ql %xx
                    306: where
                    307: .Em x
                    308: represents a hexadecimal digit.
1.1       cgd       309: .El
                    310: .Pp
                    311: There is one additional flag,
                    312: .Dv VIS_NOSLASH ,
                    313: which inhibits the
                    314: doubling of backslashes and the backslash before the default
                    315: format (that is, control characters are represented by
                    316: .Ql ^C
                    317: and
                    318: meta characters as
                    319: .Ql M-C ) .
                    320: With this flag set, the encoding is
                    321: ambiguous and non-invertible.
                    322: .Sh SEE ALSO
                    323: .Xr unvis 1 ,
1.12.6.1  nathanw   324: .Xr vis 1 ,
1.1       cgd       325: .Xr unvis 3
1.12.6.4  nathanw   326: .Rs
                    327: .%A R. Fielding
                    328: .%T Relative Uniform Resource Locators
                    329: .%O RFC1808
                    330: .Re
1.1       cgd       331: .Sh HISTORY
1.12      wennmach  332: The
                    333: .Fa vis ,
                    334: .Fa strvis ,
                    335: and
                    336: .Fa strvisx
                    337: functions first appeared in
1.9       perry     338: .Bx 4.4 .
1.12      wennmach  339: The
                    340: .Fa svis ,
                    341: .Fa strsvis ,
                    342: and
                    343: .Fa strsvisx
1.12.6.1  nathanw   344: functions appeared in
                    345: .Nx 1.5 .

CVSweb <webmaster@jp.NetBSD.org>