pwlib.c File Reference

The main PWLib library code. More...

#include <time.h>
#include <math.h>
#include <stdio.h>
#include <getopt.h>
#include <string.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.
Variables
static struct timespec	_pw_tv = {0,0}
	A buffer for the results of getting the system clock time.

---

Detailed Description

The main PWLib library code.

This library basically contains a few miscellaneous routines that I find useful in my day-to-day C work.

---

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

---

Variable Documentation

struct timespec _pw_tv = {0,0} [static]

A buffer for the results of getting the system clock time.

---