sys/man/2/arg

   1 .TH ARG 2
   2 .SH NAME
   3 ARGBEGIN, ARGEND, ARGC, ARGF, EARGF \- process option letters from argv
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .nf
  10 .B ARGBEGIN {
  11 .B char *ARGF();
  12 .B char *EARGF(code);
  13 .B Rune ARGC();
  14 .B } ARGEND
  15 .PP
  16 .B extern char *argv0;
  17 .SH DESCRIPTION
  18 These macros assume the names
  19 .I argc
  20 and
  21 .I argv
  22 are in scope; see
  23 .IR exec (2).
  24 .I ARGBEGIN
  25 and
  26 .I ARGEND
  27 surround code for processing program options.
  28 The code
  29 should be the cases of a C switch on
  30 option characters;
  31 it is executed once for each option character.
  32 Options end after an argument
  33 .BR -- ,
  34 before an argument
  35 .BR - ,
  36 or before an argument that doesn't begin with
  37 .BR - .
  38 .PP
  39 The function macro
  40 .I ARGC
  41 returns the current option character, as an integer.
  42 .PP
  43 The function macro
  44 .I ARGF
  45 returns the current option argument:
  46 a pointer to the rest of the option string if not empty,
  47 or the next argument in
  48 .I argv
  49 if any, or 0.
  50 .I ARGF
  51 must be called just once for each option
  52 argument.
  53 The macro
  54 .I EARGF
  55 is like
  56 .I ARGF
  57 but instead of returning zero
  58 runs
  59 .I code
  60 and, if that returns, calls
  61 .IR abort (2).
  62 A typical value for
  63 .I code
  64 is
  65 .BR usage() ,
  66 as in
  67 .BR EARGF(usage()) .
  68 .PP
  69 After
  70 .IR ARGBEGIN ,
  71 .I argv0
  72 is a copy of
  73 .BR argv[0]
  74 (conventionally the name of the program).
  75 .PP
  76 After
  77 .IR ARGEND ,
  78 .I argv
  79 points at a zero-terminated list of the remaining
  80 .I argc
  81 arguments.
  82 .SH EXAMPLE
  83 This C program can take option
  84 .B b
  85 and option
  86 .BR f ,
  87 which requires an argument.
  88 .IP
  89 .EX
  90 .ta \w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u
  91 #include <u.h>
  92 #include <libc.h>
  93 void
  94 main(int argc, char *argv[])
  95 {
  96         char *f;
  97         print("%s", argv[0]);
  98         ARGBEGIN {
  99         case 'b':
 100                 print(" -b");
 101                 break;
 102         case 'f':
 103                 print(" -f(%s)", (f=ARGF())? f: "no arg");
 104                 break;
 105         default:
 106                 print(" badflag('%c')", ARGC());
 107         } ARGEND
 108         print(" %d args:", argc);
 109         while(*argv)
 110                 print(" '%s'", *argv++);
 111         print("\en");
 112         exits(nil);
 113 }
 114 .EE
 115 .PP
 116 Here is the output from running the command
 117 .B
 118 prog -bffile1 -r -f file2 arg1 arg2
 119 .IP
 120 .B
 121 prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2'
 122 .PP
 123 .SH SOURCE
 124 .B /sys/include/libc.h
 125 .SH SEE ALSO
 126 .IR getflags (8)