vnm.h File Reference

Header file for an ISO C [V]irtual [N]umerical [M]achine. More...

#include <maloc/maloc_base.h>

Include dependency graph for vnm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines

#define VPOW_SAFE(x, y)   (Vnm_powsafe(x,y))
 A safe VPOW function (avoids division by zero).
#define VTIMERS   100
 the maiximal timer constant

Functions

int Vnm_sigInt (void)
 Signal and setjmp handling routine. Return the signal interrupt flag.
void Vnm_sigIntSet (void)
 Signal and setjmp handling routine. Set the signal interrupt flag.
void Vnm_sigIntClear (void)
 Signal and setjmp handling routine. Clear the signal interrupt flag.
int Vnm_jmpOk (void)
 Signal and setjmp handling routine. Return the "ok-to-jump" flag.
void Vnm_jmpOkSet (void)
 Signal and setjmp handling routine. Set the "okay-to-jump" flag.
void Vnm_jmpOkClear (void)
 Signal and setjmp handling routine. Clear the "okay-to-jump" flag.
jmp_buf * Vnm_signalInit (void)
 Initialize the signal handling data structures.
void Vnm_regHand (void)
 Register the signal handler with the operating system.
void Vnm_sigHand (int num)
 Handle events such as SIGINT. We must have first been registered with "Vnm_signalInit".
double Vnm_powsafe (double x, double y)
 A safe VPOW function (avoids division by zero).
void Vnm_typeChk (void)
 Check out the sizes of various datatypes.
double Vnm_epsmac (void)
 Computes the unit roundoff of the machine in single precision. This is defined as the smallest positive machine number u such that 1.0d0 + u .ne. 1.0d0 (in single precision).

A safe hardcoded machine epsilon as alternative:
double value;
value = 1.0e-9;
return value;.
int Vnm_gentokens (char *buf, char **argv, const int argvmax, const char *white, const char *comment)
 Generate an [argv,argc] pair from a character string "buf" (assumed NULL-terminated) in which tokens are separated by whitespace "white" with possible comments "comment" occuring. THE INPUT STRING IS MODIFIED HERE!
void Vnm_tstart (int timer, const char *name)
 Starts the timer on the particular machine.
void Vnm_tstop (int timer, const char *name)
 Stops the timer on the particular machine.
char * Vnm_getuser (char *user, int usermax)
 Ask the system for the username.
char * Vnm_getos (char *os, int osmax)
 Ask the system for the operating system name.
char * Vnm_gethost (char *host, int hostmax)
 Ask the system for the hostname.
char * Vnm_gethome (char *path, int pathmax)
 Ask the system for the home directory.
char * Vnm_getcwd (char *path, int pathmax)
 Ask the system for the current working directory.
int Vnm_chdir (const char *path)
 Interact with the system to change the working directory.
int Vnm_mkdir (const char *path)
 Interact with the system to make a new directory.
int Vnm_system (const char *cmd)
 An improved ANSI-C "system" call.
int Vnm_systemBack (const char *cmd)
 A background variant of the ANSI-C "system" call.
int Vnm_systemKill (const char *cmd)
 Something like a UNIX "killall" call.
int Vnm_exec (int argc, char **argv)
 An improved UNIX "exec" call. This routine does not return except on error.
void Vnm_sleep (int nusecs)
 Implement a sleep function with microsecond resolution.
int Vnm_ioTag (void)
 Return my I/O tag.
int Vnm_nTags (void)
 Return the total number of tags.
void Vnm_setIoTag (int myTag, int numTags)
 Set my id.
FILE * Vnm_open (const int unit)
 Open an I/O console.
int Vnm_close (const int unit)
 Close an I/O console. We MUST NOT use VASSERT (or Vnm_print!) in this routine.
void Vnm_flush (const int unit)
 Attempt to flush the specified i/o stream. We MUST NOT use VASSERT (or Vnm_print!) in this routine.
