Return to vis.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/vis.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1989 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)vis.3       5.6 (Berkeley) 6/23/90
        !            19: .\"
        !            20: .TH VIS 3 "June 23, 1990"
        !            21: .UC 7
        !            22: .SH NAME
        !            23: vis \- visually encode characters
        !            24: .SH SYNOPSIS
        !            25: .nf
        !            26: .ft B
        !            27: #include <vis.h>
        !            28: 
        !            29: char *vis(dst, c, flag, nextc)
        !            30: char *dst, c, nextc;
        !            31: int flag;
        !            32: 
        !            33: int strvis(dst, src, flag)
        !            34: char *dst, *src;
        !            35: int flag;
        !            36: 
        !            37: int strvisx(dst, src, len, flag)
        !            38: char *dst, *src;
        !            39: int len, flag;
        !            40: 
        !            41: .ft R
        !            42: .fi
        !            43: .SH DESCRIPTION
        !            44: .I Vis
        !            45: copies into dst a string which represents the character c.  If
        !            46: c needs no encoding, it is copied in unaltered.  The string is
        !            47: null terminated, and a pointer to the end of the string is
        !            48: returned.  The maximum length of any encoding is four
        !            49: characters (not including the trailing NULL); thus, when
        !            50: encoding a set of characters into a buffer, the size of the buffer should
        !            51: be four times the number of characters encoded, plus one for the trailing NULL.
        !            52: The flag parameter is used for altering the default range of
        !            53: characters considered for encoding and for altering the visual
        !            54: representation.
        !            55: The additional character, nextc, is only used when selecting the
        !            56: VIS_CSTYLE encoding format (explained below).
        !            57: .PP
        !            58: Strvis and strvisx copy into dst a visual representation of
        !            59: the string src.  Strvis encodes characters from src up to the
        !            60: first NULL.  Strvisx encodes exactly len characters from src (this
        !            61: is useful for encoding a block of data that may contain NULL's).
        !            62: Both forms NULL terminate dst.  Dst must be four times the number
        !            63: of characters encoded from src (plus one for the NULL).  Both
        !            64: forms return the number of characters in dst (not including
        !            65: the trailing NULL).
        !            66: .PP
        !            67: The encoding is a unique, invertible representation comprised entirely of
        !            68: graphic characters; it can be decoded back into the original form using 
        !            69: the unvis(3) or strunvis(3) functions.
        !            70: .PP
        !            71: There are two parameters that can be controlled: the range of
        !            72: characters that are encoded, and the type
        !            73: of representation used.  
        !            74: By default, all non-graphic characters (see isgraph(3))
        !            75: except space, tab, and newline are encoded.  The following flags
        !            76: alter this:
        !            77: .TP
        !            78: VIS_SP
        !            79: Also encode space.
        !            80: .TP
        !            81: VIS_TAB                
        !            82: Also encode tab.
        !            83: .TP
        !            84: VIS_NL
        !            85: Also encode newline.
        !            86: .TP
        !            87: VIS_WHITE      
        !            88: Synonym for VIS_SP | VIS_TAB | VIS_NL.
        !            89: .TP
        !            90: VIS_SAFE       
        !            91: Only encode "unsafe" characters.  Unsafe means control
        !            92: characters which may cause common terminals to perform
        !            93: unexpected functions.  Currently this form allows space,
        !            94: tab, newline, backspace, bell, and return - in addition
        !            95: to all graphic characters - unencoded. 
        !            96: .PP
        !            97: There are three forms of encoding.
        !            98: All forms use the backslash character (``\e'') to introduce a special
        !            99: sequence; two backslashes are used to represent a real backslash.
        !           100: These are the visual formats:
        !           101: .TP
        !           102: (default)
        !           103: Use an ``M'' to represent meta characters (characters with the 8th
        !           104: bit set), and use carat (``^'') to represent control characters see
        !           105: (\fIiscntrl\fP(3)).
        !           106: The following formats are used:
        !           107: .RS
        !           108: .TP
        !           109: \e^C
        !           110: Represents the control character ``C''.
        !           111: Spans characters \e000 through \e037, and \e177 (as \e^?).
        !           112: .TP
        !           113: \eM-C
        !           114: Represents character ``C'' with the 8th bit set.
        !           115: Spans characters \e241 through \e376.
        !           116: .TP
        !           117: \eM^C
        !           118: Represents control character ``C'' with the 8th bit set.
        !           119: Spans characters \e200 through \e237, and \e377 (as \eM^?).
        !           120: .TP
        !           121: \e040
        !           122: Represents ACSII space.
        !           123: .TP
        !           124: \e240
        !           125: Represents Meta-space.
        !           126: .sp
        !           127: .RE
        !           128: .TP
        !           129: VIS_CSTYLE
        !           130: Use C-style backslash sequences to represent standard non-printable
        !           131: characters.
        !           132: The following sequences are used to represent the indicated characters:
        !           133: .sp
        !           134: .nf
        !           135: \ea   - BEL (007)
        !           136: \eb   - BS  (010)
        !           137: \ef   - NP  (014)
        !           138: \en   - NL  (012)
        !           139: \er   - CR  (015)
        !           140: \et   - HT  (011)
        !           141: \ev   - VT  (013)
        !           142: \e0   - NUL (000)
        !           143: .fi
        !           144: .sp
        !           145: When using this format, the nextc parameter is looked at to determine
        !           146: if a NULL character can be encoded as ``\e0'' instead of ``\e000''.
        !           147: If nextc is an octal digit, the latter representation is used to
        !           148: avoid ambiguity.
        !           149: .TP
        !           150: VIS_OCTAL
        !           151: Use a three digit octal sequence.  The form is ``\eddd'' where
        !           152: d represents an octal digit.
        !           153: .PP
        !           154: There is one additional flag, VIS_NOSLASH, which inhibits the
        !           155: doubling of backslashes and the backslash before the default
        !           156: format (that is, control characters are represented by ^C and
        !           157: meta characters as M-C).  With this flag set, the encoding is
        !           158: ambiguous and non-invertible.
        !           159: .SH "SEE ALSO"
        !           160: vis(1), unvis(1), unvis(3)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.