## 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.