The man page tells us several important thing about this function and
it's use in C. All functions (in all programming languages) represent=20
a process. A process has 3 components: input, output and side effect.

Diagran of a process

The inputs of functions are the parameters. The output is the return value=
which
for main is an int. The side effects is all the work the program does whic=
h is not
it's return value.

=46rom the man page, we can see that fgets is one of a group of C functions=
which include
gets, getc and others. In addition, the man page tells us that fgets is in=
the stdio library.
It tells us to include put #include <stdio.h> into our code to gain a=
ccess to the function.
It defines the function for us as follows:

char *fgets(char *s, int size, FILE *stream);

fgets takes 3 parameters for input. A pointer to character data, an intege=
r, and a file stream. =20
Let's look at all thre definitions:

1. char *s: A pointer to character data: A pointer is a symbol which has=
   at it's value a
   memory address as a value. In this case, the memory adress has to be an al=
   located area in memory
   which is typed as a char set of data. In our example, we have a char array=
   called 'name'. With
   arrays, C will convert the symbol of an array to a pointer of the address w=
   here the array is located.
   C does this for us automatically. This is a specific property of arrays an=
   d can not be depended upon
   to happe with other kinds of data constructions unless specified in the C p=
   rogramming specification.
   
2. int size: An integer which represents a SIZE_T data type. SIZE_T is a=
   special data type in C
   which is used to store and describe the size of data constructions in our p=
   rograms.
   
3. FILE *stream: File streams are pointers to devices and or other progra=
   mming constructions which=20
   provide a stream of data into and out of our program. All programs in Unix=
   inherit three streams:
   
   • Standard In (stdin) - usualy the keyboard
   • Standard Out (std) mos=
     t normaly the screen
   • stderr(stderr) - another output most normaly to the=
     screen, but in this case, it is used only for error=20
     messages and the like
   
   

Because C has strict data typing, a function definition is very clear and s=
pecific about the use of=20
a function. Other information which is described in the man page mostly co=
ncerns the side effect of=20
the function. In the case of fgets we are told it reads in at most one les=
s than size characters=20
from stream and stores them into the buffer pointed to by s. In a=
ddition, we are told it
stops read when it recieves an End of File marker (EOF) or a new line (line=
feed) charactor. We are=20
told the line feed character is added to the buffer, and then fgets adds an=
additional character '\0'.

Let's now see how we used it in our program:

fgets(name, sizeof(name), =3D#ff00ff>stdin);

We call fgets with the parameter 'name' which is the symbol which defines o=
ur array of chars. It
automatically convert for us to a pointer to a char data construction, or o=
ur array of chars. The
second argument is sizeof(name). sizeof is a marco in C (similar to a fucnt=
ion) which returns the=20
size of a state construction. In this case, that data construction is nam=
e which is of size 255=20
(which means it has 255 bytes). The third parameter is stdin. stdin is th=
e default symbol for our
Standard Input File Stream pointer. We inherit it from the environment.

Finally, you might notice that we disregard the return value of fgets. Sin=
ce the function stores the
input into 'name', we can do this. However it is often prudent to test the=
return value of a function
to assure that it worked properly. If fgets returns a 'NULL', it would mea=
n that our program=20
encountered a problem in its environment.

It is ciritical that fgets can not try to put more characters into our arra=
y than is allocated for
it in memory. If we did that, we can create a security problem, and invade=
the memory of other
programs in our syste. This is bad. Therefor, we limit the input ability =
of fgets by the size of
our array. This is good and proper programming practice which you must ado=
pt.

The next section of our program introduces looping and flow control. Much =
of our time programming=20
involves working on conditional actions (do this if you hear a click) or lo=
ops (do this over and over
until the the user says uncle). The while key word in C creates a c=
onditional loop. The
expression inside the paranthesis is tested. If it returns a possitive int=
eger, or a non-null
character, it enter the loop. The actions within the loop are inside the c=
urly braces. When
the last action within the braces is evaluated, then it returns to the top =
and tests the expression
in the paranthesis again.

Inside the paranthesis of our while loop, we call a function called strc=
mp (do a man strcmp now).
strcmp looks at two strings and compares them. It then returns a positive =
number, a negitive number or
a 0 (zero) depending upon if the first string is great than, less than or e=
qual to the second.

Characters in a string are reprented by integer numbers which are one byte =
in size. Since their is=20
eight bits in a byte, at most, you can represent 256 characters in a char. =
There is a standard integer
which respesents each key on the keyboard. This standard association of ch=
aracters to byte integers
is called the ASCII standard table. In this table, the letter A is 65 and =
Z is 90. All the rest of
the capital letters fall inbetween in order. The letter 'a' is 97, and 'z'=
is 122. Again, all the=20
lower case letters fall inbetween in order. In this manner, strcmp can com=
pare the strings by their
ASCII representation. It is important to note at this point that there is =
a very tight relationship
between short integers (integers stored in a single byte) and characters in=
C. It should be also noted
that strcmp reads the arrays of chars until it reaches a '\0' (nul) charact=
er. Anything stored after
the nul is ignored.

Our program checks if our input buffer (name) is equal to "\n". "\n" is a =
string constant. All string
constants add a '\0' to the end of their allocated array. So the comaprisi=
on is actually to '\n\0'.
Since fgets adds the null to the end of the string, everyone is happy with =
this comparision.

Our program now repeats all the steps in the curly braces until the user en=
ters "\n" into the keyboard
on an empty line.

This sample program and the explanation is a good introduction to C for a b=
eginner. But their is far
more to learn, even for a beginner, which I hope to explore in the coming m=
onths of the NYLXS journal.
In the meantime, I challenge you to try a few things with this program.

First, change the size integer in fgets to 5 and try to enter 10 characters=
into your keyboard. What
happens with your program?

Second, try rewriting this program so that you fill the char array with 255=
characters and NO NULL value
at the end. How does this affect the strcmp function.=20

(hint try adding this code into your program and comment out the fgets:

                for(i =3D name;i<(name+256);i++){
                        *i =3D getchar();
                        printf("Char entered->%c\n", *i);
                }

Third - Try changing the size of the name array to 5 and enter 10 character=
s on the prompt. =20

What happens?




--=_YiEDa0DAkWCtVe--

____________________________
New Yorker Free Software Users Scene
Fair Use -
because it's either fair use or useless....