Re: Executable enty points incorrectly documented

Tech-Archive recommends: Repair Windows Errors & Optimize Windows Performance

Look at /Entry in MSDN. The signature of the entry point is defined and
many caveats mentioned.



Also, you are absolutely correct in that main / WinMain have nothing to do
with the core of the OS. They are, however, the entry points used by most
C/C++ programs and MSDN contains CRT and other documentation besides the
core OS too. In my MDSN anyway, they are found under the Windows Management
section and not in Win32 at all.







"Kornél Pál" <kornelpal@xxxxxxxxxxxxxxxx> wrote in message
news:49707D7D.7060801@xxxxxxxxxxxxxxxxxxx
Hi,

Thanks for your reply.

You wrote that WinMain is not a starting function in CRT, but an
user-defined entry point for a Windows application.

This is true but this actually should read entry point for a Windows
application written in C/C++.

I believe that the fact that this function is called by the C/C++ runtime
clearly backs my opinion that WinMain has nothing to do with the operating
system.

Even if WinMain documentation remains in Windows SDK it would be wise to
explicitly state that support for this entry point is provided by the
C/C++ runtime rather than Windows itself.

My bigger problem however is that the real entry point signature is not
documented anywhere in Windows SDK.

That is the entry point called by Windows in a PE executable and the entry
point signature expected by the linker. For this reason documentation for
the real entry point is definitely missing.

Some comments to Jeroen's opinion:
The fact that WinMain is suppoted both by C/C++ and some Pascal variants
(or any other languages) does not mean that it is an operating system
feature. And the entry point signature of a PE executable is definitely
part of the programming interface (call it API or ABI) rather than an OS
internal.

I agree with him that the Windows SDK's primary targer is C/C++ and all
the header files were written for C/C++. On the other hand as long as the
application binary interface (ABI) is well defined (and it is) anyone has
the chance to write his own comipler or use any compiler (and language)
he/she wants. This means that the function signatures specified in C are
only a representation of the API.

Jeroen also has the point that macros for example are C/C++ specific but
they just provide extra functionality to C/C++ users. Ideally everything
that cannot be expressed using a C function or structure signature should
be documented using texts. And fortunately this is the case for most of
the things.

And I would like to add one more documentation request related to PE
files:

HMODULE and HINSTANCE were two different things in Win16 but in Win32 (and
Win64) they both are the same and some functions use HMODULE while others
HINSTANCE that causes confusion. (See
http://blogs.msdn.com/oldnewthing/archive/2004/06/14/155107.aspx for a
short explanation.)

This HMODULE is also the base address of the module (EXE or DLL) that
means the address of the MZ header of the memory mapped image.

These facts are well known and widely used by the developer community
there are several articles about them but is not documented by the Windows
SDK.

Although - unlike PE entry point signature - this qualifies for being an
OS internal, it is so widely known fact and so many programs take
advantage of it that I can't imagine that it would change without
introducing a new OS API that would break all the applications anyway so I
belive that this should be documented in Windows SDK as well.

Kornél

Jialiang Ge [MSFT] wrote:
Hello

This is an interesting topic. I basically agree with Jeroen. Here is the
addition of my opinion. (w)mainCRTStartup, (w)WinMainCRTStartup are the
starting addresses from the C runtime library. They have the same
signature of int XXXXX(void). Only one of them will be compiled:

(The following code is quoted from C:\Program Files\Microsoft Visual
Studio 9.0\VC\crt\src\crtexe.c)

#ifdef _WINMAIN_

