CS322 - OPERATING SYSTEMS AND COMPUTER ARCHITECTURE Excerpts from the documentation for the C library -------- ---- --- ------------- --- --- - ------- The following pages are taken from the on-line Unix manual pages, and cover C library routines that may prove useful in your projects in this course. For a complete listing of all C library routines, type man 3 intro -- on Unix or help cc run-time -- on VMS To access online documentation on a particular routine (e.g. printf), type man printf -- on Unix or help cc run-time printf -- on VMS For a complete listing of Unix system service routines, type ls /usr/man/cat2 -- Unix only, of course! CTYPE(3) UNIX Programmer's Manual CTYPE(3) NAME isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toupper, tolower, toascii - character classification macros SYNOPSIS #include isalpha(c) . . . DESCRIPTION These macros classify ASCII-coded integer values by table lookup. Each is a predicate returning nonzero for true, zero for false. Isascii and toascii are defined on all integer values; the rest are defined only where isascii is true and on the single non-ASCII value EOF (see stdio(3S)). isalpha c is a letter isupper c is an upper case letter islower c is a lower case letter isdigit c is a digit isxdigit c is a hex digit isalnum c is an alphanumeric character isspace c is a space, tab, carriage return, newline, vertical tab, or formfeed ispunct c is a punctuation character (neither control nor alphanumeric) isprint c is a printing character, code 040(8) (space) through 0176 (tilde) isgraph c is a printing character, similar to isprint except false for space. iscntrl c is a delete character (0177) or ordinary control character (less than 040). isascii c is an ASCII character, code less than 0200 tolower c is converted to lower case. Return value is undefined if not isupper(c). toupper c is converted to upper case. Return value Printed 12/6/86 May 12, 1986 1 CTYPE(3) UNIX Programmer's Manual CTYPE(3) is undefined if not islower(c). toascii c is converted to be a valid ascii character. SEE ALSO ascii(7) Printed 12/6/86 May 12, 1986 2 GETC(3S) UNIX Programmer's Manual GETC(3S) NAME getc, getchar, fgetc, getw - get character or word from stream SYNOPSIS #include int getc(stream) FILE *stream; int getchar() int fgetc(stream) FILE *stream; int getw(stream) FILE *stream; DESCRIPTION Getc returns the next character from the named input stream. Getchar() is identical to getc(stdin). Fgetc behaves like getc, but is a genuine function, not a macro; it may be used to save object text. Getw returns the next int (a 32-bit integer on a VAX-11) from the named input stream. It returns the constant EOF upon end of file or error, but since that is a good integer value, feof and ferror(3S) should be used to check the suc- cess of getw. Getw assumes no special alignment in the file. SEE ALSO clearerr(3S), fopen(3S), putc(3S), gets(3S), scanf(3S), fread(3S), ungetc(3S) DIAGNOSTICS These functions return the integer constant EOF at end of file, upon read error, or if an attempt is made to read a file not opened by fopen. The end-of-file condition is remembered, even on a terminal, and all subsequent attempts to read will return EOF until the condition is cleared with clearerr(3S). BUGS Because it is implemented as a macro, getc treats a stream argument with side effects incorrectly. In particular, `getc(*f++);' doesn't work sensibly. Printed 12/6/86 May 14, 1986 1 GETS(3S) UNIX Programmer's Manual GETS(3S) NAME gets, fgets - get a string from a stream SYNOPSIS #include char *gets(s) char *s; char *fgets(s, n, stream) char *s; FILE *stream; DESCRIPTION Gets reads a string into s from the standard input stream stdin. The string is terminated by a newline character, which is replaced in s by a null character. Gets returns its argument. Fgets reads n-1 characters, or up through a newline charac- ter, whichever comes first, from the stream into the string s. The last character read into s is followed by a null character. Fgets returns its first argument. SEE ALSO puts(3S), getc(3S), scanf(3S), fread(3S), ferror(3S) DIAGNOSTICS Gets and fgets return the constant pointer NULL upon end of file or error. BUGS Gets deletes a newline, fgets keeps it, all in the name of backward compatibility. Printed 12/6/86 May 15, 1985 1 UNGETC(3S) UNIX Programmer's Manual UNGETC(3S) NAME ungetc - push character back into input stream SYNOPSIS #include ungetc(c, stream) FILE *stream; DESCRIPTION Ungetc pushes the character c back on an input stream. That character will be returned by the next getc call on that stream. Ungetc returns c. One character of pushback is guaranteed provided something has been read from the stream and the stream is actually buffered. Attempts to push EOF are rejected. Fseek(3S) erases all memory of pushed back characters. SEE ALSO getc(3S), setbuf(3S), fseek(3S) DIAGNOSTICS Ungetc returns EOF if it can't push a character back. Printed 12/6/86 May 15, 1985 1 SCANF(3S) UNIX Programmer's Manual SCANF(3S) NAME scanf, fscanf, sscanf - formatted input conversion SYNOPSIS #include scanf(format [ , pointer ] . . . ) char *format; fscanf(stream, format [ , pointer ] . . . ) FILE *stream; char *format; sscanf(s, format [ , pointer ] . . . ) char *s, *format; DESCRIPTION Scanf reads from the standard input stream stdin. Fscanf reads from the named input stream. Sscanf reads from the character string s. Each function reads characters, inter- prets them according to a format, and stores the results in its arguments. Each expects as arguments a control string format, described below, and a set of pointer arguments indicating where the converted input should be stored. The control string usually contains conversion specifica- tions, which are used to direct interpretation of input sequences. The control string may contain: 1. Blanks, tabs or newlines, which match optional white space in the input. 2. An ordinary character (not %) which must match the next character of the input stream. 3. Conversion specifications, consisting of the character %, an optional assignment suppressing character *, an optional numerical maximum field width, and a conversion character. A conversion specification directs the conversion of the next input field; the result is placed in the variable pointed to by the corresponding argument, unless assignment suppression was indicated by *. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if speci- fied, is exhausted. The conversion character indicates the interpretation of the input field; the corresponding pointer argument must usually be of a restricted type. The following conversion charac- ters are legal: Printed 12/6/86 May 15, 1985 1 SCANF(3S) UNIX Programmer's Manual SCANF(3S) % a single `%' is expected in the input at this point; no assignment is done. d a decimal integer is expected; the corresponding argu- ment should be an integer pointer. o an octal integer is expected; the corresponding argument should be a integer pointer. x a hexadecimal integer is expected; the corresponding argument should be an integer pointer. s a character string is expected; the corresponding argu- ment should be a character pointer pointing to an array of characters large enough to accept the string and a terminating `\0', which will be added. The input field is terminated by a space character or a newline. c a character is expected; the corresponding argument should be a character pointer. The normal skip over space characters is suppressed in this case; to read the next non-space character, try `%1s'. If a field width is given, the corresponding argument should refer to a character array, and the indicated number of characters is read. e a floating point number is expected; the next field is f converted accordingly and stored through the correspond- ing argument, which should be a pointer to a float. The input format for floating point numbers is an optionally signed string of digits possibly containing a decimal point, followed by an optional exponent field consisting of an E or e followed by an optionally signed integer. [ indicates a string not to be delimited by space charac- ters. The left bracket is followed by a set of charac- ters and a right bracket; the characters between the brackets define a set of characters making up the string. If the first character is not circumflex (^), the input field is all characters until the first char- acter not in the set between the brackets; if the first character after the left bracket is ^, the input field is all characters until the first character which is in the remaining set of characters between the brackets. The corresponding argument must point to a character array. The conversion characters d, o and x may be capitalized or preceded by l to indicate that a pointer to long rather than to int is in the argument list. Similarly, the conversion characters e or f may be capitalized or preceded by l to indicate a pointer to double rather than to float. The Printed 12/6/86 May 15, 1985 2 SCANF(3S) UNIX Programmer's Manual SCANF(3S) conversion characters d, o and x may be preceded by h to indicate a pointer to short rather than to int. The scanf functions return the number of successfully matched and assigned input items. This can be used to decide how many input items were found. The constant EOF is returned upon end of input; note that this is different from 0, which means that no conversion was done; if conversion was intended, it was frustrated by an inappropriate charac- ter in the input. For example, the call int i; float x; char name[50]; scanf("%d%f%s", &i, &x, name); with the input line 25 54.32E-1 thompson will assign to i the value 25, x the value 5.432, and name will contain `thompson\0'. Or, int i; float x; char name[50]; scanf("%2d%f%*d%[1234567890]", &i, &x, name); with input 56789 0123 56a72 will assign 56 to i, 789.0 to x, skip `0123', and place the string `56\0' in name. The next call to getchar will return `a'. SEE ALSO atof(3), getc(3S), printf(3S) DIAGNOSTICS The scanf functions return EOF on end of input, and a short count for missing or illegal data items. BUGS The success of literal matches and suppressed assignments is not directly determinable. Printed 12/6/86 May 15, 1985 3 PUTC(3S) UNIX Programmer's Manual PUTC(3S) NAME putc, putchar, fputc, putw - put character or word on a stream SYNOPSIS #include int putc(c, stream) char c; FILE *stream; int putchar(c) int fputc(c, stream) FILE *stream; int putw(w, stream) FILE *stream; DESCRIPTION Putc appends the character c to the named output stream. It returns the character written. Putchar(c) is defined as putc(c, stdout). Fputc behaves like putc, but is a genuine function rather than a macro. Putw appends word (that is, int) w to the output stream. It returns the word written. Putw neither assumes nor causes special alignment in the file. SEE ALSO fopen(3S), fclose(3S), getc(3S), puts(3S), printf(3S), fread(3S) DIAGNOSTICS These functions return the constant EOF upon error. Since this is a good integer, ferror(3S) should be used to detect putw errors. BUGS Because it is implemented as a macro, putc treats a stream argument with side effects improperly. In particular putc(c, *f++); doesn't work sensibly. Errors can occur long after the call to putc. Printed 12/6/86 November 6, 1985 1 PUTS(3S) UNIX Programmer's Manual PUTS(3S) NAME puts, fputs - put a string on a stream SYNOPSIS #include puts(s) char *s; fputs(s, stream) char *s; FILE *stream; DESCRIPTION Puts copies the null-terminated string s to the standard output stream stdout and appends a newline character. Fputs copies the null-terminated string s to the named out- put stream. Neither routine copies the terminal null character. SEE ALSO fopen(3S), gets(3S), putc(3S), printf(3S), ferror(3S) fread(3S) for fwrite BUGS Puts appends a newline, fputs does not, all in the name of backward compatibility. Printed 12/6/86 May 15, 1985 1 PRINTF(3S) UNIX Programmer's Manual PRINTF(3S) NAME printf, fprintf, sprintf - formatted output conversion SYNOPSIS #include printf(format [, arg ] ... ) char *format; fprintf(stream, format [, arg ] ... ) FILE *stream; char *format; sprintf(s, format [, arg ] ... ) char *s, format; #include _doprnt(format, args, stream) char *format; va_list *args; FILE *stream; DESCRIPTION Printf places output on the standard output stream stdout. Fprintf places output on the named output stream. Sprintf places `output' in the string s, followed by the character `\0'. All of these routines work by calling the internal routine _doprnt, using the variable-length argument facili- ties of varargs(3). Each of these functions converts, formats, and prints its arguments after the first under control of the first argu- ment. The first argument is a character string which con- tains two types of objects: plain characters, which are sim- ply copied to the output stream, and conversion specifica- tions, each of which causes conversion and printing of the next successive arg printf. Each conversion specification is introduced by the character %. The remainder of the conversion specification includes in the following order o+ Zero or more of following flags: o+ a `#' character specifying that the value should be converted to an ``alternate form''. For c, d, s, and u, conversions, this option has no effect. For o conversions, the precision of the number is increased to force the first character of the out- put string to a zero. For x(X) conversion, a non-zero result has the string 0x(0X) prepended to it. For e, E, f, g, and G, conversions, the Printed 12/6/86 June 5, 1986 1 PRINTF(3S) UNIX Programmer's Manual PRINTF(3S) result will always contain a decimal point, even if no digits follow the point (normally, a decimal point only appears in the results of those conver- sions if a digit follows the decimal point). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be. o+ a minus sign `-' which specifies left adjustment of the converted value in the indicated field; o+ a `+' character specifying that there should always be a sign placed before the number when using signed conversions. o+ a space specifying that a blank should be left before a positive number during a signed conver- sion. A `+' overrides a space if both are used. o+ an optional digit string specifying a field width; if the converted value has fewer characters than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width; if the field width begins with a zero, zero-padding will be done instead of blank- padding; o+ an optional period `.' which serves to separate the field width from the next digit string; o+ an optional digit string specifying a precision which specifies the number of digits to appear after the decimal point, for e- and f-conversion, or the maximum number of characters to be printed from a string; o+ the character l specifying that a following d, o, x, or u corresponds to a long integer arg. o+ a character which indicates the type of conversion to be applied. A field width or precision may be `*' instead of a digit string. In this case an integer arg supplies the field width or precision. The conversion characters and their meanings are dox The integer arg is converted to decimal, octal, or hex- adecimal notation respectively. f The float or double arg is converted to decimal nota- tion in the style `[-]ddd.ddd' where the number of d's Printed 12/6/86 June 5, 1986 2 PRINTF(3S) UNIX Programmer's Manual PRINTF(3S) after the decimal point is equal to the precision specification for the argument. If the precision is missing, 6 digits are given; if the precision is expli- citly 0, no digits and no decimal point are printed. e The float or double arg is converted in the style `[-]d.ddde+_dd' where there is one digit before the decimal point and the number after is equal to the pre- cision specification for the argument; when the preci- sion is missing, 6 digits are produced. g The float or double arg is printed in style d, in style f, or in style e, whichever gives full precision in minimum space. c The character arg is printed. s Arg is taken to be a string (character pointer) and characters from the string are printed until a null character or until the number of characters indicated by the precision specification is reached; however if the precision is 0 or missing all characters up to a null are printed. u The unsigned integer arg is converted to decimal and printed (the result will be in the range 0 through MAX- UINT, where MAXUINT equals 4294967295 on a VAX-11 and 65535 on a PDP-11). % Print a `%'; no argument is converted. In no case does a non-existent or small field width cause truncation of a field; padding takes place only if the specified field width exceeds the actual width. Characters generated by printf are printed by putc(3S). Examples To print a date and time in the form `Sunday, July 3, 10:02', where weekday and month are pointers to null- terminated strings: printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); To print pi to 5 decimals: printf("pi = %.5f", 4*atan(1.0)); SEE ALSO putc(3S), scanf(3S), ecvt(3) BUGS Very wide fields (>128 characters) fail. Printed 12/6/86 June 5, 1986 3 MALLOC(3) UNIX Programmer's Manual MALLOC(3) NAME malloc, free, realloc, calloc, alloca - memory allocator SYNOPSIS char *malloc(size) unsigned size; free(ptr) char *ptr; char *realloc(ptr, size) char *ptr; unsigned size; char *calloc(nelem, elsize) unsigned nelem, elsize; char *alloca(size) int size; DESCRIPTION Malloc and free provide a general-purpose memory allocation package. Malloc returns a pointer to a block of at least size bytes beginning on a word boundary. The argument to free is a pointer to a block previously allocated by malloc; this space is made available for further allocation, but its contents are left undisturbed. Needless to say, grave disorder will result if the space assigned by malloc is overrun or if some random number is handed to free. Malloc maintains multiple lists of free blocks according to size, allocating space from the appropriate list. It calls sbrk (see brk(2)) to get more memory from the system when there is no suitable space already free. Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. In order to be compatible with older versions, realloc also works if ptr points to a block freed since the last call of malloc, realloc or calloc; sequences of free, malloc and realloc were previously used to attempt storage compaction. This procedure is no longer recommended. Calloc allocates space for an array of nelem elements of size elsize. The space is initialized to zeros. Printed 12/6/86 May 14, 1986 1 MALLOC(3) UNIX Programmer's Manual MALLOC(3) Alloca allocates size bytes of space in the stack frame of the caller. This temporary space is automatically freed on return. Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. If the space is of pagesize or larger, the memory returned will be page-aligned. SEE ALSO brk(2), pagesize(2) DIAGNOSTICS Malloc, realloc and calloc return a null pointer (0) if there is no available memory or if the arena has been detectably corrupted by storing outside the bounds of a block. Malloc may be recompiled to check the arena very stringently on every transaction; those sites with a source code license may check the source code to see how this can be done. BUGS When realloc returns 0, the block pointed to by ptr may be destroyed. The current implementation of malloc does not always fail gracefully when system memory limits are approached. It may fail to allocate memory when larger free blocks could be broken up, or when limits are exceeded because the size is rounded up. It is optimized for sizes that are powers of two. Alloca is machine dependent; its use is discouraged. Printed 12/6/86 May 14, 1986 2 ATOF(3) UNIX Programmer's Manual ATOF(3) NAME atof, atoi, atol - convert ASCII to numbers SYNOPSIS double atof(nptr) char *nptr; atoi(nptr) char *nptr; long atol(nptr) char *nptr; DESCRIPTION These functions convert a string pointed to by nptr to floating, integer, and long integer representation respec- tively. The first unrecognized character ends the string. Atof recognizes an optional string of spaces, then an optional sign, then a string of digits optionally containing a decimal point, then an optional `e' or `E' followed by an optionally signed integer. Atoi and atol recognize an optional string of spaces, then an optional sign, then a string of digits. SEE ALSO scanf(3S) BUGS There are no provisions for overflow. Printed 12/6/86 May 15, 1985 1 STRING(3) UNIX Programmer's Manual STRING(3) NAME strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex - string operations SYNOPSIS #include char *strcat(s1, s2) char *s1, *s2; char *strncat(s1, s2, n) char *s1, *s2; strcmp(s1, s2) char *s1, *s2; strncmp(s1, s2, n) char *s1, *s2; char *strcpy(s1, s2) char *s1, *s2; char *strncpy(s1, s2, n) char *s1, *s2; strlen(s) char *s; char *index(s, c) char *s, c; char *rindex(s, c) char *s, c; DESCRIPTION These functions operate on null-terminated strings. They do not check for overflow of any receiving string. Strcat appends a copy of string s2 to the end of string s1. Strncat copies at most n characters. Both return a pointer to the null-terminated result. Strcmp compares its arguments and returns an integer greater than, equal to, or less than 0, according as s1 is lexico- graphically greater than, equal to, or less than s2. Strncmp makes the same comparison but looks at at most n characters. Strcpy copies string s2 to s1, stopping after the null char- acter has been moved. Strncpy copies exactly n characters, truncating or null-padding s2; the target may not be null- terminated if the length of s2 is n or more. Both return Printed 12/6/86 May 15, 1985 1 STRING(3) UNIX Programmer's Manual STRING(3) s1. Strlen returns the number of non-null characters in s. Index (rindex) returns a pointer to the first (last) occurrence of character c in string s, or zero if c does not occur in the string. Printed 12/6/86 May 15, 1985 2