share/doc/psd/04.uprog/p2

   1 .\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions are
   5 .\" met:
   6 .\"
   7 .\" Redistributions of source code and documentation must retain the above
   8 .\" copyright notice, this list of conditions and the following
   9 .\" disclaimer.
  10 .\"
  11 .\" Redistributions in binary form must reproduce the above copyright
  12 .\" notice, this list of conditions and the following disclaimer in the
  13 .\" documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" All advertising materials mentioning features or use of this software
  16 .\" must display the following acknowledgement:
  17 .\"
  18 .\" This product includes software developed or owned by Caldera
  19 .\" International, Inc.  Neither the name of Caldera International, Inc.
  20 .\" nor the names of other contributors may be used to endorse or promote
  21 .\" products derived from this software without specific prior written
  22 .\" permission.
  23 .\"
  24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  25 .\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  28 .\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36 .\"
  37 .\" $FreeBSD$
  38 .\"
  39 .\"     @(#)p2  8.1 (Berkeley) 6/8/93
  40 .\"
  41 .NH
  42 BASICS
  43 .NH 2
  44 Program Arguments
  45 .PP
  46 When a C program is run as a command,
  47 the arguments on the command line are made available
  48 to the
  49 function
  50 .UL main
  51 as an argument count
  52 .UL argc
  53 and an array
  54 .UL argv
  55 of
  56 pointers to
  57 character strings
  58 that contain
  59 the arguments.
  60 By convention,
  61 .UL argv[0]
  62 is the command name itself,
  63 so
  64 .UL argc
  65 is always greater than 0.
  66 .PP
  67 The following program illustrates the mechanism:
  68 it simply echoes its arguments
  69 back to the terminal.
  70 (This is essentially the
  71 .UL echo
  72 command.)
  73 .P1
  74 main(argc, argv)        /* echo arguments */
  75 int argc;
  76 char *argv[];
  77 {
  78         int i;
  79
  80         for (i = 1; i < argc; i++)
  81                 printf("%s%c", argv[i], (i<argc-1) ? ' ' : '\en');
  82 }
  83 .P2
  84 .UL argv
  85 is a pointer to an array
  86 whose individual elements are pointers to arrays of characters;
  87 each is terminated by
  88 .UL \e0 ,
  89 so they can be treated as strings.
  90 The program starts by printing
  91 .UL argv[1]
  92 and loops until it has printed them all.
  93 .PP
  94 The argument count and the arguments
  95 are parameters to
  96 .UL main .
  97 If you want to keep them around so other
  98 routines can get at them, you must
  99 copy them to external variables.
 100 .NH 2
 101 The ``Standard Input'' and ``Standard Output''
 102 .PP
 103 The simplest input mechanism is to read the ``standard input,''
 104 which is generally the user's terminal.
 105 The function
 106 .UL getchar
 107 returns the next input character each time it is called.
 108 A file may be substituted for the terminal by
 109 using the
 110 .UL <
 111 convention:
 112 if
 113 .UL prog
 114 uses
 115 .UL getchar ,
 116 then
 117 the command line
 118 .P1
 119 prog <file
 120 .P2
 121 causes
 122 .UL prog
 123 to read
 124 .UL file
 125 instead of the terminal.
 126 .UL prog
 127 itself need know nothing about where its input
 128 is coming from.
 129 This is also true if the input comes from another program via
 130 the
 131 .U
 132 pipe mechanism:
 133 .P1
 134 otherprog | prog
 135 .P2
 136 provides the standard input for
 137 .UL prog
 138 from the standard output of
 139 .UL otherprog.
 140 .PP
 141 .UL getchar
 142 returns the value
 143 .UL EOF
 144 when it encounters the end of file
 145 (or an error)
 146 on whatever you are reading.
 147 The value of
 148 .UL EOF
 149 is normally defined to be
 150 .UL -1 ,
 151 but it is unwise to take any advantage
 152 of that knowledge.
 153 As will become clear shortly,
 154 this value is automatically defined for you when
 155 you compile a program,
 156 and need not be of any concern.
 157 .PP
 158 Similarly,
 159 .UL putchar(c)
 160 puts the character
 161 .UL c
 162 on the ``standard output,''
 163 which is also by default the terminal.
 164 The output can be captured on a file
 165 by using
 166 .UL > :
 167 if
 168 .UL prog
 169 uses
 170 .UL putchar ,
 171 .P1
 172 prog >outfile
 173 .P2
 174 writes the standard output on
 175 .UL outfile
 176 instead of the terminal.
 177 .UL outfile
 178 is created if it doesn't exist;
 179 if it already exists, its previous contents are overwritten.
 180 And a pipe can be used:
 181 .P1
 182 prog | otherprog
 183 .P2
 184 puts the standard output of
 185 .UL prog
 186 into the standard input of
 187 .UL otherprog.
 188 .PP
 189 The function
 190 .UL printf ,
 191 which formats output in various ways,
 192 uses
 193 the same mechanism as
 194 .UL putchar
 195 does,
 196 so calls to
 197 .UL printf
 198 and
 199 .UL putchar
 200 may be intermixed in any order;
 201 the output will appear in the order of the calls.
 202 .PP
 203 Similarly, the function
 204 .UL scanf
 205 provides for formatted input conversion;
 206 it will read the standard input and break it
 207 up into strings, numbers, etc.,
 208 as desired.
 209 .UL scanf
 210 uses the same mechanism as
 211 .UL getchar ,
 212 so calls to them may also be intermixed.
 213 .PP
 214 Many programs
 215 read only one input and write one output;
 216 for such programs I/O
 217 with
 218 .UL getchar ,
 219 .UL putchar ,
 220 .UL scanf ,
 221 and
 222 .UL printf
 223 may be entirely adequate,
 224 and it is almost always enough to get started.
 225 This is particularly true if
 226 the
 227 .UC UNIX
 228 pipe facility is used to connect the output of
 229 one program to the input of the next.
 230 For example, the following program
 231 strips out all ascii control characters
 232 from its input
 233 (except for newline and tab).
 234 .P1
 235 #include <stdio.h>
 236
 237 main()  /* ccstrip: strip non-graphic characters */
 238 {
 239         int c;
 240         while ((c = getchar()) != EOF)
 241                 if ((c >= ' ' && c < 0177) || c == '\et' || c == '\en')
 242                         putchar(c);
 243         exit(0);
 244 }
 245 .P2
 246 The line
 247 .P1
 248 #include <stdio.h>
 249 .P2
 250 should appear at the beginning of each source file.
 251 It causes the C compiler to read a file
 252 .IT /usr/include/stdio.h ) (
 253 of
 254 standard routines and symbols
 255 that includes the definition of
 256 .UL EOF .
 257 .PP
 258 If it is necessary to treat multiple files,
 259 you can use
 260 .UL cat
 261 to collect the files for you:
 262 .P1
 263 cat file1 file2 ... | ccstrip >output
 264 .P2
 265 and thus avoid learning how to access files from a program.
 266 By the way,
 267 the call to
 268 .UL exit
 269 at the end is not necessary to make the program work
 270 properly,
 271 but it assures that any caller
 272 of the program will see a normal termination status
 273 (conventionally 0)
 274 from the program when it completes.
 275 Section 6 discusses status returns in more detail.