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.

## Macros

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

## Functions

int | Vnm_sigInt (void)
| Signal and setjmp handling routine. Return the signal interrupt flag. More...
void | Vnm_sigIntSet (void)
| Signal and setjmp handling routine. Set the signal interrupt flag. More...
void | Vnm_sigIntClear (void)
| Signal and setjmp handling routine. Clear the signal interrupt flag. More...
int | Vnm_jmpOk (void)
| Signal and setjmp handling routine. Return the "ok-to-jump" flag. More...
void | Vnm_jmpOkSet (void)
| Signal and setjmp handling routine. Set the "okay-to-jump" flag. More...
void | Vnm_jmpOkClear (void)
| Signal and setjmp handling routine. Clear the "okay-to-jump" flag. More...
jmp_buf * | Vnm_signalInit (void)
| Initialize the signal handling data structures. More...
void | Vnm_regHand (void)
| Register the signal handler with the operating system. More...
void | Vnm_sigHand (int num)
| Handle events such as SIGINT. We must have first been registered with "Vnm_signalInit". More...
double | Vnm_powsafe (double x, double y)
| A safe VPOW function (avoids division by zero). More...
void | Vnm_typeChk (void)
| Check out the sizes of various datatypes. More...
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;. More...
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! More...
void | Vnm_tstart (int timer, const char *name)
| Starts the timer on the particular machine. More...
void | Vnm_tstop (int timer, const char *name)
| Stops the timer on the particular machine. More...
char * | Vnm_getuser (char *user, int usermax)
| Ask the system for the username. More...
char * | Vnm_getos (char *os, int osmax)
| Ask the system for the operating system name. More...
char * | Vnm_gethost (char *host, int hostmax)
| Ask the system for the hostname. More...
char * | Vnm_gethome (char *path, int pathmax)
| Ask the system for the home directory. More...
char * | Vnm_getcwd (char *path, int pathmax)
| Ask the system for the current working directory. More...
int | Vnm_chdir (const char *path)
| Interact with the system to change the working directory. More...
int | Vnm_mkdir (const char *path)
| Interact with the system to make a new directory. More...
int | Vnm_system (const char *cmd)
| An improved ANSI-C "system" call. More...
int | Vnm_systemBack (const char *cmd)
| A background variant of the ANSI-C "system" call. More...
int | Vnm_systemKill (const char *cmd)
| Something like a UNIX "killall" call. More...
int | Vnm_exec (int argc, char **argv)
| An improved UNIX "exec" call. This routine does not return except on error. More...
void | Vnm_sleep (int nusecs)
| Implement a sleep function with microsecond resolution. More...
int | Vnm_ioTag (void)
| Return my I/O tag. More...
int | Vnm_nTags (void)
| Return the total number of tags. More...
void | Vnm_setIoTag (int myTag, int numTags)
| Set my id. More...
FILE * | Vnm_open (const int unit)
| Open an I/O console. More...
int | Vnm_close (const int unit)
| Close an I/O console. We MUST NOT use VASSERT (or Vnm_print!) in this routine. More...
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. More...
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. More...
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. More...
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. More...
void | Vnm_qsort (int *u, int size)
| Front-end to quick sort integer array from [-large] to [+large]. More...
void | Vnm_qsortOrd (int *u, int *ord, int size)
| Front-end to quick sort integer array from [-large] to [+large]. More...
void | Vnm_dqsort (double *u, int size)
| Front-end to quick sort integer array from [-large] to [+large]. More...
void | Vnm_dqsortOrd (double *u, int *ord, int size)
| Front-end to quick sort integer array from [-large] to [+large]. More...

## 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.22 2010/08/12 05:40:36 fetk Exp

Attention

      *
      * MALOC = < Minimal Abstraction Layer for Object-oriented C >
      * Copyright (C) 1994-- 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
      *
      *

## Macro Definition Documentation

## VPOW_SAFE

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

A safe VPOW function (avoids division by zero)

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

## VTIMERS

#define VTIMERS 100

the maiximal timer constant

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

## Function Documentation

## Vnm_chdir()

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

## Vnm_close()

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

## Vnm_dqsort()

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

## Vnm_dqsortOrd()

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

## Vnm_epsmac()

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.

## Vnm_exec()

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

## Vnm_flush()

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

## Vnm_gentokens()

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

## Vnm_getcwd()

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

## Vnm_gethome()

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

## Vnm_gethost()

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

## Vnm_getos()

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

## Vnm_getuser()

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

## Vnm_ioTag()

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.

## Vnm_jmpOk()

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.

## Vnm_jmpOkClear()

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

## Vnm_jmpOkSet()

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

## Vnm_mkdir()

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

## Vnm_nTags()

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.

## Vnm_open()

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

## Vnm_powsafe()

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

## Vnm_print()

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

## Vnm_qsort()

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

## Vnm_qsortOrd()

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

## Vnm_redirect()

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

## Vnm_regHand()

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

## Vnm_setIoTag()

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

## Vnm_sigHand()

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

## Vnm_sigInt()

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.

## Vnm_sigIntClear()

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

## Vnm_sigIntSet()

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

## Vnm_signalInit()

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

## Vnm_sleep()

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

## Vnm_system()

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

## Vnm_systemBack()

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

## Vnm_systemKill()

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

## Vnm_tprint()

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

## Vnm_tstart()

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

## Vnm_tstop()

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

## Vnm_typeChk()

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