How do I read .h files?

[Doc Mindie]

I mean... for example, in the "hello, world" program in C, you need to #include <stdio.h> to gain access to the printf()-function, right?

However, when I look at stdio.h to see the optional components of printf(), I only see *** EQU this and *** EQU that, ifndef such then DEF so, and it makes no sense whatsoever.

If I was to make a program using <stupid_doc.h> for the function idiot(), how would I go about do it?

[girv]

The std* headers aren't meant for humans to read - you picked a bad place to start

There's nothing special about .h files at all, they're just C source code files. Typically you will use them to declare constants, types, function prototypes etc. so they may be shared between modules in your program.

[eLowar]

Header files (.h files) contain declarations for functions and values that are defined elsewhere. The #include command just copies the contents of the specified file into your source file.

These declarations are required so the compiler knows what you want and can check your syntax and types; and to compute object sizes, and so forth. Since it processes one file at a time and those functions and values are implemented elsewhere, it has no other way of knowing these details.

The actual function is later combined with your program by the linker. In the case of printf you will probably not find source code for it anywhere. It is part of the Standard C library, which is typically included with the compiler in binary form. Also note that the linker is typically called implicitly by the compiler (I'm not sure if that has always been the case, but yeah).

All that #ifdef stuff and such is just to provide some kind of customization to what functions are used, you don't really have to worry about it all that much. I won't go into detail about that in this post, suffice it to say you don't have to worry about it all that much for now.

Say you have written a function foo() and bar() in foobar.c like this:

void foo(const char* text)
{
     prinft("%s", text);
}

int bar(int x, int y)
{
     return x + y;
}

Then your header file foobar.h would typically look something like this:

#ifndef FOOBAR_H
#define FOOBAR_H

void foo(const char* text);
int bar(int x, int y);

#endif

So what's with the #ifndef stuff? Well, that's there so if the file somehow gets included more than once (e.g. if you include 2 .h files that both include foobar.h), the declarations aren't repeated, as that would cause compiler errors (something like "multiple definition, blah blah"). #ifndef FOOBAR_H contines until #endif exactly if FOOBAR_H (a pre-processor symbol) wasn't defined yet, and in the next line it is defined so the next time that file is included, it'll just be skipped.

Also note the names in the signatures are optional, the following would work just as well:

...
void foo(const char*);
int bar(int, int);
...

So now you can #include "foobar.h" from some other .c file and use those functions. The linker will later look in all the files you specified when linking (or compiling when linking is implicit) for functions matching those names and signatures and make sure they're combined with the code of your executable.

I hope this helps.

[eLowar]

Originally Posted by girv

[...] , types, [...]

Good point, I forgot to mention types.

Also note that a lot of this was oversimplified and I believe linkers actually only check the name, not the signatures (C has no function overloading and in C++ it's done by mixing the signature in with the symbol name; I'm not aware of any common C++ aware linkers).

But I'm hoping my lengthy explanation, the typing of which caused me to be beaten by girv , helps you get a basic idea.

[Doc Mindie]

So... to actually see what optional/formatting components the function "printf()" have (I mean, like theescape sequences, \n, \int, \dec and those) I can't use the .h files to get any info at all? I have to goto the autodocs or some other document to see more of what I have available in each function?

printf() is a binary form function, which has it DECLARE values in stdio.h

Thanks guys. I've been wondering about this for ages, and it has actually set me back quite a few years because I've wanted to understand what the heck I'm looking at and howto decipher those blasted .h files

[eLowar]

Originally Posted by Doc Mindie

So... to actually see what optional/formatting components the function "printf()" have (I mean, like theescape sequences, \n, \int, \dec and those) I can't use the .h files to get any info at all? I have to goto the autodocs or some other document to see more of what I have available in each function?

printf() is a binary form function, which has it DECLARE values in stdio.h

Correct. Although nowadays documentation is often included in comments in the source code (and often at least partially in the header files).

Edit: If you want to see the actual implementation of the standard library functions, you may be out of luck. For one thing they might not even be implemented in C at all (although they often are), and for another -- unless you're dealing with an open source compiler -- you probably won't get those sources at all. For instance, on Windows (particularly when using Microsoft's VC compiler, but many others use it as well) the standard library functions are in msvcrt.dll which ships with the OS. I have no clue what it's like on the Amiga.

[Doc Mindie]

I found this little piece of code on the 'net.

A Weight Conversion Program


#include <stdio.h>
#define KILOS_PER_POUND .45359
main()
{       int pounds;

        printf(" US lbs      UK st. lbs       INT Kg\n");

        for(pounds=10; pounds < 250; pounds+=10)
        {       int stones = pounds / 14;
                int uklbs = pounds % 14;
                float kilos = pounds * KILOS_PER_POUND;
                printf("   %d           %d   %d        %f\n",
                                   pounds, stones, uklbs, kilos);
        }
}

Could I here take the line

#define KILOS_PER_POUND .45359

and stuff it into "conversion.h" then us "#include conversion.h" in the program instead?

(still trying to get me head around the .h system)

If we use AmigaE terms, (snippeted from the source to module Devices/cd.m)

OBJECT cdinfo
  playspeed:INT  -> This is unsigned
  readspeed:INT  -> This is unsigned
  readxlspeed:INT  -> This is unsigned
  sectorsize:INT  -> This is unsigned
  xlecc:INT  -> This is unsigned
  ejectreset:INT  -> This is unsigned
  reserved1[4]:ARRAY OF INT  -> Array is unsigned
  maxspeed:INT  -> This is unsigned
  audioprecision:INT  -> This is unsigned
  status:INT  -> This is unsigned
  reserved2[4]:ARRAY OF INT  -> Array is unsigned
ENDOBJECT

makes much more sense to me..... Maybe it's because it's an "amiga standard" or maybe it's because I started to get a grasp with AmigaE some 10-12 years back.... but the .m's of AmigaE makes more sense than C's .h

OH, and btw, eLowar.... after fove posts here, I've got more answers and more information about my first question, than I've got allotgether on several C-programming sites. I guess it's still true, after 14 years of no new Amiga, the Amiga community is STILL the best community there is

[eLowar]

Originally Posted by Doc Mindie

Could I here take the line

#define KILOS_PER_POUND .45359

and stuff it into "conversion.h" then us "#include conversion.h" in the program instead?

(still trying to get me head around the .h system)

Yeah, that would be a common use. Headers are usually just collections of function prototypes and constants like that, which share some properties. For example "stdio.h" is standard IO related stuff.

Note the difference between a constant variable like const double kilos_per_pound .45359 and a pre-processor macro like #define KILOS_PER_POUND .45359. The difference is that the former is an actual variable (albeit one that can't be modified) and the latter simply performs text substitution before compilation. For example with GCC you can use the -E parameter to see what your files look like after the preprocessor is done with them (including files, replacing #defined stuff, etc.).

Originally Posted by Doc Mindie

If we use AmigaE terms, (snippeted from the source to module Devices/cd.m)

OBJECT cdinfo
  ...
ENDOBJECT

makes much more sense to me..... Maybe it's because it's an "amiga standard" or maybe it's because I started to get a grasp with AmigaE some 10-12 years back.... but the .m's of AmigaE makes more sense than C's .h

I don't know much about E, so I don't know if that's an actual class (in the sense used in C++ and Java) or just a collection of data. If the latter, you get something similar in C in the form of structs.

The rough equivalent of the E code you posted would then be:

struct cdinfo {
  unsigned int playspeed;
  unsigned int readspeed;
  unsigned int readxlspeed;
  unsigned int sectorsize;
  unsigned int xlecc;
  unsigned int ejectreset;
  unsigned int reserved1[4];
  unsigned int maxspeed;
  unsigned int audioprecision;
  unsigned int status;
  unsigned int reserved2[4];
};

Following that you can declare and use variables like this:

struct cdinfo myCdinfo;
...
myCdinfo.playspeed = 5;

You'll definitely want to read up on the subtleties of this, but that's the basic idea. In C++ there are actual classes with inheritance, visibility modifiers and member functions. Like this:

class MyClass: public SomeOtherClass {
public:
  MyClass(): SomeOtherClass() { /* inline function code */ }
  ~MyClass(); // this function and the following are defined elsewhere
  virtual void foo();
  int bar(char* parameter);

private:
  int privateValue_;
};

That declares a class MyClass which inherits (in a certain way, hence the public, I'll skip the details for now) all properties of the class SomeOtherClass (that is, it'll contain all the functions of the other class, etc.). The function MyClass() is called when you create an instance of the class (create a variable of that type), ~MyClass() is called when an instance is destroyed (e.g. by going out of scope). privateValue_ is private and hence can only be accessed from functions inside the class, not from the outside. The virtual keyword changes how the program looks for the right function to execute in inherited classes. Again, I'll skip the details, just trying to give you an overview and maybe see if you recognize any of this from E).

Note that in C++, a struct is really just a class in which everything is public (more or less ).

Anyways, if E is an object oriented language and you've worked with it, you might feel more at home with C++ than C.

[Doc Mindie]

Thanks again, eLowar

My main reason for bringing E into this subject, is that I started to get a grasp on that back in 1996, but then sadly my HD died and I couldn't afford a new one untill YEARS later (upon which I also had gotten an A1200 and aPC and was surfing the net) and my E-diskettes (registered from Wouter himself) had more or less died already.

Anyways, .h files are used in both C and C++, so I just wanted to understand what the heck I was looking at. I guess some people doesn't need to understand what they're doing as long as it works, but for me it's important to grasp the underlying stuff that actually MAKES things work, before continuing my programming learning curve.

So, knowing that the standard library works isn't enough for me, I need to know the WHY and the HOW it works too.... otherwise, I just get heavily frustrated because I can't find the (sometimes useless) info I want

From the AmigaE site itself:

For those who don't know: E is an object-oriented/procedural/unpure functional/whatever language with quite a popular implementation on the amiga. It's mainly influenced by languages such as C++, Ada, Lisp etc., and features extremely fast compilation, inline assembler, large set of integrated functions, powerful module concept, flexible type-system, quoted expressions, immediate and typed lists, parametric and object polymorphism, exception handling, inheritance, data-hiding, methods, multiple return values, default arguments, register allocation, fast memory management, unification, LISP-Cells, macro-preprocessing, a very powerful source-level debugger, gui-toolkit, library linker, and then some.

[eLowar]

Well all you really need to know about .h files is that they're typically used with #include, which just dumps them verbatim into the place where the #include line was. Then accept that the standard library typically comes in binary form and as long as you have documentation about its behavior, you don't need to know about its internals (after all that's the whole point of using functions -- and also classes -- to begin with). From there on you should concentrate on understanding how a linker works to actually get the point of .h files and what's written in them.

[Doc Mindie]

It's the "how" and "why" that sticks in me head, mate.... if I don't understand either, I put the breaks on

Anyways, I've found the full sources for DICE C on the net somewher.... after a nice look into the archive, I found what I've been looking for all these years, namely the actual docs on the stdlib functions

(And I've picked up on AmigaE again too :look )

[YoJoe!]

Originally Posted by Doc Mindie

when I look at stdio.h to see the optional components of printf(), I only see *** EQU this and *** EQU that, ifndef such then DEF so, and it makes no sense whatsoever.

Nothing about the C language makes any sense to anyone.
Only a masochist can operate a C compiler.

Scientists have calculated that if masochists continue to write C programs at their current rate then the world will run out of curly braces by the year 2012.