Source: sysadm/SaParam.h


Annotated List
Files
Globals
Hierarchy
Index
/*
 *  Copyright (c) 1998, 2000 Silicon Graphics, Inc.  All Rights Reserved.
 *  
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of version 2.1 of the GNU Lesser General Public
 *  License as published by the Free Software Foundation.
 *  
 *  This program is distributed in the hope that it would be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *  
 *  Further, this software is distributed without any warranty that it is
 *  free of the rightful claim of any third person regarding infringement
 *  or the like.  Any license provided herein, whether implied or
 *  otherwise, applies only to this software file.  Patent licenses, if
 *  any, provided herein do not apply to combinations of this program
 *  with other software, or any other product whatsoever.
 *  
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this program; if not, write the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston MA 02111-1307,
 *  USA.
 *  
 *  Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
 *  Mountain View, CA 94043, or http://www.sgi.com/
 *  
 *  For further information regarding this notice, see:
 *  http://oss.sgi.com/projects/GenInfo/NoticeExplan/
 */
/**
 * SaParam.h
 *
 *	Interface for passing lists of key/value pairs across command
 *	invocations.  key/value pairs can be passed on the command line,
 *	in which case each argument on the command line must be of the
 *	form "key=value", or they can be passed via file descriptor 0
 *	of the command being run.  When key/value pairs are passed via
 *	file descriptor, the parameter "-input" (SaPARAM_INPUT_ARG)
 *	should be specified on the command line.
 *
 *	This API is used by both the caller of the command and the
 *	command itself.  On the calling side, use is as follows:
 *	
 *	// Create an SaParam object
 *	SaParam *params = SaParamCreate();
 *	
 *	// Set parameters for the command
 *	SaParamSet(params, "name", "rogerc");
 *	SaParamSet(params, "uid", "3099");
 *	
 *	// Create a pipe to be used to pass parameters (error code
 *	// omitted)
 *	int pipes[2];
 *	pipe(pipes);
 *	
 *	// Create a child process to run the command (error code
 *	// omitted)
 *	pid = fork();
 *	if (pid == 0) {
 *	    dup2(pipes[0], 0);
 *	    if (pipes[0] != 0)
 *	    {
 *	        close(pipes[0]);
 *	    }
 *	    close(pipes[1]);
 *	    execl(command, command, SaPARAM_INPUT_ARG, NULL);
 *	    perror(command);
 *	    exit(1);
 *	}
 *	
 *	// In the parent process, pass the parameters to the child
 *	close(pipes[0]);
 *	SaParamSend(params, pipes[1]);
 *	
 *	On the command side, use is like this:
 *	
 *	int main(int argc, char *argv[])
 *	{
 *	    const char *name = NULL;
 *	    const char *uid = NULL;
 *	
 *	    // Create params object
 *	    SaParam *params = SaParamCreate();
 *	
 *	    // Parse the command line.
 *	    SaParamParseArgs(params, argc, argv);
 *	
 *	    name = SaParamGet(params, "name");
 *	    uid = SaParamGet(params, "uid");
 *	    
 *	    ...
 *	}
 */

#ident "$Revision: 1.8 $"

