Return to Read_me CVS log

Up to [MW Coherent from dump] / coherent / d / usr / lib / misc

Annotation of coherent/d/usr/lib/misc/Read_me, revision 1.1

1.1     ! root        1: misc/Read_me 10/11/90
        !             2: 
        !             3: libmisc.a is a collection of miscellaneous useful user functions
        !             4: which can be used by C programmers to increase productivity.
        !             5: 
        !             6: misc.h
        !             7:        Is a header file with externs and #define's for the
        !             8:        various functions in libmisc.a
        !             9: 
        !            10: larges.h
        !            11:        Is a header file for model independent assembler with some
        !            12:        nice macros like Enter() and Leave. memxch is a good example
        !            13:        of a user.
        !            14: 
        !            15: char * alloc(n) unsigned n;
        !            16:        malloc() n bytes and zero them, or put out a fatal error message.
        !            17: 
        !            18: int approx(a, b) double a, b;
        !            19:        If a and b are within epsilon return 1 else 0. epsilon
        !            20:        is a visable double.
        !            21: 
        !            22: char * ask(reply, msg, ...) char *reply *msg;
        !            23:        Puts out msg as a printf style format string using any
        !            24:        trailing arguments. Gets a line from stdin with gets()
        !            25:        and returns the address of reply. For example
        !            26:        sscanf(ask(buff, "%d numbers", 3), &a, &b, &c);
        !            27:        puts out the message "Enter: 3 numbers " gets a reply
        !            28:        in buff and hands that to sscanf().
        !            29: 
        !            30: void banner(word, pad) char *word; int pad;
        !            31:        Prints word as a banner on stdout preceeded by pad
        !            32:        spaces. Each letter of the banner is composed of
        !            33:        occurances of itself.
        !            34:        
        !            35: unsigned short crc16(p) char *p;
        !            36:        Takes the crc16 of the string p and returns it. Fast
        !            37:        and perfect for hash tables, diff algorithms etc.
        !            38: 
        !            39: void fatal(msg, ...) char *msg;
        !            40:        Prints the msg as a printf style format string using
        !            41:        any trailing arguments. This is preceeded by
        !            42:        "\nfatal". fatal() then does exit(1).
        !            43: 
        !            44: char * getline(ifp, lineno) FILE *ifp; int *lineno;
        !            45:        Function to get lines from an input file.
        !            46:        Returns the address of the line, or NULL for eof.
        !            47: 
        !            48:        lineno should usually be started at 1. lineno will
        !            49:        be incremented by the number of lines in the previous call.
        !            50:        Thus lineno will be the number of the line just gotten.
        !            51: 
        !            52:        # to end of line is passed.
        !            53:        \ whitespace through end of line is passed.
        !            54:        \n newline
        !            55:        \p #
        !            56:        \a alarm
        !            57:        \b backspace
        !            58:        \r carrage return
        !            59:        \f form feed
        !            60:        \t tab
        !            61:        \\ backslash
        !            62:        \ddd octal number
        !            63:        all other \ sequences are errors and reported on stderr.
        !            64: 
        !            65: void splitter(ofp, line, limit) FILE *ofp; char *line; int limit;
        !            66:        Output line to ofp splitting it into chunks less than
        !            67:        limit. Inserts \ between chunks and attempts to do this
        !            68:        on whitespace boundarys. Splitter will produce a long line
        !            69:        rather than split on non whitespace. If line does not end in
        !            70:        \n splitter will add one.
        !            71: 
        !            72: int is_fs(special) char *special;
        !            73:        Checks if a special file is a well formed file system.
        !            74:        Users should never put file systems on /dev/ram1 but
        !            75:        For multi system software like compress it is smart
        !            76:        to test.
        !            77: 
        !            78:        Return values:
        !            79:        -1      Not a device, cannot open, read or seek failed.
        !            80:         0      No filesystem.
        !            81:         1      Legal filesystem.
        !            82: 
        !            83: char * lcase(str) char *str;
        !            84:        Converts str to lower case.
        !            85: 
        !            86: char * match(string, pattern, fin) char *string, *pattern, **fin;
        !            87:        Like pnmatch() except match returns the address of the
        !            88:        pattern matched. fin is aimed past the end of the
        !            89:        pattern found. That is match finds a pattern and tells
        !            90:        you where it is.
        !            91: 
        !            92: void memxch(s1, s2, len) char *s1, *s2;
        !            93:        Exchanges s1 and s2 for len. Fast and in assembler.
        !            94: 
        !            95: char * newcpy(str) char* str;
        !            96:        Creates a NUL terminated copy of str on the heap.
        !            97:        It calls fatal if there is no space.
        !            98: 
        !            99: char * pathn(name, envpath, deflpath, access)
        !           100:     char *name, *envpath, *deflpath, *access;
        !           101:        example: pathn("helpfile", "LIBPATH", "/lib", "r")
        !           102:        Looks for helpfile using the environmental variable
        !           103:        LIBPATH if that isn't set, or the second parm is NULL
        !           104:        it uses the default path "/lib". The file found must
        !           105:        have read permission. pathn() returns the full path
        !           106:        to the file found.
        !           107: 
        !           108: double picture (dble, format, output )
        !           109:     double dble;    /* the number to format */
        !           110:     char  *format;  /* the format mask */
        !           111:     char  *output;  /* the output area. At least as large as format */
        !           112: 
        !           113:        The picture() function gives C users far better
        !           114:        numeric formatting ability than COBOL and BASIC users. 
        !           115: 
        !           116:        9    Provides a slot for a number.
        !           117:             5.000 passed through a mask of '999 CR' gives '005   '
        !           118:            -5.000 passed through a mask of '999 CR' gives '005 CR'
        !           119:         Note: C & R are not special to picture. Trailing non special
        !           120:               characters print only if the number is negitave
        !           121:        
        !           122:        Z    Provides a slot for a number but supresses lead zeros.
        !           123:          1034.000 passed through a mask of 'ZZZ,ZZZ' gives '  1,034'
        !           124:         Note: comma is not special to picture. Imbeded non special
        !           125:               characters print only if preceeded by significant digits
        !           126:        
        !           127:        J    Provides a slot for a number but shrinks out lead zeros.
        !           128:          1034.000 passed through a mask of 'JJJ,JJJ' gives '1,034'
        !           129:        
        !           130:        K    Provides a slot for a number but shrinks out any zeros.
        !           131:         70884.000 passed through a mask of 'K9/K9/K9' gives '7/8/84'
        !           132:        
        !           133:        $    Floats a dollar sign to the front of the displayed number.
        !           134:           105.000 passed through a mask of '$ZZZ,ZZZ' gives '    $105'
        !           135:        
        !           136:        .    Separates the number between decimal and integer portions.
        !           137:           105.670 passed through a mask of 'Z,ZZZ.999' gives '  105.670'
        !           138:        
        !           139:        T    Provides a slot for a number but supresses trailing zeros.
        !           140:           105.670 passed through a mask of 'Z,ZZ9.9TT' gives '  105.67 '
        !           141:        
        !           142:        S    Provides a slot for a number but shrinks out trailing zeros.
        !           143:           105.670 passed through a mask of 'Z,ZZ9.9SS' gives '  105.67'
        !           144:        
        !           145:        -    Floats a - in front of negitive numbers
        !           146:           105.000 passed through a mask of '-Z,ZZZ' gives '   105'
        !           147:          -105.000 passed through a mask of '-Z,ZZZ' gives '  -105'
        !           148:        
        !           149:        (    Acts like - but prints a (
        !           150:           105.000 passed through a mask of '(ZZZ)' gives ' 105 '
        !           151:            -5.000 passed through a mask of '(ZZZ)' gives '  (5)'
        !           152:        
        !           153:        +    Floats a + or - infront of the number depending on its sign
        !           154:             5.000 passed through a mask of '+ZZZ' gives '  +5'
        !           155:            -5.000 passed through a mask of '+ZZZ' gives '  -5'
        !           156:        
        !           157:        *    Fills all lead spaces to its right
        !           158:           104.100 passed through a mask of '*ZZZ,ZZZ.99' gives '*****104.10'
        !           159:           104.100 passed through a mask of '*$ZZZ,ZZZ.99' gives '*****$104.10'
        !           160:        
        !           161:        Any overflow is returned by picture as a double precision number.
        !           162:         -1234.000 passed through a mask of '(ZZZ)' gives '(234)'
        !           163:            With an overflow of -1.0
        !           164:           123.400 passed through a mask of '99' gives '23'
        !           165:            With an overflow of 1.0
        !           166:          1200.000 passed through a mask of 'ZZ' gives '00'
        !           167:            With an overflow of 12.0
        !           168: 
        !           169: qsort(data, n, size, comp) char *data; int n, size, (*comp)();
        !           170:        Is your qsort() strangely slow. There are pathological cases
        !           171:        which cause qsort to act badly. Example: 1000 items whose
        !           172:        keys are all 7 and 8; a large array split into two halves
        !           173:        both of which are already in order. This qsort() detects
        !           174:        pathological conditions and adjusts.
        !           175: 
        !           176: long randl()
        !           177:        Returns a long random number uniformly distributed in
        !           178:        1..2147483562. This comes from CACM V. 31 N 6. And is
        !           179:        the best algorithm I know as of this writing.
        !           180:        see srandl() in this section.
        !           181: 
        !           182: char * replace(s1, pat, s3, all, matcher) char *s1, *pat, *s3, (matcher)();
        !           183:        Replaces one or all occurances of pat in s1 by s3 and
        !           184:        returns the result. The definition of match is set by matcher.
        !           185:        This calls the user defined function matcher(sw, pat, &fin). The
        !           186:        matcher must return the address of the pattern match and
        !           187:        it's end in &fin. match() is a valid example of matcher.
        !           188:        It replaces the first occurance, or all occurances of the
        !           189:        pattern and returns the new pattern. The new pattern has been
        !           190:        alloc()ed (see alloc).
        !           191: 
        !           192: showflag(data, flags, output) long data; char *flags, *output;
        !           193:        Turns the bits in data to the flags in flags or '-'
        !           194:        in the string output which must be as long as flags.
        !           195: 
        !           196: char * skip(s1, matcher, fin) char *s1, **fin; int (*matcher)();
        !           197:        Skip one or more characters not matching some criterion
        !           198:        such as isdigit(). Returns the first character skipped
        !           199:        points fin at the character after the skip.
        !           200: 
        !           201: char * span(s1, matcher, fin) char *s1, **fin; int (*matcher)();
        !           202:        Span one or more characters matching some criterion
        !           203:        such as isdigit(). Returns the first character spanned
        !           204:        points fin at the character after the span.
        !           205: 
        !           206: srandl(seed1, seed2) long seed1, seed2;
        !           207:        randl() needs two seeds this sets them. Used only
        !           208:        if you need to repeat a random number sequence.
        !           209: 
        !           210: strchtr(from, to, c, def) char *from, *to; int c, def;
        !           211:        Look up the char c on the string from, return the corresponding
        !           212:        char on the string to if it is found otherwise return the char
        !           213:        def. example: strchr("ab", "xy", c, d); if c == 'a' return
        !           214:        'x', if c == 'b' return 'y' otherwise return 'd'.
        !           215:        
        !           216: strcmpl(s1, s2)
        !           217:        Case insensative string compare.
        !           218: 
        !           219: #define strlcpy(to, from) memcpy(to, from, sizeof(to))
        !           220: 
        !           221: ucase(s) char *s;
        !           222:        Convert a string to upper case.
        !           223: 
        !           224: char * trim(s) char *s;
        !           225:        Remove trailing whitespace from string s.
        !           226: 
        !           227: usage(s) char *s;
        !           228:        Put out a usage: message and exit(1)
        !           229: 
        !           230: xdump(p, length) char *p;
        !           231:        Make a vertical hex dump of p for length on stdout. This
        !           232:        is a usefull debugging tool. Vertical hex prints as 3 lines
        !           233:        The top line is the display character or . if it's not
        !           234:        cleanly displayable. The next two lines are the hex digit.
        !           235:        The data is blocked in groups of four bytes.
        !           236: 
        !           237: xopen(filename, acs)
        !           238:        Like fopen() but it calls fatal() if the open fails.
        !           239: 
        !           240: yn(question, ...) char *question;
        !           241:        Ask a question with any trailing parms printf style and
        !           242:        get a y or n answer. Returns a 1 for 'Y' or 'y' a 0
        !           243:        for 'n' or 'N', reasks otherwise.
        !           244: 
        !           245: The following are part of a user virtual memory system for
        !           246: Coherent. Sometimes users port programs such as compress to
        !           247: Coherent which have a small number of very large arrays. Since
        !           248: Coherent is a small model operating system changes need to be
        !           249: made. The following functions are intended to expedite these
        !           250: changes.
        !           251: 
        !           252: void vinit(filename, ram) char *filename; unsigned ram;
        !           253:        Init the virtual system using filename for work
        !           254:        this may be a raw device such as /dev/rram1. ram
        !           255:        is the amount of buffer space to give the system
        !           256:        the more the better.
        !           257: 
        !           258: void vshutdown()
        !           259:        Shut the virtual system, and make it restartable.
        !           260: 
        !           261: unsigned vopen(amt) unsigned long amt;
        !           262:        Set up a virtual object. Say you want to emulate having
        !           263:        a 100000 byte array and a 50000 byte array. use
        !           264:        vid1 = vopen(100000L); vid2 = vopen(50000L);
        !           265:        This does some checking and tells the system that any
        !           266:        reference to vid2 will be between 100000 and 150000
        !           267:        on the virtual file.
        !           268: 
        !           269: char *vfind(vid, disp, dirty) unsigned vid, dirty; unsigned long disp;
        !           270:        Find a character on the virtual system mark the blocks
        !           271:        dirty bit if the access is to write. Given the example in
        !           272:        vopen, if you want to find the 1000 th byte in vdi1
        !           273:        c = vfind(vdi1, 1000L, 0);
        !           274:        To change the 2000 th byte in vid2 to d.
        !           275:        *(vfind(vid2, 2000L, 1)) = d;
        !           276:        Note the dirty indicator tells the system of the change so
        !           277:        that the block will be written back before it is read over.
        !           278:        Blocks are 512 bytes long so int's or long's can be read
        !           279:        or written without multiple accesses to vfind.

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