Beej himself lists this as an 'alpha-quality document' on the download page [0] and if I remember correctly, it has been so for years. Wonder why this is posted here on HN.

[0]: http://www.beej.us/guide/bgc/

I recently overhauled it in a big way.. er, "am overhauling it".

And I'm sure it's full of mistakes. It's over 500 pages, most of which has yet to be edited, so if there are fewer than 1000 defects, I'd be shocked.

But I fix them all as I find them, or as they're pointed out. And after an eventual editing pass, things will be better.

And if it's not useful to someone, I take no offense I'd they don't like it. :-)

I think posts like this are handy just for the extra exposure an alpha document might need; there's a lot of good feedback and discussion here that hopefully beej comes across someday and can finish the book

On further observation the git repository of the book [0] seems to be quite active. Maybe this book might be finished after all.

[0]: https://github.com/beejjorgensen/bgc

Backstory: I started writing this book for novice programmers about 15 years ago. It was going to be a lot shorter.

But I became disinterested because:

1. Most beginning programmers don't start with C

2. I wouldn't get a chance to go deep and explore the language.

So I shelved it, unfinished.

Flash forward to about a year ago... I had flash of inspiration: change the audience to intermediate programmers.

Now I could skim the general conceptual stuff and get into more details.

One thing, though. C actually added a lot of stuff in the intervening years. I didn't realize the magnitude of the project.

Oh well! Too late to turn back now!

Just wanted to say THANK YOU as I read your guide to network programming way back in 2000, over 20 years ago! I was just starting out in C network programming on VxWorks :) Glad to see you're still updating your guides.

Thanks! Makes my day to hear people find the work useful. :)

+1000 - I used your network programming guide extensively for my Computer Networking final project in 96, invaluable, Thankyou!

I read the beginning of this C guide and also found it very helpful and made things very easy to understand (coming from C++). Thanks!

> Most beginning programmers don't start with C