#ifdef WPRFLAG
int wWinMainCRTStartup(
#else /* WPRFLAG */
int WinMainCRTStartup(
#endif /* WPRFLAG */

#else /* _WINMAIN_ */

#ifdef WPRFLAG
int wmainCRTStartup(
#else /* WPRFLAG */
int mainCRTStartup(
#endif /* WPRFLAG */

The starting function calls to the user-defined entry point (main or
WinMain) based on the app type. WinMain is not a starting function in
CRT, but an user-defined entry point for a Windows application. MSVC
runtime actually passes some Windows arguments to WinMain (see the
Windows API GetStartupInfo. GetStartupInfo is not a part of CRT):

(The following code is quoted from C:\Program Files\Microsoft Visual
Studio 9.0\VC\crt\src\crtexe.c)

int wWinMainCRTStartup(
_TUCHAR *lpszCommandLine;
STARTUPINFO StartupInfo;
BOOL inDoubleQuote=FALSE;

.....
__try {
/*
Note: MSDN specifically notes that GetStartupInfo
returns no error, and throws unspecified SEH if it fails, so
the very general exception handler below is
appropriate
*/
GetStartupInfo( &StartupInfo );
} __except(EXCEPTION_EXECUTE_HANDLER) {
return 255;
}

.....

mainret = WinMain(
#endif /* WPRFLAG */
(HINSTANCE)&__ImageBase,
NULL,
lpszCommandLine,
StartupInfo.dwFlags & STARTF_USESHOWWINDOW
? StartupInfo.wShowWindow
: SW_SHOWDEFAULT
);

.....


Therefore, I feel that it is reasonable to place WinMain in Win32
documentation, instead of C/C++ documentation. This is my opinion. Please
feel free to further discuss it with me.


Regards,
Jialiang Ge (jialge@xxxxxxxxxxxxxxxxxxxx, remove 'online.')
Microsoft Online Community Support

Delighting our customers is our #1 priority. We welcome your comments and
suggestions about how we can improve the support we provide to you.
Please feel free to let my manager know what you think of the level of
service provided. You can send feedback directly to my manager at:
msdnmg@xxxxxxxxxxxxxx

==================================================
Get notification to my posts through email? Please refer to
http://msdn.microsoft.com/en-us/subscriptions/aa948868.aspx#notifications.

MSDN Managed Newsgroup support offering is for non-urgent issues where an
initial response from the community or a Microsoft Support Engineer
within 2 business day is acceptable. Please note that each follow up
response may take approximately 2 business days as the support
professional working with you may need further investigation to reach the
most efficient resolution. The offering is not appropriate for situations
that require urgent, real-time or phone-based interactions. Issues of
this nature are best handled working with a dedicated Microsoft Support
Engineer by contacting Microsoft Customer Support Services (CSS) at
http://msdn.microsoft.com/en-us/subscriptions/aa948874.aspx
==================================================
This posting is provided "AS IS" with no warranties, and confers no
rights.




.

Relevant Pages

  • Re: Executable enty points incorrectly documented
    ... The function signature is there though ... belong to C/C++ documentation rather than Windows API documentation. ... As for the entry point signature: ...
    (microsoft.public.win32.programmer.kernel)
  • Re: Executable enty points incorrectly documented
    ... You wrote that WinMain is not a starting function in CRT, but an user-defined entry point for a Windows application. ... I believe that the fact that this function is called by the C/C++ runtime clearly backs my opinion that WinMain has nothing to do with the operating system. ... Even if WinMain documentation remains in Windows SDK it would be wise to explicitly state that support for this entry point is provided by the C/C++ runtime rather than Windows itself. ...
    (microsoft.public.win32.programmer.kernel)
  • Re: Executable enty points incorrectly documented
    ... All these things are correct but this is more specific and related to the .NET Framework than to Windows API and the C++ linker and does not mention the actual entry point signatures either. ... The documentation problem to which you allude is that it is the CRT entry point that calls one of the versions of main / WinMain that is defined in your program. ... This is the signature of the managed entry point that has nothing to do with native executables/DLLs. ...
    (microsoft.public.win32.programmer.kernel)
  • Re: Executable enty points incorrectly documented
    ... .NET Framework than to Windows API and the C++ linker and does not mention ... the actual entry point signatures either. ... The documentation problem to which you allude is that it is the CRT entry ... This is the signature of the managed entry point (as it is stated ...
    (microsoft.public.win32.programmer.kernel)
  • Re: Executable enty points incorrectly documented
    ... This is the signature of the managed entry point that has nothing to do with native executables/DLLs. ... The documentation is sparse and often confusing; but since hardly any programs need to care about the details it isn't likely high on Microsoft's list of things to fix. ... I was speaking about Windows SDK not MSDN Library entirely, but even if Windows SDK conatins C/C++ documentation I believe that main/WinMain belong to C/C++ documentation rather than Windows API documentation. ...
    (microsoft.public.win32.programmer.kernel)