Chapter 0, memory...

chapters/chapter_0.c

@@ -11,55 +11,69 @@ It is distributed in the hope that it will be useful or harmful, it really depen
 
 #include "chapter_0.h"
 
+/*
+Function 'in' will perform read system call, literally reading 'size' bytes from standard input, which is terminal in most kernels unless it's redirected to some other file
+descriptor, and store it at 'data' memory address, if there's enough space in it. Since this is one of the core functions, if it fails, we want to abort the program and see what
+we did wrong... Maybe there wasn't enough space in 'data', maybe 'size' was negative and it overflowed because read system call internally uses 'size_t / unsigned long int', which
+is 64 bits wide, maybe we made some other mistake? Just abort, find the error and fix it.
+*/
+
 void in (void * data, int size) {
 	fatal_failure (data == NULL, "in: Failed to read from standard input, data is null pointer.");
 	fatal_failure (size == 0,    "in: Failed to read from standard input, size is zero.");
 
-	(void) read (STDIN_FILENO, data, (unsigned long int) size);
+	(void) read (STDIN_FILENO, data, (unsigned long int) size); // I cast to void type return value of read and write, because I don't really care about it.
 }
 
+/*
+Similar to 'in' function and read system call, write system call will store 'size' bytes from 'data' memory address into standard output, which is usually what you see in your
+terminal. Now, I won't talk much about teletypes, virtual terminals, file descriptor redirections and similar stuff, because I'm not very knowledgable about them. What matters is,
+you have a working operating system, terminal and compiler, and you can make things happen. Once you learn C better than me, and start writing your own multi-threaded kernel, core
+libraries, compilers and what not, you'll care about those things.
+*/
+
 void out (void * data, int size) {
-	fatal_failure (data == NULL, "out: Failed to write to standard output, data is null pointer.");
+	fatal_failure (data == NULL, "out: Failed to write to standard output, data is null pointer."); // Notice how we can use function 'fatal_failure' before its' definition.
-	fatal_failure (size == 0,    "out: Failed to write to standard output, size is zero.");
+	fatal_failure (size == 0,    "out: Failed to write to standard output, size is zero.");         // That's because we declared it in 'chapter_0.h' header file.
 
 	(void) write (STDOUT_FILENO, data, (unsigned long int) size);
 }
 
+/*
+Function 'echo' is just a simplification of function 'out', because we'll be using it a lot, notice that it must accept null terminated strings, which are sort of C-style thing. I
+really like them, because you don't need to always know size of the string in order to iterate it, but it requires some mental overhead in order to use them without creating hard
+to find bugs, which is why newer programming languages consider them unsafe. They're not unsafe, they need to be used like intended.
+*/
+
 void echo (char * string) {
-	out (string, string_length (string));
+	out (string, string_length (string)); // This function fails when we pass a string that's not null terminated, and we don't care to check for errors...
 }
 
-void fatal_failure (int condition, char * message) {
+void fatal_failure (int condition, char * message) {  // We use this function to abort the program if condition is met and to print the message.
-	if (condition != 0) {
+	if (condition != 0) {                         // If the variable 'condition' is not equal to 0, we execute the code in curly braces.
-		echo ("[\033[1;31mExiting\033[0m] ");
+		echo ("[\033[1;31mExiting\033[0m] "); // Simply printing the message using our 'echo' function, but we also use some colours, more on that later.
 		echo (message);
 		echo ("\n");
-
+		exit (EXIT_FAILURE);                  // This is the function (and '_exit' system call) that aborts the program with a return code.
-		exit (EXIT_FAILURE);
+	}                                             // If condition isn't met, function will just return, and nothing is printed, execution continues.
-	}
 }
 
-void limit (int * value, int minimum, int maximum) {
+void limit (int * value, int minimum, int maximum) {   // This is somewhat similar to limiting a variable to some values, inclusively, we'll use it later.
-	if (value == NULL) { /* We shouldn't dereference null pointer, but also don't want to abort the program for small mistake. */
+	if (value == NULL)      { return;            } // We shouldn't dereference null pointer, but also don't want to abort the program for small mistake.
-		return;
+	if (* value <= minimum) { * value = minimum; } // You can also align similar consecutive statements like this, we'll see it more often in switch statement later on...
-	}
+	if (* value >= maximum) { * value = maximum; }
-
-	if (* value <= minimum) {
-		* value = minimum;
-	}
-
-	if (* value >= maximum) {
-		* value = maximum;
-	}
 }
 
+/*
+Memory management is a whole new topic that's too complex to cover it now in details, and it's the source of most security vunrabilities and hidden bugs. For now, just remember
+that every program can read, write or execute only parts of the memory that the kernel allows it. Program can request new memory or release old memory, so some other programs can
+use it. We'll learn to use program called Valgrind to find and fix memory related bugs in later chapters. We rely on functions 'calloc', 'realloc' and 'free' from <stdlib.h>
+header file, and we'll avoid 'malloc', and use 'realloc' carefully, because they leave new memory uninitialized.
+*/
+
 void * allocate (int size) {
 	char * data = NULL;
 
-	if (size <= 0) {
-		return (NULL);
-	}
-
 	data = calloc ((unsigned long int) size, sizeof (* data));
 
 	fatal_failure (data == NULL, "standard : allocate : Failed to allocate memory, internal function 'calloc' returned null pointer.");
@@ -68,10 +82,6 @@ void * allocate (int size) {
 }
 
 void * reallocate (void * data, int size) {
-	if (size <= 0) {
-		return (data);
-	}
-
 	data = realloc (data, (unsigned long int) size);
 
 	fatal_failure (data == NULL, "standard : reallocate: Failed to reallocate memory, internal function 'realloc' returned null pointer.");

compile.sh

@@ -2,6 +2,6 @@
 
 set -xe
 
-gcc -ansi -Wall -Wextra -Wpedantic -Werror -Ofast -o xhartae xhartae.c
+gcc -Wall -Wextra -Wpedantic -Werror -Ofast -o xhartae xhartae.c
 
 exit