STLSoft: platformstl/system/environment_variable

00001 /* /////////////////////////////////////////////////////////////////////////
00002  * File:        platformstl/system/environment_variable_traits.hpp
00003  *
00004  * Purpose:     Definition of the environment_variable_traits class.
00005  *
00006  * Created:     9th December 2005
00007  * Updated:     10th August 2009
00008  *
00009  * Home:        http://stlsoft.org/
00010  *
00011  * Copyright (c) 2005-2009, Matthew Wilson and Synesis Software
00012  * All rights reserved.
00013  *
00014  * Redistribution and use in source and binary forms, with or without
00015  * modification, are permitted provided that the following conditions are met:
00016  *
00017  * - Redistributions of source code must retain the above copyright notice, this
00018  *   list of conditions and the following disclaimer.
00019  * - Redistributions in binary form must reproduce the above copyright notice,
00020  *   this list of conditions and the following disclaimer in the documentation
00021  *   and/or other materials provided with the distribution.
00022  * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
00023  *   any contributors may be used to endorse or promote products derived from
00024  *   this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00027  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00028  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00029  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00030  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00031  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00032  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00033  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00034  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00035  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * ////////////////////////////////////////////////////////////////////// */
00039 
00040 
00048 #ifndef PLATFORMSTL_INCL_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS
00049 #define PLATFORMSTL_INCL_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS
00050 
00051 /* File version */
00052 #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
00053 # define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS_MAJOR    2
00054 # define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS_MINOR    2
00055 # define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS_REVISION 2
00056 # define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS_EDIT     22
00057 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
00058 
00059 /* /////////////////////////////////////////////////////////////////////////
00060  * Auto-generation and compatibility
00061  */
00062 
00063 /*
00064 [<[STLSOFT-AUTO:NO-UNITTEST]>]
00065 */
00066 
00067 /* /////////////////////////////////////////////////////////////////////////
00068  * Includes
00069  */
00070 
00071 #ifndef PLATFORMSTL_INCL_PLATFORMSTL_HPP_PLATFORMSTL
00072 # include <platformstl/platformstl.hpp>
00073 #endif /* !PLATFORMSTL_INCL_PLATFORMSTL_HPP_PLATFORMSTL */
00074 
00075 #if defined(PLATFORMSTL_OS_IS_UNIX)
00076 #elif defined(PLATFORMSTL_OS_IS_WINDOWS)
00077 #else /* ? operating system */
00078 # error Operating system not discriminated
00079 #endif /* operating system */
00080 
00081 #ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
00082 # include <stlsoft/memory/auto_buffer.hpp>
00083 #endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */
00084 #ifndef STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING
00085 # include <stlsoft/shims/access/string.hpp>
00086 #endif /* !STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING */
00087 
00088 #ifndef STLSOFT_INCL_H_ERRNO
00089 # define STLSOFT_INCL_H_ERRNO
00090 # include <errno.h>
00091 #endif /* !STLSOFT_INCL_H_ERRNO */
00092 #ifndef STLSOFT_INCL_H_STDLIB
00093 # define STLSOFT_INCL_H_STDLIB
00094 # include <stdlib.h> // for environ, getenv(), etc.
00095 #endif /* !STLSOFT_INCL_H_STDLIB */
00096 #if defined(STLSOFT_COMPILER_IS_MWERKS)
00097 # include <crtl.h>  // for _environ
00098 #endif /* compiler */
00099 
00100 /* /////////////////////////////////////////////////////////////////////////
00101  * Feature discrimination
00102  *
00103  * Advanced Prorgramming in the UNIX Environment, Stevens, gives the following:
00104  *
00105  *  Function        Standards                         Implementations
00106  *
00107  *              ANSI C     POSIX.1    XPG3        SVR4         4.3+BSD
00108  *   getenv        *          *         *           *              *
00109  *   putenv        -          ?         *           *              *
00110  *   setenv        -          -         -           -              *
00111  *   unsetenv      -          -         -           -              *
00112  */
00113 
00114 /* set by: putenv / setenv / <not supported> */
00115 
00116 #ifdef PLATFORMSTL_ENVVAR_SET_BY_PUTENV
00117 # undef PLATFORMSTL_ENVVAR_SET_BY_PUTENV
00118 #endif /* PLATFORMSTL_ENVVAR_SET_BY_PUTENV */
00119 
00120 #ifdef PLATFORMSTL_ENVVAR_SET_BY_SETENV
00121 # undef PLATFORMSTL_ENVVAR_SET_BY_SETENV
00122 #endif /* PLATFORMSTL_ENVVAR_SET_BY_SETENV */
00123 
00124 #ifdef PLATFORMSTL_ENVVAR_SET_SUPPORTED
00125 # undef PLATFORMSTL_ENVVAR_SET_SUPPORTED
00126 #endif /* PLATFORMSTL_ENVVAR_SET_SUPPORTED */
00127 
00128 
00129 /* erase by: putenv / putenv (with equals) / unsetenv / <not supported> */
00130 
00131 #ifdef PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV
00132 # undef PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV
00133 #endif /* PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV */
00134 
00135 #ifdef PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS
00136 # undef PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS
00137 #endif /* PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS */
00138 
00139 #ifdef PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV
00140 # undef PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV
00141 #endif /* PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV */
00142 
00143 #ifdef PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
00144 # undef PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
00145 #endif /* PLATFORMSTL_ENVVAR_ERASE_SUPPORTED */
00146 
00147 
00148 /* environ / _environ / <no environ> */
00149 
00150 #ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
00151 # undef PLATFORMSTL_ENVVAR_HAS_ENVIRON
00152 #endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
00153 
00154 #ifdef PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE
00155 # undef PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE
00156 #endif /* PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE */
00157 
00158 
00159 /* putenv has _underscore */
00160 
00161 #ifdef PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE
00162 # undef PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE
00163 #endif /* PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE */
00164 
00165 
00166 #if defined(PLATFORMSTL_ENVVAR_STDC_ONLY)
00167 
00168 #elif defined(PLATFORMSTL_OS_IS_UNIX)
00169 
00170 extern char **environ;
00171 
00172 # if defined(UNIXSTL_OS_IS_LINUX)
00173 #  define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00174 #  define PLATFORMSTL_ENVVAR_SET_BY_SETENV
00175 #  define PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV
00176 # elif defined(UNIXSTL_OS_IS_MACOSX)
00177 #  define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00178 #  define PLATFORMSTL_ENVVAR_SET_BY_SETENV
00179 #  define PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV
00180 # elif defined(UNIXSTL_OSFAMILY_IS_BSD)
00181 #  define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00182 #  define PLATFORMSTL_ENVVAR_SET_BY_SETENV
00183 #  define PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV
00184 # elif defined(UNIXSTL_OSFAMILY_IS_SVR4)
00185 #  define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00186 #  define PLATFORMSTL_ENVVAR_SET_BY_PUTENV
00187 #  define PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV
00188 # elif defined(_WIN32)
00189 #  define PLATFORMSTL_ENVVAR_SET_BY_PUTENV
00190 #  define PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS
00191 #  define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00192 #  define PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE
00193 #  if defined(STLSOFT_COMPILER_IS_BORLAND)
00194     /* putenv() */
00195 #  elif defined(STLSOFT_COMPILER_IS_DMC) || \
00196         defined(STLSOFT_COMPILER_IS_GCC) || \
00197         defined(STLSOFT_COMPILER_IS_INTEL) || \
00198         defined(STLSOFT_COMPILER_IS_MSVC) || \
00199         defined(STLSOFT_COMPILER_IS_MWERKS)
00200 #   define PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE
00201 #  else /* ? compiler */
00202 #  endif /* compiler */
00203 # else /* ? UNIX OS family */
00204 #  error UNIX family flavours other than BSD and SVR4 are not currently supported.
00205 # endif /* UNIX OS family */
00206 #elif defined(PLATFORMSTL_OS_IS_WINDOWS)
00207 # define PLATFORMSTL_ENVVAR_SET_BY_PUTENV
00208 # define PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS
00209 # define PLATFORMSTL_ENVVAR_HAS_ENVIRON
00210 # define PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE
00211 # if defined(STLSOFT_COMPILER_IS_BORLAND)
00212    /* putenv() */
00213 # elif defined(STLSOFT_COMPILER_IS_DMC) || \
00214        defined(STLSOFT_COMPILER_IS_GCC) || \
00215        defined(STLSOFT_COMPILER_IS_INTEL) || \
00216        defined(STLSOFT_COMPILER_IS_MSVC) || \
00217        defined(STLSOFT_COMPILER_IS_MWERKS)
00218 #  define PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE
00219 # else /* ? compiler */
00220 # endif /* compiler */
00221 #else /* ? operating system */
00222 # error Operating systems other than UNIX and Win32 are not currently supported.
00223 #endif /* operating system */
00224 
00225 
00226 #if defined(PLATFORMSTL_ENVVAR_SET_BY_PUTENV) || \
00227     defined(PLATFORMSTL_ENVVAR_SET_BY_SETENV)
00228 # define PLATFORMSTL_ENVVAR_SET_SUPPORTED
00229 #endif /* set ? */
00230 
00231 #if defined(PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV) || \
00232     defined(PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS) || \
00233     defined(PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV)
00234 # define PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
00235 #endif /* set ? */
00236 
00237 /* /////////////////////////////////////////////////////////////////////////
00238  * Namespace
00239  */
00240 
00241 #if defined(_STLSOFT_NO_NAMESPACE) || \
00242     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
00243 /* There is no stlsoft namespace, so must define ::platformstl */
00244 namespace platformstl
00245 {
00246 #else
00247 /* Define stlsoft::platformstl_project */
00248 
00249 namespace stlsoft
00250 {
00251 
00252 namespace platformstl_project
00253 {
00254 #endif /* _STLSOFT_NO_NAMESPACE */
00255 
00256 /* /////////////////////////////////////////////////////////////////////////
00257  * Classes
00258  */
00259 
00265 struct environment_variable_traits
00266 {
00269 public:
00271     typedef char        char_type;
00273 
00276 public:
00277 #ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
00281     static char_type const** get_environ();
00285     static void release_environ(char_type const** env) throw();
00286 
00287 #endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
00288 
00293     static char_type const* get_variable(char_type const* name) throw();
00294 
00295 #ifdef PLATFORMSTL_ENVVAR_SET_SUPPORTED
00304     static int set_variable(char_type const* name, char_type const* value) throw();
00305 #endif /* PLATFORMSTL_ENVVAR_SET_SUPPORTED */
00306 #ifdef PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
00316     static int erase_variable(char_type const* name) throw();
00317 #endif /* PLATFORMSTL_ENVVAR_ERASE_SUPPORTED */
00319 
00322 private:
00323 #if defined(PLATFORMSTL_ENVVAR_SET_BY_PUTENV) || \
00324     defined(PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV)
00325     static int          call_putenv_(char_type const* str) throw();
00326     static int          call_putenv_(char_type const* name, char_type const* value) throw();
00327 #endif /* putenv ? */
00329 };
00330 
00331 /* /////////////////////////////////////////////////////////////////////////
00332  * Implementation
00333  */
00334 
00335 #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
00336 
00337 #ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
00338 inline /* static */ environment_variable_traits::char_type const** environment_variable_traits::get_environ()
00339 {
00340 # ifdef PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE
00341     return const_cast<char_type const**>(_environ);
00342 # else /* ? PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE */
00343     return const_cast<char_type const**>(environ);
00344 # endif /* PLATFORMSTL_ENVVAR_ENVIRON_HAS_UNDERSCORE */
00345 }
00346 
00347 inline /* static */ void environment_variable_traits::release_environ(environment_variable_traits::char_type const**) throw()
00348 {}
00349 #endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
00350 
00351 inline /* static */ environment_variable_traits::char_type const* environment_variable_traits::get_variable(environment_variable_traits::char_type const* name) throw()
00352 {
00353     STLSOFT_ASSERT(NULL != name);
00354     STLSOFT_MESSAGE_ASSERT("Name may not contain '='", NULL == ::strchr(name, '='));
00355 
00356     return const_cast<char_type const*>(::getenv(name));
00357 }
00358 
00359 #ifdef PLATFORMSTL_ENVVAR_SET_SUPPORTED
00360 inline /* static */ int environment_variable_traits::set_variable(environment_variable_traits::char_type const* name, environment_variable_traits::char_type const* value) throw()
00361 {
00362     STLSOFT_ASSERT(NULL != name);
00363     STLSOFT_ASSERT(NULL != value);
00364     STLSOFT_MESSAGE_ASSERT("Name may not contain '='", NULL == ::strchr(name, '='));
00365 
00366 #if defined(PLATFORMSTL_ENVVAR_SET_BY_PUTENV)
00367     return call_putenv_(name, value);
00368 #elif defined(PLATFORMSTL_ENVVAR_SET_BY_SETENV)
00369     return ::setenv(name, value, 1);
00370 #endif /* unsetenv */
00371 }
00372 #endif /* PLATFORMSTL_ENVVAR_SET_SUPPORTED */
00373 
00374 #ifdef PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
00375 inline /* static */ int environment_variable_traits::erase_variable(environment_variable_traits::char_type const* name) throw()
00376 {
00377     STLSOFT_ASSERT(NULL != name);
00378     STLSOFT_MESSAGE_ASSERT("Name may not contain '='", NULL == ::strchr(name, '='));
00379 
00380 #if defined(PLATFORMSTL_ENVVAR_ERASE_BY_UNSETENV)
00381     static_cast<void>(::unsetenv(name));    // Some definitions of unsetenv() return void
00382 
00383     return 0;
00384 #else /* ? unsetenv */
00385     return call_putenv_(name, NULL);
00386 #endif /* unsetenv */
00387 }
00388 #endif /* PLATFORMSTL_ENVVAR_ERASE_SUPPORTED */
00389 
00390 #if defined(PLATFORMSTL_ENVVAR_SET_BY_PUTENV) || \
00391     defined(PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV)
00392 
00393 inline /* static */ int environment_variable_traits::call_putenv_(environment_variable_traits::char_type const* str) throw()
00394 {
00395 #ifdef PLATFORMSTL_ENVVAR_PUTENV_HAS_UNDERSCORE
00396     return ::_putenv(str);
00397 #else /* ? compiler */
00398     return ::putenv(str);
00399 #endif /* compiler */
00400 }
00401 
00402 inline /* static */ int environment_variable_traits::call_putenv_(environment_variable_traits::char_type const* name, environment_variable_traits::char_type const* value) throw()
00403 {
00404     STLSOFT_ASSERT(NULL != name);
00405     STLSOFT_ASSERT(NULL == ::strchr(name, '='));
00406 
00407 #ifndef PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS
00408     if(NULL == value)
00409     {
00410         return call_putenv_(name);
00411     }
00412     else
00413 #endif /* !PLATFORMSTL_ENVVAR_ERASE_BY_PUTENV_EQUALS */
00414     {
00415 #ifdef STLSOFT_CF_THROW_BAD_ALLOC
00416         try
00417 #endif /* STLSOFT_CF_THROW_BAD_ALLOC */
00418         {
00419             const ss_size_t                 cchName     =   ::strlen(name);
00420             const ss_size_t                 cchValue    =   stlsoft::c_str_len(value);
00421             stlsoft::auto_buffer<char_type> buff(cchName + 1 + cchValue + 1);
00422 
00423 #ifdef STLSOFT_CF_THROW_BAD_ALLOC
00424             STLSOFT_ASSERT(!buff.empty());
00425 #else /* ? STLSOFT_CF_THROW_BAD_ALLOC */
00426             if(buff.empty()) // This check worthwhile since implementation of ator may not support bad_alloc
00427             {
00428                 errno = ENOMEM;
00429                 return -1;
00430             }
00431             else
00432 #endif /* STLSOFT_CF_THROW_BAD_ALLOC */
00433             {
00434                 ::strncpy(&buff[0], name, cchName);
00435                 buff[cchName] = '=';
00436                 ::strncpy(&buff[cchName + 1], value, cchValue);
00437                 buff[cchName + 1 + cchValue] = '\0';
00438                 STLSOFT_ASSERT(::strlen(buff.data()) == buff.size() - 1);
00439 
00440                 return call_putenv_(buff.data());
00441             }
00442         }
00443 #ifdef STLSOFT_CF_THROW_BAD_ALLOC
00444         catch(std::bad_alloc &)
00445         {
00446             errno = ENOMEM;
00447             return -1;
00448         }
00449 #endif /* STLSOFT_CF_THROW_BAD_ALLOC */
00450     }
00451 }
00452 #endif /* putenv ? */
00453 
00454 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
00455 
00456 /* ////////////////////////////////////////////////////////////////////// */
00457 
00458 #if defined(_STLSOFT_NO_NAMESPACE) || \
00459     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
00460 } // namespace platformstl
00461 #else
00462 } // namespace platformstl_project
00463 } // namespace stlsoft
00464 #endif /* _STLSOFT_NO_NAMESPACE */
00465 
00466 /* ////////////////////////////////////////////////////////////////////// */
00467 
00468 #endif /* !PLATFORMSTL_INCL_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_TRAITS */
00469 
00470 /* ///////////////////////////// end of file //////////////////////////// */