Infrastructure: Switch testing over to Autotest.

[mLib] / sys / env.h

/* -*-c-*-
 *
 * Fiddling with environment variables
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * mLib 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 Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

#ifndef MLIB_ENV_H
#define MLIB_ENV_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifndef MLIB_SYM_H
#  include "sym.h"
#endif

/*----- Functions provided ------------------------------------------------*/

/* --- @env_get@ --- *
 *
 * Arguments:	@sym_table *t@ = pointer to a symbol table
 *		@const char *name@ = pointer to variable name to look up
 *
 * Returns:	Pointer to corresponding value string, or null.
 *
 * Use:		Looks up an environment variable in the table and returns its
 *		value.  If the variable can't be found, a null pointer is
 *		returned.
 */

extern char *env_get(sym_table */*t*/, const char */*name*/);

/* --- @env_put@ --- *
 *
 * Arguments:	@sym_table *t@ = pointer to a symbol table
 *		@const char *name@ = pointer to variable name to set
 *		@const char *value@ = pointer to value string to assign
 *
 * Returns:	---
 *
 * Use:		Assigns a value to a variable.  If the @name@ contains an
 *		equals character, then it's assumed to be of the form
 *		`VAR=VALUE' and @value@ argument is ignored.  Otherwise, if
 *		@value@ is null, the variable is deleted.  Finally, the
 *		normal case: @name@ is a plain name, and @value@ is a normal
 *		string causes the variable to be assigned the value in the
 *		way you'd expect.
 */

extern void env_put(sym_table */*t*/,
		    const char */*name*/, const char */*value*/);

/* --- @env_import@ --- *
 *
 * Arguments:	@sym_table *t@ = pointer to a symbol table
 *		@char **env@ = pointer to an environment list
 *
 * Returns:	---
 *
 * Use:		Inserts all of the environment variables listed into a symbol
 *		table for rapid access.  Equivalent to a lot of calls to
 *		@env_put@.
 */

extern void env_import(sym_table */*t*/, char **/*env*/);

/* --- @env_export@ --- *
 *
 * Arguments:	@sym_table *t@ = pointer to a symbol table
 *
 * Returns:	A big environment list.
 *
 * Use:		Extracts an environment table from a symbol table
 *		representation of an environment.  The table and all of the
 *		strings are in one big block allocated from the heap.
 */

extern char **env_export(sym_table */*t*/);

/* --- @env_destroy@ --- *
 *
 * Arguments:	@sym_table *t@ = pointer to symbol table
 *
 * Returns:	---
 *
 * Use:		Destroys all the variables in the symbol table.
 */

extern void env_destroy(sym_table */*t*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif