Main Page   Modules   File List   Related Pages   Examples  

editenv -- implementation.

Detailed Description

editenv contains a function main() that collects the options from the commandline and loops through the remaining non-option arguments.

The arguments can have two forms:

  1. varname
    is used to delete an environment variable (option -d) or to display the contents of a variable (default behaviour).
  2. varname=``a value''
    is used to assign contents to an environment variable. The quotation marks may be omitted if the value to assign consists of a single word.

If the program is running on a Windows NT type of operating system (Windows NT/2000/XP), function doWinNT() is called to query or edit the registry. On Windows 95 type of operating systems (Windows 95/98/me), function doWin95() is called to query or edit the file autoexec.bat. However, if optCurEnv has been set (option -e), the current environment is used instead of the registry or autoexec.bat.

Information about the Win32 API is obtained from the Microsoft® Win32® Programmer's Reference (Win32.hlp) help file as distributed with Borland C++ version 5.


Namespaces

namespace  std

Typedefs

typedef void(* signal_fptr )()
 Ctrl-C (user interrupt) handler function type.


Functions

int author (int status, FILE *stream)
 print author contact information to stream, return status.

int usage (int status, FILE *stream)
 print intent and usage of applicationto stream, return status.

int manual (int status, FILE *stream)
 print a description of this program to stream, return status.

int platform (int status, FILE *stream)
 print platform information to stream, return status.

int doWinNT (const string &cmd, const string &name, string &value)
 set, change or delete environment variable on Windows NT type (Windows NT/2000/XP).

int doWin95 (const string &cmd, const string &name, string &value)
 set, change or delete environment variable on Windows 95 type (Windows 95/98/Me).

int isWinNT ()
 return true if running on Windows NT type OS (Windows NT/2000/XP).

int isWin95 ()
 return true if running on Windows 95 type OS (Windows 95/98/Me).

int splitArg (const string &arg, string &cmd, string &name, string &value)
 split arg into (name,command,value).

void _USERENTRY catcher ()
 Ctrl-C (user interrupt) handler.

int main (int argc, char *argv[])
 handle commandline arguments.

int readCurEnv (const string &name, string &value)
 read variable from current program's environment.

int writeCurEnv (const string &name, const string &value)
 write variable to current program's environment.

int readRegEnv (const string &name, string &value, int cu)
 read environment variable from registry.

int writeRegEnv (const string &name, const string &value, int cu)
 write environment variable to registry.

int deleteRegEnv (const string &name, int cu)
 delete environment variable from registry.

int readIniVar (string name, string &value, string section, string fname)
 read variable from initialization file.

int writeIniVar (string name, string value, string section, string fname)
 write variable to initialization file. See editIniVar().

int deleteIniVar (string name, string section, string fname)
 delete variable from initialization file. See editIniVar().

string replaceExt (const string &name, const string &ext)
 replace filename extension.

int editIniVar (string name, string value, string section, string fname, int doDelete)
 write variable to or delete variable from initialization file.


Variables

const char * title
 program banner.

int optDelete = 0
 option -d: delete environment variable

int optCurDir = 0
 option -c: autoexec in current dir (Win95)

int optCurEnv = 0
 option -e: use current environment

int optKeepReg = 0
 option -k: keep registry editing file (WinNT)

int optHKCU = 0
 option -u: environment variable in Current User environment (WinNT)

int optVerbose = 0
 option -v/V: verbose

Function Documentation

int deleteIniVar (  string  name,
string  section,
string  fname
) 
 

deleteIniVar() deletes variable name from the initialization file specified by fname. section may specify the section to restrict the action to.

However, if a section name is specified, deleteIniVar() warns that it will be ignored: deleteIniVar() uses editIniVar() that is designed to handle autoexec.bat, but is not yet able to handle Windows initialization file [section]'s.

See further editIniVar().

int deleteRegEnv (  const string &  name,
int  cu
) 
 

deleteRegEnv() deletes environment variable name from the registry. writeRegEnv() uses Windows API functions RegOpenKeyEx(), RegDeleteValueEx() and RegCloseKey().

Parameters:
name the name of the variable
cu if true, use Current User hive, otherwise use Local Machine hive
Returns:
0, 1 (Ok, error)

int doWin95 (  const string &  cmd,
const string &  name,
string &  value
)  [static]
 

