NAME
libio - CVIPtools toolkit library for general purpose I/O,
memory management, etc.
SYNOPSIS
#include <CVIPio.h>
#include <CVIPtoolkit.h>
DESCRIPTION
TYPES AND CONSTANTS
#define LINELENGTH 80
INITIALIZATION
********************************************************
void init_CVIP( int* argcP, char* argv[] )
********************************************************
<argcP> - pointer to the number of command line arguments
<argv> - array of pointers to the command line arguments
Description: searches for global command line arguments such
as -- "-quit" - do not print messages issued w/
cvip_msg(...) "-version" - print current version of CVIP-
tools and then exit program. Author(s): Gregory Hance.
MESSAGES AND ERRORS
*************************************************
void quiet_CVIP(void)
*************************************************
Description: turns off messages displayed by msg_CVIP(...)
*************************************************
void verbose_CVIP(void)
*************************************************
Description: turns on messages displayed by msg_CVIP(...).
Author(s): Gregory Hance.
*************************************************
void usage_CVIP( const char *fn, const char *usage )
*************************************************
<fn> - pointer to character string containing the
name of the program
<usage> - pointer to character string containing a
usage message for the current program.
Description: prints a usage message out to stderr and then
exits the program. Author(s): Gregory Hance.
*************************************************
void perror_CVIP( const char *fn, const char *reason )
*************************************************
<fn> - pointer to character string containing the
name of the program
<usage> - pointer to character string containing a
message about the reason of the error.
Description: print a system error to stderr. Author(s):
Gregory Hance.
*************************************************
void msg_CVIP( const char *fn, const char *msg, ... )
*************************************************
<fn> - pointer to character string containing the
name of the program/function
<msg> - pointer to a format control string in the
form of printf(...) (e.g. "x = %d").
<...> - list of variables, seperated by commas, to be
used by the format control string. (e.g.) -
msg_CVIP("myfunc", "x = %d", 3) => "myfunc: x = 3"
Description: print an informational message. Author(s):
Gregory Hance.
*************************************************
void print_CVIP( const char *msg, ... )
*************************************************
<msg> - pointer to a format control string in the
form of printf(...) (e.g. "x = %d").
<...> - list of variables, seperated by commas, to be
used by the format control string. (e.g.) -
msg_CVIP("myfunc", "x = %d", 3) => "myfunc: x = 3"
Description: print an informational message. Like msg_CVIP
except the source function is not printed. Author(s): Gre-
gory Hance.
*************************************************
void error_CVIP( const char *fn, const char *error, ... )
*************************************************
<fn> - pointer to character string containing the
name of the program/function
<format> - pointer to a format control string in the
form of printf(...) (e.g. "x != %d").
<...> - list of variables, seperated by commas, to be
used by the format control string.
Description: print an error message prefixed by a standard
CVIPtools error tag. (e.g.) - error_CVIP("myfunc", "x !=
%d", 3) => "<myfunc-error>: x != 3" Author(s): Gregory
Hance.
PARSING USER INPUT
*************************************************
char *getString_CVIP(void)
*************************************************
Returns: pointer to string of input text LINELENGTH charac-
ters long
Description: obtain a string of characters from stdin up to
the first newline character. If more than LINELENGTH charac-
ters are read the rest of the input is dicarded up to and
including the newline char.
Diagnostics: returns NULL pointer w/ appropriate error mes-
sage upon (1) memory allocation failure, (2) error reading
from standard input.
Author(s): Gregory Hance.
*************************************************
long getInt_CVIP(int base, long low_limit, long up_limit)
*************************************************
<base> - base/radix of number (2 to 36 inclusive)
<low_limit> - lower limit of acceptable input
<up_limit> - upper limit of acceptable input
Returns: an integer value Description: obtain value of type
int from standard input within a specified range
<low_limit>...<up_limit>. This function uses the C library
function-- strtol(..) and expects the number to consist
of... (1) an optional plus or minus sign. (2) a sequence of
decimal digits which may be preceeded by 0x or 0X for hexa-
decimal values. Diagnostics: prompts user for another value
when the value entered is... (1) - a candidate for overflow,
(2) bogus, (4) not within the specified range <low_limit>...
<up_limit>. Returns with value of 0 w/ appropriate error
message when a call is made to get_int(...) and <low_limit>
< <up_limit> or base is not between 2 and 36. Author(s):
Gregory Hance.
*************************************************
unsigned long getUInt_CVIP(int base, unsigned long low_limit, unsigned long up_limit)
*************************************************
<base> - base/radix of number (2 to 36 inclusive)
<low_limit> - lower limit of acceptable input
<up_limit> - upper limit of acceptable input
Returns: unsigned integer value Description: obtain value of
type unsigned int from standard input within a specified
range <low_limit>...<up_limit>. This function uses the C
library function-- strtoul(..) and expects the number to
consist of... (1) an optional plus or minus sign. (2) a
sequence of decimal digits which may be preceeded by 0x or
0X for hexadecimal values. Diagnostics: prompts user for
another value when the value entered is... (1) - a candidate
for overflow, (2) bogus, (4) not within the specified range
<low_limit>... <up_limit>. Returns with value of 0 w/
appropriate error message when a call is made to
get_uint(...) and <low_limit> < low_limit> - lower limit of acceptable input
<up_limit> - upper limit of acceptable input
Returns: double precison floating point value Description:
obtain value of type double from standard input within a
specified range <low_limit>...<up_limit>. This function
uses the C library function -- strtod(..) and expects the
number to consist of... (1) an optional plus or minus sign.
(2) a sequence of decimal digits possibly containing a sin-
gle decimal point, and (3) an optional exponent part, con-
sisting of the letter e or E. an optional sign, and a
sequence of decimal digits. Diagnostics: prompts user for
another value when the value entered is... (1) - a candidate
for overflow, (2) a candidate for overflow, (3) bogus, (4)
not within the specified range <low_limit>...<up_limit>.
Returns with value of 0 w/ appropriate error message when a
call is made to get_float(...) and <low_limit> < depth> - depth of matrix
<rows> - number of rows in matrix
<cols> - number of columns in matrix
<size> - size of each matrix element (e.g. sizeof(float))
Returns: triple pointer to a new instance of an array of
matrices. Description: allocate an array of <depth>
matrices each with <rows> rows and <cols> cols with an ele-
ment size of <size>. NOTE: use freeMatrix3D_CVIP(...) to
free the matrix Diagnostics: returns NULL pointer w/
corresponding error message upon memory allocation failure.
Author(s): Gregory Hance.
*************************************************
void *allocMatrix_CVIP(unsigned int rows, unsigned int cols, size_t size)
*************************************************
<rows> - number of rows in matrix
<cols> - number of columns in matrix
<size> - size of each matrix element (e.g. sizeof(float))
Returns: double pointer to a new instance of a matrix.
Description: allocate an array of <rows> rows and <cols>
cols with an element size of <size>. NOTE: use
freeMatrix_CVIP(...) to free the matrix. Diagnostics:
returns NULL pointer w/ corresponding error message upon
memory allocation failure. Author(s): Gregory Hance.
*************************************************
void freeMatrix_CVIP(void *matP)
*************************************************
<matP> - pointer to matrix allocated w/ matalloc
<number_of_planes> - depth of matrix (number of data bands)
Description: free the memory associated with a matrix allo-
cated by allocMatrix_CVIP. Author(s): Gregory Hance.
*************************************************
void freeMatrix3D_CVIP(void *matP)
*************************************************
<matP> - pointer to matrix allocated w/ matalloc
<number_of_planes> - depth of matrix (number of data bands)
Description: free the memory associated with a matrix allo-
cated by allocMatrix3D_CVIP Author(s): Gregory Hance
*************************************************
FILE * openRead_CVIP( const char *name)
*************************************************
<name> - file name
Description: opens a file for reading Author(s): Gregory
Hance.
*************************************************
FILE * openWrite_CVIP( const char *name, CVIP_BOOLEAN nice)
*************************************************
<name> - file name
<nice> - priority level of the command; if non-zero, checks
for existing file of same name
Description: writes a file to disk, prompting for overwrite
permission. Author(s): Gregory Hance.
*************************************************
void * close_CVIP(FILE* f)
*************************************************
<f> - file name
Description: closes a file Author(s): Gregory Hance.
BUGS
none as of yet
SEE ALSO
CVIPtools
AUTHOR
Copyright (C) 1992, 1993 SIUE - by Gregory Hance and Scott
Umbaugh.