If you are not interested in details, read at least sections with red text

GiveFnptrsToDll() declaration in (my) bots source code and in SDK is : (read more)

void DLLEXPORT GiveFnptrsToDll( ... )

Well SDK uses lots of strange macros, so first I had to determine what they mean.

in eiface.h (which is part of SDK) we can found definition for our macro :

#define DLLEXPORT __stdcall

EXPORT macro is used for all exported function in bot, except GiveFnptrsToDll() :

extern "C" EXPORT int GetNewDLLFunctions( ... )
extern "C" EXPORT int GetEntityAPI( ... )
extern "C" EXPORT int GetEntityAPI2( ... )
extern "C" EXPORT int Server_GetBlendingInterface( ... )

All functions exported with Botmans LINK_ENTITY_TO_FUNC are exported with extern "C" EXPORT too.

in cbase.h (which is part of SDK) there is this definition :

#define EXPORT	_declspec( dllexport )

(Note that accorting to Microsoft, correct syntax is __declspec (two underscores), but MSVC accepts also one underscore. Valve incorrectly uses one underscore in SDK. Though in WIN16 applications only one underscore is correct, we don't need WIN16 compatible applications anymore IMO)

DllMain is declared as

BOOL WINAPI DllMain( ... )

So we have another strange macro, WINAPI

MSDN C++ Language reference reveals that WINAPI is defined as __stdcall. Also in VC6 and VC7, in file include/windef.h, WINAPI is defined as :

#ifdef _MAC
#define WINAPI      CDECL
#elif (_MSC_VER >= 800) || defined(_STDCALL_SUPPORTED)
#define WINAPI      __stdcall
#else
#define WINAPI
#endif

(For WIN16, WINAPI is defined as FAR PASCAL. FAR is empty definition in WIN32 and PASCAL is __stdcall again :). In WIN16, it is obviously __far __pascal. Both of these calling conventions are obsolete in WIN32)

To be complete, CDECL is defined in VC6 and VC7, in file include/windef.h as :

#if defined(DOSWIN32) || defined(_MAC)
#define CDECL _cdecl
#else
#define CDECL
#endif

To summarize, we have learned that :

• DLLEXPORT is __stdcall
• WINAPI is __stdcall
• EXPORT is __declspec(dllexport)
• we have found new strange symbol : __cdecl

Now we only have to learn, what those __xxx things are, and what extern "C" means

NOTE : GiveFnptrsToDll() is exported as __stdcall and all other functions are exported as extern "C" __declspec( dllexport )

(DllMain() is not exported, because it is called by main entry point function called _DllMainCRTStartup)

NOTE : WINAPI and DLLEXPORT macros must be after functions return type, extern "C" specifier and EXPORT macros must be before functions return type

NOTE : WINAPI, DLLEXPORT and EXPORT macros are empty definitions in linux. Seems like in linux, everything is easier

BEWARE : DLLEXPORT is defined differently in META. It is not the same macro as we had above

This and this MSDN references explains what __declspec(dllexport) is.

Shortly, it is for exporting functions in DLL. Functions with __declspec(dllexport) specifier can be called by another program which loads your DLL

You can read more in tutorial on creating and using DLLs on www.flipcode.com

Also www.mindcracker.com has some tutorials for begginers

Important thing is also that __declspec(dllexport) keyword must be before function prototype. This means before functions return type. Example :

// WRONG :
int __declspec(dllexport) MyFunction(int a, double b);

// WRONG, function does not have return type :
// ISO C++ forbids declaration of functions with no type
__declspec(dllexport) MyFunction(int a, double b);

// GOOD :
__declspec(dllexport) int  MyFunction(int a, double b);

__declspec(dllexport) is one of three ways how to export function in MSVC. The other two are .def files and /EXPORT parameter in linker options

How to know what functions are exported ?

Fortunately, there are several programs which help you view all exported functions under windows :