On Windows 95 type operating systems, file autoexec.bat is edited, or created if none exists. First autoexec.bat is scanned to look for ocurrences of the specified variable and if found, the last location is remembered. Then a new autoexec.bat is created as follows:

  • new a new environment variable is appended to the file
  • update the last occurrence of the environment variable in question is updated
  • remove the last occurrence of the environment variable in question is removed

doWin95() uses functions deleteIniVar(), writeIniVar() and readIniVar() from module iniio.cpp to query and edit autoexec.bat.

Note 1: if multiple definitions of the variable exist, the last but one becomes active again after removal of the last occurrence.

Note 2: unless option -c (current directory) has been specified, it is assumed that autoexec.bat resides on drive C: .

Note 3: if option -e (current environment ) has been specified, file autoexec.bat is not referenced or changed at all.

Parameters:
cmd one of [-:=], meaning delete, display, assign
name variable name
value value queried or value to assign
Returns:
E_OK, E_OPT, E_PS
See also:
deleteIniVar(), writeIniVar(), readIniVar()

int doWinNT (  const string &  cmd,
const string &  name,
string &  value
)  [static]
 

On Windows NT type operating systems, the environment information is contained in the registry.

doWinNT() queries and edits the registry via the Windows API functions. To this end it uses functions deleteRegEnv(), writeRegEnv() and readRegEnv() from module envio.cpp.

Note that it is also possible to use program regedit to edit the registry. For an example of how this can be done, see Edit Registry via Program Regedit.

Parameters:
cmd one of [-:=], meaning delete, display, assign
name variable name
value value queried or value to assign
Returns:
E_OK, E_OPT, E_PS
See also:
deleteRegEnv(), writeRegEnv(), readRegEnv()

int editIniVar (  string  name,
string  value,
string  section,
string  fname,
int  doDelete
) 
 

editIniVar() looks for the variable specified by name in a Windows initializaton (.ini) file, or in the file autoexec.bat as specified by fname and section. Then it

  • creates the variable with the value specified,
  • replaces the variable's contents with the value specified, or
  • deletes the variable from the file id doDelete is true. However, see the note below.

First editIniVar() opens the file specified by fname, or create one if it does not yet exist.

Then editIniVar() locates the line(s) with variable name.

The lines of interest are searched for by looking at the pattern 

   {whitespace}* [sSeEtT] {whitespace}+ [a-zA-Z0-9]+
to read variable names and compare them to the one looked for.

editIniVar() remembers the linenumber of the last occurrence of the variable name.

Now the file fname.new is created to copy the contents of the original file to, skipping the last line with variable name if it must be deleted, or replacing that line when a new value must be assigned to the variable. If it is a new variable, a new line is simply appended to the new file.

Note that if the edited file contains a script with labels and goto's, a line appended to the end of the file may never be reached.

Finally editEnv() makes the new file available as fname and retains a copy of the original file in fname.sav.

Note:
editIniVar() currently cannot select Windows initialization file [section]'s. The section specification is ignored.
editIniVar() is used by functions writeIniVar() and deleteIniVar().

Parameters:
name variable name
value the variable value passed back
section the name of a section [name] (currently ignored)
fname name of the initialization file (currently implemented for autoexec.bat)
doDelete if true, delete the variable specified by name
Returns:
0, 1 (variable edited, error)

int main (  int  argc,
char *  argv[]
) 
 

main() processes the commandline arguments as follows.

If no arguments are specified on the commandline, main() calls usage() to print a short help screen, otherwise main() collects the options from the commandline.

If after collecting the options, there are no arguments left on the commandline specified, main() also calls usage() to print a short description of the program's usage.

Now main() starts handling the commandline arguments (var[=value] ...).

For each argument main() tries to split it into a (name, command, value) triple, using function splitArg(). If optDelete has been set (option -d), command is set to - .

On Windows NT types of operating systems, main() delegates the work to doWinNT() and passes it the triple, On Windows NT types of operating systems, main() delegates the work to doWin95() and passes it the triple.

If main() is deleting or setting an environment variable and doWinNT() or doWin95() returns with an error main() exits, issuing an error message and reminding the user: "do you have sufficient administrative rights?".

If all went well, main() returns E_OK.

Parameters:
argc argument count
argv argument vector
Returns:
see E_OK
Examples:
main-simple.cpp.

