/*
* 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. |