Put in remaining pages and wiki contents.
[ikiwiki.git] / docs / developer / C_Development_Under_DragonFly_BSD-Volume_1_C_For_Beginners.mdwn
1 # C Development Under DragonFly BSD Volume 1: C For Beginners \r
2 ## old title Volume 1: C For Beginners\r
3 \r
4 <<TableOfContents>>\r
5 \r
6 ## Prologue \r
7
8 * Discuss a small bit about C's features, pros and cons, etc. \r
9
10 * Tell a bit about its history, authors, etc. \r
11
12 * Why is understanding C important? \r
13
14 * Discuss its use in DragonFly \r
15
16 * Why is DragonFly BSD a good programming environment? \r
17 \r
18 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. \r
19 \r
20 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. \r
21 \r
22 ## Discussion of the C Language  \r
23 \r
24 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. \r
25 \r
26 ### Overview \r
27 \r
28 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_Book_Glossary) of the C language as well as the aesthetical organization of source code within programs. \r
29 \r
30 \r
31 ### Our First Program \r
32 \r
33 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: \r
34 \r
35     \r
36     /* Includes */\r
37     #include <stdio.h>\r
38     \r
39     /* Main */\r
40     int\r
41     main(void)\r
42     {\r
43             printf("Hello, World!\n");\r
44             return (0);\r
45     }\r
46 \r
47 \r
48 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. \r
49 \r
50     \r
51     /* Includes */\r
52 \r
53 \r
54 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. \r
55 \r
56     \r
57     #include <stdio.h>\r
58 \r
59 \r
60 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. \r
61 \r
62     \r
63     /* Main */\r
64 \r
65 \r
66 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. \r
67 \r
68     \r
69     int\r
70     main(void)\r
71 \r
72 \r
73 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: \r
74 \r
75     \r
76     modifier type functionname(parameterlist);\r
77 \r
78 \r
79 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`. \r
80 \r
81 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." \r
82 \r
83     \r
84     {\r
85             printf("Hello, World!\n");\r
86             return (0);\r
87     }\r
88 \r
89 \r
90 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 }). \r
91 \r
92     \r
93             printf("Hello, World!\n");\r
94 \r
95 \r
96 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: \r
97 \r
98     \r
99     $ ./hello\r
100     Hello, World!\r
101     $\r
102 \r
103 \r
104 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. \r
105 \r
106     \r
107     return (0);\r
108 \r
109 \r
110 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. \r
111 \r
112 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. \r
113 \r
114 So, we're done with our overview of the source code. Now how do we run it? \r
115 \r
116 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: \r
117 \r
118     \r
119     $ cc hello.c -o hello\r
120 \r
121 \r
122 When the program is compiled, you can test it with: \r
123 \r
124     \r
125     $ ./hello\r
126 \r
127 \r
128 This will produce the output we saw above: \r
129 \r
130     \r
131     Hello, World!\r
132     $\r
133 \r
134 \r
135 Most of the programs discussed in this book can be compiled in this same manner. \r
136 \r
137 ## Simple Concepts - Variables, Operators, Types and Expressions \r
138 \r
139 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? \r
140 \r
141  **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. \r
142 \r
143  **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. \r
144 \r
145  **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). \r
146 \r
147 An  **expression**  is the grouping of the above (variables, operators and types) to express a certain process. \r
148 \r
149 ### Variables and Types \r
150 \r
151 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. \r
152 \r
153 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: \r
154 \r
155
156 * `int` -- `int` refers to an integral number (an integer). An integer is any non-fractional number (..., -1, 0, 1, ...). \r
157
158 * `float` -- The `float` type refers to a floating point number; that is, a number with a decimal point. \r
159
160 * `double` -- `double` means double precision floating point: it is another way to represent fractional numbers, but has better precision than the float type. \r
161
162 * `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. \r
163
164 * `void` -- Variables of this type are unable to store information; they are void of type. \r
165 \r
166 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. \r
167 `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). \r
168 `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. \r
169 `enum` -- `enum`, short for "enumeration," is used to declare and initialize a sequence of integers. \r
170 \r
171 \r
172 ## Controlling the Flow of Programs: Control Structures and Functions \r
173 \r
174 ### Control Structures \r
175 \r
176 Control Structures are statements which are used to repeatedly or conditionally execute part of the program. \r
177 \r
178 #### Conditional execution \r
179 \r
180 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). \r
181 \r
182 ###### Format \r
183 \r
184     \r
185     if (expression) {\r
186             /* These statements will execute */\r
187             ;\r
188     } else {\r
189             /* These other statements will execute */\r
190             ;\r
191     }\r
192 \r
193 \r
194 ###### Example \r
195 \r
196     \r
197     if (i # 128) {\r
198             printf("The variable i has the value 128!\n");\r
199     } else {\r
200             printf("i isn't 128, sorry!\n");\r
201     }\r
202 \r
203 \r
204 ##### Loops \r
205 \r
206 `do`, `for` and `while` are used to execute parts of the program multiple times. \r
207 \r
208 ##### do \r
209 \r
210 ##### for \r
211 \r
212 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. \r
213 \r
214 ###### Format \r
215 \r
216     \r
217     for (initial; expression; increment) {\r
218             /* Statements to be executed */\r
219             ;\r
220     }\r
221 \r
222 \r
223 The following `for` loop will count from 0 to 9. \r
224 ###### Example \r
225 \r
226     \r
227     int i;\r
228     \r
229     for (i = 0; i < 10; i++) { \r
230             printf("This is the %d time this loop has fired\n", i); \r
231     }\r
232 \r
233 \r
234 ##### while \r
235 \r
236 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. \r
237 \r
238 The `while` loop checks the condition  **before**  it executes any statements, see `do while` loop for condition check  **after**  the first statement execution. \r
239 ###### Format \r
240 \r
241     \r
242     while (expression) {\r
243              /* Statements to execute */\r
244              ;\r
245     }\r
246 \r
247 ###### Example \r
248 \r
249     \r
250     while (finished != true) {\r
251             /* code goes here */\r
252     }\r
253 \r
254 \r
255 ##### do while \r
256 \r
257     \r
258     do {\r
259              /* Statements to execute */\r
260              ;\r
261     } while (again # true);\r
262 \r
263 \r
264
265 * Small overview of (simple) frequently used functions from the standard library. \r
266
267 * When should you used typedef, macros, etc. \r
268
269 * More... \r
270
271 * Overview, exercises and examples \r
272 \r
273 ### Functions \r
274 \r
275 \r
276 \r
277 ## Arrays and Pointers \r
278 \r
279 Arrays are arrangements of variables of the same [type](/C_Book_Glossary). \r
280 \r
281 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.\r
282 For example the word `Dragon` is an array of chars, with a length of six. We can create it as follows:\r
283 \r
284 `char my_array_name[6];`\r
285 \r
286 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]`. \r
287 \r
288 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.\r
289 \r
290 XXX: I haven't been able to found the graphic named "a graph with two dimensions" that should\r
291 be here. You can't download images from the google cache :(\r
292 \r
293 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:\r
294 \r
295     \r
296     int my_array_name[3][2];\r
297 \r
298 \r
299 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. \r
300 \r
301 XXX: Here should be a table with different colors that i don't know how to do\r
302 \r
303 my_array_name[0][0]='0'; \r
304 my_array_name[0][1]='0'; \r
305 my_array_name[1][0]='1'; \r
306 my_array_name[1][1]='2'; \r
307 my_array_name[2][0]='2'; \r
308 my_array_name[2][1]='1'; \r
309 \r
310                 0-0 holds 0     1-0 holds 1     2-0 holds 2 \r
311 0-1 holds 0     1-1 holds 2     2-1 holds 1 \r
312 \r
313 \r
314 \r
315 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. \r
316 \r
317 ### more on pointers later \r
318 \r
319 ## Allocating Memory \r
320 \r
321 I'd actually like to discuss how memory is handled here and provide a small, simple, secure allocator that I've written. \r
322 \r
323 \r
324 ## Structures \r
325 \r
326 It's late in the book to go deep into them, but we can do some really neat stuff with them later. \r
327 \r
328 \r
329 ## The Standard Library \r
330 \r
331 \r
332 ## POSIX and C99 Features \r
333 \r
334 Discuss integer types, functions, and portability with C programs following the C99 and POSIX standards. \r
335 \r
336 \r
337 ## The Programming Process \r
338 \r
339
340 * Discuss the theory of writing programs \r
341
342 * Partition large programs into libraries. \r
343
344 * How to write Makefiles for programs \r
345
346 * DragonFly BSD's /usr/share/mk/* and how it makes everything easier \r
347
348 * Compiling many files into single binaries \r
349
350 * Building static libraries \r
351
352 * Building dynamic libraries \r
353 \r
354 \r
355 \r
356 ### Section Notes \r
357 \r
358 ## Unorganized Information \r
359 \r
360 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. \r
361 \r
362 \r
363 ### Data Types \r
364
365 * C has a few simple data types \r
366
367 * `int` -- A non-factional number (integer), e.g. 123456 \r
368
369 * `float` -- A number with a decimal point, e.g. 3.14 \r
370
371 * `double` -- Another number with a decimal point. While it has better precision than `float`, it does use more memory, e.g. 3.14159 \r
372
373 * `char` -- A special case for integers that represent a single ASCII character \r
374
375 * `void` -- A special type used to denote nothing \r
376 \r
377 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: \r
378 \r
379     \r
380     /* Includes */\r
381     #include <stdio.h>\r
382     \r
383     /* Main */\r
384     int\r
385     main(void)\r
386     {\r
387             int a;\r
388     \r
389             a = 1;\r
390             printf("a is %d\n", a);\r
391             return 0;\r
392     }\r
393 \r
394 \r
395 \r
396 ### Arrays \r
397 \r
398 An array is a collection of items of a certain type. \r
399 \r
400 \r
401 ### Structures \r
402 \r
403 #### This section needs to be moved into a separate chapter on structures \r
404 \r
405 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: \r
406 \r
407     \r
408     struct {\r
409             char FirstName[50];\r
410             char MiddleName[50];\r
411             char LastName[50];\r
412     } person;\r
413 \r
414 \r
415 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. \r
416 \r
417 #### Section Notes \r
418 \r
419 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 \r
420 \r
421 TODO: deal with the dangling `else` problem\r
422 \r
423 TODO: explain the `do` statement \r
424 \r
425 \r
426 ### Memory and C \r
427
428 * Briefly and superficially discuss how memory works as seen by a program. (It is okay to discuss `sbrk()` & friends) \r
429
430 * `mmap()` When is it really useful. Matt wrote something about it a while back. \r
431
432 * Why is working with memory important? \r
433
434 * Terminology: pointer to type, (de)referencing, etc \r
435
436 * Discuss simple pointer usage \r
437
438 * Strings \r
439
440 * Overview, exercises and examples \r
441 \r
442 \r
443 #### Section Notes \r
444 \r
445 \r
446 ### Stuff \r
447 \r
448 that should go somewhere but needs to find a good place: \r
449 \r
450 ### Syntax \r
451 \r
452 The C syntax is a combination of [keywords](/C_Book_Glossary), [operators](/C_Book_Glossary), variables and symbols to determine program content and flow. \r
453 \r
454 ### Header files \r
455 \r
456 In general they do not actually implement functions. As these files implement interfaces, they are generally used for two purposes: \r
457
458 * To provide interfaces to a library (the standard C library, for example), and \r
459
460 * To allow for proper abstraction in projects by providing interfaces which can be used between source files. \r
461 \r
462 Header files are imported into C source files using the [preprocessor directive](PreprocessorDirective) `#include`. \r
463 \r
464 ### Comments \r
465 \r
466 Comments can span multiple lines and can contain any text (other than */), however, they cannot be nested. \r
467 \r
468 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: \r
469
470 * To give information about any license(s) under which the code is available. \r
471
472 * To discuss the purpose of a function. \r
473
474 * To give information about perhaps otherwise difficult to understand pieces of code. \r
475 \r
476 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. \r
477 \r
478 Examples of different kinds of comments include: \r
479 \r
480     \r
481     /* This is a comment on a single line. */\r
482     /*\r
483     
484 * This is how comments that span multiple lines should be formatted,\r
485     
486 * as detailed by the style(9) manual page.\r
487     
488 */\r
489     /*\r
490     
491 * /* This comment is invalid because it is nested. This will cause a\r
492     
493 *  * compiler error on the line that closes the ***first comment.\r
494     
495 *  */\r
496     
497 */\r
498 \r
499 \r
500 \r
501 ### Functions \r
502
503 * Function declaration \r
504 \r
505 A function is declared using the following syntax: \r
506 \r
507 Some valid function definitions are: \r
508 \r
509     \r
510     extern int\r
511     ext_function(char *, char *, unsigned long);\r
512     char *\r
513     function_b(void);\r
514     int\r
515     printf(const char *format, ...);\r
516 \r
517 \r
518 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: \r
519     \r
520     int\r
521     main(void)\r
522     {\r
523             :\r
524             :\r
525             :\r
526     }\r
527 \r
528 \r
529  **- or -** \r
530     \r
531     int\r
532     main(int argc, char **argv)\r
533     {\r
534             :\r
535             :\r
536             :\r
537     }\r
538 \r
539 \r
540  **TODO**  Add chapter about the preprocessor\r