It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.
Closed 10 years ago.
What is the correct way to name files and functions that are part of a C based code library/API?
What you can (but should not) do is be completely careless and use no systematic naming conventions at all. This 'works', but makes life uncomfortable for your customers; they have no easy way of knowing which names they can use in their own program. (I came across a library which defined a undocumented function for its internal use that was called error(). The name didn't match any part of the external documented namespaces. At the time, one of my own standard error reporting functions was also called error() — though it is now err_error(); that meant I couldn't use my own standard error reporting functions with that library. The upshot was I didn't use that library if I didn't have to; it was too much of a nuisance to use.)
So, you shouldn't be like that. You should be careful in the names you expose.
Your public header should use one (or a very few) systematic prefixes, which are documented. Typically, you'd choose a prefix such as PFX, and use that:
enumeration constants start PFX_.
macros start PFX_.
functions start pfx_.
global variables (you don't have any of those, do you) start pfx_.
type names and structure or union tags start pfx_.
Your private variables and functions that are visible outside their own source file have a systematic prefix (possibly pfx_ again, or maybe pfxp_ where the last p is for private, or perhaps pfx[A-Z] so that private names are camel-cased but start with pfx).
Only variables or functions that are strictly file scope (no external linkage) are not constrained by these rules, but even then, it is advisable to use the naming convention (so if a function needs to be used by two files later, you don't have to revise the calls in the code where the function was previously static).
This way, you can simply document that names starting PFX_ or pfx_ are reserved by your library. Users can still use names with the same prefix (you can't stop them), but they do so at their own risk because upgrades to the library might add names that are reserved. They can keep well clear of your names because you've documented them, and because the documentation is (relatively) easy to understand.
Note that the C standard and the POSIX standards both lay down rules for reserved names. However, the rules for the reserved POSIX and C names are considerably more complex than just a single prefix. They're also sweeping. For example, POSIX reserves all names ending _t for use as type names if any POSIX header is included.
Related
This question already has answers here:
Where to document functions in C or C++? [closed]
(10 answers)
Closed 8 years ago.
Suppose we have function (external only considered here) int foo(int a, char *b), normally there will be a header that goes with it documenting what the function does, what each parameter and return value does, etc. It'll probably be in doxygen format too. My habit is that such header should go into .h files because that's where the interface is defined and reader should have all the information in that place. But a lot of people keep such headers in C file where the actual implimentation goes. I've seen this in the Linux kernel code also. So was I wrong? Which would you prefer?
Although header files can be used in any which way, they are primarily a mechanism to enable external linkage.
You design an API that is meant for external consumption, and you put everything required to consume this API (constants, types, prototypes) in header file(s).
All the other stuff, that is a part of implementation, and doesn't need to be seen by external users, can go in the source files (if the usage is localized to one file), or private headers that can be shared between multiple files. The latter is another example of header files enabling external linkage, but for internal consumption.
The answer to this question is largely "it depends":
Depends on what? Who's reading the documentation, and how they access it.
If you're developing a program, then having the documentation inline with the implementation is probably OK, because anybody who wants to know about your program can access the source code and read about it. Your target audience is probably developers working on the program itself, so having the documentation in the C file, along with the bulk of the code they're working on, is a suitable approach.
If you're developing a library, the target audience changes (or you might have two target audiences). You still have the developers, who could make use of more detailed documentation as it relates to private implementation detail. You also have the users of the library, who only care about the interface that they're working with; from a code-browsing point of view, they typically only have access to the headers.
I put them in the .h file by preference when it's my choice, if I have a .h file. If I just have a .c file, I will document the functions when they are defined, simply because if I just have a .c file, I'm probably still coding, and I want to change the documentation if I change the code.
I feel that documentation and declarations go together in a separate file in a finished c project. Documentation in the code breaks up the code and can be redundant.
If I'm contributing somewhere, I'll follow the established convention.
If we look to the draft of C11, the following names were reserved :
7.31 Future library directions
The following names are grouped under individual headers for convenience. All external
names described below are reserved no matter what headers are included by the program.
7.31.1 Complex arithmetic <complex.h>
The function names
cerf cerfc cexp2 cexpm1 clog10 clog1p clog2 clgamma ctgamma
and the same names suffixed with f or l may be added to the declarations in the
<complex.h> header.
As I would like very much to see the complex gamma functions as a part of standard C (because they are a basis for a lot of other complex functions), I wonder what is the real signification of the 7.31.1 clause.
Why only add declarations and not their definitions ?
Can we expect them for the next C standard or for a minor release ? (and if the answer is yes, when the next standard is expected ?)
Is there any implementations already available as non-standard extensions of compilers ?
A couple of months ago, I have published a library libcerf that provides the missing functions cerf and cerfc, based on numerical code by Steven G. Johnson. Our implementation is accurate to 13-14 digits, which is good enough for almost every practical use - but in achieving this, one understands how much more work needs to be done to write an acceptable standard: it is not likely that this will be undertaken by anybody any soon.
So concerning your question about clgamma and ctgamma: don't wait for the standard. Search for code that just works. Ideally, wrap this code and provide a library like libcerf that is almost as good as a standard implementation.
The glibc maintainers almost never want to add new functions that aren't standardized in any way, and cerf is NOT part of the C99 standard --- it is merely reserved for possible future use, which makes it especially unlikely that glibc will accept an implementation until the required behavior of the function has been standardized.
It sure would be nice though, if it were incorporated, to be just like "erf()" in the C++ code, but instead "cerf()".
As per manual :
cerf[f|l]C99 An optional complex error function that, if provided, must be
declared in complex.h.
As per above statement, the functions will be declared only if provided.
It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.
Closed 11 years ago.
Every program written in C that I've ever seen #includes <stdlib.h>, at least indirectly. You can't really do much useful without it.
Why aren't its functions just part of "standard C"?
Why should I have to #include <stdlib.h> before malloc()ing something?
C is a minimalistic language. There are no built-in functions.
The C language was designed, from the start, to be used both in ordinary applications (running in a 'hosted environment') and OS kernels (and other specialized environments, running in a 'freestanding environment'). In the latter, ordinary C library functions like malloc() may be unavailable.
In order to allow the same compiler to be used for both hosted and freestanding environments, library functions are not hardcoded into the compiler, but rather are placed into header files loaded by the compiler - such as stdlib.h. OS kernels and other specialized programs do not (and cannot) include these standard headers.
Not all programs need to call malloc(). And those that do need dynamic memory allocation may prefer to do it a different way. C does not try to force a single way of working on programmers.
This is still a perfectly valid program that doesn't require libc and can do much stuff apart from interfacing with the underlying operating system:
int main (void) {
int x = 2;
int y = 3;
return x + y;
}
One reason I can think of is that by putting the stdlib functions into a library, they exist in their own namespace, making it easier to overload them.
It might sound a little crazy to think of overloading malloc, but it's one way to implement a resource buffering system that might be used for say... dynamically creating game objects during a game loop without triggering allocations. You can preallocate a buffer, then overload malloc to create the objects into the buffer rather than allocating new memory for them.
It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.
Closed 11 years ago.
I am searching for some information.
I have seen in many programmes following files included
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
I want to know more what the above header files are used for i.e. in which conditions which header file is used.
Any link which clearly mentions which header file serves what purpose that will be great.
sys/types.h: "data types"
sys/socket.h: "main sockets header"
sys/un.h: "definitions for UNIX domain sockets"
unistd.h: "standard symbolic constants and types"
Header files are used for declaring items that are defined in some existing library.
If you want to use socket(), you'll need to include sys/types.h and sys/socket.h. If you want to use atan(), you'll need to include math.h. If you want to use printf(), you'll need to include stdio.h.
Knowing which header file is needed for a function is given in its documentation (man printf on Unix/Linux).
Knowing which function can be used for solving a problem is given by experience, stackoverflow and Google.
If you want to know what's in a header file, try looking at it, seriously: most will start with some comment describing the content if it's not obvious anyway.
If you want to know what part of a header file is being used by the program that's including, try removing it and looking at the error messages. That may also sound glib, but sadly there's generally not a better way to find this out. But, it may be that on one platform some functionality requires including two headers, whereas on some other platform only one of them is required (perhaps because the second header is indirectly picked up by some earlier include anyway): if you test on the platform where one header is needed and decide to remove the second include, you may break the build on the other platform. So, when you find stuff that is needed, consult the man pages for the required headers - they may be specified by some Standard that both platforms honour.
If you want to know which header files to use yourself, then again - you have to look at the documentation for the functions you need to call. Even then, as a C++ programmer you should prefer the C++ versions of certain C headers, and standard documentation tools like man - given the C function name - won't tell you about the C++ headers. Have a read of e.g. http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt01ch03s02.html - it's GCC documentation but describes C++ Standard requirements for these headers.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
If you code in C and configure your compiler to insist that all functions are declared before they are used (or if you code in C++), then you can end up with one of (at least) two organizations for your source files.
Either:
Headers
Forward declarations of (static) functions in this file
External functions (primary entry points)
Static - non-public - functions
Or:
Headers
Static - non-public - functions
External functions (primary entry points)
I recognize that in C++, the term 'static' is not preferred, but I'm primarily a C programmer and the equivalent concept exists in C++, namely functions in an anonymous namespace within the file.
Question:
Which organization do you use, and why do you prefer it?
For reference, my own code uses the second format so that the static functions are defined before they are used, so that there is no need to both declare them and define them, which saves on having the information about the function interfaces written out twice - which, in turn, reduces (marginally) the overhead when an internal interface needs to change. The downside to that is that the first functions defined in the file are the lowest-level routines - the ones that are called by functions defined later in the file - so rather than having the most important code at the top, it is nearer the bottom of the file. How much does it matter to you?
I assume that all externally accessible functions are declared in headers, and that this form of repetition is necessary - I don't think that should be controversial.
I've always used method #1, the reason being that I like to be able to quickly tell which functions are defined in a particular file and see their signatures all in one place. I don't find the argument of having to change the prototypes along with the function definition particularly convincing since you usually wind up changing all the code that calls the changed functions anyway, changing the function prototypes while you are at it seems relatively trivial.
In C code I use a simple rule:
Every C file with non-static members will have a corresponding header file defining those members.
This has worked really well for me in the past - makes it easy enough to find the definition of a function because it's in the same-named .h file if I need to look it up. It also works well with doxygen (my preferred tool) because all the cruft is kept in the header where I don't spend most of my time - the C file is full of code.
For static members in a file I insist in ordering the declarations in such a way that they are defined by instantiation before use anyway. And, I avoid circular dependency in function calls almost all of the time.
For C++ code I tried the following:
All code defined in the header file. Use #pragma interface/#pragma implementation to inform the compiler of that; kind of the same way templates put all the code in the header.
That's worked really well for me in C++. It means you end up with HUGE header files which can increase compile time in some cases. You also end up with a C++ body file where you simply include the header and compile. You can instantiate your static member variables here. It also became a nightmare because it was far too easy to change your method params and break your code.
I moved to
Header file with doxygen comments (except for templates, where code must be included in the header) and full body file, except for short methods which I know I'd prefer be inlined when used.
Separating out implementation from definition has the distinct plus that it's harder to change your method/function signatures so you're less likely to do it and break things. It also means that I can have huge doxygen blocks in the header file documenting how things work and work in the code relatively interruption free except for useful comments like "declare a variable called i" (tongue in cheek).
Ada forces the convention and the file naming scheme on you. Most dynamic languages like Ruby, Python, etc don't generally care where/if you declare things.
Number 2: because I write many short functions and refactor them freely, it'd be a significant nuisance to maintain forward declarations. If there's an Emacs extension that does that for you with no fuss, I'd be interested, since the top-down organization is a bit more readable. (I prefer top-down in e.g. Python.)
Actually not quite your Number 2, because I generally group related functions together in the .c regardless of whether they're public or private. If I want to see all the public declarations I'll look in the header.
Number 2 for me.
I think using static or other methods to make your module functions and variables private to the module is a good practice.
I prefer to have my api functions at the bottom of the module. Conversely I put the api functions at the top of my classes as classes are generally reusable. Putting the api functions at the top make it easier to find them quickly. Most IDEs, can take you to any function pretty directly.
(Talking about C code)
Number 2 for me because I always forget to update forward decls to reflect static functions changes.
But I think that the best practice should be
headers
forward declarations + comment on function behaviour for each one
exported functions + eventual comments about implementation details when code is not clear enough
static functions + eventual comments about implementation details
How much does it matter to you?
It's not.
It is important that all local function will be marked as static, but for my opinion defining how to group function in the file is too much. There is no strong reasoning for any version and i don't find any strong disadvantage ever.
In general coding convention is very important and we trying to define as much as possible, but in this case my feeling, that this is unjustified overhead.
After reading all posts again it seems like i should simply upvote (which i did) Darius answer, instead writing all of these ...