• DumpBin utility. It is part of MSVC. Example : dumpbin /exports yourdll.dll
• PE Explorer, most popular commercial program. (official site www.pe-explorer.com is down)
• Quickview, only under Windows 95/98
• Compile this program which will list undecorated exported functions
• Best utility for bot coder

To summarize, we have learned that :

• Exporting functions means that we want some other program to be able to run our function
• __declspec(dllexport) tells linker that we want to export function
• it is not the only way how to export function in MSVC
• __declspec(dllexport) must be before functions return type

But there is one catch, name-decoration. Read about it in next section

NOTE : There is no such thing as __declspec(dllexport) in linux. It is all Microsoft specific thingy. In linux, functions are exported by using -share parameter in linker

Look at this list of exported functions :

...
        162   A0 000661F0 ?VIP_SafetyTouch@CVIP_SafetyZone@@QAEXPA...
        163   A1 00045940 ?Wait@CFuncTrain@@QAEXXZ
        164   A2 000493C0 ?Wait@CGunTarget@@QAEXXZ
        165   A3 000205E0 ?WaitTillLand@CGib@@QAEXXZ
        166   A4 00060AF0 DelayedUse
        167   A5 00014CF0 GetEntityAPI
        168   A6 00014D20 GetNewDLLFunctions
          1   A7 00034980 GiveFnptrsToDll
        169   A8 0000E9E0 Server_GetBlendingInterface
...

Do you see all these ? and @ and QAEXXZ things ?

Well this is because internal name of function is NOT the same as we specified in source code. This is called name decoration or name mangling

Undecorated name is name we specified in our source code (GiveFnptrsToDll)

There are two name decorations (there are more, but MSVC recognizes only 2):

• C decoration : adds underscore or more (_GiveFnptrsToDll or _GiveFnptrsToDll@8)
• C++ decoration : adds whole mess (?GiveFnptrsToDll@@YAXPAUenginefuncs_s@@PAUglobalvars_t@@@Z)

Programs compiled under C++ uses C++ name decoration by default

Why new name decoration ? :

• With C decoration, there is no way to export overloaded functions
• You cannot export classes with C decoration

Main disadvantage of C++ name decoration : Name is different on diferrent compilers, even on different versions of same compiler

extern "C"

As you probably guessed, extern "XXX" keyword controls which name decoration should compiler use

Theory behind extern "XXX" is called linkage specification : It is the protocol for linking functions (or procedures) written in different languages. Function calling conventions are affected by the linkage specification selected. An example of a linkage specification is extern "C". (taken from MSDN)

extern "C" keyword is called C linkage specifier : It is a declaration of a function or object as extern "C", indicating to the C++ compiler that the function name that follows the linkage specifier is an undecorated C function. C linkage allows existing C code to be used in new C++ applications. (taken from MSDN)

Read more about extern "C" here, here and here

Another article about extern "C" and name decoration on Intel fortran compiler for linux

But extern "C" does more than just change to C decoration. In combination with __declspec(dllexport), it tries to export with undecorated name. What is worse, it does not always succeed.

extern "C" :

• exports undecorated name, only if function has __cdecl keyword (all "nice" names in list above), see IMPORTANT block few lines below
• exports C decorated name, if function has other keyword (__stdcall, __fastcall, ...)

We will talk about __cdecl and __stdcall in next section

If we insist on exporting with C++ decoration, we must call our exported function by ordinal, rather than by name. This "advanced" feature is beyond scope of this document. (We must NOT export with __declspec(dllexport). We must know at what position function will be exported, and import it by calling GetProcAddress with its position, rather than its name)

IMPORTANT : __declspec(dllexport) behave diferrently when in export "C" __cdecl mode : If the function is exported with the C calling convention (_cdecl), it strips the leading underscore (_) when the name is exported.

To summarize, we have learned that :

