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.