The source code for busybox's syslogd implementation contains some annotations I'm unfamiliar with. The language is C, not C++.
int syslogd_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
int syslogd_main(int argc UNUSED_PARAM, char **argv)
Specifically, MAIN_EXTERNALLY_VISIBLE and UNUSED_PARAM.
What exactly are these annotations doing? Where can I read more about them and other annotations?
Are these part of the C standard, or are they compiler extensions? If they are compiler extensions, how widely supported are they?
I assume the first one is why this file doesn't have a main() function. If these are compiler extensions rather than part of the standard, does this mean this file can't be meaningfully compiled as-is by a compiler that adheres only to the C standard?
Why did they declare a prototype of the syslogd_main function immediately before the full definition? Can the MAIN_EXTERNALLY_VISIBLE annotation only be applied to function prototypes?
1. What exactly are these annotations doing?
See include/platform.h and include/libbb.h
UNUSED_PARAM expands to __attribute__ ((__unused__)). It specifies the variable (argc in your example) as "possibly unused" and disables the "unused variable" warning.
From the GCC manual [Specifying Attributes of Variables]:
unused
This attribute, attached to a variable, means that the variable is meant to be possibly unused. GCC will not produce a warning for this variable.
MAIN_EXTERNALLY_VISIBLE expands to EXTERNALLY_VISIBLE and then to __attribute__(( visibility("default") )). It controls the visibility of the function.
From the GCC manual [Declaring Attributes of Functions]:
... On ELF, default visibility means that the declaration is visible to other modules and, in shared libraries, means that the declared entity may be overridden.
From include/libbb.h:
/* We need to export XXX_main from libbusybox
* only if we build "individual" binaries
*/
#if ENABLE_FEATURE_INDIVIDUAL
#define MAIN_EXTERNALLY_VISIBLE EXTERNALLY_VISIBLE
#else
#define MAIN_EXTERNALLY_VISIBLE
#endif
2. Are these part of the C standard, or ...?
No, those are macros defined in the BusyBox project.
3. I assume the first one is why this file doesn't have a main() function. ...
No. BusyBox combines many utilities into a single executable. That explains the "lack of a main() function" in syslogd.c.
4. Why did they declare a prototype of the syslogd_main function immediately before the full definition? ...
From the GCC manual [Declaring Attributes of Functions]:
The keyword __attribute__ allows you to specify special attributes when making a declaration.
Related
I am trying to implement a global singleton variable in the header-only library in C (not C++). So after searching on this forum and elsewhere, I came across a variation of Meyer's singleton that I am adapting to C here:
/* File: sing.h */
#ifndef SING_H
#define SING_H
inline int * singleton()
{
static int foo = 0;
return &foo;
}
#endif
Notice that I am returning a pointer because C lacks & referencing available in C++, so I must work around it.
OK, now I want to test it, so here is a simple test code:
/* File: side.h */
#ifndef SIDE_H
#define SIDE_H
void side();
#endif
/*File: side.c*/
#include "sing.h"
#include <stdio.h>
void side()
{
printf("%d\n",*(singleton()));
}
/*File: main.c*/
#include "sing.h"
#include "side.h"
#include <stdio.h>
int main(int argc, char * argv[])
{
/* Output default value - expected output: 0 */
printf("%d\n",*(singleton()));
*(singleton()) = 5;
/* Output modified value - expected output: 5 */
printf("%d\n",*(singleton()));
/* Output the same value from another module - expected output: 5*/
side();
return 0;
}
Compiles and runs fine in MSVC in C mode (also in C++ mode too, but that's not the topic). However, in gcc it outputs two warnings (warning: ‘foo’ is static but declared in inline function ‘singleton’ which is not static), and produces an executable which then segfaults when I attempt to run it. The warning itself kind of makes sense to me (in fact, I am surprised I don't get it in MSVC), but segfault kind of hints at the possibility that gcc never compiles foo as a static variable, making it a local variable in stack and then returns expired stack address of that variable.
I tried declaring the singleton as extern inline, it compiles and runs fine in MSVC, results in linker error in gcc (again, I don't complain about linker error, it is logical).
I also tried static inline (compiles fine in both MSVC and gcc, but predictably runs with wrong output in the third line because the side.c translation unit now has its own copy of singleton.
So, what am I doing wrong in gcc? I have neither of these problems in C++, but I can't use C++ in this case, it must be straight C solution.
I could also accept any other form of singleton implementation that works from header-only library in straight C in both gcc and MSVC.
I am trying to implement a global singleton variable in the header-only library in C (not C++).
By "global", I take you to mean "having static storage duration and external linkage". At least, that's as close as C can come. That is also as close as C can come to a "singleton" of a built-in type, so in that sense, the term "global singleton" is redundant.
Notice that I am returning a pointer because C lacks & referencing available in C++, so I must work around it.
It is correct that C does not have references, but you would not need either pointer or reference if you were not using a function to wrap access to the object. I'm not really seeing what you are trying to gain by that. You would likely find it easier to get what you are looking for without. For example, when faced with duplicate external defintions of the same variable identifier, the default behavior of all but the most recent versions of GCC was to merge them into a single variable. Although current GCC reports this situation as an error, the old behavior is still available by turning on a command-line switch.
On the other hand, your inline function approach is unlikely to work in many C implementations. Note especially that inline semantics are rather different in C than in C++, and external inline functions in particular are rarely useful in C. Consider these provisions of the C standard:
paragraph 6.7.4/3 (a language constraint):
An inline definition of a function with external linkage shall not contain a definition of a modifiable object with static or thread storage duration, and shall not contain a reference to an identifier with internal linkage.
Your example code is therefore non-conforming, and conforming compilers are required to diagnose it. They may accept your code nonetheless, but they may do anything they choose with it. It seems unreasonably hopeful to expect that you could rely on a random conforming C implementation to both accept your code for the function and compile it such that callers in different translation units could obtain pointers to the same object by calling that function.
paragraph 6.9/5:
An external definition is an external declaration that is also a definition of a function (other than an inline definition) or an object. If an identifier declared with external linkage is used in an expression [...], somewhere in the entire program there shall be exactly one external definition for the identifier [...].
Note here that although an inline definition of a function identifier with external linkage -- such as yours -- provides an external declaration of that identifier, it does not provide an external definition of it. This means that a separate external definition is required somewhere in the program (unless the function goes altogether unused). Moreover, that external definition cannot be in a translation unit that includes the inline definition. This is large among the reasons that extern inline functions are rarely useful in C.
paragraph 6.7.4/7:
For a function with external linkage, the following restrictions apply: [...] If all of the file scope declarations for a function in a translation unit include the inline function specifier without extern, then the definition in that translation unit is an inline definition. An inline definition does not provide an external definition for the function, and does not forbid an external definition in another translation unit. An inline definition provides an alternative to an external definition, which a translator may use to implement any call to the function in the same translation unit. It is unspecified whether a call to the function uses the inline definition or the external definition.
In addition to echoing part of 6.9/5, that also warns you that if you do provide an external definition of your function to go with the inline definitions, you cannot be sure which will be used to serve any particular call.
Furthermore, you cannot work around those issues by declaring the function with internal linkage, for although that would allow you to declare a static variable within, each definition of the function would be a different function. Lest there be any doubt, Footnote 140 clarifies that in that case,
Since an inline definition is distinct from the corresponding external definition and from any other corresponding inline definitions in other translation units, all corresponding objects with static storage duration are also distinct in each of the definitions.
(Emphasis added.)
So again, the approach presented in your example cannot be relied upon to work in C, though you might find that in practice, it does work with certain compilers.
If you need this to be a header-only library, then you can achieve it in a portable manner by placing an extra requirement on your users: exactly one translation unit in any program using your header library must define a special macro before including the header. For example:
/* File: sing.h */
#ifndef SING_H
#define SING_H
#ifdef SING_MASTER
int singleton = 0;
#else
extern int singleton;
#endif
#endif
With that, the one translation unit that defines SING_MASTER before including sing.h (for the first time) will provide the needed definition of singleton, whereas all other translation units will have only a declaration. Moreover, the variable will be accessible directly, without either calling a function or dereferencing a pointer.
I recently got a snippet of code in Linux kernel:
static int
fb_mmap(struct file *file, struct vm_area_struct * vma)
__acquires(&info->lock)
__releases(&info->lock)
{
...
}
What confused me is the two __functions following static int fb_mmap() right before "{",
a).What is the purpose of the two __funtions?
b).Why in that position?
c).Why do they have the prefix "__"?
d).Are there other examples similar to this?
Not everything ending with a pair of parenthesis is a function (call). In this case they are parameterized macro expansions. The macros are defined as
#define __acquires(x) __attribute__((context(x,0,1)))
#define __releases(x) __attribute__((context(x,1,0)))
in file include/linux/compiler.h in the kernel build tree.
The purpose of those macros expanding into attribute definitions is to annotate the function symbols with information about which locking structures the function will acquire (i.e. lock) and release (i.e. unlock). The purpose of those in particular is debugging locking mechanisms (the Linux kernel contains some code that allows it to detect potential deadlock situations and report on this).
https://en.wikipedia.org/wiki/Sparse
__attribute__ is a keyword specific to the GCC compiler, that allows to assign, well, attributes to a given symbol
http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#Function-Attributes
Since macros are expanded at the text level, before the compiler is even looking at it, the result for your particular snippet, that the actual compilers sees would be
static int
fb_mmap(struct file *file, struct vm_area_struct * vma)
__attribute__((context(&info->lock,0,1)))
__attribute__((context(&info->lock,1,0)))
{
…
}
Those macros start with a double underscore __ to indicate, that they are part of the compiler environment. All identifiers starting with one or two underscores are reserved for the compiler environment implementation. In the case of the Linux kernel, because Linux is a operating system kernel that does not (because it simply is not availible) use the standard library, it's natural for it, do define it's own compiler environment definitions, private to it. Hence the two underscores to indicate, that this is compiler environment/implementation specific stuff.
They're probably macros defined with #define. You should look for the definition of such macros and see what they expand to. They might expand to some pragma giving hints to the compiler; they might expand to nothing giving hints to the developers or some analysis tool. The meaning might vary
The __attribute__ these macros evaluate to are compiler-specific features. man gcc explains some of the uses.
The prefix __ typically is used to avoid name clashes; double underscore as prefix and postfix mark an identifier as being used by the compiler itself.
More on gcc attributes can be found here.
More on the kernel use of these can be found here.
Those are macro's defined as
# define __acquires(x) __attribute__((context(x,0,1)))
# define __releases(x) __attribute__((context(x,1,0)))
in Linux/include/linux/compiler.h
I'm trying to read a project documentation. Under the title Prototype, I'm having this code :
VisionAPI_RETURN VisionAPI VisionInterf_ImageAttach(
VisionAPI_HANDLE ImageHandle ,
uint32_t NumImages
);
The project's interfaces will be build in C, when the functions will be in C++.
When reading the documentation, I read prototype, so I supposed it is "functions prototypes". When reading more, I find the author sometimes using the term "function" and sometimes "interface". I know how to make an interface in C++ but not in C.
So is the code above about interface or function prototype?
Otherwise, how to create an interface in C language? Is it by creating structure (struct) ?
I hope my question is not stupid. I'm a Java developer, and a C/C++ simple student.
This declares the function, without providing an implementation (the definition). So, you could say this is an interface. You just tell the compiler: "Hey, there is a function with the name VisionInterf_ImageAttach" so it doesn't complain when you call it. More about declaration vs. definition.
This, of course depends on what VisionAPI_RETURN and VisionAPI resolve to, assuming they are macros.
There is no such thing in C language as an interface: in addition to primitive types and pointers, the language supports structs and functions; that's all you have to work with.
Your code shows an example of a forward declaration of a function. Interfaces to C modules consist of multiple such declarations, along with declaration of structs that these functions use.
(Adding to the already useful info given by #bitmask and #dasblinkenlight)
In C a function prototype is, roughly, the declaration of a function signature, i.e. the declaration of the function name, return type and parameter list types (i.e. the types of the parameters the function accepts, in their respective order).
Therefore, in a sense, the prototype of a function can be viewed as the interface of the function towards client code (in this case the term interface is used in a general way, unlike what it means in OOP and Java in particular).
As a simpler example, suppose you defined a function like this:
int MyFunc( double x, char * z )
{
// function body code
}
then its prototype would be:
int MyFunc( double x, char * z );
or even
int MyFunc( double, char * );
since parameter names are optional in function prototypes.
There is no mechanism in C for creating an equivalent replica to Java interfaces, although often programmers refer to specially crafted C header files as "interfaces". These header files are filled with function prototypes and other declarations that represent the "interface" of the library they belong toward client code.
Therefore client code can #include those header files to access the facilities offered by the library without knowing its implementation (here is the "interface" thing), which usually is resolved at link time (or at run-time if dynamic linking is involved).
Edit (to answer a comment)
What you see before function name is probably some macro trick. Since I don't know what's the context I can only guess. The two identifiers VisionAPI_RETURN VisionAPI are most probably defined as macros. From their names I guess that the first expands to the actual return type, while the second could be either an empty macro (usually used to mark some category of declarations) or expands to some compiler-specific keyword combination, usually used to declare the function low-level calling convention.
For example, somewhere there could be these macro definitions:
#define VisionAPI_RETURN int
#define VisionAPI
so that, after the preprocessor has finished its work, the compiler will see this:
int VisionInterf_ImageAttach(
VisionAPI_HANDLE ImageHandle,
uint32_t NumImages
);
Another example - if those macros are defined like this:
#define VisionAPI_RETURN struct MyReturn
#define VisionAPI __stdcall
then the prototype will be expanded like this:
struct MyReturn __stdcall VisionInterf_ImageAttach(
VisionAPI_HANDLE ImageHandle,
uint32_t NumImages
);
In this case the return type would be struct MyReturn, while the __stdcall keyword would indicate the "stdcall" calling convention (the __stdcall keyword is used by Microsoft compilers). This resulting syntax is an extension to standard C syntax (many compilers have some kind of such extensions).
I've been reading the stdio.h file and I'm confused.
For example, there is this line:
_CRTIMP FILE* __cdecl __MINGW_NOTHROW fopen (const char*, const char*);
I know FILE* means returning type and I found that _CRTIMP is constant, defined as
# ifndef _CRTIMP
# define _CRTIMP __declspec(dllimport)
# endif
I don't understand it, what is it there for? And what are rest of strings (__cdecl, __MINGW_NOTHROW) ?
__declspec(dllimport) specifies that the function is to be imported from a separate dll; I suppose that, depending on the CRT static/dynamic linking settings, it's defined in different ways.
__cdecl is the calling convention used for the function; the calling convention tells to the compiler how the function expects to be called (in which order parameters are pushed on the stack, if any register is used for parameters, where the return value is stored, who is responsible for stack cleanup, ...); in general you shouldn't worry about it as long as you're not writing libraries.
__MINGW_NOTHROW is #defined to expand to __attribute__ ((__nothrow__)), which is a MinGW-specific extension that tells to the compiler that the function will not throw exceptions; this lets the compiler perform some optimizations.
Note that all these are not standard C attributes, but compiler/platform specific stuff. Again, in general you shouldn't worry about them, they are required to make the CRT work fine, but as long as you're not building libraries you can get away without knowing anything about them. :)
You should take a look at _mingw.h and the gcc manual: In case of gcc - or any other compiler supporting __GNUC__ - the following definitions apply:
#define __cdecl __attribute__ ((__cdecl__))
#define __MINGW_NOTHROW __attribute__ ((__nothrow__))
The former tells the compiler to use the cdecl x86 calling convention (see gcc manual), the latter that the function is guaranteed not to throw C++ exceptions (see gcc manual).
__declspec(dllimport) is necessary to make dynamic linking work (see gcc manual).
__declspec(dllimport) tells the compiler that this function needs to be imported from a DLL, it's a Windows-specific extension. See this page for details.
Likewise, __cdecl is an attribute that specifies that the function uses a particular calling convention (namely, the one used by C). See this page.
I would guess that the __MINGW_NOTHROW macro is a synonym for the GCC nothrow attribute, which informs the compiler that the function in question cannot throw exceptions. See the documentation for details.
Theses are declarations specific to the environment or the compiler you're using.
The __declspec(dllimport) indicates, on windows, that this function is in a dll and should be placed in the import table of the executable PE file generated.
The __cdecl indicate a standard C calling convention and will modify the way the compiler transform the function to conform to this calling convention.
__MINGW_NOTHROW is specific to your compiler and might de-activate support for exception.
In all case, there must be an explanation in the documentation of your compiler.
I'm looking at the vim source code, specifically the file normal.c, and I see this function nv_operator being used, but it's not defined anywhere (I grepped the entire src directory)
It's only declared as:
static void nv_operator __ARGS((cmdarg_T *cap));
I've looked up the definition of __ARGS but it's just ... nothing (pretty much)
in vim.h:
#define __ARGS(x) x
So what could be going on? Is this some kind of C technique to create a dummy function or something?
There is a definition present here:
/*
* Handle an operator command.
* The actual work is done by do_pending_operator().
*/
static void
nv_operator(cap)
cmdarg_T *cap;
....
That style of definition is using an identifier list for its parameters. The style is deprecated (obsolescent) but can still be used in C. The identifiers are named in the parameter list, and their type are named in declarations that immediately follow the function declarator but precede the functions body.
The __ARGS macro is there to handle compilers that don't know about prototypes for functions (the other form to declare parameters - with type and name combined directly in the function parameter list). It would then just emit no parameters at all in declarations, i think.
Update: See this code in vim.h:
#if defined(MACOS) && (defined(__MRC__) || defined(__SC__))
/* Apple's Compilers support prototypes */
# define __ARGS(x) x
#endif
#ifndef __ARGS
# if defined(__STDC__) || defined(__GNUC__) || defined(WIN3264)
# define __ARGS(x) x
# else
# define __ARGS(x) ()
# endif
#endif
It's simply a forward declaration, so that the function is known to the C compiler (and can be used (called from other functions)) before it's actually defined (in line 8247). The actual formatting of the definition (which includes newlines) makes it hard to grep for it's existence.
Don't get distracted by the __ARGS macro. It's only a compatibility macro for the different function declaration syntaxes of K&R C vs. ANSI C.
In ANSI C a function declaration must look like this:
int getopt(int, char * const *, const char *);
In the (older) Kernighan and Ritchie C http://en.wikipedia.org/wiki/C_(programming_language)#K.26R_C
int getopt();
Its hard to find because of how it is defined:
nv_operator(cap)
appears on a line by itself.
I am not too sure what is going on, but here are some hints to help you in your search:
First of all, the __ARGS macro seems to be there because there may be versions of C where you shouldn't include the args in the declaration of the functions (Notice that the macro is defined differently depending on other preprocessor symbols... the comments say it).
Secondly, searching for the function nv_operator may not be good enough. The function might be generated by macros and such, so you can't search for an explicit definition.... for example, maybe the "nv" prefix is added by the preprocessor.
Hope this helps.