void Vnm_redirect (const int flag)
 Set/unset the redirect flag for UNIT zero. When redirected, I/O goes to the file: ${MCSH_HOME}/io.mc. We MUST NOT use VASSERT (or Vnm_print!) in this routine.
void Vnm_print (const int unit, const char *format,...)
 External interface to the console i/o routine. We MUST NOT use VASSERT (or Vnm_print!) in this routine.
void Vnm_tprint (const int unit, const char *format,...)
 Add our ioTag to Vnm_print output. We MUST NOT use VASSERT (or Vnm_print!) in this routine.
void Vnm_qsort (int *u, int size)
 Front-end to quick sort integer array from [-large] to [+large].
void Vnm_qsortOrd (int *u, int *ord, int size)
 Front-end to quick sort integer array from [-large] to [+large].
void Vnm_dqsort (double *u, int size)
 Front-end to quick sort integer array from [-large] to [+large].
void Vnm_dqsortOrd (double *u, int *ord, int size)
 Front-end to quick sort integer array from [-large] to [+large].


Detailed Description

Header file for an ISO C [V]irtual [N]umerical [M]achine.

Author:
Michael Holst
Note:
None
Version:
Id
vnm.h,v 1.21 2009/04/24 22:53:50 fetk Exp

Attention:
 *
 * MALOC = < Minimal Abstraction Layer for Object-oriented C >
 * Copyright (C) 1994--2008 Michael Holst
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 * 
 *  

Define Documentation

#define VPOW_SAFE ( x,
 )     (Vnm_powsafe(x,y))

A safe VPOW function (avoids division by zero).

Note:
Useful constants and functions (timers, epsilon, token generators, i/o)

#define VTIMERS   100

the maiximal timer constant

Note:
Useful constants and functions (timers, epsilon, token generators, i/o)


Function Documentation

int Vnm_chdir ( const char *  path  ) 

Interact with the system to change the working directory.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
Success enumeration
Parameters:
path Pointer to the path

int Vnm_close ( const int  unit  ) 

Close an I/O console. We MUST NOT use VASSERT (or Vnm_print!) in this routine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
Success enumeration
Parameters:
unit index for the file unit

void Vnm_dqsort ( double *  u,
int  size 
)

Front-end to quick sort integer array from [-large] to [+large].

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
u Pointer to quick sort integer array
size size of the integer array

void Vnm_dqsortOrd ( double *  u,
int *  ord,
int  size 
)

Front-end to quick sort integer array from [-large] to [+large].

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
u Pointer to quick sort integer array
ord Pointer to reordered array
size size of the integer array

double Vnm_epsmac ( void   ) 

Computes the unit roundoff of the machine in single precision. This is defined as the smallest positive machine number u such that 1.0d0 + u .ne. 1.0d0 (in single precision).

A safe hardcoded machine epsilon as alternative:
double value;
value = 1.0e-9;
return value;.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
the unit roundoff of the machine in single precision.

int Vnm_exec ( int  argc,
char **  argv 
)

An improved UNIX "exec" call. This routine does not return except on error.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
no return except on error
Parameters:
argc number of the command line arguments
argv the command line arguments

void Vnm_flush ( const int  unit  ) 

Attempt to flush the specified i/o stream. We MUST NOT use VASSERT (or Vnm_print!) in this routine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
unit index for the file unit

int Vnm_gentokens ( char *  buf,
char **  argv,
const int  argvmax,
const char *  white,
const char *  comment 
)

Generate an [argv,argc] pair from a character string "buf" (assumed NULL-terminated) in which tokens are separated by whitespace "white" with possible comments "comment" occuring. THE INPUT STRING IS MODIFIED HERE!

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)

Again, the input string "buf" IS MODIFIED; white space characters (defined in the input string "white") are replaced by the NULL character '\0'. The output "argv" is simply a list of pointers to the start of the tokens in "buf", which are NULL-terminated after we replace the white space with NULLs.

