System calls and libraries

How to use library functions

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:

name: The manual page names its components and briefly states its purpose. Some manual pages cover several commands, functions or other UnixWare components; thus, components defined along with other related components share the same manual page title. For example, references to the function calloc cite malloc(3C) because the function calloc is described with the function malloc on the malloc(3C) manual page.
Synopsis: Specifies the C language programming interface(s). It summarizes the component interface by compactly representing the order of any arguments for the component, the type of each argument (if any) and the type of value the component returns.
Description: Details the behavior of the component(s), including the built-in file names, the return values, and possible errors. It specifies the functionality of components without stipulating the implementation; it excludes the details of how UnixWare implements these components and concentrates on defining the external features of a standard computing environment instead of the internals of the operating system, such as the scheduler or memory manager. Portable software should avoid using any features or side-effects not explicitly defined.
Examples: Gives code samples, caveats and guidance on usage.
References: Lists related component interface descriptions. These may be other related manual pages in the UnixWare reference manual set as well as other documents.

As an example manual page, we'll look at the strcmp function, which compares character strings. The routine is described on the string(3C) manual page. Related functions are described there as well, but only the sections relevant to strcmp are shown in the following figure.

   string: 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 . . .

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'' is

#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:

the type of value returned by the function
the arguments the function expects to receive when called, if any
the argument types

For example, the ``Synopsis'' for the macro feof is:

#include <stdio.h>

int feof( FILE *sfp )

The ``Synopsis'' section for feof shows that:

The macro feof requires the header file <stdio.h>
The macro feof returns a value of type int
The argument sfp is a pointer to an object of type FILE, defined in <stdio.h>.

To use feof in a program, you need only write the macro call, preceded at some point by the #include control line, as in the following:

   #include <stdio.h>   /* include definitions */
   
   main() {
      FILE *infile;     /* define a file pointer */
   

      . . .
   

      while (!feof(infile)) {   /* until end-of-file */
         /* operations on the file */
      }
   

   }

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.

   #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:

Text in courier represents source-code typed just as it appears.
Text in italic usually represents substitutable argument prototypes.
Square brackets [ ] around arguments indicate optional arguments.
Ellipses . . . indicate that the previous arguments may repeat.
If the type of an argument may vary, the ``Synopsis'' omits the type.

For example, the ``Synopsis'' for the function printf is:

#include <stdio.h>

int printf( char *fmt [ , arg . . . ] )

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.

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:

EBADF: fildes is not an open file descriptor.
ESPIPE: fildes is associated with a pipe or fifo.
EINVAL: The resulting file pointer would be negative.

The errno.h symbolic names for error conditions are described in intro(2). For more information on error conditions, see ``System call error handling''.