(no commit message)

[ikiwiki.git] / docs / developer / C_Development_Under_DragonFly_BSD-Volume_1_C_For_Beginners.mdwn

# C Development Under DragonFly BSD Volume 1: C For Beginners 

## old title Volume 1: C For Beginners


[[!toc  levels=2]]




## Prologue 


* Discuss a small bit about C's features, pros and cons, etc. 


* Tell a bit about its history, authors, etc. 


* Why is understanding C important? 


* Discuss its use in DragonFly 


* Why is DragonFly BSD a good programming environment? 



Contrary to what might be perceived of the C programming language by a beginner, the language is not large at all. In fact, C is one of the smaller programming languages, with a mere 32 keywords. 



Written singlehandedly in 1972 by AT&T Bell Laboratories' Dennis Ritchie, C has had almost thirty years to mature into what it is today. It is a general-purpose, low-level programming language which has, over the years, been used for myriad tasks. Many of the programs and utilities (and probably the better part of the operating systems) you've used have been written in C. 



## Discussion of the C Language  



This chapter should be a breeze-through of the following chapters, touching on several key points, but mostly providing information for the sake of getting the reader oriented with the syntax, writing style, etc. 



### Overview 



In this chapter, we will walk through the C language, touching on some of the more important features of the language. After reading this chapter, you should be superficially familiar with the [syntax](/C_Development_Under_DragonFly_BSD-Volume_7_Glossary_and_Tables_for_all_Volumes/#index1h1) of the C language as well as the aesthetical organization of source code within programs. 





### Our First Program 



In the tradition of any programming book, we will begin our journey into the C programming language with a program which will output the words, "Hello, World!" onto our screen. In C, "Hello, World!" looks like this: 



    

    /* Includes */

    #include <stdio.h>

    

    /* Main */

    int

    main(void)

    {

            printf("Hello, World!\n");

            return (0);

    }





While this is one of the most basic C programs that can be written, there are many things that can be learned from it. Let's take this program apart and discuss what each section of it does. 



    

    /* Includes */





The first line in this program is a [comment](/C_Book_Glossary). In C, comments are declared in between the symbol combinations `/*` and `*/`; they are not compiled and are only useful to inform persons reading the source code of what is happening in the code. We'll talk more about them in our next example. 



    

    #include <stdio.h>





Since C is such a small language, it's pretty unuseful by itself. DragonFly BSD provides an implementation of the [standard library](/C_Book_Glossary), which contains a number of useful functions. [Header Files](/C_Book_Glossary) contain definitions of functions, structures, and other interface portions of a program. In this case, we're telling the compiler to load the header file containing definitions for standard input and output routines. We use the file `stdio.h` because it provides the definition of the function `printf()`, which we use later in the program. 



    

    /* Main */





Here, we see a comment implying that we're looking at the main section of the program. This is the case; all C programs begin with the `main` function, which is defined directly after this comment. 



    

    int

    main(void)





This is the definition of the `main` function, and there are several things that we should touch on before taking a look into the body of the function. First of all, function declarations all follow a standard pattern: 



    

    modifier type functionname(parameterlist);





The [modifier](/C_Book_Glossary) is an optional keyword which specifies (modifies) the function type. [type](/C_Book_Glossary) refers to the variable type that should be returned by the function. `Functionname` is any valid C language variable name. The list of parameters that should be passed to the function are given in a comma-delimited format in the `parameterlist`. 



Using the above information, we can assume that the modifier is missing, the type of the function is `int` (this means "integer"), its name is `main` and it accepts an argument of type `void`. All these assumptions are correct except the last; a function accepting an argument of type `void` actually signifies a function with no arguments. Thus, we would read our definition of the main function, "Main is a function returning an integer type and accepting no (void) arguments." 



    

    {

            printf("Hello, World!\n");

            return (0);

    }





This is the body of the main function. All function bodies must be contained between a matching set of open and closed curly braces ({ and }). 



    

            printf("Hello, World!\n");





The function printf is provided in the standard library, and is used to print formatted output to the standard output (usually a monitor, console, or terminal session). In this case, we're asking it to print the [string](/C_Book_Glossary), "Hello, World!\n" to the standard output. If you were to actually run this program, you would notice the following output: 



    

    $ ./hello

    Hello, World!

    $





What happened to the `\n? \n` is an escape string signifying a newline. Since it is illegal to put line breaks inside of C strings, we must signify that we would like to insert one somehow. `\n` is the solution. 



    

    return (0);





Since we defined the `main` function as a function returning an integer, we must actually do so. The `return` keyword signifies that the function should terminate at its current point of execution and give the returned value to its calling function. 



You may be wondering where this value is returned - after all, the `main` function signifies the beginning of the program, so why do we need to return something from it? There's nothing calling our program, is there? In fact, there is, but this is outside the scope of this section. This will be discussed later in the book, but if you absolutely can't wait to find out, please see the Glossary entry on the [return](/C_Book_Glossary) keyword. 



So, we're done with our overview of the source code. Now how do we run it? 



To be able to run the program, we must first compile it. Compiling C programs is quite simple in DragonFly BSD; the GNU Compiler Collection (GCC) is included in DragonFly BSD and it is used to compile C programs which can be distributed among and run on any DragonFly BSD system. To compile our "Hello, World!" program above, simply save the text of the program in a file called `hello.c`. Run the following command to compile the source code file: 



    

    $ cc hello.c -o hello





When the program is compiled, you can test it with: 



    

    $ ./hello





This will produce the output we saw above: 



    

    Hello, World!

    $





Most of the programs discussed in this book can be compiled in this same manner. 



## Simple Concepts - Variables, Operators, Types and Expressions 



In most programming languages, understanding how to program in that language requires the understanding of some quite simple concepts: variables, operators, types and expressions. What do all of these terms mean? 



 **Variables**  are essentially mnemonics for data; this definition applies to C as well. Variables are used in C to refer to data. The term "variable" itself implies that the data contained in the mnemonic may vary. This is not always the case in C and, in this sense, the term "variable" may seem a misnomer. 



 **Operators**  refer to popular mathematical operators. Operators are symbols that represent operations that should be applied to or carried out upon a variable. The symbol "+" in C is thus the addition operator, "-" is the subtraction operator, and so forth. 



 **Types**  refer to the sort of data that a variable can contain. In C, there are several data types, including integral, decimal, character and grouped types (called structures). 



An  **expression**  is the grouping of the above (variables, operators and types) to express a certain process. 



### Variables and Types 



Variables in C are used for many different purposes: to keep track of iterations in a loop, to store data from a file, to store input from a user, and much more. However, different types of variables might be used for each one of the previous examples. Since variables and types are so closely related, we will discuss them hand-in-hand in this section. 



C is what is called a `typed`  language. This means that variables must be given a type when they are defined in a program. As explained earlier, variables in C can be of several data types. The following types are supported in C: 




* `int` -- `int` refers to an integral number (an integer). An integer is any non-fractional number (..., -1, 0, 1, ...). 


* `float` -- The `float` type refers to a floating point number; that is, a number with a decimal point. 


* `double` -- `double` means double precision floating point: it is another way to represent fractional numbers, but has better precision than the float type. 


* `char` -- Characters are represented with the `char` type. This type is really a special case for denoting that the number should be mapped to represent a single ASCII character. 


* `void` -- Variables of this type are unable to store information; they are void of type. 



In addition to these types, there are a few other special data types in C; these types will be discussed later in the book since the application of these types is usually reserved for semi-advanced work. 

`struct` -- Structures, denoted by their C type `struct`, are variables that contain multiple variable types. One might use a structure to store information about an employee (such as their name, address, phone number, salary, etc). 

`union` -- Unions are similar to structures in that they can contain multiple types, but different in that can only store one type at a time. Unions are useful to store information with a variable type. 

`enum` -- `enum`, short for "enumeration," is used to declare and initialize a sequence of integers. 





## Controlling the Flow of Programs: Control Structures and Functions 



### Control Structures 



Control Structures are statements which are used to repeatedly or conditionally execute part of the program. 



#### Conditional execution 



Conditional execution is accomplished with the if statement. If the expression following it evaluates to nonzero the statements following if are executed. If the expression's value is zero then all statements following the else are executed (if an else exists). 



###### Format 



    

    if (expression) {

            /* These statements will execute */

            ;

    } else {

            /* These other statements will execute */

            ;

    }





###### Example 



    

    if (i # 128) {

            printf("The variable i has the value 128!\n");

    } else {

            printf("i isn't 128, sorry!\n");

    }





##### Loops 



`do`, `for` and `while` are used to execute parts of the program multiple times. 



##### do 



##### for 



The `for` loop is commonly used when you know the number of times to repeat your statements. It has three clauses: initial, expression, and increment. The initial clause is only executed when the `for` loop is first entered. After that for each iteration of the loop first the expression clause is evaluated. If the result of the expression is nonzero the statements are executed. If it is zero, the loop is finished. If the value of the expression clause was nonzero the increment clause is executed after statement execution. Each clause can be ommitted. 



###### Format 



    

    for (initial; expression; increment) {

            /* Statements to be executed */

            ;

    }





The following `for` loop will count from 0 to 9. 

###### Example 



    

    int i;

    

    for (i = 0; i < 10; i++) { 

            printf("This is the %d time this loop has fired\n", i); 

    }





##### while 



The `while` loop is used when the number of times statements should be executed depends on a condition. The `while` loop is executed as long as the expression evaluates to nonzero. 



The `while` loop checks the condition  **before**  it executes any statements, see `do while` loop for condition check  **after**  the first statement execution. 

###### Format 



    

    while (expression) {

             /* Statements to execute */

             ;

    }



###### Example 



    

    while (finished != true) {

            /* code goes here */

    }





##### do while 



    

    do {

             /* Statements to execute */

             ;

    } while (again # true);






* Small overview of (simple) frequently used functions from the standard library. 


* When should you used typedef, macros, etc. 


* More... 


* Overview, exercises and examples 



### Functions 







## Arrays and Pointers 



Arrays are arrangements of variables of the same [type](/C_Book_Glossary). 



A good example of a simple array is a word, where each character of this word is a single variable of the type `char`, with it's own fixed place.

For example the word `Dragon` is an array of chars, with a length of six. We can create it as follows:



`char my_array_name[6];`



The number inside the brackets indicates the amount of variables the array is made up of. Each single character has it's own place and thus each place has an address whereby we can reach it. `D` is at the first position in the word `Dragon`, and because most programming languages start counting at zero, `D` can be found at `my_array_name[0]`, whereas `r` is stored at `my_array_name[1]`, and the last character of `Dragon`, `n` resides at `my_array_name[5]`. 



Arrays are even more flexible than that. We can add more dimensions to it, so like in a graph with an abscissa and an ordinate, every X value should have corresponding Y entry.



XXX: I haven't been able to found the graphic named "a graph with two dimensions" that should

be here. You can't download images from the google cache :(



So if we want to store information in pairs or more, of the same data type, we add a dimension while creating the array, thus having a two dimensional array:



    

    int my_array_name[3][2];





So `[3][2]` means, the first dimension of our array of ints, has a length of three and each of those three are infact two values in the second dimension. If the first entry of a pair represents the abscissa and the second the ordinate, our graph above could be described as follows. 



XXX: Here should be a table with different colors that i don't know how to do



my_array_name[0][0]='0'; 

my_array_name[0][1]='0'; 

my_array_name[1][0]='1'; 

my_array_name[1][1]='2'; 

my_array_name[2][0]='2'; 

my_array_name[2][1]='1'; 



                0-0 holds 0     1-0 holds 1     2-0 holds 2 

0-1 holds 0     1-1 holds 2     2-1 holds 1 







By adding more `deepness` to the second dimension e.g. `int array_name[3][4]`, it is possible to add more attributes to a group of data, an Z-axis value for the graph or thickness at a certain point. You may already have noticed that, logically, `int array_name[n]` equals to `int array_name[n][0]` or `int array_name[n][0][0]`. Because we always address the first value of the next empty dimension. 



### more on pointers later 



## Allocating Memory 



I'd actually like to discuss how memory is handled here and provide a small, simple, secure allocator that I've written. 





## Structures 



It's late in the book to go deep into them, but we can do some really neat stuff with them later. 





## The Standard Library 





## POSIX and C99 Features 



Discuss integer types, functions, and portability with C programs following the C99 and POSIX standards. 





## The Programming Process 




* Discuss the theory of writing programs 


* Partition large programs into libraries. 


* How to write Makefiles for programs 


* DragonFly BSD's /usr/share/mk/* and how it makes everything easier 


* Compiling many files into single binaries 


* Building static libraries 


* Building dynamic libraries 







### Section Notes 



## Unorganized Information 



When learning C, especially when coming from other programming languages, it is important to fully understand the fundamentals of the language. In this chapter, we will discuss the fundamentals of the C programming language, explore example programs, and discuss some basic, DragonFly BSD-specific features. 





### Data Types 


* C has a few simple data types 


* `int` -- A non-factional number (integer), e.g. 123456 


* `float` -- A number with a decimal point, e.g. 3.14 


* `double` -- Another number with a decimal point. While it has better precision than `float`, it does use more memory, e.g. 3.14159 


* `char` -- A special case for integers that represent a single ASCII character 


* `void` -- A special type used to denote nothing 



C is what is called a `typed` language. This means that variables must be given a type when they are defined in a program. For more information about typed languages, please see the Section Notes. C provides several types which you must use when defining your variables. Let's take a look at an example: 



    

    /* Includes */

    #include <stdio.h>

    

    /* Main */

    int

    main(void)

    {

            int a;

    

            a = 1;

            printf("a is %d\n", a);

            return 0;

    }







### Arrays 



An array is a collection of items of a certain type. 





### Structures 



#### This section needs to be moved into a separate chapter on structures 



Another "type" available in C is the structure. C also allows its user to create their own types using the struct keyword. Below is an example of a user-defined structure: 



    

    struct {

            char FirstName[50];

            char MiddleName[50];

            char LastName[50];

    } person;





The above example has created a structure called person that consists of a FirstName, MiddleName, and a LastName. Each name is limited to 50 ASCII characters. 



#### Section Notes 



Should we go into more depth about language types? It's a quite disputed field and people don't generally agree on the absolute definitions of: "strongly typed," "weakly typed," "statically typed," or "dynamically typed." I don't want to start an introduction to the language with confusing definitions about what 



TODO: deal with the dangling `else` problem



TODO: explain the `do` statement 





### Memory and C 


* Briefly and superficially discuss how memory works as seen by a program. (It is okay to discuss `sbrk()` & friends) 


* `mmap()` When is it really useful. Matt wrote something about it a while back. 


* Why is working with memory important? 


* Terminology: pointer to type, (de)referencing, etc 


* Discuss simple pointer usage 


* Strings 


* Overview, exercises and examples 





#### Section Notes 





### Stuff 



that should go somewhere but needs to find a good place: 



### Syntax 



The C syntax is a combination of [keywords](/C_Book_Glossary), [operators](/C_Book_Glossary), variables and symbols to determine program content and flow. 



### Header files 



In general they do not actually implement functions. As these files implement interfaces, they are generally used for two purposes: 


* To provide interfaces to a library (the standard C library, for example), and 


* To allow for proper abstraction in projects by providing interfaces which can be used between source files. 



Header files are imported into C source files using the [preprocessor directive](PreprocessorDirective) `#include`. 



### Comments 



Comments can span multiple lines and can contain any text (other than */), however, they cannot be nested. 



Comments are very useful inside code and are used in DragonFly BSD (and in most C programs in general) frequently for any of the following reasons: 


* To give information about any license(s) under which the code is available. 


* To discuss the purpose of a function. 


* To give information about perhaps otherwise difficult to understand pieces of code. 



When programming for DragonFly BSD, comments are encouraged. It is in general good practice to add comments describing what happens in a function before its declaration, rather than in the body of that function. That said, comments should absolutely not be overused. When overused, comments can make code unreadable. 



Examples of different kinds of comments include: 



    

    /* This is a comment on a single line. */

    /*
    
     * This is how comments that span multiple lines should be formatted,
    
     * as detailed by the style(9) manual page.
    
     */

    /*
    
     * /* This comment is invalid because it is nested. This will cause a
    
     *  * compiler error on the line that closes the ***first comment.
    
     *  */
    
     */







### Functions 


* Function declaration 



A function is declared using the following syntax: 



Some valid function definitions are: 



    

    extern int

    ext_function(char *, char *, unsigned long);

    char *

    function_b(void);

    int

    printf(const char *format, ...);





Don't worry if you don't understand what each definition implies; we will cover this in more detail later. One function defintion that is important to understand at this point is the `main` function: it is called at the beginning of every program and is thus necessary for every C program. The `main` function will always take one of the following forms: 

    

    int

    main(void)

    {

            :

            :

            :

    }





 **- or -** 

    

    int

    main(int argc, char **argv)

    {

            :

            :

            :

    }





 **TODO**  Add chapter about the preprocessor