getargs.h

Go to the documentation of this file.

/* @(#)getargs.h    1.22 16/10/23 Copyright 1985-2016 J. Schilling */
/*
 *  Definitions for getargs()/getallargs()/getfiles()
 *
 *  Copyright (c) 1985-2016 J. Schilling
 */
/*
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * See the file CDDL.Schily.txt in this distribution for details.
 * A copy of the CDDL is also available via the Internet at
 * http://www.opensource.org/licenses/cddl1.txt
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file CDDL.Schily.txt from this distribution.
 */
 
#ifndef _SCHILY_GETARGS_H
#define _SCHILY_GETARGS_H
 
#ifndef _SCHILY_MCONFIG_H
#include <schily/mconfig.h>
#endif
#ifndef _SCHILY_UTYPES_H
#include <schily/utypes.h>
#endif
 
#ifdef  __cplusplus
extern "C" {
#endif
 
/*
 * Return values for get*args()/get*files()
 *
 * This package calls options "flags", they are returned from get*args().
 *
 * Note that NOTAFILE is not returned by the interface functions.
 * NOTAFILE is however used as return code from the user's callback functions
 * to signal that the current arg may be an option the callback function does
 * not know and definitely is no file type argument.
 *
 * General rules for the return code of the interface functions
 * get*args()/get*files():
 *
 *  > 0     A file type argument was found
 *    0     All arguments have been parsed
 *  < 0     An error occured
 *
 * Flag and file arg processing should be terminated after getting a return
 * code <= 0.
 */
#define FLAGDELIM     2     /* "--" stopped flag processing */
#define NOTAFLAG      1     /* Not a flag type argument */
#define NOARGS        0     /* No more args         */
#define BADFLAG     (-1)        /* Not a valid flag argument    */
#define BADFMT      (-2)        /* Error in format string   */
#define NOTAFILE    (-3)        /* Seems to be a flag type  */
 
/*
 * The callback functions are called with the following parameters:
 *
 * arg      The option argument
 * valp     A pointer to the related value argument from a get*arg*() call
 * pac      A pointer to the current argument counter
 * pav      A pointer to the current argument vector
 * opt      The option that caused the call
 *
 * The return value of the callback function may be:
 *
 * FLAGDELIM    Pretend "--" stopped flag processing
 * FLAGPARSED   A valid flag was found, getallargs() will continue scanning
 * ------------ the following codes will interrupt getallargs() processing:
 * NOARGS   Pretend all arguments have been examined
 * BADFLAG  Not a valid flag argument
 * BADFMT   General Error
 * NOTAFILE Continue to check the format string for matches with option arg
 */
#define FLAGPARSED    1     /* Flag was sucessfully parsed  */
 
typedef int (*getargfun)    __PR((const char *__arg, void *__valp));
typedef int (*getpargfun)   __PR((const char *__arg, void *__valp,
                        int *__pac, char *const **__pav,
                        const char *__opt));
 
#define NO_ARGFUN   (getargpfun)0
 
struct ga_flags {
    const char  *ga_format; /* Comma separated list for one flag */
    void        *ga_arg;    /* Ptr. to variable to fill for flag */
    getpargfun  ga_funcp;   /* Ptr. for function to call (&/~)   */
};
 
struct ga_props {
    UInt32_t    ga_flags;   /* Flags to define behavior */
    UInt32_t    ga_oflags;  /* State flags          */
    size_t      ga_size;    /* Size of this struct gs_props */
};
 
/*
 * This may be used instead of a struct ga_props * parameter:
 */
#define GA_NO_PROPS (struct ga_props *)0    /* Default behavior */
#define GA_POSIX_PROPS  (struct ga_props *)-1   /* POSIX behavior   */
 
/*
 * Definitions for ga_flags
 */
#define GAF_DEFAULT     0x00    /* The default behavior         */
#define GAF_NO_PLUS     0x01    /* Options may not start with '+'   */
#define GAF_NO_EQUAL        0x02    /* Disallow '=' between opt and val */
#define GAF_NEED_DASH       0x04    /* Need dash before (-name=val),    */
                    /*  name=val is not allowed     */
#define GAF_DELIM_DASHDASH  0x08    /* "--" stops even get?allargs()    */
#define GAF_POSIX       0x1000  /* Will be expanded as shown below  */
 
/*
 * POSIX does not allow options in the form "+option", "-option=value" or
 * "option=value". get*files() needs to know what may be a valid option.
 *
 * If ga_flags == GAF_POSIX, ga_flags is replaced with the value
 * of the current definition for GAF_POSIX_DEFAULT.
 *
 * GAF_NO_PLUS      do not allow options to start with a '+'
 * GAF_NO_EQUAL     do not allow options to contain '=' between name & val
 *
 * Warning: future versions may need different flags for POSIX, better use the
 * GA_POSIX_PROPS "struct" or the GAF_POSIX flag.
 */
#define GAF_POSIX_DEFAULT   (GAF_NO_PLUS | GAF_NO_EQUAL)
 
/*
 * Keep in sync with schily.h
 */
extern  int getallargs __PR((int *, char * const**, const char *, ...));
extern  int getargs __PR((int *, char * const**, const char *, ...));
extern  int getfiles __PR((int *, char * const**, const char *));
extern  char    *getargerror __PR((int));
 
/*
 * The new list versions of the functions need struct ga_props and thus need
 * getargs.h
 */
extern  int getlallargs __PR((int *, char * const**, struct ga_props *,
                        const char *, ...));
extern  int getlargs __PR((int *, char * const**, struct ga_props *,
                        const char *, ...));
extern  int getlfiles __PR((int *, char * const**, struct ga_props *,
                        const char *));
extern  int _getarginit __PR((struct ga_props *, size_t, UInt32_t));
 
#define getarginit(p, f)    _getarginit(p, sizeof (struct ga_props), f)
 
/*
 * The vector versions of the functions need struct ga_flags and thus need
 * getargs.h
 */
extern  int getvallargs __PR((int *, char * const**, struct ga_props *,
                        struct ga_flags *));
extern  int getvargs __PR((int *, char * const**, struct ga_props *,
                        struct ga_flags *));
extern  int getvfiles __PR((int *, char * const**, struct ga_props *,
                        struct ga_flags *));
 
#ifdef  __cplusplus
}
#endif
 
#endif  /* _SCHILY_GETARGS_H */