pwlib.h File Reference

The main PWLib library definitions and function headers. More...

#include <stdio.h>
#include <getopt.h>

Functions

double gettime (void)
 Get the current time to nanosecond precision.
void print_duration (double remain, int use_long_format)
 Print a description of a duration in long or short format.
void Help (char *progname, const struct option *options, const char *argsdesc[])
 Print a description of the program's options.
int chomp (char *str)
 Remove end-of-line carriage returns and line feeds.


Detailed Description

The main PWLib library definitions and function headers.


Function Documentation

int chomp ( char *  str  ) 

Remove end-of-line carriage returns and line feeds.

This function performs a similar function to Perl's chomp function - however it removes both carriage return (\r, 0x0d) and line feeds (\n, 0x0a) from the end of the line. It replaces all such characters found with null (\0, 0x00). Once it finds a character that is not a carriage return or line feed, it finishes - so these characters will not be removed from within the line if there is a non-EOL character after them. chomp() returns the length of the truncated line. It does not truncate the actual memory allocation.

Parameters:
str A character string to truncate
Returns:
The number of characters in the truncated string, excluding the final terminating null character (as strlen() does).

double gettime ( void   ) 

Get the current time to nanosecond precision.

This returns the number of seconds since the epoch (on Unix systems this means Midnight, January 1 1970 UTC). Fractional seconds are returned; the resolution of this is as good as your system can provide.

Returns:
Current unix time in seconds.

void Help ( char *  progname,
const struct option *  options,
const char *  argsdesc[] 
)

Print a description of the program's options.

This function is designed to give your users a description of the options your program takes in a fairly standard, easy-to-read format. For this it requires two things - a defined string called 'progdesc' which contains a short (one-line) description of what the program does, and an array of strings that contain similarly short descriptions of what each option does, in the same order that the options structure array lists them. (Your options list also has to have the last element with a value of -1 to 'terminate' the array).

For instance, if you had:

    const char progdesc[] = "Mabulate files.";
    const struct option optionset[] = {
        { "file",      required_argument, NULL, 'f' },
        { "help",      no_argument      , NULL, 'h' },
        { "quiet",     no_argument      , NULL, 'q' },
        { "",          -1               , NULL, -1  }
    };
    const char *argsdesc[] = {
        "The name of a file to mabulate.",
        "Get help on using the options of this program.",
        "Don't print any status information while reading."
    };

Then calling Help(argv[0], optionset, argsdesc) would print:

mabulate: Mabulate files
  -f|--file <argument> : The name of the file to mabulate
  -h|--help : Get help on using the options of this program
  -q|--quiet : Don't print any status information while reading.
 * 
Parameters:
progname The name of the called executable (e.g. argv[0])
options An options structure containing the program options
argsdesc An array of option descriptions in the same order

void print_duration ( double  remain,
int  use_long_format 
)

Print a description of a duration in long or short format.

This function provides an easy way to display a time duration - such as the difference in time between the start and end of a process - in a readily comprehensible way. It allows you to select one of two presentations - a 'long' format as an English sentence, such as '18.7 seconds' or '4 hours 12 minutes' - or a 'short' format that is always 7 characters long (e.g. '00.17s ' or '4h12m ').

The time description is printed to stdout. Times that are negative are considered errors.

Parameters:
remain The number of seconds duration of the event.
use_long_format If true, the output will be printed in long descriptive form; if false, a short display format will be used.
See also:
gettime


Generated on Fri Jan 23 11:58:35 2009 for PWLib by  doxygen 1.4.7