/*
   <p>Wrappers for <i>malloc(), realloc()</i> and <i>free()</i>.</p>

   <kbd>
   <b>environ - C programming support functions</b><br>
   Copyright (C) 2005  Martin C Gregorie
   
   This program is free software; you can redistribute it and/or
   modify it under the terms of the Lesser GNU General Public License.
   
   This program 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 General Public License for more details.
  
   You should have received a copy of the Lesser GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
   </kbd>
  
   <p>Contact Martin Gregorie at <i>martin@gregorie.org</i></p>
*/

#include <stdlib.h>
#include <environ.h>

/*
   This is a convenience wrapper for <i>malloc()</i>. It
   allocates <u>n</u> bytes and returns a pointer to it.
   If this fails to get the requested space it abandons
   with a suitable error message by calling <i>error()</i>.
*/
void *get_space(size_t n)
{
   void  *p;

   if (n < 1)
      error("get_space()", "less than one byte requested", "");
      
   p = malloc(n);
   if (!p)
      error("get_space()", "unable to obtain heap space", "");
      
   return p;
}

/*
   This is a convenience wrapper for <i>realloc()</i>. It
   expands the area pointed to by <u>pp</u> to <u>n</u> bytes
   and returns a pointer to the new area.
   If it fails to get the requested space it abandons with
   a suitable error message by calling <i>error()</i>.
*/
void *expand_space(void *pp, size_t n)
{
   void  *p;

   if (!pp)
      error("expand_space()", "NULL pointer to existing space", "");

   if (n < 1)
      error("expand_space()", "can't reduce heap allocation", "");
      
   p = realloc(pp, n);
   if (!p)
      error("expand_space()", "unable to expand heap space", "");
      
   return p;
}

/*
   This is a convenience wrapper for <i>free()</i>. It
   releases the space pointed to by <u>p</u> and returns null.
   If <u>p</u> is null it abandons with a suitable error
   message by calling <i>error()</i>.
*/
void *release_space(void *p)
{
   if (!p)
      error("release_space()", "NULL pointer to space to be released", "");

   free(p);
   return NULL;
}