We follow convention and "NULL"-terminate "argv" by setting the pointer following the last token to "VNULL". The return value is "argc", the number of tokens found (not including the terminating NULL pointer). For safety you must pass in the maximal length of argv in the parameter "argvmax".

If we encounter a token which begins with a comment character (defined in the input string "comment"), then we ignore the rest of the tokens in the input buffer "buf". This is suitable for parsing shell languages such as sh/ksh/bash which have comments that start with e.g. "#" and continue until a newline.

We DO NOT use the C library function strtok in this routine. (There are some bad implementations of strtok around apparently; the internal state variables maintained by strtok can get very messed up if you use strtok in multiple places in a code.)
Returns:
number of tokens
Parameters:
buf buffer containing message
argv the command line arguments
argvmax maximal number of the command line arguments
white Pointer to the input string
comment token which begins with a comment character

char* Vnm_getcwd ( char *  path,
int  pathmax 
)

Ask the system for the current working directory.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)

Consider it an error if we can't return something useful; therefore we will VASSERT(path!=VNULL) before returning.

Note that unlike Vnm_gethome, a call to Vnm_getcwd returns the current directory, possibly modified from call to call.

I.e., calls to Vnm_chdir can change the current working directory; Vnm_getcwd returns the current directory, whatever that might be.
Returns:
the current working directory
Parameters:
path Pointer to the path
pathmax index for the size of path

char* Vnm_gethome ( char *  path,
int  pathmax 
)

Ask the system for the home directory.

=

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)

The following preference order is used to set the home directory:

MCSH_HOME (the user must define this in his environment)
CWD (always defined as the current working directory)

We consider it an error if we can't return something useful; therefore we will VASSERT(path!=VNULL) before returning.

We settle on a home directory the first time we are called, and then we simply return this fixed home directory forever. In other words, the first call to Vnm_gethome, regardless of who makes the call, establishes the home directory for everyone else (as long as everyone goes through Vnm_gethome!).
Returns:
the home directory
Parameters:
path Pointer to the path
pathmax index for the size of path

char* Vnm_gethost ( char *  host,
int  hostmax 
)

Ask the system for the hostname.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
the hostname
Parameters:
host Pointer to the hostname.
hostmax index for maximal size of host name

char* Vnm_getos ( char *  os,
int  osmax 
)

Ask the system for the operating system name.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
the operating system name
Parameters:
os Pointer to the OS type
osmax index for maximal size of OS name

char* Vnm_getuser ( char *  user,
int  usermax 
)

Ask the system for the username.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
the username of the system
Parameters:
user Pointer to the username of the system
usermax index for maximal size of user name

int Vnm_ioTag ( void   ) 

Return my I/O tag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
my I/O tag.

int Vnm_jmpOk ( void   ) 

Signal and setjmp handling routine. Return the "ok-to-jump" flag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
"ok-to-jump" flag.

void Vnm_jmpOkClear ( void   ) 

Signal and setjmp handling routine. Clear the "okay-to-jump" flag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None

void Vnm_jmpOkSet ( void   ) 

Signal and setjmp handling routine. Set the "okay-to-jump" flag.

Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Author:
Michael Holst
Returns:
None

int Vnm_mkdir ( const char *  path  ) 

Interact with the system to make a new directory.

Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Author:
Michael Holst
Returns:
Success enumeration
Parameters:
path Pointer to the path

int Vnm_nTags ( void   ) 

Return the total number of tags.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
total number of tags.

FILE* Vnm_open ( const int  unit  ) 