int readCurEnv (  const string &  name,
string &  value
) 
 

readCurEnv() reads the contents of variable name from the current program's environment using Windows API function GetEnvironmentVariable() and passes it back in value.

If the variable does not exist, readCurEnv() returns 1, and value is unchanged. On success readCurEnv() returns 0.

Parameters:
name the name of the variable
value the contents of the variable passed back
Returns:
0, 1 (Ok, no variable name)

int readIniVar (  string  name,
string &  value,
string  section,
string  fname
) 
 

readIniVar() reads the contents of a variable from a Windows initializaton (.ini) file, or from the file autoexec.bat. However, see the note below.

If a section name is specified, readIniVar() warns that it will be ignored: readIniVar() is designed to handle autoexec.bat, but it is not yet able to handle Windows initialization file [section]'s.

readIniVar() opens the file specfied by fname. It returns 1 if this fails.

Then readIniVar() locates the line(s) with variable name and obtains the variable's value from the last occurrence.

The lines of interest are searched for by looking at the pattern 

   {whitespace}* [sSeEtT] {whitespace}+ [a-zA-Z0-9]+
to read variable names and compare them to the one looked for.

If the variable is found, readIniVar() reads the value with pattern 

   ^[^=]=[\\"]?([^\\"\\n]+)

When all lines are read, the file is closed. If this fails, readIniVar() returns 1.

Finally readIniVar() returns 0 if the requested variable has been found, or 1 if it could not be read.

Note:
readIniVar() currently cannot select Windows initialization file [section]'s. The section specification is ignored and a warning message is printed to stderr.
Parameters:
name variable name
value the variable value passed back
section the name of a section [name] (currently ignored)
fname name of the initialization file (currently implemented for autoexec.bat)
Returns:
0, 1 (variable value read, error or variable not found)

int readRegEnv (  const string &  name,
string &  value,
int  cu
) 
 

readRegEnv() reads the contents of environment variable name from the registry and passes it back in value. readRegEnv() uses Windows API functions RegOpenKeyEx(), RegQueryValueEx() and RegCloseKey().

Parameters:
name the name of the variable
value the contents of the variable passed back
cu if true, use Current User hive, otherwise use Local Machine hive
Returns:
0, 1 (Ok, error)

int splitArg (  const string &  arg,
string &  cmd,
string &  name,
string &  value
)  [static]
 

splitArg() takes the argument in the form varname[=value] and decomposes it into a variable name, a command and a value.

In all situations the variable name is passed via the name parameter. If only the varname is given, parameter cmd is set to : indicating display. If an assignment is given, parameter cmd is set to = to indicate assign and the value is passed to parameter value.

Parameters:
arg the input argument var[=value]
cmd command specifying assign (=) or display (:)
name variable name concerned
value value to assign
Returns:
0 (Ok)

int writeCurEnv (  const string &  name,
const string &  value
) 
 

writeCurEnv() writes value as the contents of variable name in the current program's environment using Windows API function SetEnvironmentVariable().

Parameters:
name the name of the variable
value the contents of the variable passed back
Returns:
0, 1 (Ok, error)

int writeIniVar (  string  name,
string  value,
string  section,
string  fname
) 
 

writeIniVar() writes variable name with contents value to the initialization file specified by fname. section may specify the section to put the variable in.

However, if a section name is specified, writeIniVar() warns that it will be ignored: writeIniVar() uses editIniVar() that is designed to handle autoexec.bat, but is not yet able to handle Windows initialization file [section]'s.

See further editIniVar().

int writeRegEnv (  const string &  name,
const string &  value,
int  cu
) 
 

writeRegEnv() writes value as the new contents of environment variable name in the registry. writeRegEnv() uses Windows API functions RegOpenKeyEx(), RegSetValueEx() and RegCloseKey().

Parameters:
name the name of the variable
value the new contents of the variable
cu if true, use Current User hive, otherwise use Local Machine hive
Returns:
0, 1 (Ok, error)

Variable Documentation

const char* title
 

Initial value:

   "editenv  " VERSION_STRING "  edit environment variables.\n"
   "Copyright (C) 2003, Leiden University. All rights reserved.\n"
   "editenv is free software, released under the terms of the GNU GPL."

Generated on Tue Apr 29 11:20:46 2003 for Edit Env by doxygen 1.3