mstools/readme.txt - view

File: [WindowsNT SDKs] / mstools / readme.txt
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs
Thu Aug 9 18:21:01 2018 UTC (7 years, 9 months ago) by root
Branches: msft, MAIN
CVS tags: ntsdk-oct-1992, HEAD

Microsoft Windows NT Build 328 10-12-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 development tools, C/C++ language, and libraries provided with the Microsoft(R) Windows NT(TM) Software Development Kit (BETA). The information in this document is more up to date than that included in the manuals. =============================< Contents >============================= This file has six parts: Part Title ---- ----- 1 Additional 32-bit Run-time Functions 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 ===============< Part 1: Additional 32-bit Run-time Functions >========= 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 ------------ This function find the first matching file, the next matching file, or releases resources from previous find operations. #include <io.h> 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 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 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 above if a match is found. The _findclose routine closes the specified search handle and releases 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 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 File specification that could not be matched. 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. _seterrormode ------------- Description ------------ This function controls whether the operating system or the calling application handles hard errors. #include <stdlib.h> void _seterrormode (int 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 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 _loaddll -------- Description ----------- Loads the specified Dynamic Link Library (DLL) into memory. #include <process.h> int _loaddll (char *dllname); dllname Null-terminated string that names the DLL to be loaded. Remarks ------- 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 <process.h> int _unloaddll (int handle); handle Handle to the loaded DLL, from a previous call to _loaddll. Remarks ------- 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 <process.h> int (* _getdllprocaddr(int handle, char *procname, int ordinal))(); 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. ordinal Function's ordinal value, or -1 if the function's name is used. Remarks ------------ The _getdllprocaddr function retrieves the address of exported functions in DLLs. The function can be specified by name or by ordinal 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 <direct.h> include <dos.h> int _getdiskfree (unsigned drive, struct _diskfree_t diskinfo); 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 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 unsigned avail_clusters Total number of free clusters on the disk unsigned sectors_per_cluster Number of sectors per cluster 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 <stdlib.h> void _sleep (unsigned long duration); duration Specifies the length of time, in milliseconds, of the delay. Remarks -------- 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 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 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 _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 a beep on the speaker. #include <stdlib.h> void _beep (unsigned frequency, unsigned duration); 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 ----------- Description ----------- Retrieves the current system time. #include <time.h> unsigned _getsystime (struct tm *tmstruct); tmstruct Pointer to a tm time structure containing information about the system date and time. Remarks -------- 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 system time. #include <time.h> unsigned _setsystime (struct tm *tmstruct, unsigned milliseconds); tmstruct Pointer to a tm time structure containing information about the system date and time milliseconds Fractional portion of nearest second, in milliseconds Remarks ------- 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); handle Handle to open file 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 of a file or a path to a file. Although the _utimbuf structure contains a field for access time, only the modification time is set with systems 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 bitmap representing the currently available disk drives. #include <direct.h> unsigned long _getdrives (void); Return Value ------------ 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 <io.h> long _get_osfhandle (int filehandle); 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 <io.h> int _open_osfhandle (long osfhandle, int flags); osfhandle Operating system file handle 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 or more of the manifest constants defined in FCNTL.H and listed below. When two or more manifest constants are used to form the flags argument, the constants are combined with the bitwise-OR operator (|). 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. _O_RDONLY Opens file for reading only. _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: Notes on the _beginthread function >============= Windows NT handles the allocation of the stack when the _beginthread 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 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 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 58 ------- The __cdecl calling convention is the default for 32-bit targets. 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 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 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 following keywords are not supported by the 32-bit compiler: __near __far Page 170 -------- The following keywords are not supported for 32-bit targets: __fortran __pascal Page 175 -------- 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 the following form to specify an interrupt function: __interrupt declarator (The 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 inline function. 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 using the __interrupt attribute with the __saveregs attribute or with the __fastcall calling convention. The following example of a statement declares a function pointer that can be used to point to an interrupt handler: void (__interrupt __far *oldtime) (void); Page 176 --------- The following keywords are not supported in 32-bit targets: __loadds __saveregs Page 199 -------- 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. 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. Page 210 ------------- The following pragmas are supported for 16-bit targets only: #pragma check_pointer ([[{ on | off }]]) #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.) Page 211 --------- #pragma intrinsic (function1 [[, function2, ...]]) 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. 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 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. 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 -------- Long double and double are the same for the 32-bit compiler. ===================< Part 4: Notes on 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." The correct syntax for the /DEBUG option is: /DEBUG:[{MAPPED|NOTMAPPED},]{NONE|MINIMAL|PARTIAL|FULL} ====<Part 5: Notes on Building Multithreaded Applications and DLLs >==== Add the following information should Chapter 1 "Building Applications and DLLS" of the Programming Techniques manual. Building Multithreaded Programs ------------------------------- Building a multithreaded program is only slightly different from building a single-threaded program. Two additional parameters must be specified: 1. Compile with the /D_MT option. 2. Link with LIBCMT.LIB (multithread C run-time library) instead 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 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: 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 | unless the casted expression is enclosed in parentheses. For example: (char *) &i would become (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. Process Specifiers ------------------ The process-specifier syntax should be as follows: Symbol Description ------ ----------- |. The current process. |<number> The process number. |* All processes. Set Breakpoint (BP) ------------------- 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. 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. 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. 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<commandlist>, where <commandlist> 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<commandlist>, where <commandlist> specifies commands to execute before an exception riggers 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).

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.