6aa1f5995a
Add Caldera license. Approved by: David Taylor <davidt@caldera.com> Make buildable under FreeBSD.
276 lines
6.4 KiB
Plaintext
276 lines
6.4 KiB
Plaintext
.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are
|
|
.\" met:
|
|
.\"
|
|
.\" Redistributions of source code and documentation must retain the above
|
|
.\" copyright notice, this list of conditions and the following
|
|
.\" disclaimer.
|
|
.\"
|
|
.\" Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\"
|
|
.\" This product includes software developed or owned by Caldera
|
|
.\" International, Inc. Neither the name of Caldera International, Inc.
|
|
.\" nor the names of other contributors may be used to endorse or promote
|
|
.\" products derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
|
|
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
|
|
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
|
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
|
|
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" @(#)p2 8.1 (Berkeley) 6/8/93
|
|
.\"
|
|
.NH
|
|
BASICS
|
|
.NH 2
|
|
Program Arguments
|
|
.PP
|
|
When a C program is run as a command,
|
|
the arguments on the command line are made available
|
|
to the
|
|
function
|
|
.UL main
|
|
as an argument count
|
|
.UL argc
|
|
and an array
|
|
.UL argv
|
|
of
|
|
pointers to
|
|
character strings
|
|
that contain
|
|
the arguments.
|
|
By convention,
|
|
.UL argv[0]
|
|
is the command name itself,
|
|
so
|
|
.UL argc
|
|
is always greater than 0.
|
|
.PP
|
|
The following program illustrates the mechanism:
|
|
it simply echoes its arguments
|
|
back to the terminal.
|
|
(This is essentially the
|
|
.UL echo
|
|
command.)
|
|
.P1
|
|
main(argc, argv) /* echo arguments */
|
|
int argc;
|
|
char *argv[];
|
|
{
|
|
int i;
|
|
|
|
for (i = 1; i < argc; i++)
|
|
printf("%s%c", argv[i], (i<argc-1) ? ' ' : '\en');
|
|
}
|
|
.P2
|
|
.UL argv
|
|
is a pointer to an array
|
|
whose individual elements are pointers to arrays of characters;
|
|
each is terminated by
|
|
.UL \e0 ,
|
|
so they can be treated as strings.
|
|
The program starts by printing
|
|
.UL argv[1]
|
|
and loops until it has printed them all.
|
|
.PP
|
|
The argument count and the arguments
|
|
are parameters to
|
|
.UL main .
|
|
If you want to keep them around so other
|
|
routines can get at them, you must
|
|
copy them to external variables.
|
|
.NH 2
|
|
The ``Standard Input'' and ``Standard Output''
|
|
.PP
|
|
The simplest input mechanism is to read the ``standard input,''
|
|
which is generally the user's terminal.
|
|
The function
|
|
.UL getchar
|
|
returns the next input character each time it is called.
|
|
A file may be substituted for the terminal by
|
|
using the
|
|
.UL <
|
|
convention:
|
|
if
|
|
.UL prog
|
|
uses
|
|
.UL getchar ,
|
|
then
|
|
the command line
|
|
.P1
|
|
prog <file
|
|
.P2
|
|
causes
|
|
.UL prog
|
|
to read
|
|
.UL file
|
|
instead of the terminal.
|
|
.UL prog
|
|
itself need know nothing about where its input
|
|
is coming from.
|
|
This is also true if the input comes from another program via
|
|
the
|
|
.U
|
|
pipe mechanism:
|
|
.P1
|
|
otherprog | prog
|
|
.P2
|
|
provides the standard input for
|
|
.UL prog
|
|
from the standard output of
|
|
.UL otherprog.
|
|
.PP
|
|
.UL getchar
|
|
returns the value
|
|
.UL EOF
|
|
when it encounters the end of file
|
|
(or an error)
|
|
on whatever you are reading.
|
|
The value of
|
|
.UL EOF
|
|
is normally defined to be
|
|
.UL -1 ,
|
|
but it is unwise to take any advantage
|
|
of that knowledge.
|
|
As will become clear shortly,
|
|
this value is automatically defined for you when
|
|
you compile a program,
|
|
and need not be of any concern.
|
|
.PP
|
|
Similarly,
|
|
.UL putchar(c)
|
|
puts the character
|
|
.UL c
|
|
on the ``standard output,''
|
|
which is also by default the terminal.
|
|
The output can be captured on a file
|
|
by using
|
|
.UL > :
|
|
if
|
|
.UL prog
|
|
uses
|
|
.UL putchar ,
|
|
.P1
|
|
prog >outfile
|
|
.P2
|
|
writes the standard output on
|
|
.UL outfile
|
|
instead of the terminal.
|
|
.UL outfile
|
|
is created if it doesn't exist;
|
|
if it already exists, its previous contents are overwritten.
|
|
And a pipe can be used:
|
|
.P1
|
|
prog | otherprog
|
|
.P2
|
|
puts the standard output of
|
|
.UL prog
|
|
into the standard input of
|
|
.UL otherprog.
|
|
.PP
|
|
The function
|
|
.UL printf ,
|
|
which formats output in various ways,
|
|
uses
|
|
the same mechanism as
|
|
.UL putchar
|
|
does,
|
|
so calls to
|
|
.UL printf
|
|
and
|
|
.UL putchar
|
|
may be intermixed in any order;
|
|
the output will appear in the order of the calls.
|
|
.PP
|
|
Similarly, the function
|
|
.UL scanf
|
|
provides for formatted input conversion;
|
|
it will read the standard input and break it
|
|
up into strings, numbers, etc.,
|
|
as desired.
|
|
.UL scanf
|
|
uses the same mechanism as
|
|
.UL getchar ,
|
|
so calls to them may also be intermixed.
|
|
.PP
|
|
Many programs
|
|
read only one input and write one output;
|
|
for such programs I/O
|
|
with
|
|
.UL getchar ,
|
|
.UL putchar ,
|
|
.UL scanf ,
|
|
and
|
|
.UL printf
|
|
may be entirely adequate,
|
|
and it is almost always enough to get started.
|
|
This is particularly true if
|
|
the
|
|
.UC UNIX
|
|
pipe facility is used to connect the output of
|
|
one program to the input of the next.
|
|
For example, the following program
|
|
strips out all ascii control characters
|
|
from its input
|
|
(except for newline and tab).
|
|
.P1
|
|
#include <stdio.h>
|
|
|
|
main() /* ccstrip: strip non-graphic characters */
|
|
{
|
|
int c;
|
|
while ((c = getchar()) != EOF)
|
|
if ((c >= ' ' && c < 0177) || c == '\et' || c == '\en')
|
|
putchar(c);
|
|
exit(0);
|
|
}
|
|
.P2
|
|
The line
|
|
.P1
|
|
#include <stdio.h>
|
|
.P2
|
|
should appear at the beginning of each source file.
|
|
It causes the C compiler to read a file
|
|
.IT /usr/include/stdio.h ) (
|
|
of
|
|
standard routines and symbols
|
|
that includes the definition of
|
|
.UL EOF .
|
|
.PP
|
|
If it is necessary to treat multiple files,
|
|
you can use
|
|
.UL cat
|
|
to collect the files for you:
|
|
.P1
|
|
cat file1 file2 ... | ccstrip >output
|
|
.P2
|
|
and thus avoid learning how to access files from a program.
|
|
By the way,
|
|
the call to
|
|
.UL exit
|
|
at the end is not necessary to make the program work
|
|
properly,
|
|
but it assures that any caller
|
|
of the program will see a normal termination status
|
|
(conventionally 0)
|
|
from the program when it completes.
|
|
Section 6 discusses status returns in more detail.
|