/[ascend]/trunk/base/generic/utilities/ascEnvVar.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/ascEnvVar.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1061 - (show annotations) (download) (as text)
Sun Jan 7 07:19:52 2007 UTC (13 years, 6 months ago) by johnpye
File MIME type: text/x-chdr
File size: 11553 byte(s)
Fixed compiler warnings from test_ascEnvVar.c
1 /* ASCEND modelling environment
2 Copyright (C) 1997 Benjamin Andrew Allan
3 Copyright (C) 2006 Carnegie Mellon University
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2, or (at your option)
8 any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19 *//**
20 @file
21 Ascend Environment Variable Imitation.
22
23 This file exists because win32, among others, aren't POSIX
24 compliant. In particular, getting and setting environment vars
25 is exceedingly unreliable. This file implements a general way
26 to store and fetch multiple paths.
27
28 Requires:
29 #include "utilities/ascConfig.h"
30
31 Linking against this header requires linking optionally
32 (depending on defines in list.h and the makefile):
33 - ascmalloc.o,
34 - pool.o,
35 and definitely
36 - list.o
37 - ascPanic.o
38 - ascEnvVar.o
39 *//*
40 by Ben Allan
41 Created: 6/3/97
42 Version: $Revision: 1.4 $
43 Version control file: $RCSfile: ascEnvVar.h,v $
44 Date last modified: $Date: 1997/07/18 12:04:08 $
45 Last modified by: $Author: mthomas $
46 */
47
48 #ifndef ASC_ENVVAR_H
49 #define ASC_ENVVAR_H
50
51 #include <utilities/ascConfig.h>
52
53 #define MAX_ENV_VAR_LENGTH 4096
54 /**< Maximum length of an environment variable string. */
55
56 ASC_DLLSPEC(int ) Asc_InitEnvironment(unsigned long anticipated);
57 /**<
58 * Creates an empty environment of size anticipated.
59 * There is a minimum environment size, so the actual size
60 * can be larger than requested. The size will be increased
61 * if necessary during use. Calls to other functions in this
62 * module will fail until Asc_InitEnvironment() is called. It
63 * should not, however, be called more than once without an
64 * intervening call to Asc_DestroyEnvironment(). It is not a
65 * fatal error to do so, but the subsequent calls will fail.
66 *
67 * @param anticipated The expected number of envoronment variables.
68 * @return Returns 0 on success, 1 on failure.
69 */
70
71 ASC_DLLSPEC(void ) Asc_DestroyEnvironment(void);
72 /**<
73 * Destroys any information currently in the stored environment.
74 * All memory associated with the storage is released.
75 */
76
77 ASC_DLLSPEC(int ) Asc_SetPathList(CONST char *var, CONST char *path);
78 /**<
79 * Assigns the elements in path to ASCEND environment variable var.
80 * path should contain one or more strings delimited with :
81 * (Linux/unix) or ; (Windows). Leading and trailing whitespace is
82 * stripped, as is whitespace around any delimiters. Spaces may not
83 * be embedded in var. Spaces embedded in the path string(s) are
84 * assumed significant and left in place. Leading, trailing, and
85 * embedded double delimiters will be parsed as empty strings at the
86 * beginning, end, or middle of the list of paths. Empty strings
87 * will not be stored, so if all substrings parse to empty, you will
88 * have an environment variable registered that has no path values.<br><br>
89 *
90 * Note that if any of the substrings in path are longer than
91 * MAX_ENV_VAR_LENGTH, they will be truncated. The input strings are
92 * not kept by this routine; internal copies are made as needed.<br><br>
93 *
94 * If the environment variable is already assigned, it is replaced
95 * with the new path value. Otherwise, a new ASCEND environement
96 * variable is created.<br><br>
97 *
98 * An error condition occurs and non-zero is returned if:
99 * - Asc_InitEnvironment() has not been called
100 * - var or path is NULL
101 * - var or path is an empty string
102 * - var is longer than MAX_ENV_VAR_LENGTH
103 * - var contains embedded spaces
104 * - available memory is insufficient
105 *
106 * If any of these conditions exist, then the current environment
107 * structure is not modifed. That is, an existing environment variable
108 * will not have it's path value(s) modified if one of these occurs.
109 * Otherwise, you should assume that the value of the old variable will
110 * be destroyed even if the new value is not successfully assigned.
111 *
112 * @param var Name of the ASCEND environment variable to create
113 * or replace.
114 * @param path String(s) to assign to the new environment variable
115 * delimited by : (Linux/unix) or ; (Windows) as appropriate.
116 * @return Returns 0 if var is successfully created and assigned,
117 * 1 otherwise.
118 */
119
120 ASC_DLLSPEC(int) Asc_PutEnv(CONST char *putenv_input_string);
121 /**<
122 * Creates an ASCEND environment variable from a putenv()-type string.
123 * The input string should have the form "varname=path". The path
124 * portion should contain one or more substrings delimited with :
125 * (Linux/unix) or ; (Windows). Leading and trailing whitespace is
126 * stripped, as is whitespace around any delimiters. Spaces may not
127 * be embedded in the varname part of the string. Spaces embedded in
128 * the path string(s) are assumed significant and left in place.
129 * Leading, trailing, and embedded double delimiters will be parsed
130 * as empty strings at the beginning, end, or middle of the list of
131 * paths. Empty strings will not be stored, so if all substrings
132 * parse to empty, you will have an environment variable registered
133 * that has no path values.<br><br>
134 *
135 * Note that putenv_input_string may not be longer than
136 * MAX_ENV_VAR_LENGTH. The input string is not kept by this routine;
137 * internal copies are made as needed.<br><br>
138 *
139 * If the environment variable is already assigned, it is replaced
140 * with the new path value. Otherwise, a new ASCEND environement
141 * variable is created.<br><br>
142 *
143 * An error condition occurs and non-zero is returned if:
144 * - Asc_InitEnvironment() has not been called
145 * - putenv_input_string is NULL
146 * - putenv_input_string is an empty string
147 * - putenv_input_string is longer than MAX_ENV_VAR_LENGTH
148 * - the variable name part of putenv_input_string is empty or
149 * contains embedded spaces
150 * - putenv_input_string does not contain an '=' char
151 * - available memory is insufficient
152 *
153 * If any of these conditions exist, then the current environment
154 * structure is not modifed. That is, an existing environment variable
155 * will not have it's path value(s) modified if one of these occurs.
156 * Otherwise, you should assume that the value of the old variable will
157 * be destroyed even if the new value is not successfully assigned.
158 *
159 * @param putenv_input_string A string having the form "varname=path"
160 * which will be parsed to create an
161 * ASCEND environment variable named
162 * varname having the value path.
163 * @return Returns 0 if variable is successfully created and assigned,
164 * 1 otherwise.
165 */
166
167 ASC_DLLSPEC(int) Asc_ImportPathList(CONST char *osEnvVar);
168 /**<
169 * Imports a system environment variable into the ASCEND environment.
170 * If osEnvVar is already a variable in the ASCEND environment space,
171 * it's value is replaced with the system version. The imported path
172 * is parsed into substrings delimited by ':' or ';' depending on
173 * platform.<br><br>
174 *
175 * Returns non-zero if the variable is not found or empty, memory cannot
176 * be allocated, or the syntax of the variable is unexpected (see
177 * Asc_SetPathList().
178 *
179 * @param osEnvVar The name of a system environment variable to import.
180 * @return Returns 0 if variable is successfully imported, 1 otherwise.
181 */
182
183 ASC_DLLSPEC(int ) Asc_AppendPath(char *envvar, char *newelement);
184 /**<
185 * Adds a new element to the list of values for an ASCEND environment
186 * variable. If envvar does not exist, it is created. newelement is
187 * not parsed into substrings or checked for validity. The input strings
188 * are not kept by this routine; internal copies are made as needed.<br><br>
189 *
190 * An error condition occurs and non-zero is returned if:
191 * - Asc_InitEnvironment() has not been called
192 * - envvar or newelement is NULL
193 * - envvar or newelement is an empty string
194 * - available memory is insufficient
195 *
196 * @param envvar Name of the ASCEND environment variable to modify.
197 * @param newelement New element to add to the list of values for envvar.
198 * @return Returns 0 if newelement was successfully added, 1 otherwise.
199 */
200
201 ASC_DLLSPEC(const char **) Asc_GetPathList(const char *envvar, int *argcPtr);
202 /**<
203 * Retrieve the current value(s) for ASCEND environment variable envvar.
204 * The values are returned as an array of pointers to the value strings.
205 * On return, argcPtr will be set to the number of elements in the
206 * returned array. If envar or argcPtr is NULL, or Asc_InitEnvironment()
207 * has not been called, *argcPtr will be -1. If envar cannot be found
208 * (including if envvar is empty), *argcPtr will be 0. In either of
209 * these cases, the returned array will be NULL. Otherwise, the caller
210 * is responsible for freeing argv; when argv is freed all the data it
211 * contains is simultaneously freed.
212 *
213 * @param envvar Name of the ASCEND environment variable to query.
214 * @param argcPtr Address of an int variable to hold the number of
215 * elements in the returned array.
216 * @return Returns an array of *argcPtr elements containing the string
217 * values of envvar. If *argcPtr is -1 (error) or 0 (none found),
218 * the returned array pointer will be NULL.
219 */
220
221 ASC_DLLSPEC(char*) Asc_GetEnv(const char *envvar);
222 /**<
223 * Retrieve the value(s) of ASCEND environment variable envvar
224 * as a delimited string. The elements of envvar are assembled
225 * into a single string delimited by ':' or ';' depending on
226 * platform. The returned pointer will be NULL if an error occurs,
227 * including envvar being NULL or empty, or Asc_InitEnvironment()
228 * not having been called. The caller is responsible for freeing
229 * the returned pointer.
230 *
231 * @param envvar Name of the ASCEND environment variable to query.
232 * @return Pointer to a string containing the value(s) of envvar
233 * delimited by ':' or ';' depending on platform, or NULL
234 * on error. The caller is responsible for freeing it.
235 */
236
237 ASC_DLLSPEC(const char **) Asc_EnvNames(int *argc);
238 /**<
239 * Retrieve a list of currently defined ASCEND environment variables.
240 * Pointers to the variable names are returned in a NULL-terminated
241 * array having (*argc + 1) elements. The caller is responsible for
242 * freeing argc, but should under no circumstances change or free
243 * any of the strings it points to.<br><br>
244 *
245 * If Asc_InitEnvironment() has not been called or memory cannot be
246 * allocated, *argc will be -1. Otherwise, *argc will be the number
247 * of names found and loaded into the returned array. If *argc >= 0,
248 * the returned array should be freed by the caller.
249 *
250 * @param argc Address of an int variable to hold the number of
251 * non-NULL elements in the returned array.
252 * @return Returns an array of *argc elements containing the string
253 * values of the environment variable names. If *argc is -1
254 * (error) the returned array pointer will be NULL. Otherwise,
255 * the caller should free the array when finished with it.
256 */
257
258 #endif /* ASC_ENVVAR_H */
259

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22