Open an I/O console.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
   We MUST NOT use VASSERT (or Vnm_print!) in this routine.   

   The following codes are used:                                               

   unit#      C output unit      
   -------    -------------                                                

   unit==0    garbage   -- Non-interactive i/o; lots of stuff                        
                           (can be redirected to ${MCSH_HOME/io.mc)
   
   unit==1    stdout    -- standard output (Interactive I/O)            

   unit==2    stderr    -- standard error (IMPORTANT interactive I/O)          

   unit==3    history   -- History file ${MCSH_HOME}/hist.mcsh                       

   unit==else /dev/null -- Error...                                
   
Returns:
None
Parameters:
unit index for the file unit

double Vnm_powsafe ( double  x,
double  y 
)

A safe VPOW function (avoids division by zero).

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
output value of a VPOW function
Parameters:
x input parameter
y input parameter

void Vnm_print ( const int  unit,
const char *  format,
  ... 
)

External interface to the console i/o routine. We MUST NOT use VASSERT (or Vnm_print!) in this routine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
unit index for the file unit
format Pointer to the print format

void Vnm_qsort ( int *  u,
int  size 
)

Front-end to quick sort integer array from [-large] to [+large].

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
u Pointer to quick sort integer array
size size of the integer array

void Vnm_qsortOrd ( int *  u,
int *  ord,
int  size 
)

Front-end to quick sort integer array from [-large] to [+large].

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None *
Author:
Michael Holst
Parameters:
u Pointer to quick sort integer array
ord Pointer to reordered array
size size of the integer array

void Vnm_redirect ( const int  flag  ) 

Set/unset the redirect flag for UNIT zero. When redirected, I/O goes to the file: ${MCSH_HOME}/io.mc. We MUST NOT use VASSERT (or Vnm_print!) in this routine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
flag index for the redirect flag

void Vnm_regHand ( void   ) 

Register the signal handler with the operating system.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None

void Vnm_setIoTag ( int  myTag,
int  numTags 
)

Set my id.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
myTag index for the tag
numTags number of tags

void Vnm_sigHand ( int  num  ) 

Handle events such as SIGINT. We must have first been registered with "Vnm_signalInit".

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None

int Vnm_sigInt ( void   ) 

Signal and setjmp handling routine. Return the signal interrupt flag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
Signal interrupt flag.

void Vnm_sigIntClear ( void   ) 

Signal and setjmp handling routine. Clear the signal interrupt flag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None

void Vnm_sigIntSet ( void   ) 

Signal and setjmp handling routine. Set the signal interrupt flag.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None

jmp_buf* Vnm_signalInit ( void   ) 

Initialize the signal handling data structures.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
the signal handling data structures

void Vnm_sleep ( int  nusecs  ) 

Implement a sleep function with microsecond resolution.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
This is hacked out of the "sleep_us" example in Rick Steven's Advance Unix Programming book.
Returns:
None
Parameters:
nusecs number of microseconds

int Vnm_system ( const char *  cmd  ) 

An improved ANSI-C "system" call.

Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Author:
Michael Holst
Returns:
Success enumeration
Parameters:
cmd Pointer to the command

int Vnm_systemBack ( const char *  cmd  ) 

A background variant of the ANSI-C "system" call.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
Success enumeration
Parameters:
cmd Pointer to the command

int Vnm_systemKill ( const char *  cmd  ) 

Something like a UNIX "killall" call.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
Success enumeration
Parameters:
cmd Pointer to the command

void Vnm_tprint ( const int  unit,
const char *  format,
  ... 
)

Add our ioTag to Vnm_print output. We MUST NOT use VASSERT (or Vnm_print!) in this routine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o) For a tag to be added, both of the following conditions must hold:
Vnm_ioTag() >= 0 (I.e., I must have been given a tag)
Vnm_nTags() > 1 (I must not be the only one given a tag)
Returns:
None
Parameters:
unit index for the file unit
format Pointer to the print format

void Vnm_tstart ( int  timer,
const char *  name 
)

Starts the timer on the particular machine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
timer index for the starting timer
name Pointer to the object

void Vnm_tstop ( int  timer,
const char *  name 
)

Stops the timer on the particular machine.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None
Parameters:
timer index for the starting timer
name Pointer to the object

void Vnm_typeChk ( void   ) 

Check out the sizes of various datatypes.

Author:
Michael Holst
Note:
Useful constants and functions (timers, epsilon, token generators, i/o)
Returns:
None


Generated on Mon Aug 9 11:08:02 2010 for MALOC by  doxygen 1.5.6