Algorithms Design   |   C language   |   Index

Embellished sample of the stdlib library interface

This library contains various basic functions and constants.  Almost all C programs use this library.

// File stdlib.h.
// Interface of the stdlib library.
///////////////////////////////////////////////////////////

#ifndef _STDLIB_H
#define _STDLIB_H

#include <stddef.h>


///////////////////////////////////////////////////////////
// Section 1 -- Communication with the operating system          
///////////////////////////////////////////////////////////

// The program ended in an exceptional manner.

#define	EXIT_FAILURE  1

// The program ended in a normal manner.

#define	EXIT_SUCCESS  0

// The exit function interrupts the execution of the
// program and closes the files that the program may have
// opened. If status = 0, the operating system is notified
// that the program ended successfully; otherwise, the
// operating system is notified that the program ended in
// an exceptional manner. Typical use: exit (EXIT_FAILURE).

void exit (int status); 



///////////////////////////////////////////////////////////
// Section 2 -- Pseudorandom numbers
///////////////////////////////////////////////////////////

#define RAND_MAX  2147483647


// The rand function returns a random integer in the closed
// interval 0..RAND_MAX. (We hope that the numbers are
// uniformly distributed in the interval.) Usage:
// i = rand ().

int rand (void);


// The srand function defines a "seed" for the rand
// function. It must be called before the first use of rand
// to ensure that rand does not always return the same
// sequence of numbers. Usage: srand (time (NULL)).

void srand (unsigned int);



///////////////////////////////////////////////////////////
// Section 3 -- Conversion of strings into numbers
///////////////////////////////////////////////////////////

// The strtol ("string-to-long") function receives a string
// s of ASCII characters and an integer b in the set 2..36,
// interprets s as an um integer represented in base b, and
// returns this integer. Example:
//     strtol ("-1234", NULL, 10) returns -1234 and 
//     strtol ("159", NULL, 16) returns 9f.
// The string s must have the following form:
//  - a possibly empty sequence of white-space characters
//    (these characters will be discarded),
//  - possibly followed by a '+' or a '-',
//  - followed by a nonempty sequence of digits in base b
//    (if b is 10, the digits belong to 0..9; if b is 16,
//    the digits belong to 0..9 union a..f; etc.),
//  - followed by a sequence whose first character is not
//    a digit in base b (typically this character is \0).
// The final segment, known as tail of s, is ignored by the
// function. If the parameter tailptr is not NULL, strtol
// stores in *tailptr the address of the tail of s. If the
// integer represented by s does not fit into a long int,
// strtol returns LONG_MAX or LONG_MIN depending on the
// sign of the integer. [This summary omits some details;
// see the full documentation.]  Typical use:
// n = strtol (s, NULL, 10).

long int strtol (char *s, char **tailptr, int b);


// The atoi ("alphanumeric-to-integer") function receives a
// string that represents an integer in decimal notation
// and converts this string into the corresponding integer.
// Example:
//      atoi ("-1234") returns -1234,
//      atoi ("1234") returns 1234.
// The user must be certain that the integer represented by
// the string belongs to the closed interval
// INT_MIN..INT_MAX. Usage: i = atoi (s).
// This function is OBSOLETE.

int atoi (char *); 


// The atof ("alphanumeric-to-float") function receives a
// string that represents a real number in decimal notation
// and converts this string into the corresponding real
// number. Example: 
//     atof ("1234.56") returns 1234.56. 
// Usage: f = atof (str).
// This function is OBSOLETE.

double atof (char *);



///////////////////////////////////////////////////////////
// Section 4 -- Memory allocation
///////////////////////////////////////////////////////////

#define NULL 0

// size_t ("size-type") is the type of the object returned
// by the sizeof operador.

typedef unsigned int size_t;


// The malloc ("memory-allocation") function receives an
// integer N and allocates a block of N consecutive bytes
// in memory. It returns the address of the first byte
// allocated. If it cannot allocate the N bytes, malloc
// returns NULL. Typical use: ptr = malloc (N).

void *malloc (size_t N);


// The realloc function increases or decreases the size of
// a block of memory that has been previously allocated by
// malloc or realloc. The address of the memory block is
// ptr and the desired size of the block is N. Let's say
// that the original size of the block is M. If M < N then
// the function allocates a new block of N bytes, copies to
// it the contents of the old block, and returns the
// address of the new block (or NULL in case of failure).
// The function liberates the original block by means of a
// a call to free. If M > N then no memory allocation is
// done and the contents of the original block is not
// moved; the address of the new, smaller, block is the
// same as that of the original block, and the function
// returns this address. Usage: ptr = realloc (ptr, N).

void *realloc (void *ptr, size_t N);


// The free function receives the address of a block of
// bytes previously allocated by malloc or realloc and
// deallocates the block. Usage: free (ptr).

void free (void *);



///////////////////////////////////////////////////////////
// Section 5 -- Binary search
///////////////////////////////////////////////////////////

// The bsearch function receives the address, key, of an
// object and an array v[0..n-1] of objects. Each object
// occupies s bytes. The array is in increasing order, and
// the comparison between objects is done by the function
// compar (see details below). The function returns the
// address of an element of the array whose value is equal
// to *key or returns NULL if such element does not exist.

void *bsearch (void *key, void *v, size_t n, size_t s,
               int (*compar) (void *, void *));



///////////////////////////////////////////////////////////
// Section 6 -- Sorting 
///////////////////////////////////////////////////////////

// The qsort function rearranges the array v[0..n-1] in
// increasing order. Each element of v occupies s bytes.
// The comparison between elements of the array is done by
// the function compar. (See details below.)

void qsort (void *v, size_t n, size_t s, 
            int (*compar) (void *, void *));


#endif

void qsort (void *v, size_t n, size_t s, 
            int (*compar) (const void *, const void *));