Return to Read_me CVS log

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

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

1.1     ! root        1: 
        !             2: libmisc.a is a miscellaneous collection of useful functions
        !             3: for C programmers.
        !             4: 
        !             5: misc.h A header file with externs and #define's for the
        !             6:        various functions in libmisc.a
        !             7: 
        !             8: char * alloc(n) unsigned n;
        !             9:        malloc() n bytes and zero them, or put out a fatal error message.
        !            10: 
        !            11: int approx(a, b) double a, b;
        !            12:        If a and b are within epsilon, then return 1; else return 0. epsilon
        !            13:        is a visible double.
        !            14: 
        !            15: char * ask(reply, msg, ...) char *reply *msg;
        !            16:        Print msg as a printf-style format string using any
        !            17:        trailing arguments. Gets a line from stdin with gets()
        !            18:        and returns the address of reply. For example:
        !            19: 
        !            20:        sscanf(ask(buff, "%d numbers", 3), &a, &b, &c);
        !            21: 
        !            22:        puts out the message "Enter: 3 numbers ", gets a reply,
        !            23:        write it into buff, and hands that to sscanf().
        !            24: 
        !            25: void banner(word, pad) char *word; int pad;
        !            26:        Prints word as a banner on stdout preceeded by pad
        !            27:        spaces.  Each letter of the banner consists of multiple
        !            28:        occurrences of itself.  You can use this to make your listings
        !            29:        just the ones used by the mainframe professionals ...
        !            30: 
        !            31: int copyd(outfile, infile, length) FILE *outfile, *infile; unsigned long length;
        !            32:        Copy data from one file to another for a length.
        !            33:        Returns 1 on success, 0 on failure.
        !            34:        If copyd cannot read the length given it will write all it can read.
        !            35:        copyd usses buffers for efficiency.
        !            36: 
        !            37: unsigned short crc16(p) char *p;
        !            38:        Takes the crc16 of the string p and returns it. Fast
        !            39:        and perfect for hash tables, diff algorithms etc.
        !            40: 
        !            41: void fatal(msg, ...) char *msg;
        !            42:        Prints msg as a printf-style format string using
        !            43:        any trailing arguments.  This is proceeded by
        !            44:        "\nfatal".  fatal() then calls exit(1).
        !            45: 
        !            46: getargs(argc, argv, optstring) int argc; char *argv[]; char *optstring;
        !            47:        This is an improved form of getopt. If an option is followed
        !            48:        by an ! it has an optional argument.
        !            49:                while(EOF != (c = getargs(argc, argv, "xyf:g!")))
        !            50:        Is a call of getargs from its test section. The x and y
        !            51:        options take no arguments. The f option takes a mandidory
        !            52:        argument, -f arg, and -farg, are both legal forms. The g option
        !            53:        takes an optional argument which if present must be connected
        !            54:        -garg. Additional arguments are returned as if they were preceeded
        !            55:        by an option of '\0'. This allows programs such as ld and as to
        !            56:        process mixed options and file names.
        !            57: 
        !            58: char * getline(ifp, lineno) FILE *ifp; int *lineno;
        !            59:        Get lines from an input file.  Returns the address of the line,
        !            60:        or NULL for eof.
        !            61: 
        !            62:        lineno should usually be started at 1. lineno will
        !            63:        be incremented by the number of lines in the previous call.
        !            64:        Thus lineno will be the number of the line just gotten.
        !            65: 
        !            66:        # to end of line is passed. This for comments.
        !            67:        \ whitespace through end of line is passed. This is for long
        !            68:          lines.
        !            69:        \n newline
        !            70:        \p #
        !            71:        \a alarm
        !            72:        \b backspace
        !            73:        \r carrage return
        !            74:        \f form feed
        !            75:        \t tab
        !            76:        \\ backslash
        !            77:        \ddd octal number
        !            78:        all other \ sequences are errors and reported on stderr.
        !            79: 
        !            80: int  getpseudotty(char *newtty, char *newpty) char *newtty, *newpty;
        !            81:        Claim a pseudo-tty.
        !            82:        Takes pointers to buffers for the names of the newly claimed pair
        !            83:        and returns a file descriptor on the open pty.
        !            84: 
        !            85:        Returns -1 on any sort of failure.  errno will be set to ENXIO
        !            86:        if there were no more ptys.
        !            87: 
        !            88: int select(nfd, *rfds, *wfds, *xfds, *to)
        !            89:        int nfd, fd_set *rfds, *wfds, *xfds, struct timeval *to
        !            90:        Simulate BSD select() system call with poll().
        !            91: 
        !            92: void splitter(ofp, line, limit) FILE *ofp; char *line; int limit;
        !            93:        Output line to ofp, splitting it into chunks less than
        !            94:        limit. Inserts \ between chunks and attempts to do this
        !            95:        on whitespace boundaries.  splitter produces a long line
        !            96:        rather than split on non-whitespace. If line does not end in
        !            97:        \n, splitter adds one.
        !            98: 
        !            99: int if_COHERENT();
        !           100:        Returns 1 if Coherent else 0.
        !           101: 
        !           102: int is_fs(special) char *special;
        !           103:        Checks if a special file is a well-formed file system.
        !           104:        Users should never put file systems on /dev/ram1 but
        !           105:        for multi-system software, like compress, it is smart
        !           106:        to test.
        !           107: 
        !           108:        Return values:
        !           109:        -1      Not a device, cannot open, read or seek failed.
        !           110:         0      No filesystem.
        !           111:         1      Legal filesystem.
        !           112: 
        !           113: char * lcase(str) char *str;
        !           114:        Converts str to lower case.
        !           115: 
        !           116: char * match(string, pattern, fin) char *string, *pattern, **fin;
        !           117:        Like pnmatch(), except match returns the address of the
        !           118:        pattern matched. fin is aimed past the end of the
        !           119:        pattern found - that is, match finds a pattern and tells
        !           120:        you where it is.
        !           121: 
        !           122: char *metaphone(char * word)
        !           123:        Translates word to a short phonetic equivalent (4 characters
        !           124:        controlled by a #define). Charles becomes XRLS. Good for looking
        !           125:        up names.
        !           126: 
        !           127: char * newcpy(str) char* str;
        !           128:        Create a NUL-terminated copy of str on the heap.
        !           129:        It calls fatal if there is no space.
        !           130: 
        !           131: char * pathn(name, envpath, deflpath, access)
        !           132:     char *name, *envpath, *deflpath, *access;
        !           133:        example: pathn("helpfile", "LIBPATH", "/lib", "r")
        !           134:        Look for helpfile using the environmental variable
        !           135:        LIBPATH.  If that isn't set, or the second parm is NULL,
        !           136:        it uses the default path "/lib".  The file found must
        !           137:        have read permission.  pathn() returns the full path
        !           138:        to the file found.
        !           139: 
        !           140: double picture (dble, format, output )
        !           141:     double dble;    /* the number to format */
        !           142:     char  *format;  /* the format mask */
        !           143:     char  *output;  /* the output area. At least as large as format */
        !           144: 
        !           145:        Perform numeric formatting.  This function is superior
        !           146:        to anything available under BASIC or COBOL.
        !           147: 
        !           148:        9    Provide a slot for a number.
        !           149:             5.000 passed through a mask of '999 CR' gives '005   '
        !           150:            -5.000 passed through a mask of '999 CR' gives '005 CR'
        !           151:         Note: C & R are not special to picture. Trailing non-special
        !           152:               characters print only if the number is negative
        !           153: 
        !           154:        Z    Provide a slot for a number but suppress leading zeros.
        !           155:             1034.000 passed through a mask of 'ZZZ,ZZZ' gives '  1,034'
        !           156:             Note: comma is not special to picture. Embedded non-special
        !           157:             characters print only if preceeded by significant digits
        !           158:        
        !           159:        J    Provide a slot for a number but shrink out lead zeros.
        !           160:             1034.000 passed through a mask of 'JJJ,JJJ' gives '1,034'
        !           161:        
        !           162:        K    Provide a slot for a number but shrink out any zeros.
        !           163:             70884.000 passed through a mask of 'K9/K9/K9' gives '7/8/84'
        !           164:        
        !           165:        $    Float a dollar sign to the front of the displayed number.
        !           166:             105.000 passed through a mask of '$ZZZ,ZZZ' gives '    $105'
        !           167:        
        !           168:        .    Separate the number between decimal and integer portions.
        !           169:             105.670 passed through a mask of 'Z,ZZZ.999' gives '  105.670'
        !           170:        
        !           171:        T    Provide a slot for a number but supresse trailing zeros.
        !           172:             105.670 passed through a mask of 'Z,ZZ9.9TT' gives '  105.67 '
        !           173:        
        !           174:        S    Provide a slot for a number but shrink out trailing zeros.
        !           175:             105.670 passed through a mask of 'Z,ZZ9.9SS' gives '  105.67'
        !           176:        
        !           177:        -    Float a - in front of negative numbers
        !           178:             105.000 passed through a mask of '-Z,ZZZ' gives '   105'
        !           179:            -105.000 passed through a mask of '-Z,ZZZ' gives '  -105'
        !           180:        
        !           181:        (    Act like - but prints a (
        !           182:             105.000 passed through a mask of '(ZZZ)' gives ' 105 '
        !           183:            -5.000 passed through a mask of '(ZZZ)' gives '  (5)'
        !           184:        
        !           185:        +    Float a + or - in front of the number depending on its sign
        !           186:             5.000 passed through a mask of '+ZZZ' gives '  +5'
        !           187:            -5.000 passed through a mask of '+ZZZ' gives '  -5'
        !           188:        
        !           189:        *    Fill all lead spaces to its right
        !           190:             104.100 passed through a mask of '*ZZZ,ZZZ.99' gives '*****104.10'
        !           191:             104.100 passed through a mask of '*$ZZZ,ZZZ.99' gives '*****$104.10'
        !           192:        
        !           193:        Any overflow is returned by picture as a double-precision number.
        !           194:            -1234.000 passed through a mask of '(ZZZ)' gives '(234)'
        !           195:             With an overflow of -1.0
        !           196:             123.400 passed through a mask of '99' gives '23'
        !           197:             With an overflow of 1.0
        !           198:             1200.000 passed through a mask of 'ZZ' gives '00'
        !           199:             With an overflow of 12.0
        !           200: 
        !           201: tm_t* jday_to_tm(jd) jday_t jd;
        !           202:        Turn Julian date structure to time date structure.
        !           203: 
        !           204: time_t jday_to_time(jd) jday_t jd;
        !           205:        Turn Julian date structure to COHERENT time.
        !           206: 
        !           207: void bedaemon()
        !           208:        Make the caller a daemon.
        !           209: 
        !           210:        [From "The New Hacker's Dictionary":]
        !           211:        daemon: /day'mn/ or /dee'mn/
        !           212: 
        !           213:        n.  A program that is not invoked explicitly, but lies dormant
        !           214:        waiting for some condition(s) to occur.  The idea is that the
        !           215:        perpetrator of the condition need not be aware that a daemon is
        !           216:        lurking (though often a program will commit an action only because
        !           217:        it knows that it will implicitly invoke a daemon.)...
        !           218: 
        !           219:        For example, when you submit a program to be
        !           220:        printed with 'hpr', your file is copied to
        !           221:        /usr/spool/hpd, and then the printer daemon,
        !           222:        '/usr/bin/hpd' is notified that there is another
        !           223:        file to print.  The advantage is that the user
        !           224:        program, 'hpr', need not compete with other user
        !           225:        programs for access to the printer--'/usr/bin/hpd'
        !           226:        handles all access to the printer.
        !           227: 
        !           228:        Another example of a daemon in /etc/crond (or
        !           229:        /etc/cron).  It spends most of its time waiting.
        !           230:        When the time comes about for the next job from
        !           231:        crontab, the daemon wakes up and starts the job.
        !           232: 
        !           233:        As a general rule, anything that does not interact
        !           234:        directly with users can be classified as a daemon.
        !           235:        Daemons do not generally generate output to a
        !           236:        user's terminal.
        !           237: 
        !           238:        Any time you have a resource, like a printer or
        !           239:        database, to which access should be controlled,
        !           240:        you can use a daemon.  
        !           241: 
        !           242: long randl()
        !           243:        Return a long random number uniformly distributed in
        !           244:        1..2147483562.  This comes from "Communications of the
        !           245:        ACM", vol. 31, number 6. It is the best algorithm we know
        !           246:        as of this writing.
        !           247:        see srandl() in this section.
        !           248: 
        !           249: char * replace(s1, pat, s3, all, matcher) char *s1, *pat, *s3, (matcher)();
        !           250:        Replace one or all occurrences of pat in s1 by s3 and
        !           251:        returns the result.  The definition of match is set by matcher.
        !           252:        This calls the user-defined function matcher(sw, pat, &fin). The
        !           253:        matcher must return the address of the pattern match; e.g.,
        !           254:        its end in &fin. match() is a valid example of matcher.
        !           255:        It replaces the first occurrence, or all occurrences of the
        !           256:        pattern and returns the new pattern. The new pattern has been
        !           257:        alloc()ed (see alloc).
        !           258: 
        !           259: showflag(data, flags, output) long data; char *flags, *output;
        !           260:        Turns the bits in data to the flags in flags or '-'
        !           261:        in the string output which must be as long as flags.
        !           262: 
        !           263: char * skip(s1, matcher, fin) char *s1, **fin; int (*matcher)();
        !           264:        Skip one or more characters not matching some criterion
        !           265:        such as isdigit().  Returns the first character skipped
        !           266:        points fin at the character after the skip.
        !           267: 
        !           268: char * span(s1, matcher, fin) char *s1, **fin; int (*matcher)();
        !           269:        Span one or more characters matching some criterion
        !           270:        such as isdigit().  Returns the first character spanned
        !           271:        points fin at the character after the span.
        !           272: 
        !           273: srandl(seed1, seed2) long seed1, seed2;
        !           274:        randl() needs two seeds this sets them.  Used only
        !           275:        if you need to repeat a random number sequence.
        !           276: 
        !           277: strchtr(from, to, c, def) char *from, *to; int c, def;
        !           278:        Look up the char c on the string from, return the corresponding
        !           279:        char on the string to if it is found otherwise return the char
        !           280:        def. example: strchr("ab", "xy", c, d); if c == 'a' return
        !           281:        'x', if c == 'b' return 'y' otherwise return 'd'.
        !           282: 
        !           283: strcmpl(s1, s2)
        !           284:        Case-insensitive string compare.
        !           285: 
        !           286: #define strlcpy(to, from) memcpy(to, from, sizeof(to))
        !           287: 
        !           288: jday_t time_to_jday(CoherentTime) time_t CoherentTime;
        !           289:        Turn COHERENT time to Julian date structure. This has days
        !           290:        form 1/1/4713 BC.
        !           291: 
        !           292: jday_t tm_to_jday(tm) tm_t *tm;
        !           293:        Turn tm structured date to Julian date.
        !           294: 
        !           295: void tocont()
        !           296:        Prints the message "Enter <NL> to continue " and then waits for
        !           297:        a new line.
        !           298: 
        !           299: ucase(s) char *s;
        !           300:        Convert a string to upper case.
        !           301: 
        !           302: char * trim(s) char *s;
        !           303:        Remove trailing whitespace from string s.
        !           304: 
        !           305: usage(s) char *s;
        !           306:        Put out a usage: message and exit(1)
        !           307: 
        !           308: xdump(p, length) char *p;
        !           309:        Make a vertical hex dump of p for length on stdout. This
        !           310:        is a useful debugging tool. Vertical hex prints as 3 lines
        !           311:        The top line is the display character or . if it's not
        !           312:        cleanly displayable. The next two lines are the hex digit.
        !           313:        The data is blocked in groups of four bytes.
        !           314: 
        !           315: xopen(filename, acs)
        !           316:        Like fopen() but it calls fatal() if the open fails.
        !           317: 
        !           318: yn(question, ...) char *question;
        !           319:        Ask a question with any trailing parms printf style and
        !           320:        get a y or n answer. Returns a 1 for 'Y' or 'y' a 0
        !           321:        for 'n' or 'N', reasks otherwise.
        !           322: 
        !           323: For an egrep style regular expression analizer see regsub.doc
        !           324: 
        !           325: The following are part of a user virtual-memory system for
        !           326: COHERENT.  Sometimes users port programs such as compress to
        !           327: COHERENT, which have a small number of very large arrays. Since
        !           328: COHERENT is a SMALL-model operating system changes need to be
        !           329: made. The following functions are intended to expedite these
        !           330: changes.
        !           331: 
        !           332: void vinit(filename, ram) char *filename; unsigned ram;
        !           333:        Init the virtual system using filename for work
        !           334:        this may be a raw device such as /dev/rram1. ram
        !           335:        is the amount of buffer space to give the system
        !           336:        the more the better.
        !           337: 
        !           338: void vshutdown()
        !           339:        Shut the virtual system, and make it restartable.
        !           340: 
        !           341: unsigned vopen(amt) unsigned long amt;
        !           342:        Set up a virtual object.  For example, if you want to emulate having
        !           343:        a 100,000-byte array and a 50,000 byte array, use
        !           344:        vid1 = vopen(100000L); vid2 = vopen(50000L);
        !           345:        This does some checking and tells the system that any
        !           346:        reference to vid2 will be between 100000 and 150000
        !           347:        on the virtual file.
        !           348: 
        !           349: char *vfind(vid, disp, dirty) unsigned vid, dirty; unsigned long disp;
        !           350:        Find a character on the virtual system, mark the blocks
        !           351:        dirty bit if the access is to write.  Given the example in
        !           352:        vopen, if you want to find the 1000 th byte in vdi1
        !           353:        c = vfind(vdi1, 1000L, 0);
        !           354:        To change the 2000 th byte in vid2 to d.
        !           355:        *(vfind(vid2, 2000L, 1)) = d;
        !           356:        Note the dirty indicator tells the system of the change so
        !           357:        that the block will be written back before it is read over.
        !           358:        Blocks are 512 bytes long so int's or long's can be read
        !           359:        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.