• Internal name of function is NOT the same as we specified in source code. This is called name-decoration
• Exported functions are exported with their internal name, unless we tell them not to
• If we export functions with C++ name decoration, we cannot determine their name, because this decoration is compiler-specific
• To prevent name-decoration in MSVC, use extern "C" in declaration of function
• __declspec(dllexport) with extern "C" exports undecorated name, but it should not (it omits leading underscore)
• __declspec(dllexport) with extern "C" together with __stdcall produce correct internal name. This is worst, because many people don't understand why it is so
• If we are using __stdcall and we want to have undecorated name in export list, we *must* export our function with technique other than simple usage of __declspec(dllexport)

__stdcall and __cdecl are calling conventions : A convention that determines the order in which arguments passed to functions are pushed on the stack (the calling sequence), whether the calling or called function removes the arguments from the stack, and the name-decorating convention the compiler uses to identify individual functions. (taken from MSDN)

__cdecl is C calling convention, and __stdcall is standard calling convention

Detailed : Calling convention specify how and who clears stack, how are parameters pushed and more. See this document if you are into low level stuff

__cdecl is default calling convention in MSVC (you can set it in Project properties dialog), so you don't see it in source codes much

PERFECT articles about calling conventions can be found at The Old New Thing : 1, 2, 3, 4 and 5. Best for us is 3rd article.

Another detailed article about calling conventions.

Summarization :

• Function can be called in different ways. One way is good for caller, another for calee
• Calling convention specify system of calling a function
• __cdecl is default calling convention, and we should not care more about it
• GiveFnptrsToDll must have __stdcall calling convention, because SDK wants it
• Half-Life will crash if GiveFnptrsToDll does not have __stdcall calling convention, because calee will not clear stack upon exiting (it will probably crash in next function call)
• All other functions in your bot/mod have default C calling convention, which is good

Using .def file in yout bot is another way how to export functions. (Read more)

Example of bot file from SDK :

LIBRARY mp
EXPORTS
	GiveFnptrsToDll	@1
SECTIONS
	.data READ WRITE

Part LIBRARY defines the name of your dll (mp.dll in above example)

Part SECTIONS defines properties of sections in your dll (in our example, section .data will have read and write "access")

Most important for us is part EXPORT, which defines list of exported functions

.def file can be used together with other methods of exporting (__declspec(dllexport) and /EXPORTS)

Full syntax for EXPORTS is :

entryname[=internalname] [@ordinal [NONAME]] [PRIVATE] [DATA]

@ordinal defines position in list of exported functions. This is sometimes very important, because function can be imported not only by its name, but also by its position.

[NONAME], [PRIVATE] and [DATA] are not important for us :-)

Interesting for us is entryname[=internalname], which let us completely change name of our function

Example

We have MyFunction declared as :

extern "C" int __stdcall MyFunction(int a, double b, char c)

which will result in internal name :

_MyFunction@16

If caller wants undecorated name, or even completelly different name, we can fix it :

EXPORTS
	HelloPierre=_MyFunction@16

Caller should now import function with name HelloPierre, which in reality is our MyFunction

Also notice that we havent used __declspec(dllexport), because we are already exporting through .def file. If we included __declspec(dllexport) in declaration, function would be exported twice. Once as _MyFunction@16 and once as HelloPierre

EXPORTS
	GiveFnptrsToDll	@1

EXPORTS
	GiveFnptrsToDll=_GiveFnptrsToDll@8	@1

Summary :

• .def file is another way how to export functions
• .def file gives us more options how to export function
• To correctly use .def file, we must tell our project that we are using .def file. It is done by adding /def:".\mybot.def" to linker parameters (You can do it in Project properties dialog)
• We can control final name and ordinal (position in exports list) of exported function in .def file
• To correctly link to our function in .def file, we must know functions internal name. (which is mostly decorated)
• .def file has undocumented feature, which lets us undecorate functions name, without knowing its internal name. See above in yellow marked section.

How export of GiveFnptrsToDll() is implemented in SDK :

GiveFnptrsToDll() is defined in dlls\h_export.cpp :

