Return to unvis.3 CVS log

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

Annotation of 43BSDReno/lib/libc/gen/unvis.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: .\"    @(#)unvis.3     1.2 (Berkeley) 6/27/90
        !            19: .\"
        !            20: .TH UNVIS 3 "June 27, 1990"
        !            21: .UC 7
        !            22: .SH NAME
        !            23: unvis, strunvis - decode a visual representation of characters
        !            24: .SH SYNOPSIS
        !            25: .nf
        !            26: .ft B
        !            27: #include <vis.h>
        !            28: 
        !            29: int unvis(cp, c, astate, flag)
        !            30: u_char *cp, c;
        !            31: int *astate, flag;
        !            32: 
        !            33: int strunvis(dst, src)
        !            34: char *dst, *src;
        !            35: 
        !            36: .ft R
        !            37: .fi
        !            38: .SH DESCRIPTION
        !            39: .I Unvis
        !            40: and
        !            41: .I strunvis
        !            42: are used to decode a visual representation of characters, as produced
        !            43: by the vis(3) function, back into
        !            44: its original form.  Unvis is called with successive characters in c 
        !            45: until a valid
        !            46: sequence is recognized, at which time the decoded character is
        !            47: available at the character pointed to by cp.  Strunvis decodes the
        !            48: characters pointed to by src into the buffer pointed to by dst.
        !            49: .LP
        !            50: .I Strunvis
        !            51: simply copies src to dst, decoding any escape sequences along the way,
        !            52: and returns the number of characters placed into dst, or -1 if an
        !            53: invalid escape sequence was detected.  The size of dst should be
        !            54: equal to the size of src (that is, no expansion takes place during
        !            55: decoding).
        !            56: .LP
        !            57: .I Unvis
        !            58: implements a state machine that can be used to decode an arbitrary
        !            59: stream of bytes.  All state associated with the bytes being decoded
        !            60: is stored outside the
        !            61: .I unvis
        !            62: function (that is, a pointer to the state is passed in), so
        !            63: calls decoding different streams can be freely intermixed.  To
        !            64: start decoding a stream of bytes, first initialize an integer
        !            65: to zero.  Call unvis with each successive byte, along with a pointer
        !            66: to this integer, and a pointer to an destination character.
        !            67: .I Vis
        !            68: has several return codes that must be handled properly.  They are:
        !            69: .TP 
        !            70: 0 (zero)
        !            71: Another character is necessary; nothing has been recognized yet.
        !            72: .TP
        !            73: UNVIS_VALID    
        !            74: A valid character has been recognized and is available at the location
        !            75: pointed to by cp.
        !            76: .TP
        !            77: UNVIS_VALIDPUSH
        !            78: A valid character has been recognized and is available at the location
        !            79: pointed to by cp; however, the character currently passed in should
        !            80: be passed in again.
        !            81: .TP
        !            82: UNVIS_NOCHAR
        !            83: A valid sequence was detected, but no character was produced.  This
        !            84: return code is necessary to indicate a logical break between characters.
        !            85: .TP
        !            86: UNVIS_SYNBAD
        !            87: An invalid esacpe sequence was detected, or the decoder is in an
        !            88: unknown state.  The decoder is placed into the starting state.
        !            89: .LP
        !            90: When all bytes in the stream have been processed, call
        !            91: .I unvis
        !            92: one more time with flag set to
        !            93: .B UNVIS_END
        !            94: to extract any remaining character (the character passed in is ignored).
        !            95: .LP
        !            96: The following code fragment illustrates a proper use of
        !            97: .IR unvis .
        !            98: .PP
        !            99: .nf
        !           100: int state = 0;
        !           101: char out;
        !           102: 
        !           103: while ((ch = getchar()) != EOF) {
        !           104: again:
        !           105:        switch(unvis(&out, ch, &state, 0)) {
        !           106:        case 0:
        !           107:        case UNVIS_NOCHAR:
        !           108:                break;
        !           109:        case UNVIS_VALID:
        !           110:                (void) putchar(out);
        !           111:                break;
        !           112:        case UNVIS_VALIDPUSH:
        !           113:                (void) putchar(out);
        !           114:                goto again;
        !           115:        case UNVIS_SYNBAD:
        !           116:                (void)fprintf(stderr, "bad sequence!\n");
        !           117:                exit(1);
        !           118:        }
        !           119: }
        !           120: if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
        !           121:        (void) putchar(out);
        !           122: .fi
        !           123: .SH "SEE ALSO"
        !           124: vis(1)

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