mdw@git.distorted.org.uk Git - mLib/blob - ui/quis.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for program name
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH quis 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @quis
  33 .\" @ego
  34 .\" @QUIS
  35 .\" @pquis
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH NAME
  39 quis \- remember the program's name for use in messages
  40 .
  41 .\"--------------------------------------------------------------------------
  42 .SH SYNOPSIS
  43 .
  44 .nf
  45 .B "#include <mLib/quis.h>"
  46 .PP
  47 .BI "void ego(const char *" p );
  48 .B "const char *quis(void);"
  49 .B "const char *QUIS;"
  50 .BI "int pquis(FILE *" fp ", const char *" p );
  51 .fi
  52 .
  53 .\"--------------------------------------------------------------------------
  54 .SH DESCRIPTION
  55 .
  56 The
  57 .B ego
  58 function should be called early in your program's initialization
  59 sequence, with the value of
  60 .B argv[0]
  61 as its argument.  It will strip away leading path components, and a
  62 leading `\-' character (in case the program was called as a login
  63 shell), and keep the resulting short name for later.
  64 .PP
  65 The
  66 .B quis
  67 function returns the stored program name.  There is also a macro
  68 .B QUIS
  69 which expands to the name of a global variable whose value is the string
  70 returned by
  71 .BR quis() .
  72 .PP
  73 Don't ask why it's done this way.  There are raisins, but they're mostly
  74 hysterical.
  75 .PP
  76 The function
  77 .B pquis
  78 is passed a file pointer
  79 .I fp
  80 and a string
  81 .IR p :
  82 it writes the string to the file, replacing every lone occurrence of the
  83 character
  84 .RB ` $ '
  85 by the program name.  Pairs
  86 .RB (` $$ ')
  87 are written as single dollar signs.  The return value is zero if
  88 everything went OK, or the constant
  89 .B EOF
  90 if there was an error.
  91 .PP
  92 The program name is used in the messages produced by the
  93 .BR die (3)
  94 and
  95 .BR moan (3)
  96 functions.
  97 .
  98 .\"--------------------------------------------------------------------------
  99 .SH "SEE ALSO"
 100 .
 101 .BR report (3),
 102 .BR mLib (3).
 103 .
 104 .\"--------------------------------------------------------------------------
 105 .SH AUTHOR
 106 .
 107 Mark Wooding, <mdw@distorted.org.uk>
 108 .
 109 .\"----- That's all, folks --------------------------------------------------