#ifdef _WIN32
void DLLEXPORT  GiveFnptrsToDll(enginefuncs_t* pengfuncsFromEngine,globalvars_t *pGlobals)
#else
extern "C" void GiveFnptrsToDll(enginefuncs_t* pengfuncsFromEngine,globalvars_t *pGlobals)
#endif

DLLEXPORT is defined in engine\eiface.h :

#ifdef _WIN32
#define DLLEXPORT __stdcall
#else
#define DLLEXPORT /* */
#endif

.def file is used : dlls\mp.def :

LIBRARY mp
EXPORTS
	GiveFnptrsToDll	@1
SECTIONS
	.data READ WRITE

In dlls\mp.dsp, def is included to project : /def:".\mp.def"

of course SDKs approach works, but here are my thoughts, why it is not good :

• use of undocumented (at least to me) feature of .def file, which allows one to not to specify functions internal name
• Process of exporting GiveFnptrsToDll() is divided into 3 files, thus not simple and not transparent

Also other problems arise :

• Does GiveFnptrsToDll really have to have ordinal 1, making it first function on export list ? Experimets showed that SDK is searching for name, not ordinal, so specifiing ordinal in .def file is irrelevant
• Is .data READ WRITE relevant ? (.data section has READ and WRITE attribute by default)

Here I will present my solution on how to export GiveFnptrsToDll :

If you are already using .def file :

• delete .def file used in MSVC
• remove all references to your .def file from your project

Change functions definition to :

#if defined _WIN32
#pragma comment(linker, "/EXPORT:GiveFnptrsToDll=_GiveFnptrsToDll@8,@1")
#pragma comment(linker, "/SECTION:.data,RW")
#endif

#ifndef __linux__
extern "C" void __stdcall GiveFnptrsToDll( enginefuncs_t* pengfuncsFromEngine, globalvars_t *pGlobals )
#else
extern "C" void GiveFnptrsToDll( enginefuncs_t* pengfuncsFromEngine, globalvars_t *pGlobals )
#endif

{
...
}

Advantages of my approach :

• whole export procedure is controlled in one file, no need to create special .def file just for one export
• fully compatible with SDKs approach. (Including making GiveFnptrsToDll first on export list and explicitly defining READ and WRITE attribute for .data section)

Note that this solution is for MSVC and linux. You have to include additional code for Borland or MingW32 to export it (But you had to do it also in old approach, hadn't you ?)

All tested bots are using .def files (HPB4, HPBT3, HPBT4, JOE, META, POD26, RACCP, RACC1, RACC2, REAL, WHIST)

For authors of these bots, I strongly recommend reading declaration of GiveFnptrsToDll() and Server_GetBlendingInterface() where they may find more useful stuff

Hey Pierre and Botman ! You have error in one or more of your bots. Read it and fix errors (Errors with return type of GiveFnptrsToDll() under linux and somewhat serious error in Server_GetBlendingInterface())

SDK :

• http://dev.valve-erc.com/?go=hl_sdk
• Valve corporation
• Alfred Reinolds patch
• Licensed under Valves SDK LICENSE

HPB4, HPBT3, HPBT4 :

• http://hpb-bot.bots-united.com

JOE :

• http://joebot.bots-united.com
• Licensed under GNU GPL

META :

• http://www.metamod.org
• Licensed under GNU GPL

POD26 :

• http://podbot.nuclearbox.com

RACCP, RACC1, RACC2 :

• http://www.metamod.org
• Licensed under BSD license

REAL :

• http://realbot.bots-united.com
• Licensed under GNU GPL

WHIST :

• http://yapb.bots-united.com

Visual C++ 6.0, Visual C++ 7.0 (Visual Studio .NET 2003) :

• http://www.microsoft.com
• Licensed under Microsoft EULA

Other :

• Bots united
• Microsoft Developer Network
• The Old New Thing
• flipcode
• mindcracker
• devx
• hackcraft