|
|
The manual page for each function describes how you should use the function in your program. Manual pages follow a common format; although, some manual pages may omit some sections:
As shown, the ``Description'' section tells you what the function or macro does. It is the ``Synopsis'' section, though, that contains the critical information about how you use the function or macro in your program. Note that the first line in the ``Synopsis'' isstring
:strcat
,strdup
,strncat
,strcmp
,strncmp
,strcpy
,strncpy
,strlen
,strchr
,strrchr
,strpbrk
,strspn
,strcspn
,strok
- string operations
Synopsis
#include <string.h>
int strcmp(const char *sptr1, const char *sptr2);
Description
. . .strcmp
compares its arguments and returns an integer less than, equal to, or greater than 0, according as the first argument is lexicographically less than, equal to, or greater than the second . . .
#include <string.h>That means that you should include the header file <string.h> in your program because it contains useful definitions or declarations relating to strcmp.
In fact, <string.h> contains the strcmp ``function prototype'' as follows:
extern int strcmp(const char *, const char *);A function prototype describes the kinds of arguments expected and returned by a C language function. Function prototypes afford a greater degree of argument type checking than old-style function declarations, and reduce the chance of using the function incorrectly. Including <string.h>, assures that the C compiler checks calls to strcmp against the official interface. You can, of course, examine <string.h> in the standard place for header files on your system, usually the /usr/include directory.
The ``Synopsis'' for a C library function closely resembles the C language declaration of the function and its arguments. The ``Synopsis'' tells the reader:
#include <stdio.h>The ``Synopsis'' section for feof shows that:int feof( FILE *sfp )
#include <stdio.h> /* include definitions */By way of further illustration, let us look at how you might use strcmp in your own code. The following figure shows a program fragment that will find the bird of your choice in an array of birds.main() { FILE *infile; /* define a file pointer */
. . .
while (!feof(infile)) { /* until end-of-file */ /* operations on the file */ }
}
#include <string.h>/* birds must be in alphabetical order */ char *birds[] = { "albatross", "canary", "cardinal", "ostrich", "penguin" };
/* Return the index of the bird in the array. */ /* If the bird is not in the array, return -1 */
int is_bird(const char *string) { int low, high, midpoint; int cmp_value;
/* use a binary search to find the bird */ low = 0; high = sizeof(birds)/sizeof(char *) - 1; while(low <= high) { midpoint = (low + high)/2; cmp_value = strcmp(string, birds[midpoint]); if (cmp_value < 0) high = midpoint - 1; else if (cmp_value > 0) low = midpoint + 1; else /* found a match */ return midpoint; } return -1; }
How strcmp is used in a program
The format of a ``Synopsis'' section only resembles, but does not duplicate, the format of C language declarations. To show that some components take varying numbers of arguments, the ``Synopsis'' section uses additional conventions not found in actual C function declarations:
#include <stdio.h>The ``Synopsis'' section for printf shows that the argument arg is optional, may be repeated and is not always of the same data type. The ``Description'' section of the manual page provides any remaining information about the function printf and the arguments to it.int printf( char *fmt [ , arg . . . ] )
The ``Return values'' section specifies return values. The text in the ``Return values'' takes a conventional form that describes the return value in case of successful completion followed by the consequences of an unsuccessful completion, as in the following example:
On success, lseek returns a non-negative integer indicating the file pointer value. On failure, lseek returns -1, sets errno to identify the error, and the file pointer remains unchanged.
The ``Errors'' section lists the possible error conditions and their symbolic values from the header file errno.h, as in the following example:
The errno.h symbolic names for error conditions are described in intro(2). For more information on error conditions, see ``System call error handling''.