#ifndef _SA_PARAM_H
#define _SA_PARAM_H
#ifdef __cplusplus
extern "C" {
#endif

#include <sys/types.h>

/**
 * If SaParamParseArgs() sees this argument, it will read arguments
 * from file descriptor 0 in addition to the command line.
 */
#define SaPARAM_INPUT_ARG "-input"

typedef struct _SaParam SaParam;
typedef struct _SaParamIter SaParamIter;
typedef struct _SaParamExecArgs SaParamExecArgs;

/**
 * Creating and destroying parameters.  SaParamCreate() returns NULL
 * if malloc() fails.
 */
extern SaParam *SaParamCreate(void);
extern void SaParamDestroy(SaParam *param);

/**
 * Getting and setting parameters.  SaParamSet() returns 0 if
 * successful, -1 if malloc() fails.  SaParamGet() returns NULL if
 * there is no value for "key".
 */
extern int SaParamSet(SaParam *param, const char *key, const char *value);
extern const char *SaParamGet(SaParam *param, const char *key);

/**
 * SaParamSetHidden is used to hide sensitive parameters from log
 * files.  If SaParamSetHidden(param, "key", "value") is called, then
 * the SaExecArgs routines will pass the parameter for "key" via stdin
 * rather than on the command line.
 */
extern int SaParamSetHidden(SaParam *param, const char *key, const
			     char *value);
			     

/**
 * Sending and receiving parameters.  SaParamSend() returns 0 if
 * successful, -1 if it cannot write to fd.  Both methods return -1 if
 * malloc() fails.
 */
extern int SaParamSend(SaParam *param, int fd);
extern int SaParamReceive(SaParam *param, int fd);

/**
 * Parse command line arguments of the form "key=value" into key/value
 * pairs.  In any key/value pair, if "value" is the empty string then
 * subsequent calls to SaParamGet() for that key will return NULL.  If
 * the argument SaPARAM_INPUT_ARG is encountered, key value pairs are
 * read from file descriptor 0 as well by calling SaParamReceive().
 * 
 * Returns 0 if successful, -1 if memory is exhausted, if read fails,
 * or if an unrecognized argument is encountered.
 */
extern int SaParamParseArgs(SaParam *param, int argc, char *argv[]);

/**
 * Pass arguments to another command via exec().
 *
 * SaParamExecArgsCreate() breaks "params" into two chunks.  The first
 * chunk is returned by SaParamExecArgsGet() and should be passed to
 * the execv() system call as its second parameter.  The second chunk
 * should be sent to the command's standard input by calling
 * SaParamExecArgsSend().
 *
 * The dividing line between the two chunks is the point at which the
 * size of the arguments + the size of the environment reaches the
 * maximum size supported by the kernel.  If all of the parameters fit
 * on the command line, the second chunk will be empty.
 *
 * Any parameters that were set with SaParamSetHidden() are passed in
 * the second chunk, regardless of whether the args fit.
 * 
 * The "env" argument to SaParamExecArgsCreate() is the environment
 * which will be used for the new command, and is used to calculate
 * the maximum argument size.  The arguments following "env" are the
 * initial arguments for the command; SaParamExecArgsCreate() will
 * append the arguments corresponding to "param".  The last argument
 * to SaParamExecArgsCreate() should be NULL.
 */
extern SaParamExecArgs *SaParamExecArgsCreate(SaParam *param,
					      const char *const *env,
					      ...);

/**
 * SaPramExecArgsCreateV() takes arguments in argc, argv form instead
 * of as varargs. 
 */
extern SaParamExecArgs *SaParamExecArgsCreateV(SaParam *param,
					       int argc,
					       const char *const *argv,
					       const char *const *env);
extern void SaParamExecArgsDestroy(SaParamExecArgs *args);

/** 
 * SaParamExecArgsGet() returns the first chunk in a form suitable for
 * passing to execv().  The return value is owned by libsysadmParam
 * and should not be modified or freed by the caller.  The return
 * value remains valid until SaParamExecArgsDestroy() is called.
 * 
 * SaParamExecArgsSend() sends the second chunk over "fd".  "fd" is
 * assumed to the write end of a pipe which is the command's standard
 * input.
 *
 * SaParamExecArgsSendNeeded() can be used to determine whether a call
 * to SaParamExecArgsSend() is necessary.  If
 * SaParamExecArgsSendNeeded() returns 0, then there is no need to
 * call SaParamExecArgsSend() (although it doesn't hurt).
 */
extern char *const *SaParamExecArgsGet(SaParamExecArgs *args);
extern int SaParamExecArgsSendNeeded(SaParamExecArgs *args);
extern int SaParamExecArgsSend(SaParamExecArgs *args, int fd);

/**
 * Utility function for measuring the size of an environment.
 */
extern size_t SaParamGetEnvSize(const char *const *env);

/**
 * Iterating over the keys.
 */
extern SaParamIter *SaParamIterCreate(SaParam *param);
extern void SaParamIterDestroy(SaParamIter *iter);
extern const char *SaParamIterGetKey(SaParamIter *iter);
extern const char *SaParamIterGetValue(SaParamIter *iter);
extern void SaParamIterReset(SaParamIter *iter);

#ifdef __cplusplus
}
#endif
#endif /* _SA_PARAM_H */

Generated by: rusty@irem on Mon Sep 18 18:07:52 2000, using kdoc 2.0a36.