--- mstools/readme.txt 2018/08/09 18:20:25 1.1 +++ mstools/readme.txt 2018/08/09 18:21:01 1.1.1.2 @@ -1,139 +1,124 @@ - LANGREAD.TXT File - README file for Microsoft(R) Windows NT(TM) SDK (BETA) - Development Tools - (C) Copyright Microsoft Corporation, 1992 + DEVTOOLS.TXT File + README file for Microsoft(R) Windows NT(TM) + Software Development Kit (BETA) + + Development Tools + (C) Copyright Microsoft Corporation, 1992 -This document contains release notes for the developent tools, C/C++ +This document contains release notes for the development tools, C/C++ language, and libraries provided with the Microsoft(R) Windows NT(TM) -Software Development Kit (BETA). The information in this file is newer, -and therefore supersedes any similar information in the printed -manuals. +Software Development Kit (BETA). The information in this document is more +up to date than that included in the manuals. -================================< Contents >================================ +=============================< Contents >============================= This file has six parts: - Part Title - ---- ----- - 1 Additional 32-bit Run-time Functions: - _find Functions - _seterrormode - _loaddll - _unloaddll - _getdllprocaddr - _getdiskfree - _sleep - _beep - _getsystime - _setsystime - _futime - _getdrives - _get_osfhandle - _open_osfhandle - - 2 Further note on the _beginthread function + Part Title + ---- ----- - 3 Notes on "C Language Reference" + 1 Additional 32-bit Run-time Functions - 4 Linker Options + 2 Notes on the _beginthread function + + 3 Notes on "C Language Reference" + + 4 Notes on Linker Options + + 5 Notes on Building Multithreaded + Applications and DLLs + + 6 The WinDebug Graphical Debugger + + 7 Post-Mortem Debugging - 5 Building Multithreaded Applications and DLLs - 6 The WinDebug Graphical Debugger ===============< Part 1: Additional 32-bit Run-time Functions >========= -In addition to the 32-bit C run-time functions listed in the appendix -to the Programming Techniques manual, the following routines are -specific to 32-bit operating systems: + +The following functions are specific to 32-bit operating systems. These +functions are in addition those described in the Appendix to PROGRAMMING +TECHNIQUES. _find Functions -*************** +--------------- Description -=========== -Find the first matching file, find the next matching file, or release -resources from previous find operations. +------------ +This function find the first matching file, the next matching file, +or releases resources from previous find operations. #include -long _findfirst( char *filespec, struct _finddata_t *fileinfo ); -int _findnext( long handle, struct _finddata_t *fileinfo ); -int _findclose( long handle ); - -filespec Target file specification (may include - wildcards) -handle Search handle returned by a previous call to - _findfirst -fileinfo File information buffer +long _findfirst (char *filespec, struct _finddata_t *fileinfo); +int _findnext (long handle, struct _finddata_t *fileinfo); +int _findclose (long handle); + +filespec The target file specification (may include wildcards) + +handle The search handle returned by a previous call to + _findfirst + +fileinfo The file information buffer Remarks -======= -The _findfirst routine returns information about the first instance of -a file whose name matches the filename argument. The filename argument -may use wildcards (* and ?). Any wildcard combination supported by the -host operating system may be used. - -Information is returned in a _finddata_t structure, defined in IO.H. -The _finddata_t structure contains the following elements: - -Element Description -------- ----------- -unsigned attrib File attribute - -time_t time_create Time of file creation (-1 for FAT file - systems) - -time_t time_access Time of last file access (-1 for FAT file - systems) - -time_t time_write Time of last write to file - -_fsize_t size Length of file in bytes - -char name[_MAX_FNAME] Null-terminated name of matched - file/directory, without the path - -_MAX_FNAME is defined in STDLIB.H. - -Unlike its MS-DOS counterpart, _findfirst does not allow the programmer -to specify target attributes (_A_RDONLY, etc.) by which to limit the -find operation. This attribute is returned in the attrib field of the -_finddata_t structure and can have the following values (defined in -IO.H): - -Constant Meaning Value --------- ------- ----- -_A_ARCH Archive. Set whenever the file 0x20 - is changed, and cleared by the - MS-DOS BACKUP command. - -_A_HIDDEN Hidden file. Cannot be found 0x02 - with the MS-DOS DIR command. Returns - information about normal files as well - as about files with this attribute. - -_A_NORMAL Normal. File can be read or written 0x00 - without restriction. - -_A_RDONLY Read-only. File cannot be opened for 0x01 - writing, and a file with the same name - cannot be created. Returns information - about normal files as well as about - files with this attribute. - -_A_SUBDIR Subdirectory. Returns information about 0x10 - normal files as well as about files - with this attribute. - -_A_SYSTEM System file. Cannot be found with the 0x04 - MS-DOS DIR command. Returns information - about normal files as well as about - files with this attribute. +-------- +The _findfirst function provides information about the first instance +of a filename that matches the file specified in the filename argument. +Wildcard characters (* and ?) may be used in the filename argument. Any +wildcard combination supported by the host operating system may be used. + +File information is returned in a _finddata_t structure, defined in IO.H. The +_finddata_t structure includes the following elements: + +Element Description +------- ------------ +unsigned attrib File attribute + +time_t time_create Time of file creation + (-1 for FAT file systems) + +time_t time_access Time of last file access + (-1 for FAT file systems) + +time_t time_write Time of last write to file + +_fsize_t size Length of file in bytes + +char name[_MAX_FNAME] Null-terminated name of matched + file/directory, without the path + _MAX_FNAME is defined in STDLIB.H. + +You cannot specify target attributes (_A_RDONLY) to limit the find +operation. This attribute is returned in the attrib field of the +_finddata_t structure and can have the following values +(defined in IO.H): + +Constant Description Value +-------- ----------- -------- +_A_ARCH Archive. Set whenever the file 0x20 + is changed, and cleared by the + MS-DOS BACKUP command. + +_A_HIDDEN Hidden file. Not normally seen 0x02 + with the MS-DOS DIR command. + +_A_NORMAL Normal. File can be read or 0x00 + written to without restriction. + +_A_RDONLY Read-only. File cannot be opened 0x01 + for writing, and a file with the + same name cannot be created. + +_A_SUBDIR Subdirectory. 0x10 + +_A_SYSTEM System file. Not normally seen with 0x04 + the MS-DOS DIR command. -The _findnext routine finds the next name, if any, that matches the +The _findnext function finds the next name, if any that matches the filespec argument specified in a prior call to _findfirst. The fileinfo argument should point to a structure initialized by a previous call to _findfirst. The contents of the structure will be altered as described @@ -144,315 +129,327 @@ associated resources. The _find functions allow nested calls. For example, if the file found by a call to _findfirst or _findnext is a subdirectory, a new search -can then be initiated with another call to _findfirst or _findnext. +can be initiated with another call to _findfirst or _findnext. Return Value -============ +------------------ If successful, the _findfirst function returns a unique search handle identifying the file or group of files matching the filespec specification which can be used in a subsequent call to _findnext or _findclose. Otherwise, it returns -1 and sets errno to one of the following values: -Value Description ------ ----------- -ENOENT filespec could not be matched +Value Description +-------- ------------ +ENOENT File specification that could + not be matched. -EINVAL Illegal filename specification + +EINVAL Illegal filename specification If successful, the _findnext and _findclose functions return 0. Otherwise, they return -1 and set errno to ENOENT, indicating that no -more matching files could be found. Although each search operation -returns its own unique handle, the same +more matching files could be found. + _seterrormode -************* +------------- Description -=========== -Controls whether the operating system handles hard errors or allows the -calling application to handle them. +------------ +This function controls whether the operating system or the calling +application handles hard errors. #include -void _seterrormode( int mode ); +void _seterrormode (int mode); -mode Error mode +mode Error mode Remarks -======= +------------- The mode argument specifies the error-mode flag. If mode is set to -_CRIT_ERROR_PROMPT, The system displays an error message prompt +_CRIT_ERROR_PROMPT, the system displays an error message prompt indicating that a hard error has occurred. If mode is set to _CRIT_ERROR_FAIL, the system returns the failed call to the calling application with an error indicating the cause. Return Value -============ -None. +------------------ +None + _loaddll -******** +-------- Description -=========== -Loads the specified DLL into memory. +----------- +Loads the specified Dynamic Link Library (DLL) into memory. #include -int _loaddll( char *dllname ); +int _loaddll (char *dllname); -dllname Null-terminated string that names the DLL to - be loaded. +dllname Null-terminated string that names the DLL to + be loaded. Remarks -======= -The _loaddll routine loads the specified Dynamic Link Library. If the -dllname argument does not include a fully-qualified path name, the +------- +The _loaddll routine loads the specified DLL. If the +dllname argument does not include a qualified path name, the library is searched for according to the search path specified by the host operating system. Return Value -============ +------------ If successful, the _loaddll routine returns a unique handle to the DLL. Otherwise, it returns 0. + _unloaddll -********** +---------- Description -=========== +----------- Unloads the specified DLL from the current process. #include -int _unloaddll( int handle ); +int _unloaddll (int handle); -handle Handle to the loaded DLL, from a previous call - to _loaddll. +handle Handle to the loaded DLL, from a previous call + to _loaddll. Remarks -======= -The _unloaddll routine unloads the specified DLL. The DLL’s resources -may be freed if no other processes are using it. +------- +The _unloaddll function unloads the specified DLL. If there are no +other processes using the DLL, its resources may be released. Return Value -============ +------------ If successful, the _unloaddll routine returns 0. Otherwise, it returns an operating system error code. + _getdllprocaddr -*************** +--------------- Description -=========== +----------- Returns the address of the specified exported DLL function. #include int (* _getdllprocaddr(int handle, char *procname, int ordinal))(); -handle Handle to DLL module that contains the function - (returned by previous call to _loaddll) +handle Specifies the handle to the DLL module that contains + the function. (This is returned by previous call to + _loaddll) + +procname This points to the null-terminated string containing + the function name, or NULL if the function's + ordinal value is used. -procname Pointer to null-terminated string containing - the function name, or NULL if the function's - ordinal value is to be used. - -ordinal Function's ordinal value, or -1 if the - function's name is to be used. +ordinal Function's ordinal value, or -1 if the + function's name is used. Remarks -======= -The _getdllprocaddr routine retrieves the address of exported +------------ +The _getdllprocaddr function retrieves the address of exported functions in DLLs. The function can be specified by name or by ordinal -value. The retrieved address can then be called as a function pointer. +value. Once retrieved, an address can be called as a function pointer. Return Value -============ +------------- If successful, the _getdllprocaddr function returns a pointer to the function's entry point. Otherwise, it returns NULL. + _getdiskfree -************ +------------ Description -=========== +------------ Retrieves information about the current or specified disk drive, including the amount of free space on the disk. include include -int _getdiskfree( unsigned drive, struct _diskfree_t diskinfo ); +int _getdiskfree (unsigned drive, struct _diskfree_t diskinfo); -drive Specified drive number. This argument is 0 for - the current drive, or 1-26 for another - specified disk drive. +drive This specifies the drive number. The argument is + 0 for the current drive or 1-26 for another + specified disk drive. -diskinfo Disk information structure +diskinfo Disk information structure Remarks -======= +------- The _getdiskfree function retrieves information about the specified disk drive. This information is returned in a _diskfree_t structure, which is defined in DIRECT.H and has the following fields: -Element Description -------- ----------- -unsigned total_clusters Total number of clusters on the disk +Element Description +------- ---------------- +unsigned total_clusters Total number of clusters on the disk -unsigned avail_clusters Total number of free clusters on the disk +unsigned avail_clusters Total number of free clusters on the + disk -unsigned sectors_per_cluster Number of sectors per cluster +unsigned sectors_per_cluster Number of sectors per cluster -unsigned bytes_per_sector Number of bytes per sector +unsigned bytes_per_sector Number of bytes per sector Return Value -============ +------------ If successful, the _getdiskfree routine returns 0. Otherwise, it returns an operating system error code. + _sleep -****** +------ Description -=========== +----------- Delays execution of the current thread or process for a specified interval. include -void _sleep( unsigned long duration ); +void _sleep (unsigned long duration); -duration Specifies the relative time, in milliseconds, - that the delay is to occur. +duration Specifies the length of time, in milliseconds, + of the delay. Remarks -======= -In multithreaded operating systems, the _sleep routine causes the +-------- +In multi-threaded operating systems, the _sleep routine causes the current thread to enter a waiting state until the specified interval of -time has passed. In single- threaded operating systems, the _sleep +time has passed. In single-threaded operating systems, the _sleep routine causes the current process to be delayed. During the delay, other threads or processes can continue execution. With MS-DOS, yield messages are sent periodically which can be handled by Windows or other -multitasking operating systems. +multi-tasking operating systems. The duration argument indicates the length of the interval in milliseconds. It can also be one of the following two values: -Constant Value --------- ----- -_SLEEP_MINIMUM Function returns immediately +Constant Value +-------- -------- +_SLEEP_MINIMUM Function returns immediately -_SLEEP_FOREVER Infinite delay +_SLEEP_FOREVER Infinite delay Note that in non-preemptive multitasking operating systems (such as Windows), the duration may be longer than specified, since other processes may not return control at the end of the delay. Return Value -============ +------------ None. + _beep -***** +--------- Description -=========== -Generates simple tones on the speaker. +----------- +Generates a beep on the speaker. #include -void _beep( unsigned frequency, unsigned duration ); +void _beep (unsigned frequency, unsigned duration); -frequency Specifies the frequency of the sound in hertz. - Audible sounds will be generated by frequencies - between 37 (25 hex) and 32767 (07FFF hex). - -duration Specifies the duration of the sound in - milliseconds. See the description of the _sleep - function for possible values. Note that in - non-preemptive multitasking operating systems - (such as Windows), the duration may be longer - than specified, since other processes may not - return control at the end of the delay. +frequency Specifies the frequency of the sound in hertz. + Frequencies between 37 (25 hex) and 32767 + (07FFF hex) will produce audible sounds + +duration Specifies the duration of the sound in + milliseconds. See the description of the _sleep + function for possible values. Note that in + non-preemptive multi-tasking operating systems + (such as Windows), the duration may be longer + than specified, since other processes may not + return control at the end of the delay. Return Value -============ +------------- None. -_getsystime -*********** +_getsystime +----------- Description -=========== +----------- Retrieves the current system time. #include -unsigned _getsystime( struct tm *tmstruct ); +unsigned _getsystime (struct tm *tmstruct); -tmstruct Pointer to a tm time structure containing - information about the system date and time. +tmstruct Pointer to a tm time structure containing + information about the system date and time. Remarks -======= -The _getsystime routine fills in a tm time structure (defined in +-------- +The _getsystime function fills in a tm time structure (defined in TIME.H) with information about the system date and time. The routine then returns the fractional portion of the nearest second, in milliseconds. Return Value -============ +------------- The _getsystime function returns the fractional portion of the nearest second, in milliseconds. + _setsystime -*********** +----------- Description -=========== -Sets the current system time. +----------- +Sets the system time. #include -unsigned _setsystime( struct tm *tmstruct, unsigned milliseconds ); +unsigned _setsystime (struct tm *tmstruct, unsigned milliseconds); -tmstruct Pointer to a tm time structure containing - information about the system date and time +tmstruct Pointer to a tm time structure containing + information about the system date and time -milliseconds Fractional portion of nearest second, in - milliseconds +milliseconds Fractional portion of nearest second, in + milliseconds Remarks -======= -The _setsystime routine sets the current system time to the specified +------- +The setsystime function sets the system time to the specified time. Return Value -============ +------------ If successful, the _setsystime routine returns 0. Otherwise, it returns an operating system error code. + _futime -******* +-------- Description -=========== +----------- Sets the modification time on an open file. #include <\sys\utime.h> -int _futime( int handle, struct _utimbuf *filetime ); +int _futime (int handle, struct _utimbuf *filetime); -handle Handle to open file +handle Handle to open file -filetime Pointer to structure containing new - modification date +filetime Pointer to structure containing new + modification date Remarks -======= +-------- The _futime routine sets the modification date on the open file associated with handle. It is identical to the _utime function, except that its argument is the handle to an open file, rather than the name @@ -461,67 +458,70 @@ a field for access time, only the modifi that do not support access time (such as MS- DOS). Return Value -============ +------------- The _futime function returns 0 if successful. A return value of -1 indicates an error; in this case, errno is set to EBADF, indicating an invalid file handle. + _getdrives -********** +---------- Description -=========== -Returns a bitmask representing the currently available disk drives. +----------- +Returns a bitmap representing the currently available disk drives. #include -unsigned long _getdrives ( void ); +unsigned long _getdrives (void); Return Value -============ -The return value is a bit map with bits set for each currently +------------ +The return value is a bitmap with bits set for each currently available disk drive. Bit position 0 (the least-significant bit) is drive A, bit position 1 is drive B, bit position 2 is drive C, and so on. + _get_osfhandle -************** +-------------- Description -=========== +----------- Associates an operating system file handle with an existing C run-time file handle. #include -long _get_osfhandle( int filehandle ); +long _get_osfhandle (int filehandle); -filehandle User file handle +filehandle User file handle Return Value -============ +------------ If successful, the _get_osfhandle routine returns an operating system file handle, corresponding to filehandle. Otherwise, it returns -1 and sets errno to EBADF, indicating an invalid file handle. + _open_osfhandle -*************** +--------------- Description -=========== +------------ Associates a C run-time file handle with an existing operating system file handle. #include -int _open_osfhandle( long osfhandle, int flags ); +int _open_osfhandle (long osfhandle, int flags); -osfhandle Operating system file handle +osfhandle Operating system file handle -flags Type of operations allowed +flags Type of operations allowed Remarks -======= +-------- The _open_osfhandle routine allocates a C run-time file handle and sets it to point to the operating system file handle specified by osfhandle. The flags argument is an integer expression formed from one @@ -531,445 +531,370 @@ argument, the constants are combined wit The FCNTL.H file defines the following manifest constants: -Constant Meaning --------- ------- -_O_APPEND Repositions the file pointer to the end of the - file before every write operation. +Constant Meaning +-------- ------------ +_O_APPEND Repositions the file pointer to the end of the + file before every write operation. -_O_RDONLY Opens file for reading only. +_O_RDONLY Opens file for reading only. -_O_TEXT Opens file in text (translated) mode. +_O_TEXT Opens file in text (translated) mode. Return Value -============ +------------- If successful, the _open_osfhandle function returns a C run-time file handle. Otherwise, it returns -1. -=============< Part 2: Further note on the _beginthread function >============== +============< Part 2: Notes on the _beginthread function >============= + Windows NT handles the allocation of the stack when the _beginthread -routine is called. Therefore, unlike previous 16-bit versions of the -function, the programmer does not need to pass the address of the -thread stack to _beginthread. The following description supersedes the -information in the appendix to the Programming Techniques manual: - -unsigned long _beginthread( void( *start_address )( void * ), unsigned -stack_size, void *arglist ); - -start_address Starting address of thread -stack_size Stack size for thread -arglist Argument list for thread - -=====================< Part 3: C Language Reference >================================ - -The following information is 16- and 32-bit specific information that -supersedes the information listed on the corresponding pages of the -Microsoft C/C++ C Language Reference manual. +routine is called. You do not need to pass the address of the thread +stack to _beginthread. + +The following description of the _beginthread function replaces +that in the Appendix of the Programming Techniques manual. In addition, +the description provided in APP.WRI contains the correct information. + +unsigned long _beginthread (void (*start_address) (void *) , unsigned +stack_size, void *arglist); + +start_address Starting address of thread +stack_size Stack size for thread +arglist Argument list for thread + + +=============< Part 3: Notes on the C Language Reference >============== +The following 16- and 32-bit specific information replaces the +information on the corresponding pages of the Microsoft C/C++ C +Language Reference manual. Page 5 -The following keywords are not supported for 32-bit targets: __far, -__fortran, __huge, __interrupt, __loadds, __pascal, __saveregs, -__segment, __self. Limited 32-bit support is available for __based. The -__try, __except and __finally keywords are supported only for 32-bit -compilations. +--------- +The following keywords are NOT supported for 32-bit targets: +__far __fortran __huge +__interrupt __loadds __pascal +__saveregs __segment __self + +The following keywords are supported ONLY for 32-bit compilations: +__try __except __finally + +LIMITED 32-bit support is available for __based. Page 13 +------- For 32-bit targets, the values of long double are the same as for double. Page 48 +-------- The 32-bit compiler ignores the register keyword. Page 56 +------- The 32-bit compiler ignores the use of the __near keyword. Page 57 -The 32-bit compiler does not allow the use of the __far keyword. - -Page 57 -The 32-bit compiler does not allow the use of the __huge keyword. +------- +The 32-bit compiler does not allow the use of the following keywords: + __far __huge __fortran + __pascal + +The following keyword: + __based + specifies that a pointer is a 32-bit offset from a 32-bit base. -Page 57 -For 32-bit targets, __based specifies that a pointer is a 32-bit offset -from a 32-bit base. - -Page 57 -The __fortran and __pascal keywords are not accepted for 32-bit targets. Page 58 +------- The __cdecl calling convention is the default for 32-bit targets. -Page 58 + The 32-bit compiler uses the ECX and EDX registers, but Microsoft reserves the right to change the registers and implementation of the __fastcall calling convention between releases of the compiler. Page 59 +------- The __segment keyword is not supported by the 32-bit compiler. Page 70 -The default packing size is 4 for 32-bit targets. +-------- +The default packing size for 32-bit targets is 4. Page 71 +------- Bit fields default to size long for the 32-bit compiler. Page 76 +------- For 32-bit targets, size_t is unsigned long and the __huge keyword is not required. Page 80 -The __segment type and the built-in function __segname are not -supported by the 32-bit compiler. +------- +The following are not supported by the 32-bit compiler: + __segment type built-in function __segname Page 82 +------- Pointers based on pointers are the only form of the __based keyword valid in 32-bit compilations. In such compilations, they are 32-bit displacements from a 32-bit base. Page 84 +------- Pointers based on __self are not available for 32-bit targets. Page 95 +------- On 32-bit computers, sizeof is unsigned long. Page 100 +-------- The 32-bit compiler maps long double to type double. Page 121 +-------- The base operator is not supported for 32-bit targets. Page 169 -The use of the __near keyword is ignored by the 32-bit compiler. - -Page 169 -The use of the __far keyword is illegal for 32-bit targets. +-------- +The following keywords are not supported by the 32-bit +compiler: + __near __far Page 170 -The __fortran and __pascal keywords are illegal for 32-bit targets. +-------- +The following keywords are not supported for 32-bit targets: + __fortran __pascal Page 175 -For 16-bit targets, the __interrupt keyword specifies that the function -is an interrupt handler. The compiler generates appropriate entry and +-------- +The __interrupt keyword is not supported in 32-bit targets. ( +See Help for more information on writing interrupt functions.) + +The __interrupt keyword is used with 16-bit functions, to +specify that the function is an interrupt handler. +The compiler generates appropriate entry and exit sequences for the handling function, including saving and restoring all registers and executing an IRET instruction to return. -Use this form to specify an interrupt function: +Use the following form to specify an interrupt function: __interrupt declarator +(The declarator is the name of the function to be called. -where declarator is the name of the function to be called. An interrupt -function must be __far. If you are compiling with the small (default) -or compact memory model, you must explicitly declare the function with -the __far attribute. An interrupt function cannot be declared as an +An interrupt function must be __far. +If you are compiling with the small (default) or compact + memory model, you must explicitly declare the function with +the __far attribute. + An interrupt function cannot be declared as an inline function. -Interrupt functions must observe the C calling convention. If you use -the /Gc compiler option (forcing the __pascal or __fortran calling +Interrupt functions must observe the C calling convention. +If you use the /Gc compiler option (forcing the __pascal or __fortran calling convention) or the /Gr compiler option (forcing the __fastcall calling convention), you must explicitly declare your interrupt-handling function with the __cdecl attribute. -You cannot declare an interrupt function with both the __interrupt -attribute and the __saveregs attribute or the __fastcall calling -convention. - -This example statement declares a function pointer that can be used to -point to an interrupt handler: +You cannot declare an interrupt function using the +__interrupt attribute with the __saveregs attribute or +with the __fastcall calling convention. -void ( __interrupt __far *oldtime ) ( void ); +The following example of a statement declares a function +pointer that can be used to point to an interrupt handler: -Page 175 -The __interrupt keyword is illegal in 32-bit targets. See Help for -more information on writing interrupt functions. +void (__interrupt __far *oldtime) (void); -Page 176 -The __loadds keyword is not supported in 32-bit targets. Page 176 -The __saveregs keyword is not supported in 32-bit targets. +--------- +The following keywords are not supported in 32-bit targets: +__loadds __saveregs Page 199 -The following predefined macros are for 16-bit targets only: +-------- +The following predefined macros are supported for +16-bit targets only: + +Identifier Function +---------- --------- +_DLL Code for run-time library as a dynamic-link + library. Defined when /MD is specified. + +_FAST This Fast-compile macro is defined when /f + is specified (the default). (__FAST replaces + __QC, which is still supported but is not + recommended.) Using /Od causes CL to + compile your program with /f. The /f option + compiles source files without default + optimizations. + +M_I8086, _M_I8086 This macro is defined for 8086 and 8088 + processors(default or /G0 option) + +M_I286, _M_I286 This macro is defined for 80286 processor + (/G1 or /G2 option). + +M_I86mM, _M_I86mM This macro, which is always defined, + identifies the memory model. + "m' can be any of the following models: + + Model Defined by + ----- ---------- + T (tiny model) \AT + S (small model) \AS + C (compact model) \AC + M (medium model) \AM + L (large model) \AL + H (huge model) \AH + If the huge model is used, both M_I86LM and + M_I86HM are defined. The default model is small. + +_PCODE This macro is defined for sections of code that + are compiled as pcode. Defined when /Oq is + enabled. + +_QC This macro is supported for compatibility with + Microsoft C version 6.0. The _FAST macro + (or /f) is the default for Microsoft C version + 8.0, and is the recommended alternative. + +_WINDLL This macro, the Windows protected-mode + dynamic-link library, is selected with /GD. + +_WINDOWS This macro sets Windows protected mode. It + is selected with /GA, /Gn, /GW, /Mq, or /GD. -Identifier Function ----------- -------- -_DLL Code for run-time library as a dynamic-link - library. Defined when /MD is specified. (For - 16-bit targets only.) - -_FAST Fast-compile. Defined when /f is specified - (the default). Supersedes _QC, which is still - supported but not recommended. Using /Od causes - CL to compile your program with /f. The /f - option compiles source files without any default - optimizations.(For 16-bit targets only.) - -M_I8086, _M_I8086 Defined for 8086 and 8088 processors (default - or /G0 option) (For 16-bit targets only.) - -M_I286, _M_I286 Defined for 80286 processor (/G1 or /G2 option). - (For 16-bit targets only.) - -M_I86mM, _M_I86mM Always defined. Identifies memory model, where - `m' is either T (tiny model), S (small model), - C (compact model), M (medium model), L (large - model), or H (huge model). Defined by /AT, /AS, - /AC, /AM, /AL and /AH, respectively. If huge - model is used, both M_I86LM and M_I86HM are - defined. Small model is the default. (For - 16-bit targets only.) - -_PCODE Defined for sections of code that are compiled - as pcode. Defined when /Oq is enabled. (For - 16-bit targets only.) - -_QC Supported for compatibility with Microsoft C - version 6.0. The _FAST macro (or /f) is the - default for C8 and is the recommended - alternative. (For 16-bit targets only.) - -_WINDLL Windows protected-mode dynamic-link library is - selected with /GD. (For 16-bit targets only.) - -_WINDOWS Windows protected mode is selected with /GA, - /Gn, /GW, /Mq, or /GD. (For 16-bit targets - only.) -Page 199 The following predefined macro is for 32-bit targets only: -Identifier Function ----------- -------- -_M_IX86 Defined as 300 for the 80386 processor (/G3 - option) and as 400 for the 80486 (/G4) processor. +Identifier Function +---------- -------- +_M_IX86 Defined as 300 for the 80386 processor + (/G3 option) and as 400 for the 80486 + (/G4) processor. Page 210 -The following pragmas are for 16-bit targets only: +------------- +The following pragmas are supported for 16-bit targets only: -#pragma check_pointer ([[{ on | off }]]) ----------------------------------------- -Instructs the compiler to turn off pointer checking if off is -specified, or to turn on pointer checking if on is specified. If turned -on, this pragma causes the compiler to check every pointer dereference -to make sure the pointer is not a null or out- of-range pointer. The -check_pointer pragma is also enabled with the /Zr command-line option, -which is only available with the /f option. If you do not specify -either on or off, the effect of check_pointer is to reverse the -current state of pointer checking. If pointer checking is on, it is -turned off and vice versa. - -This pragma works function by function, not statement by statement. To -use this pragma, place a pair of check_pointer pragmas around any -function definition that contains pointer usage you want to check. - -#pragma code_seg ( [[ "segment-name" [[, "segment-class"]] ) ------------------------------------------------------------- -Specifies a segment where functions are to be allocated, allowing the -use of based allocation without rewriting code. The code_seg pragma -specifies the default segment for functions. This is equivalent to -using the /NT (name of TEXT segment) compilation option. It is also -equivalent to specifying functions as based. You can, optionally, -specify the class as well as the segment name. For example: - -#pragma code_seg( "MY_CODE", "CODE" ) - -The preceding example causes functions following to be allocated in a -segment called MY_CODE. The segment is given a CODE class. - -Specifying the code_seg pragma with no arguments causes the compiler -to allocate all following functions in the default code segment called -MY_CODE. The segment is given a CODE class. - -Note ----- -There is no way to specify the segment class using based function -allocation or the /NT compilation option. - -Functions allocated using the /NT option or code_seg pragma do not -retain any information about their location. However, functions -allocated using the based function-allocation syntax retain that -information in their external name. - -#pragma data_seg ( [[ "segment-name"[[, "segment-class"]] ) ------------------------------------------------------------ -Specifies the default segment for data. This is equivalent to using the -/ND (name of DATA segment) compilation option. It is also equivalent to -specifying objects or pointers as based. You can, optionally, specify -the class as well as the segment name. For example: - -#pragma data_seg( "MY_DATA", "DATA" ) - -The preceding example causes functions following to be allocated in a -segment called MY_DATA. The segment is given a DATA class. - -Specifying the data_seg pragma with no arguments causes the compiler -to allocate all following data in the default data segment called -MY_DATA. The segment is given a DATA class. - -Note ----- -There is no way to specify the segment class using based function -allocation or the /ND compilation option. - -Data allocated using the /ND option or data_seg pragma do not retain -any information about their location. However, data allocated using the -based syntax retain that information in their external name. - -If you compile with /Za, the data_seg pragma does not affect the -allocation of uninitialized objects. This is true under /Za. However, -under /Ze the uninitialized objects also get allocated in the segment -specified by the data_seg pragma. - -#pragma native_caller ( [[ { on | off } ]] ) --------------------------------------------- -Controls the removal of native-code entry points from within source -code on a function by function basis. To suppress all native entry -points, use the /Gn command-line option. See the Programming Techniques -manual for more information about p-code. +#pragma check_pointer ([[{ on | off }]]) -Page 210 -#pragma alloc_text( textsegment, function1, ...) ------------------------------------------------- -Names the segment where the specified function definitions are to -reside. This must occur between a function declarator and the function -definition for the named functions. +#pragma code_seg ([[ "segment-name" [[, "segment-class"]]) + +#pragma data_seg ([[ "segment-name"[[, "segment-class"]]) +] +#pragma native_caller ([[ { on | off } ]]) + + +Use the _alloctext pragma: + +#pragma alloc_text (textsegment, function1, ...) + + to name the location segment of specified function definitions in 32-bit targets. This must occur between a function declarator and the function definition for the named functions. + +(The recommended technique for functions in 16-bit targets is to use _based to specify the function location. _based is not supported in 32-bit targets.) -The recommended technique for functions in 16-bit targets is to use -__based to specify the function location. -Use the alloc_text pragma for 32-bit targets since __based is not -supported for functions in 32-bit targets. Page 211 -#pragma intrinsic( function1 [[, function2, ...]] ) ---------------------------------------------------- -Specifies that calls to the specified functions are intrinsic (a -library function known to the compiler). Alternatively, you can use the -/Oi option to make intrinsic the default for functions that have -intrinsic forms. In this case, you can use the function pragma to -override /Oi for specified functions. This pragma cannot be used with -/f. This pragma takes effect at the first function defined after the -pragma is seen. +--------- +#pragma intrinsic (function1 [[, function2, ...]]) -The following functions have intrinsic forms for both the 16-bit and -32-bit compilers: +This pragama sets calls to the specified functions to intrinsic (a library function known to the compiler). +The /Oi option can be also be used to make intrinsic the default for +functions that have intrinsic forms. You can use the function pragma +to override /Oi for specified functions. This pragma cannot be used +with/f. This pragma takes effect at the first function defined after the pragma is defined. -_alloca -_disable -_enable -_inp -_inpw -_lrotl -_lrotr -_outp -_outpw -_rotl -_rotr -_strset -abs -acos -asin -atan -atan2 -ceil -cos -cosh -exp -fabs -floor -fmod -labs -log -log10 -memcmp -memcpy -memset -pow -sin -sinh -sqrt -strcat -strcmp -strcpy -strlen -tan -tanh - -The following functions have intrinsic forms for the 16-bit compiler -only: - -_acosl -_asinl -_atanl -_atan2l -_ceill -_cosl -_coshl -_expl -_floorl -_fmodl -_logl -_log10l -_powl -_sinl -_sinhl -_sqrtl -_tanl -_tanhl -_fmemcmp -_fmemcpy -_fmemset -_fstrcat -_fstrcmp -_fstrcpy -_fstrlen -_fstrsetu -Page 212 -#pragma optimize( "[[optimization-option-list]]", {off | on } ) ---------------------------------------------------------------- -Specifies optimizations to be performed. Must appear outside a -function. The optimization option list may be zero or more of the -following: a, c, e, g, l, n, p, q, t, and w. These letters correspond -to the /O compilation options. This pragma takes effect at the first -function defined after the pragma is seen. The optimization list for -32-bit targets may be zero or more of the following: a, g, n, p, t, and -w. + +The following functions have intrinsic forms for BOTH 16-bit and 32-bit compilers: + + _alloca _disable _enable + _inp _inpw _lrotl + _lrotr _outp _outpw + _rotl _rotr _strset + abs acos asin + atan atan2 ceil + cos cosh exp + fabs floor fmod + labs log log10 + memcmp memcpy memset + pow sin sinh + sqrt strcat strcmp + strcpy strlen tan + tanh + +The following functions have intrinsic forms + for the 16-bit compiler only: + +_acosl _asinl _atanl +_atan2l _ceill _cosl +_coshl _expl _floorl +_fmodl _logl _log10l +_powl _sinl _sinhl +_sqrtl _tanl _tanhl +_fmemcmp _fmemcpy _fmemset +_fstrcat _fstrcmp _fstrcpy +_fstrlen _fstrsetu + Page 212 -#pragma pack( [[{1 | 2 | 4 | 8 | 16 }]] ) ------------------------------------------ -Specifies packing alignment for structure types. You can use the /Zp -option to specify the same packing for all structures in a module. The -default is 2 for 16- bit targets and 4 for 32-bit targets. +-------- + +#pragma optimize ("[[optimization-option-list]]", {off | on }) + +This pragma specifies optimizations to be performed. It must appear +outside of a function. The optimization list for 32-bit targets +may be zero or more of the following letters: + a g n p t w + +The letters correspond to the /O compilation options. +The pragma takes effect at the first function defined after the +pragma is seen. + + +#pragma pack ([[{1 | 2 | 4 | 8 | 16 }]]) + +This pragma specifies packing alignment for structure types. +you can use the /Zp option to specify the same packing +for all structures in a module. The default is 2 for 16- bit +targets and 4 for 32-bit targets. When you give the /Zpn option, where n is 1, 2, 4, 8, or 16, each structure member after the first is stored on n-byte boundaries, -depending on the number you choose. If you use the /Zp option without -an argument, structure members are packed on one-byte boundaries. No -space is allowed between /Zp and its argument. This pragma takes effect -at the first function defined after the pragma is seen. +depending on the number you choose. If you use the /Zp option +without an argument, structure members are packed on one-byte +boundaries. No space is allowed between /Zp and its argument. +This pragma takes effect at the first function defined after the +pragma is seen. On 32-bit targets, the packing can be set at 8 or 16 as well as 1, 2, or 4 as given for 16-bit targets. Page 240 -For the 32-bit compiler, long double and double are the same. +-------- +Long double and double are the same for the 32-bit compiler. + +===================< Part 4: Notes on Linker Options >================= -========================< Part 4: Linker Options >=========================== +In Chapter 1, "Building Applications and DLLS" of the Programming +Techniques manual and Chapter 5 "Linker" of the Tools manual, the +NOTMAPPED parameter for the LINK and COFF /DEBUG: option is +incorrectly given as "NOMAPPED." -Throughout Programming Techniques (Chapter 1: Building Applications -and DLLs) and Tools (Chapter 5: Linker), the NOTMAPPED parameter for -the LINK and COFF /DEBUG: option is incorrectly given as "NOMAPPED." The correct syntax for the /DEBUG option is: /DEBUG:[{MAPPED|NOTMAPPED},]{NONE|MINIMAL|PARTIAL|FULL} -=============< Part 5: Building Multithreaded Applications and DLLs >============ +======== -The following information should be added to Programming Techniques -Chapter 1: Building Applications and DLLs: +Add the following information should Chapter 1 "Building Applications and DLLS" of the Programming Techniques manual. + Building Multithreaded Programs ------------------------------- @@ -983,121 +908,172 @@ specified: of LIBC.LIB (single-thread C run-time library). Using the C Run-Time DLL ------------------------- +------------------------- You can reduce the size of an executable file by using the C run-time -DLL instead of statically linking the C run-time libraries to the -program. The cost is a small startup overhead to initialize the DLL, -and the normal DLL calling overhead. - -To use the C run-time DLL (CRTDLL.DLL) with either a single- threaded -or multithreaded program, link with CRTDLL.LIB. Do not link with either -LIBC.LIB or LIBCMT.LIB. The C run-time DLL supports both types of -programs. +DLL instead of linking the C Run-Time libraries to a +program. The C Run-Time DLL supports both single and multithreaded +programs. +Using the C Run-Time DLL may require additional set up time to +initialize the DLL along with the time required for normal DLL +calling. + +To use the C Run-Time DLL (CRTDLL.DLL) with a single-threaded +or multithreaded program, link with CRTDLL.LIB. +Do not link with either LIBC.LIB or LIBCMT.LIB) -=============< Part 6: The WinDebug Graphical Debugger >============= - - -Loading Programs ----------------- - -NOTE: The Program menu is disabled in this version of WinDebug. To - load a program for debugging, you must enter the program - name on the command-line when you start the debugger. For - example: - - WINDBG MYPROG.EXE - - WINDBG C:\BUILDDIR\TESTOR.EXE - +========< Part 6: Notes on The WinDebug Graphical Debugger >========= Expression Evaluator -------------------- The expression evaluator in this release of WinDebug cannot -evaluate a type-cast followed by the following characters: *, &, -+, and |. You can acheive the same meaning by enclosing the casted -expression in parenthesis. For example: +evaluate a type-cast followed by the following characters: *, &, ++, and | unless the casted expression is enclosed in parentheses. - (char *) &i +For example: + (char *) &i would become - (char *) (&i) + (char *) (&i) +Editing the Command Window +-------------------------- +You can use editing keys similar to those available from the +NT command prompt in the Command window. +Use the up and down-arrow keys to retrieve previously-entered +WinDebug commands. +Use the Backspace, Delete, Insert, and You can edit the +current command line with the Backspace, Delete, Insert, +and left and right arrow keys. -Command Window --------------- - Command Window Editing - ---------------------- - In the Command window, you can use editing keys similar to those - available from the NT command prompt. The Up- and Down-Arrow keys let - You retrieve previously-entered WinDebug commands. You can edit the - current command line with the Backspace, Delete, Insert, and Left- - and Right-Arrow keys. +Process Specifiers +------------------ + +The process-specifier syntax should be as follows: +Symbol Description +------ ----------- +|. The current process. - Process Specifiers - ------------------ +| The process number. - The process-specifier syntax should be as follows: +|* All processes. - Symbol Description - ------ ----------- - |. The current process. - |number The process number. - |* All processes. + Set Breakpoint (BP) + ------------------- - Set Breakpoint (BP) - ------------------ +The Set Breakpoint (BP) options /M and /H are not available in this +release. - The Set Breakpoint (BP) options /M and /H are not available in this - release. +With the /C option, you must enclose the semicolon-separated list +of multiple commands in quotation marks. - With the /C option, you must enclose the semicolon-separated list - of multiple commands in quotation marks. +Enter ANSI Characters (EA) +-------------------------- - Enter ANSI Characters (EA) - -------------------------- +If you want to include space (" ") characters, you must enclose +the character string in quotation marks (" or '). +If you enclose the string in double quotation marks, WinDebug will +automatically null-terminate the string. Single quotation marks (') +will not add a null character. - If you want to include space (" ") characters, you must enclose - the character string in quotation marks (" or '). If you enclose - the string in double quotation marks, WinDebug will automatically - null-terminate the string. Single quotation marks (') will not add - a null character. +Display and Entry Commands (D* and E*) +-------------------------------------- +The display and entry commands (such as DD and EB) will use the +current default radix. You can enter numbers with a different radix +by using the standard C/C++ radix overrides (such as 0x). - Display and Entry Commands (D* and E*) - -------------------------------------- - The display and entry commands (such as DD and EB) will use the - current default radix. You can enter numbers with a different radix - by using the standard C/C++ radix overrides (such as 0x). +Find and Search (F and S) +------------------------- +These commands are unavailable in this release. - Find and Search (F and S) - ------------------------- - These commands are unavailable in this release. +Display Stack Backtrace (K) +--------------------------- +This command can be used when handling an exception. - Display Stack Backtrace (K) - --------------------------- - This command can be used when handling an exception. +Set Exceptions (SX*) +-------------------- +The set exception commands can be followed by /C2, +where is a quote-enclosed, semicolon-separated +list of WinDebug commands to execute after an exception is handled. +The SXE command can also be followed by /C, where + specifies commands to execute before an exception +riggers the debugger. - Set Exceptions (SX*) - -------------------- - These commands can be followed by /C2, where - is a quote-enclosed, semicolon-separated list of - WinDebug commands to execute after an exception is handled. The - SXE command can also be followed by /C, where - specifies commands to execute before an exception - triggers the debugger. +Remote Debugging +---------------- + +To setup remote debugging: +1. Connect the com ports with an NT standard debug cable. +2. Run "DBTarget.exe tlser.dll com?" on the target machine where ? is the port + number. It will pop up a little window in the left top corner of the screen. +3. Run Windbg on your windbg machine as if you were to do local debugging. Use + Options+Debug menu to load the remote transport dll "tlser.dll". +4. Enter the com port if not using the defult (com1). Then start the debuggee. + +It may take a few seconds, but the sybols loading message will appear on the +debugger and the app will begin to run on the other machine. You can then +debug the application as though you were on the local machine. + +Notes: + +1. You need the binary and the source files on the Windbg machine. + The debuggee binary is also needed on the target machine. The absolute + path for the location of the src/binary files should be the same on both + machines. + +2. For convenience, you can save two workspaces for your debuggee. One that uses + the local trasport layer, and another one that points to the remote transport + tlser.dll. Then you can easily switch between the local and the remote + debugging by loading the corresponding workspace for your debuggee. + +3. To specify a non-default baudrate, one may specify "com?:####" in place of + "com?", where #### is a valid baudrate such as 9600, 2400, etc. + + +========< Part 7: Post-Mortem Debugging >========= + + +Windows NT allows you to specify a debugger to execute in the event of an +application error. Through this mechanism, you can actually connect the +debugger to the process which failed. The following is an example of how +this is achieved with NTSD. You could alternatively specify any debugger +which has the ability to take process ids from the command line. + +NOTE: Windbg does not currently support this mechanism. + +When an unhandled exception occurs, an AE popup is displayed. + + This popup will always provide an OK button. Selecting OK will + terminate the application. + + In some cases, the popup will also provide a CANCEL button. Selecting + this button will invoke the debugger of your choice. The way you choose + your debugger is adding an AeDebug section in your win.ini file. + + [AeDebug] + Debugger = ntsd -d -p %d -e %d -g + + The Debugger = line is a sprintf format string. It is sprintf'd into a + command line where two parameters are passed. The first parameter is + the process id of the process that encountered the exception. The + second parameter is the value of an event handle inherited by the + debugger. The debugger should signal this event once it has reached an + idle state and is ready to see the exception from the application (this + usually means that the debugger has fielded the first breakpoint + exception from the process).