os2sdk/os2doc/c500.txt - view

File: [OS/2 SDKs] / os2sdk / os2doc / c500.txt
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs
Thu Aug 9 12:25:13 2018 UTC (7 years, 9 months ago) by root
Branches: msft, MAIN
CVS tags: os2sdk-1987, HEAD

Microsoft OS/2 SDK 12-15-1987

(C) Copyright Microsoft Corporation, 1987 Microsoft(R) Operating System/2(R) Software Development Kit README.DOC This document contains information about Version 5.10 of the Microsoft C Optimizing Compiler and libraries for MS-DOS(R). The information contained in this document is more up to date than that in the printed manuals. As a result, where information in the manuals conflicts with information in this document, this document should be assumed to contain the correct information. REQUESTING ASSISTANCE FROM MICROSOFT If you need to contact Microsoft Product Support for assistance, the four-digit phone code for the Microsoft C Optimizing Compiler is 1222. OTHER ON-LINE DOCUMENTS For additional information, consult the following files: File Disk Contents ---- ---- -------- ERRMSG.DOC 1 New and changed error messages FPEXCEPT.DOC 1 Information about handling floating-point exceptions SETUP.DOC 1 Information about SETUP program \PATCH\README.DOC 2 DOS 3.2 patch information \STARTUP\README.DOC 3 Information about start-up source files \SOURCE\CFLOW.DOC 9 Information about CFLOW.C demo program INSTALLING AND BUILDING COMBINED LIBRARIES The LIBBUILD program creates combined C libraries. The Software Development Kit (SDK) does not include a SETUP program to install the compiler software. You will need to run the LIBBUILD program to create combined C libraries; otherwise, you must override library search records each time you link, by using the /NOD option. You can use LIBBUILD at any time to create more combined C libraries. To run LIBBUILD, type a command line of the following form: libbuild <mem> <fp> [gr] <dest> The arguments you type on the command line are described below. (These arguments may be either uppercase or lowercase.) Argument Description -------- ----------- <mem> Specifies the memory model. Type S for small, M for medium, C for compact, or L for large model. <fp> Specifies the floating-point math package. Type EM for the emulator, 87 for the 8087/80287/80387 package, or A for the alternate math package. [gr] Tells LIBBUILD whether or not you want the graphics- library package added to your library. Type GR if you do; otherwise, omit this argument. <dest> Directory where the initial (release-disk) .LIB files can be found. This is also the directory where your combined library will reside. Type a complete path name, including a drive designation. LIBBUILD asks if you want to build the combined library from components that reside on your hard disk or from components on the C disk set. If you specify the C disk set, LIBBUILD prompts you to insert the C 5.10 diskettes as needed. See Chapter 2 of the Microsoft C Optimizing Compiler User's Guide for more information about combined libraries. Compiling and Linking Combined Libraries ---------------------------------------- If you link with the CL driver, giving the /Lc or /Lp option, then CL will automatically link in the correct libraries. However, if you link separately by directly invoking LINK, then you must specify the name of your combined library in the LINK command line. If you link a protected mode program, then you need to specify both the name of the library, and the file DOSCALLS.LIB in the LINK command line. Examples: LINK sample.obj,,SLIBC3.LIB; LINK psample.obj,,MLIBCP.LIB+DOSCALLS.LIB; DIFFERENCES FROM VERSION 4.0 memcpy function ---------------- As noted in the Microsoft C Run-Time Library Reference, in Version 5.10 of Microsoft C the memcpy function does NOT ensure that overlapping regions are copied before they are overwritten. The memmove function should be used in cases where overlapping regions of memory must be copied. If you need to ensure that memcpy exhibits its original behavior, include the following #define directive in your source program: #define memcpy(d,s,n) memmove(d,s,n) MSC Driver ---------- The MSC compiler driver is not supported in Version 5.10 of the Microsoft C Optimizing Compiler. If you have batch files in which you use the MSC command, you can make the following global changes to the MSC command lines to ensure that your programs will be compiled the same: 1. Replace any MSC command with a CL command. 2. Replace the terminating semicolon on the MSC command line with the /c (compile-only) CL option. 3. If commas appear on the MSC command line: Replace the first comma (preceding the object-file name) with /Fo. (This step is not required if no file name follows the first comma; that is, if the comma is simply used as a placeholder.) Replace the second comma (preceding the source-listing-file name) with /Fs. Replace the third comma (preceding the object-listing-file name) with /Fc. Note that each of these options must appear immediately before the corresponding file name, with no intervening spaces. For example, to convert the MSC command line MSC test.c,,,; to a CL command line, follow these steps: 1. Replace the MSC command with a CL command, giving CL test.c,,,; 2. Replace the semicolon with the /c option, giving CL test.c,,src.lst, /c 3. Since no object-file name follows the first comma, you do not need to add an /Fo option. Replace the first comma with a blank and the second comma with an /Fs option, giving CL test.c /Fssrc.lst, /c 4. Replace the second comma with an /Fc option, giving CL test.c /Fssrc.lst /Fc /c Parameter-Type Lists in Function Prototypes ------------------------------------------- To conform with the ANSI standard, parameter-type lists in a function prototype must match the corresponding function definition in types and number of parameters and in the use of ellipsis terminators. Thus, code such as the following, which was legal in Version 4.0, generates warning messages in Version 5.10: int func(int,...); /* prototype: ellipsis terminator */ int func(x, y, z) /* definition: no ellipsis terminator */ int x, y, z; { } Function Prototypes/Definitions with Float Arguments ---------------------------------------------------- In Version 4.0 of Microsoft C, the following code fragment apparently specified a function that expected an argument of type float: void takesfloat(float); . . . void takesfloat(f) float f; { . . . } However, C as defined by Kernighan and Ritchie did not actually support float (single-precision) arithmetic (unless double and float were both single-precision). Therefore, the argument was assumed to be of type double in both cases and the compiler simply made the change. Under ANSI C, which specifically allows single-precision arithmetic, you can now pass single-precision actual arguments. However, a change made to support this feature in Version 5.10 of Microsoft C may require you to change existing code and recompile. When compiled with Version 5.10, the code fragment above causes a warning about a parameter mismatch between the prototype and the definition of the takesfloat function. ALTHOUGH THIS IS A WARNING RATHER THAN AN ERROR, THE RESULTING CODE WILL NOT WORK CORRECTLY. The problem is that ANSI C considers old- and new-style function definitions to be different. In particular, old-style definitions, such as the definition in the fragment above, are forced to widen type-float arguments to type double. Thus, the fragment generates the parameter-mismatch error because the prototype specifies a type-float argument and the definition specifies a type-double argument. However a new-style definition, such as void takesfloat(float f) { . . . } accepts the narrower argument type. If you have code of this kind that causes parameter-mismatch problems, you have two possible solutions, depending on whether the desired argument type is actually float or double: 1. If you want type-double arguments, then change argument types in the prototype to double. (Also change the definition if you use the /Zg option to generate the prototypes and you want to clarify the change for anyone who will read the code later.) 2. If you want type-float arguments, change the definition to use the new-style format illustrated above. If the code must be portable to other (non-ANSI) C compilers, you must use solution 1, since such compilers will not handle the new-style definitions. NEW AND CHANGED FEATURES The following notes describe important new and changed features in the Microsoft C Optimizing Compiler and in the software provided with the compiler. Start-Up Code Assembling Start-Up Files ------------------------- The start-up files provided with Version 5.10 of Microsoft C should be assembled with Version 4.0 or later of the Microsoft Macro Assembler (MASM). Open File Handles ----------------- Version 5.10 of Microsoft C supports more than 20 open file handles. This feature can be used beginning with DOS Version 3.3. Use the following procedure to set a larger upper limit on the number of file handles: 1. Edit the startup source file CRT0DAT.ASM, which is provided in the product, and change the line _NFILE_ = 20 so that _NFILE_ is set to the new upper limit. For example, for an upper limit of 40 files, change the line to read as follows: _NFILE_ = 40 2. Assemble the newly edited CRT0DAT.ASM. 3. Either explicitly link with this new CRT0DAT.OBJ, or use the new object file to replace the CRT0DAT.OBJ module in the C run-time library for the appropriate memory model. Note that this changes the number of integer file handles that can be used by or returned by functions such as open(), read(), write(), lseek(), and dup(). However, the number of "FILE *" standard I/O streams is not affected by this change; this number remains fixed at 20 in all cases. Mouse Driver If you will be using the Microsoft Mouse with the Microsoft CodeView debugger or the Microsoft QuickC Compiler, you must have Version 6.0 or later of the Microsoft Mouse. If you do not, use the version of the MOUSE.COM driver provided in Disk 9 of the package. Copy MOUSE.COM to the appropriate mouse directory. When you are ready to use the mouse, type mouse at the DOS command level. If you want to install the mouse driver automatically every time you reboot, insert the "mouse" command in your AUTOEXEC.BAT file. Note that in earlier releases of Microsoft C, both the MOUSE.SYS and the MOUSE.COM driver were provided. If you have been using an earlier version of the MOUSE.SYS driver, delete the following line from your CONFIG.SYS file: device=\<directory>\mouse.sys where <directory> is the directory where the earlier mouse driver resides. Compiler Function Prototypes ------------------- When a call to a function precedes its declaration or definition, the default function prototype that is constructed does not specify the number or type(s) of the arguments. Converting unsigned long to double ---------------------------------- Unsigned long items are now converted directly to type double. They are not first converted to type long. The interrupt Attribute ------------------------ The interrupt attribute can be applied to a function to tell the compiler that the function is an interrupt handler. This attribute tells the compiler to generate entry and exit sequences that are appropriate for an interrupt- handling function, including saving and restoring all registers and executing an IRET instruction to return. You can access the registers that are saved before the normal entry sequence by declaring the function with a parameter list containing a formal parameter for each register saved. The following example illustrates such a declaration: void interrupt cdecl far int_handler(es,ds,di,si,bp,sp,bx,dx,cx,ax, ip,cs,flags) unsigned es, ds, di, si, bp, sp, bx, dx, cx, ax, ip, cs, flags; { . . . } Note that the formal parameters must appear in the opposite order from the order in which the registers are pushed onto the stack; that is, the parameter representing the first register pushed must appear last in the list, and so on. Observe the following precautions when using interrupt functions: 1. In general, it is not a good idea to call standard-library functions, especially functions that rely on DOS INT 21H system calls, within an interrupt function. (Functions that rely on INT 21H calls include stream- and low-level-I/O functions.) Functions that do not rely on INT 21H, such as string-handling functions, may be safe to use. Before using a standard-library function in an interrupt function, be sure that you are familiar with the library function and what it does. 2. If you change any of the parameters of an interrupt function while the function is executing, the corresponding register will contain the changed value when the function returns. For example, void interrupt cdecl far int_handler(es,ds,di,si,bp,sp,bx,dx,cx,ax, ip,cs,flags) unsigned es, ds, di, si, bp, sp, bx, dx, cx, ax,ip,cs,flags; { . . . ax = -1; . . . } causes the AX register to contain -1 when the int_handler function returns. In general, it is not a good idea to modify the values of the parameters representing the IP, CS, and flags registers in interrupt functions. Limit on Nested Include Files ----------------------------- The limit given in Section E.3.4 for nested include files refers to the total number of open files that the compiler allows. Since the original source file counts as an open file, a total of nine files (in addition to the original file) may have #include directives. CL Driver C1L.EXE ------- An alternate form of compiler pass 1 named C1L.EXE is provided for compiling programs that get "out of near/far heap space" errors. Invoke C1L.EXE by entering the CL command with the /B1 <path> option as illustrated below: cl /B1 <path>\c1l.exe <sourcefile>.c where <path> is the path (including drive and directory) where C1L.EXE resides and <sourcefile> is the name of the C source file you are compiling. Specifying Overlays ------------------- You can now specify overlays on the CL command line. Simply enclose the names of the overlay source or object files in parentheses. For example, if you enter the command line cl src_1.c (src_2.c obj_1) obj_2 then the SRC_2.OBJ and OBJ_1.OBJ modules are overlays in the SRC_1.EXE file and are read into memory from disk only if and when they are needed. Expanding Wild-Card Arguments ---------------------------- If you are linking your program with the SETARGV.OBJ file to expand wild-card arguments, you must specify the /NOE linker option, which tells the linker not to use the extended dictionary in searching libraries. (See the description of the /NOE option under the heading "Linker Options" later in this document.) The correct form for compiling a program WILDCARD.C that uses wild-card expansion is shown below: CL wildcard.c \lib\setargv /link /NOE or QCL wildcard.c \lib\setargv /link /NOE This procedure is not necessary if you have used LIB to place the wild-card expansion routines in the standard C combined library (mLIBCf.LIB). /Fa Option ---------- You must use Version 5.10 of the Microsoft Macro Assembler to assemble output from the /Fa option. Earlier versions of the Macro Assembler do not support the new communal variables generated by the /Fa option. /D Option --------- Note that the /Didentifier= and /Didentifier=string forms of this option cannot be defined in the CL environment variable. This is because the SET command does not accept the equal sign (=), which is a special character in the environment. Predefined Identifiers ---------------------- The compiler now defines the following new identifiers: Identifier Function ---------- -------- M_I8086 Identifies the target processor as an 8086. Defined by default or when the /G0 option is given explicitly. M_I286 Identifies the target processor as an 80286. Defined when the /G1 or /G2 option is given. You can still give the same number of /D options on the CL command line. Note that the /u option no longer removes the definition of the predefined identifier M_I86mM, which identifies the memory model. You can use the /U option to remove the definition of M_I86mM; however, if you do, the NULL constant will not be defined automatically in the program (since the definition of NULL in the stdio.h and stddef.h files depends on the memory model in use). If you compile a program with the /UM_I86mM option, be sure to define NULL explicitly if you use it in the program. /J Option --------- When the /J option is given on the CL command line, a new predefined identifier, _CHAR_UNSIGNED, is defined. This identifier is used with #ifndef in the limits.h file to define the range of the default char type. Note that compiling with /J reduces by 1 the number of constant and macro definitions that can be given on the command line. /Oi Option/#pragma intrinsic ---------------------------- In addition to the functions listed in Section 3.3.13 under "Generating Intrinsic Functions," the following functions have intrinsic forms: Floating-point functions: ------------------------- pow, log, log10, exp sin, cos, tan asin, acos, atan, atan2 sinh, cosh, tanh sqrt fabs, fmod Other functions: ---------------- _enable, _disable inpw, outpw If you use intrinsic forms of the floating-point functions listed above (that is, if you compile with the /Oi option or specify any of the functions in an intrinsic pragma), you cannot link with an alternate-math library (mLIBCA.LIB). Any attempt to do so will cause unresolved-external errors at link time. Note that this restriction applies even if you link with an alternate-math library after compiling with the /FPc or /FPc87 option. If you want to compile with /Oi (to use the intrinsic forms of non-floating-point functions) and then link with an alternate-math library, specify any floating-point functions that appear in a program in a function pragma. /Ox Option ---------- For Version 5.10 of Microsoft C, the /Ox option performs more optimizations than in previous versions, including loop optimizations and generation of intrinsics for certain library functions. If you have problems compiling programs with the /Ox (maximum optimization) option, try breaking the option down to its component parts and removing either the "i" (generate intrinsics) or the "l" (perform loop optimizations) from the option string; then try recompiling the program. For Version 5.10, the "expanded" version of the /Ox option is /Oailt /Gs Disabling Unsafe Loop Optimizations: The /On Option ---------------------------------------------------- The new /On option disables potentially unsafe loop optimizations in programs compiled with the /Ol or /Ox option. When the /On option is used, the compiler does not perform the following types of loop optimizations: o Hoisting division operations out of loops. This type of optimization can cause problems in code such as the following: for (i=0; i<=99; i+=10) { if (denom != 0) { array[i] += (numer/denom); printf("%f ", array[i]); } } When loop optimizations are turned on, the compiler knows that numer/denom does not change within the loop. Therefore, it calculates numer/denom only once: before the start of the loop and before the if statement within the loop can check for division by zero. Compiling with the /On option helps to avoid "divide by zero" errors that may result from code like that shown above. o Loop-induction optimizations. When loop optimizations are turned on, this code int larray[400]; unsigned char k, top_val, inc_val, var; for( k = 3; k < top_val; k += 8 ) { larray[k*4] = k*4; } is optimized to code such as the following: unsigned char t; for( t = 12; t < top_val*4; t += 32 ) { larray[t] = t; } If the loop-control variable top_val in the original code is 64, the induction expression top_val*4 overflows the limit for type unsigned char, and the loop never terminates. To avoid this problem, the code is optimized as shown below when the /On option is used: unsigned char t; for( t = 12, k=3; k < top_val; k += 8, t += 32 ) { larray[t] = t; } The /On option can be used to solve similar overflow problems in cases where induction variables result from array or pointer references and the offset part of the address is close to wrapping. In general, you may want to compile with /On if your programs use arrays that are larger than 32K, or if divide-by-zero or infinite-loop errors occur in programs compiled with the /Ol option. /Za and /Ze Options ------------------- Two new Microsoft extensions have been added to the list in Section 3.3.14: (1) Casting data pointers to function pointers, as in the following example: int *ip; int foo(); ((int (*)())ip)(); (2) Casting function pointers to data pointers, as in the following example: int *ip; int foo(); ip = (int *)foo; Casts like these generate error C2068, "illegal cast," in programs compiled with the /Za option. Otherwise, they generate warning C4074, "non standard extension used," at warning level 3 or higher. The ANSI-standard way to cast from data pointers to function pointers, and from function pointers to data pointers, is to (1) Cast to an integral type (int or long depending on pointer size) (2) Cast to the final pointer type For example, in a small-model program, the examples above could be rewritten as follows to conform to the ANSI convention: ip = (int *)(int)foo; /* cast function pointer to data pointer */ ((int (*)())(int)ip)(); /* cast data pointer to function pointer */ Examples like those above work correctly whether or not the program is compiled with the /Za option. Segment Setup for Memory Models ------------------------------- The primary segments of a C program are ordered in memory as shown below, from the highest memory location to the lowest: Segment Contents ------- -------- (Heap) Area of unallocated memory that is available for dynamic allocation by the program. Its size varies, depending on the program's other storage requirements. STACK User's stack, used for all local data items _BSS All uninitialized static data items except those that are explicitly declared as far or huge. c_common Uninitialized global data items for small- and medium-model programs. In compact- or large-model programs, this type of data item is placed in a data segment with class FAR\_BSS. CONST Read-only constants, including floating-point constants, string literals, and segment values for data items declared far or huge or forced into their own segments by use of the /Gt option. _DATA Default data segment: initialized global and static data except data explicitly declared far or huge, or data forced into different segments by use of the /Gt option. NULL Special-purpose segment at the beginning of DGROUP that contains the compiler copyright notice. This segment is checked before and after the program executes. If its contents change during program execution, the program has written to this area, usually by an inadvertent assignment through a null pointer. The error message "Null pointer assignment" appears to warn of this error. (Data segments) Initialized static and global data items, placed in their own segments with class name FAR_DATA, allowing the linker to combine these items so that they precede DGROUP. Uninitialized static and global far data items are placed in segments that have class FAR_BSS, allowing the linker to place these items between the _TEXT segment(s) and DGROUP. Uninitialized huge items are placed in segments with class FAR_DATA. In large- and huge-model programs, global uninitialized data are treated as though declared far (unless specifically declared near) and given class FAR_BSS. _TEXT In small and compact model, segment containing code for all modules. In medium, large, and huge models, each module has its own text segment with the name of the module plus the suffix _TEXT. When you look at a map file produced by linking a C program, you may notice other segments in addition to the names listed below. These additional segments have specialized uses for Microsoft languages and should not be used by other programs. alloc_text Pragma ----------------- No more than 10 alloc_text pragmas may appear in the same compilation unit. The alloc_text pragma MUST appear after the declarations of any functions given in the pragma. Functions given in an alloc_text pragma may be implicitly near (because the small or compact memory model is used) or explicitly near (declared with the near keyword), provided that they are called only by functions in the same segment. Functions referenced in an alloc_text pragma should be defined in the same module as the pragma. If this is not done, and an undefined function is later compiled into a different text segment, the error may or may not be caught. Although the program will usually run correctly, the function will not be allocated in the intended segments. The following example shows code that may cause these problems: Module 1 -------- #pragma alloc_text(SEG1, foo, bar) int foo(int i) { i = bar(10); } Module 2 -------- int bar(int i) { return(i*i); } In the example above, the definitions of the functions foo and bar should appear in the same module to avoid problems. Include Files float.h ------- For conformance with the ANSI C standard, the following constants defined in the include file float.h refer to a base-2 exponent in Version 5.10 of Microsoft C: DBL_MIN_EXP DBL_MAX_EXP FLT_MIN_EXP FLT_MAX_EXP LDBL_MIN_EXP LDBL_MAX_EXP In Version 4.0, these constants refer to a base-10 exponent. The base-10 versions of these constants are now named DBL_MIN_10_EXP, DBL_MAX_10_EXP, and so on. graph.h ------- See the current version of the file for the most recent constant names and definitions related to graphics functions. Graphics-Library Functions Graphics Functions ------------------ Several new elements have been added to the graph.h file, including elements in the videoconfig structure and manifest constants that allow you to test the adapter and monitor information in the videoconfig structure. Colors in Graphics and Text Modes --------------------------------- In a color text mode (such as _TEXTC80), _setbkcolor accepts (and _getbkcolor returns) an attribute, or pixel value. The value for the default colors is given by the table in Section 4.4 of the QuickC Programmer's Guide. For example, _setbkcolor(2L) sets the background color to pixel value 2. The actual color displayed depends on the palette mapping for pixel value 2. The default is green in a color text mode. In a color graphics mode (such as _ERESCOLOR), _setbkcolor accepts (and _getbkcolor returns) a color (as used in _remappalette). The value for the background color is given by the manifest constants defined in the graph.h include file. For example, _setbkcolor(_GREEN) sets the background color in a graphics mode to green. These manifest constants are provided as a convenience in defining and manipulating the most common colors. The actual range of colors is, in general, much greater. The function _setcolor accepts an int value as an argument. It is an attribute or pixel value. In general, whenever an argument is long, it refers to a color, and whenever it is short, it refers to an attribute or pixel value. The two exceptions are _setbkcolor and _getbkcolor described above. Other Library Functions The following notes refer to the reference pages in the Microsoft C Run-Time Library Reference. _amblksiz --------- In Chapter 3 of the Library Reference, _amblksiz should be defined with type unsigned int rather than type int. atof, strtod ------------ In compact- and large-model programs, the string argument to these functions can be a maximum of 100 characters in length. _bios_keybrd, _bios_printer --------------------------- The return value from the functions _bios_keybrd and _bios_printer should be unsigned int. cputs, fputs, puts ------------------ The return value from the cputs, fputs, or puts function is 0 if the function returns normally or a nonzero value if an error occurs. ctime, gmtime, localtime, mktime -------------------------------- Calls to the mktime and ctime functions modify the single statically allocated buffer used by gmtime and localtime. Thus, a mktime or ctime call destroys the results of any previous localtime or gmtime call. The parameter to the localtime function should be declared as const time_t *time; The documentation of the TZ environment variable should appear in the description of the gmtime function rather than the localtime function. _dos_findfirst, _dos_findnext ----------------------------- If the attributes argument to either of these functions is _A_RDONLY, _A_HIDDEN, _A_SYSTEM, or _A_SUBDIR, the function also returns any "normal" files (that is, any files that are not read-only, hidden, or system files or subdirectories) that match the path argument. _dos_open --------- The argument to the _dos_open function should be *handle. Also, the constant O_RDONLY is defined in the fcntl.h header file, which should be included if O_RDONLY is used as the mode argument. exec*, spawn* functions ----------------------- Because of a bug in DOS Versions 2.0 and 2.1, child processes generated by the exec family of routines (or by the equivalent spawn routines with the P_OVERLAY argument) may cause fatal system errors when they exit. If you are running under these versions of DOS, you must upgrade to DOS Version 3.0 to use these functions in your programs. fclose ------ This function takes one parameter, which is declared as int fclose(stream); FILE *stream; FP_OFF, FP_SEG -------------- The argument to these functions should be declared as a void far pointer rather than a char far pointer. In models that use near data pointers (small and medium), the FP_SEG and FP_OFF macros work only if the far-pointer argument is stored in the default data segment. If the far pointer is stored in a far data segment, the macros will not work correctly. fopen ----- The parameters should be declared as const char *path; const char *type; _fpreset -------- In the example, the second to last line should read longjmp(mark, -1); fwrite ------ The first parameter should be declared as const void *buffer; int86x ------ Under "Return Values," the second paragraph should refer to the cflag field in the outregs union. malloc, _fmalloc, _nmalloc -------------------------- The second paragraph under "Return Value" should read, "To get a pointer to a type other than void, use a type cast on the return value." In the entry for malloc, delete the sentence that reads, "The resulting pointer can be passed to the realloc function to adjust the size at any time." To ensure compatibility a recent change to the ANSI C standard, malloc(0) now returns a non-null pointer. In this regard, malloc works the same as it did under Version 4.0 of Microsoft C. memccpy ------- The dest and src arguments should have type void * rather than const void *. memchr ------ The c argument should have type int rather than size_t, and the count argument should have type size_t rather than unsigned. memmove ------- This function should be added to the list of functions (in Section 2.12) that support the use of huge pointers. This function returns the value of the dest parameter, not the src parameter. open and sopen -------------- Certain calls to the open or sopen function may set the global variable errno to EINVAL. For example, a call to sopen with an invalid shflag argument (for example, 6) or a call to open with an invalid oflag argument (for example, O_RDWR|O_WRONLY) return a value of -1 and set errno to EINVAL. outpw ----- The return value from this function should have type unsigned rather than type void. printf ------ In Table R.3, the "Default" column for the "f" format type should read as follows: Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed. In the same table (R.3), in the "Default" column for the "g" format type, the statement All significant digits are printed. should read Six significant digits are printed, less any trailing zeros that are truncated. realloc ------- First paragraph under "Return Value" should read, "The realloc function returns a void pointer to the reallocated memory block." Third paragraph should read, "To get a pointer to a type other than void, use a type cast on the return value." scanf ----- The "D," "O," "X," and "I" type characters, which represented long-integer input fields, are no longer supported. setvbuf ------- The setvbuf function can be used for an open stream only if that stream has NOT yet been read from or written to. strlen ------ The string parameter should have type const char * rather than char *. tmpnam ------ The description of this function under "Summary" should read "Create temporary file in the directory defined by P-tmpdir." Also, the sentence beginning "The tmpnam function uses malloc to allocate space..." actually describes the tempnam function rather than the tmpnam function. ungetc ------ In the first paragraph under "Description," the second sentence should read, "The stream must be open for reading." Microsoft CodeView Debugger CVPACK Utility -------------- A new utility named CVPACK.EXE is provided with this version of Microsoft C. CVPACK can be used to pack the debug information in an executable file that has been compiled with the /Zi option or linked with the /CO option. Packing information allows CodeView to load larger programs without running out of memory. The CVPACK utility has the following command line: CVPACK [/p] <exefile> If you invoke CVPACK without the /p option, the packed debug information is appended to the executable file, so that the file is larger. CodeView uses only the packed debug information. If you invoke CVPACK with the /p option, unused debug information is discarded, and the packed information is written to the executable file, resulting in a smaller executable file. Running CVPACK without the /p option is slightly faster than with the option. To use packed debugging information, you must use Version 2.10 or later of the CodeView debugger. Compiling BASIC Programs for CodeView Debugger ---------------------------------------------- To compile BASIC programs for use with the CodeView debugger, specify the /Zi option rather than the /D option. Expression Evaluator for BASIC Programs --------------------------------------- In the BASIC expression evaluator, "+" is not supported for string concatenation. Microsoft Pascal Programs ------------------------- Microsoft Pascal programs cannot be debugged with the CodeView debugger for this release. The Pascal example on pg. 61 should read PAS1 /Z TEST; rather than PAS1 /Zi TEST; Exit Codes for Utilities The exit codes for LINK and the utilities in the Microsoft CodeView and Utilities Guide should appear as follows: LINK ---- Code Meaning 0 No error. 2 Program error--something was wrong with the commands or files input to the linker. 4 System error. The linker - ran out of space on output files - was unable to reopen the temporary file - experienced an internal error - was interrupted by the user LIB, EXEPACK, EXEMOD, MAKE, and SETENV --------------------------------------- Code Meaning 0 No error. 2 Program error--something was wrong with the commands or files input to the utility. 4 System error. The utility ran out of memory, was interrupted by the user, or experienced an internal error. Microsoft LINK Linker Linker Options -------------- The following new options have been added to the linker: /NOE[XTDICTIONARY] Tells the linker not to use the extended dictionary in searching libraries. Use this option if you redefine a standard-library routine (such as _setargv or _nullcheck) in a program module, or if you get linker error L2044 during linking (see the section titled "Linker Errors" later in this file for more information). This option may slow the linking process on some programs. The "extended dictionary" is a block of data telling the linker about interlibrary dependencies; that is, for each module in the library, the extended dictionary tells the linker which other modules in the same library are also required. Although the linker can process libraries faster with this information, it has trouble in processing if you redefine symbols (such as the names of standard-library routines) that otherwise would have been defined in one of the modules described in the extended dictionary. Overlay Restrictions -------------------- You cannot use long jumps (using the longjmp library function) or indirect calls (through a function pointer) to pass control to an overlay. When a function is called through a pointer, the called function must be in the same overlay or in the root. MAKE Program-Maintenance Utility Backslash (\) As Continuation Character --------------------------------------- Note that MAKE considers a backslash immediately followed by a new-line character to be a continuation character. When it finds this combination in a description file, MAKE concatenates the line immediately following the combination with the line where the combination appears. If you define a macro that ends in a backslash, make sure that you put a space after the terminating backslash. For example, if you want to define macros for the path C:\SRC\BIN and C:\SRC\LIB, you must use the format illustrated below: BINPATH=C:\SRC\BIN\<space><new-line> LIBPATH=C:\SRC\LIB\<space><new-line> To illustrate the problems that can result if you do not put a space before the new-line character, assume that the macros above appear as shown below instead: BINPATH=C:\SRC\BIN\<new-line> LIBPATH=C:\SRC\LIB\<new-line> Because a new-line character appears immediately after the backslash at the end of the first macro, MAKE assumes that you are defining the single macro shown below: BINPATH=C:\SRC\BIN\LIBPATH=C:\SRC\LIB\ New /X Option ------------- The new /X option has the following syntax: /X <filename> This option redirects errors output by MAKE, or by any programs that MAKE runs, to the given file. If the <filename> argument is a dash (-), MAKE redirects error output to the standard output device. You may send both error output and standard output to the same file by combining the "/X -" form of this option with DOS redirection, as in the following example: MAKE /X - project.mak >make.log DO NOT specify the same filename to /X as the file following the redirection symbol (>). ERROUT Standard-Error Redirection Utility The ERROUT utility does not accept batch files. To redirect standard-error output from a batch file, you must enter a command of the following form: ERROUT COMMAND /c <batchcommand> If no /f option is given, then ERROUT redirects standard-error output to the standard-output device. Mixed-Language Programming C Naming Conventions -------------------- C recognizes the first 31 characters of a symbolic name. Accessing Parameters on the Stack --------------------------------- In Section 6.1.5 of the Mixed Languages Programming Guide, the instruction mov bx, [bp+6] loads the argument into the BX register rather than the BP register. Setting Up Calls to High-Level Languages ---------------------------------------- Section 6.6 of the Mixed Languages Programming Guide gives instructions for setting up a call to a high-level language from assembly language. Before you execute a call to a BASIC, Pascal, or FORTRAN routine, remember to declare an additional parameter if the return value is noninteger. This additional parameter must contain the offset address of the return value, for which you must allocate room within the stack segment (normally DGROUP, the same as the default data segment). BASIC Return Values ------------------- BASIC functions use the FORTRAN/Pascal conventions, rather than the C conventions, for receiving return values. Passing C Strings to BASIC -------------------------- In Section 8.4.3 of the Mixed Languages Programming Guide, in the example illustrating how C passes string arguments to BASIC functions, the sd_len field should be declared as shown below: int sd_len BASIC Array Declarations ------------------------ The sample BASIC array declaration in Table 9.1 should read DIM x(c-1, r-1) Linking with MASM Files ----------------------- If you are linking C modules with modules created by the Microsoft Macro Assembler (MASM), either assemble the MASM modules with the /MX option to preserve case sensitivity in these modules, or use the LINK command to link in a separate step and do NOT specify the /NOI linker option. Linking Mixed-Language Programs ------------------------------- This section explains how to link Microsoft C modules with modules created by other Microsoft languages. The discussions assume that you are linking with Version 3.61 of the Microsoft Overlay Linker, LINK. (This is the version of LINK provided with Version 5.10 of the Microsoft C Optimizing Compiler.) 1. C 5.10 / FORTRAN 4.0 To link object modules created using the Microsoft C Compiler, Version 5.10, with those created using Microsoft FORTRAN Version 4.00 or 4.01, you must create a special version of each of the FORTRAN libraries you intend to use. Create one FORTRAN library to correspond to each C library you are using; that is, create a FORTRAN library that supports the same memory-model/math- option combination as the corresponding C library. Be sure that you choose the "C compatibility" option when you build each FORTRAN library. Next, use the SETUP program provided with Microsoft C, Version 5.10, to create all the combined C 5.10 libraries that you will need. SETUP creates a subdirectory named \MIXLANG under the C 5.10 base directory. Place the FORTRAN libraries you have created in this directory. Then make the \MIXLANG directory the current directory and run F4COMPAT, which brings the FORTRAN libraries up to date and makes them compatible with C 5.10. F4COMPAT takes two arguments: one specifying the memory model and one specifying the floating-point-math package that the library supports. For example, F4COMPAT L 7 makes a C 5.10-compatible version of LLIBFOR7.LIB. Once the libraries are built, use the following LINK command line to link the appropriate C library with the FORTRAN library that you converted in the previous example: LINK objs,,,LLIBC7.LIB LLIBFOR7.LIB /NOE; The LINK command lines for other memory models and floating-point math packages are similar. Note that the C library must be given first on the command line. Specify the \MIXLANG subdirectory either in the LIB environment variable or on the LINK command line so that the linker can find the FORTRAN library. Use only large- and medium-model libraries. Huge-model programs use large-model libraries. 2. C 5.10 / QuickBASIC 4.0 To create a program whose components are built using Microsoft C 5.10 and Microsoft QuickBASIC 4.0, you should compile your C source files using the /AL option (large memory model). The QuickBASIC source files can be compiled either with or without the /o option of the BC command, depending on whether you want to use the BCOM40.LIB or BRUN40.LIB run-time library. The LLIBCE.LIB version of the C library is recommended. The main program must be written in BASIC, and the BASIC run-time library must be given before the C library on the LINK command line. Two recommended compile-and-link sequences are (a) CL /AL /c cmodule.c BC /o bmain.bas; LINK bmain cmodule,,,BCOM40.LIB LLIBCE.LIB /NOE; (b) CL /AL /c cmodule.c BC bmain.bas; LINK bmain cmodule,,,BRUN40.LIB LLIBCE.LIB /NOE; 3. C 5.10 / Pascal 4.0 To create a program whose components are built using Microsoft C 5.10 and Microsoft Pascal 4.0, compile your C source files with the /AL option (large memory model). When you give the run-time libraries on the LINK command line, use a single math package, and use only large-model C libraries. The three recommended combinations of libraries are (a) LINK objs,,,LLIBC7.LIB LIBPAS7.LIB /NOE; (b) LINK objs,,,LLIBCE.LIB LIBPASE.LIB /NOE; (c) LINK objs,,,LLIBCA.LIB LIBPASA.LIB /NOE; LIBRARY MANAGER (LIB) There is a new option for LIB: /NOIGNORECASE (abbreviated as /N). This option tells LIB to not ignore case when comparing symbols. names. By default, LIB ignores case. Multiple symbols which are the same except for case can be put in the same library. For example: "_Open" and "_open". Normally you could not add both these symbols to the same library. Note that if a library is built with /NOI, the library is internally "marked" to indicate /NOI. All libraries built with earlier versions of LIB are not marked. If you combine multiple libraries, and any one of them is marked /NOI, then /NOI is assumed for the output library. In addition we just added a new option, /IGNORECASE (abbr. /I) which is completely analagous to /NOIGNORECASE. /I is the default. The only reason to use it would be if you had an existing library marked /NOI which you wanted to combine with other libraries which were not marked, and have the output library be not marked. If you didn't use /IGNORECASE, the output would be marked /NOI (see above).

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