Except literally every indian engineer. They teach C to mechanical and chemical engineers for some reason. (It's not an elective)

Glad to hear this, thank you!

On a quick skim of some introductory parts I found:

> When you have a variable in C, the value of that variable is in memory somewhere, at some address. Of course. After all, where else would it be?

It would be in a register. Of course. Or it would be eliminated by a compiler optimization. Of course.

Same error later on:

> When you pass a value to a function,a copy of that value gets made in this magical mystery world known as the stack

No. In most common cases, arguments will not be passed via the stack. This goes on to clarify in a footnote that the implementation might not actually use a stack, and that the stack has something to do with recursion. That part is true, but the values saved on the stack for recursing are not the same as function arguments.

Neither in the Variadic Functions chapter nor anywhere else are the default argument promotions mentioned -- this will bite someone who tries to write a variadic function that gets floats out of the variadic argument list, which you cannot do, since passing a float to a variadic function promotes it to double.

Speaking of floats... This is one of those tutorials that are very confused regarding their target audience. For example, in the "Variables" section it goes out of its way to define: "A “byte” is an 8-bit binary number. Think of it as an integer that can only hold the values from 0 to 255, inclusive." (which isn't the C definition, but this really is nit-picking) but then happily goes on to talk about Booleans and floats without explaining what those are. What reader has a background that would make this useful?

Overall, from the little I've seen, I'd give this an initial rating of "broadly correct but with definite mistakes".

Even if it were fully correct, I dislike the verbose style, and I wouldn't recommend this tutorial. For example, in the Hello World chapter, we have the following "explanation" of the line "#include <stdio.h>":

> Now, what is this#include? GROSS! Well, it tells the C Preprocessor to pull the contents of another fileand insert it into the code rightthere.Wait—what’s a C Preprocessor? Good question. There are two stages (well, technically there are more thantwo, but hey, let’s pretend there are two and have a good laugh) to compilation: the preprocessor and thecompiler. Anything that starts with pound sign, or “octothorpe”, (#) is something the preprocessor operateson before the compiler even gets started. Commonpreprocessor directives, as they’re called, are#includeand#define. More on that later.Before we go on, why would I even begin to bother pointing out that a pound sign is called an octothorpe?The answer is simple: I think the word octothorpe is so excellently funny, I have to gratuitously spread itsname around whenever I get the opportunity. Octothorpe. Octothorpe, octothorpe, octothorpe.Soanyway. After the C preprocessor has finished preprocessing everything, the results are ready for thecompiler to take them and produceassembly code8,machine code9, or whatever it’s about to do. Don’t worryabout the technical details of compilation for now; just know that your source runs through the preprocessor,then the output of that runs through the compiler, then that produces an executable for you to run. Octothorpe.What about the rest of the line? What’s<stdio.h>? That is what is known as aheader file. It’s the dot-hat the end that gives it away. In fact it’s the “Standard I/O” (stdio) header file that you will grow to knowand love. It contains preprocessor directives and function prototypes (more on that later) for common inputand output needs. For our demo program, we’re outputting the string “Hello, World!”, so we in particularneed the function prototype for theprintf()function from this header file. Basically, if we tried to useprintf()without#include <stdio.h>, the compiler would have complained to us about it.How did I know I needed to#include <stdio.h>forprintf()? Answer: it’s in the documentation. Ifyou’re on a Unix system,man printfand it’ll tell you right at the top of the man page what header files are required. Or see the reference section in this book.:-)Holy moly. That was all to cover the first line! But, let’s face it, it has been completely dissected. No mysteryshall remain!

Only one sentence of this is relevant for an introductory Hello World chapter: "Basically, if we tried to use printf() without #include <stdio.h>, the compiler would have complained to us about it." None of the rest is relevant or helpful to a beginner who is just seeing their first ever C program. Also "completely dissected" isn't true either; there is a lot more to be said about headers.

> It would be in a register. Of course. Or it would be eliminated by a compiler optimization. Of course.

Since you mention relevance for beginners later on in your post I'd argue this isn't relevant either. This concept holds true for simple code that doesn't do advanced stuff like working with hardware. As soon as you do &variable, you get an address and can work with it. If the compiler optimized something away you never use you might as well just pretend it's in memory somewhere for the sake of a mental model that's easy to grasp. Same with passing variables via stack. A simple compiler could do it just like that.

That isn't to say the tutorial is good/not good, but these points in particular seem rather sane to me. Far from "Mastering C Pointers" at least :)

> Since you mention relevance for beginners later on in your post I'd argue this isn't relevant either.

Agreed. At the time that variables are introduced, it should just say "a variable is a name for a location where a value is stored". I didn't mean to suggest that the tutorial should go into needless detail at that point. Just that the needless detail that it currently goes into is wrong.

> Same with passing variables via stack.

Again, my problem is just with the needless detail. When you pass a value it is copied (that is the relevant part) somewhere where the callee can find it (that somewhere is the irrelevant part).

> It would be in a register. Of course. Or it would be eliminated by a compiler optimization

As long as you’re taking, and using, the address of that variable, it’s almost guaranteed to be in memory. Even if it won’t, the compiler guarantees the output of the program will be equivalent to unoptimized code.

> arguments will not be passed via the stack

I’m not sure explaining nuances of various calling conventions, and how they differ across processors and OSes, is useful information in a document about C and targeted towards beginners.

You’re talking about things which are underneath C in the abstraction layer hierarchy. The abstraction has many layers, the lowest one being quantum physics. One has to stop somewhere, and this article decided to stop at C, as opposed to assembly.

> One has to stop somewhere, and this article decided to stop at C, as opposed to assembly.

As soon as you mention the stack, you've gone beyond C and started talking about something that is not C.

See my reply to your sibling comment. I wasn't proposing adding more irrelevant detail. If anything, I was proposing removing the existing irrelevant and incorrect/very incomplete detail.

It's a tough line between intro and The Rabbit Hole. But I'll see what I can do there.

Appreciate the feedback. Some good suggestions here that I'll add.

> Only one sentence of this is relevant for an introductory Hello World chapter: "Basically, if we tried to use printf() without #include <stdio.h>, the compiler would have complained to us about it."

Quite the contrary in my opinion. As a beginner I was very frustrated with most approach that say "Just put that thing that is needed and will be explained latter. And it work good job attaboy!"

And maybe 250 pages latter if the author didn't forgot in the meantime you get a one liner mention that link back to the first introduction of the syntax.

At least this guide don't let the reader in the fog wondering.