src/libopts/pgusage.c

   1
   2 /**
   3  * \file pgusage.c
   4  *
   5  * Time-stamp:      "2012-01-29 16:09:14 bkorb"
   6  *
   7  *   Automated Options Paged Usage module.
   8  *
   9  *  This routine will run run-on options through a pager so the
  10  *  user may examine, print or edit them at their leisure.
  11  *
  12  *  This file is part of AutoOpts, a companion to AutoGen.
  13  *  AutoOpts is free software.
  14  *  AutoOpts is Copyright (c) 1992-2012 by Bruce Korb - all rights reserved
  15  *
  16  *  AutoOpts is available under any one of two licenses.  The license
  17  *  in use must be one of these two and the choice is under the control
  18  *  of the user of the license.
  19  *
  20  *   The GNU Lesser General Public License, version 3 or later
  21  *      See the files "COPYING.lgplv3" and "COPYING.gplv3"
  22  *
  23  *   The Modified Berkeley Software Distribution License
  24  *      See the file "COPYING.mbsd"
  25  *
  26  *  These files have the following md5sums:
  27  *
  28  *  43b91e8ca915626ed3818ffb1b71248b pkg/libopts/COPYING.gplv3
  29  *  06a1a2e4760c90ea5e1dad8dfaac4d39 pkg/libopts/COPYING.lgplv3
  30  *  66a5cedaf62c4b2637025f049f9b826f pkg/libopts/COPYING.mbsd
  31  */
  32
  33 /*=export_func  optionPagedUsage
  34  * private:
  35  *
  36  * what:  Decipher a boolean value
  37  * arg:   + tOptions* + pOpts    + program options descriptor +
  38  * arg:   + tOptDesc* + pOptDesc + the descriptor for this arg +
  39  *
  40  * doc:
  41  *  Run the usage output through a pager.
  42  *  This is very handy if it is very long.
  43  *  This is disabled on platforms without a working fork() function.
  44 =*/
  45 void
  46 optionPagedUsage(tOptions* pOptions, tOptDesc* pOD)
  47 {
  48 #if ! defined(HAVE_WORKING_FORK)
  49     if ((pOD->fOptState & OPTST_RESET) != 0)
  50         return;
  51
  52     (*pOptions->pUsageProc)(pOptions, EXIT_SUCCESS);
  53 #else
  54     static pid_t     my_pid;
  55     char zPageUsage[ 1024 ];
  56
  57     /*
  58      *  IF we are being called after the usage proc is done
  59      *     (and thus has called "exit(2)")
  60      *  THEN invoke the pager to page through the usage file we created.
  61      */
  62     switch (pagerState) {
  63     case PAGER_STATE_INITIAL:
  64     {
  65         if ((pOD->fOptState & OPTST_RESET) != 0)
  66             return;
  67
  68         my_pid  = getpid();
  69 #ifdef HAVE_SNPRINTF
  70         snprintf(zPageUsage, sizeof(zPageUsage), TMP_USAGE_FMT, (tAoUL)my_pid);
  71 #else
  72         sprintf(zPageUsage, TMP_USAGE_FMT, (tAoUL)my_pid);
  73 #endif
  74         unlink(zPageUsage);
  75
  76         /*
  77          *  Set usage output to this temporary file
  78          */
  79         option_usage_fp = fopen(zPageUsage, "w" FOPEN_BINARY_FLAG);
  80         if (option_usage_fp == NULL)
  81             _exit(EXIT_FAILURE);
  82
  83         pagerState = PAGER_STATE_READY;
  84
  85         /*
  86          *  Set up so this routine gets called during the exit logic
  87          */
  88         atexit((void(*)(void))optionPagedUsage);
  89
  90         /*
  91          *  The usage procedure will now put the usage information into
  92          *  the temporary file we created above.
  93          */
  94         (*pOptions->pUsageProc)(pOptions, EXIT_SUCCESS);
  95
  96         /* NOTREACHED */
  97         _exit(EXIT_FAILURE);
  98     }
  99
 100     case PAGER_STATE_READY:
 101     {
 102         tCC* pzPager  = (tCC*)getenv(PAGER_NAME);
 103
 104         /*
 105          *  Use the "more(1)" program if "PAGER" has not been defined
 106          */
 107         if (pzPager == NULL)
 108             pzPager = MORE_STR;
 109
 110         /*
 111          *  Page the file and remove it when done.
 112          */
 113 #ifdef HAVE_SNPRINTF
 114         snprintf(zPageUsage, sizeof(zPageUsage), PAGE_USAGE_FMT, pzPager, (tAoUL)my_pid);
 115 #else
 116         sprintf(zPageUsage, PAGE_USAGE_FMT, pzPager, (tAoUL)my_pid);
 117 #endif
 118         fclose(stderr);
 119         dup2(STDOUT_FILENO, STDERR_FILENO);
 120
 121         (void)system(zPageUsage);
 122     }
 123
 124     case PAGER_STATE_CHILD:
 125         /*
 126          *  This is a child process used in creating shell script usage.
 127          */
 128         break;
 129     }
 130 #endif
 131 }
 132
 133 /*
 134  * Local Variables:
 135  * mode: C
 136  * c-file-style: "stroustrup"
 137  * indent-tabs-mode: nil
 138  * End:
 139  * end of autoopts/pgusage.c */