![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to c500.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [OS/2 SDKs] / os2sdk / os2doc|
Return to c500.txt CVS log | Up to [OS/2 SDKs] / os2sdk / os2doc |
1.1 root 1: (C) Copyright Microsoft Corporation, 1987
2: Microsoft(R) Operating System/2(R) Software Development Kit
3: README.DOC
4:
5:
6: This document contains information about Version 5.10 of the Microsoft C
7: Optimizing Compiler and libraries for MS-DOS(R). The information contained
8: in this document is more up to date than that in the printed manuals.
9: As a result, where information in the manuals conflicts with information in
10: this document, this document should be assumed to contain the correct
11: information.
12:
13: REQUESTING ASSISTANCE FROM MICROSOFT
14:
15: If you need to contact Microsoft Product Support for assistance, the
16: four-digit phone code for the Microsoft C Optimizing Compiler is 1222.
17:
18:
19: OTHER ON-LINE DOCUMENTS
20:
21: For additional information, consult the following files:
22:
23: File Disk Contents
24: ---- ---- --------
25: ERRMSG.DOC 1 New and changed error messages
26: FPEXCEPT.DOC 1 Information about handling
27: floating-point exceptions
28: SETUP.DOC 1 Information about SETUP program
29:
30: \PATCH\README.DOC 2 DOS 3.2 patch information
31:
32: \STARTUP\README.DOC 3 Information about start-up source files
33:
34: \SOURCE\CFLOW.DOC 9 Information about CFLOW.C demo program
35:
36:
37:
38: INSTALLING AND BUILDING COMBINED LIBRARIES
39:
40: The LIBBUILD program creates combined C libraries. The Software Development
41: Kit (SDK) does not include a SETUP program to install the compiler software.
42: You will need to run the LIBBUILD program to create combined C libraries;
43: otherwise, you must override library search records each time you link,
44: by using the /NOD option. You can use LIBBUILD at any time to create
45: more combined C libraries.
46:
47: To run LIBBUILD, type a command line of the following form:
48:
49: libbuild <mem> <fp> [gr] <dest>
50:
51: The arguments you type on the command line are described below. (These
52: arguments may be either uppercase or lowercase.)
53:
54: Argument Description
55: -------- -----------
56: <mem> Specifies the memory model. Type S for small, M for
57: medium, C for compact, or L for large model.
58:
59: <fp> Specifies the floating-point math package. Type EM for
60: the emulator, 87 for the 8087/80287/80387 package, or
61: A for the alternate math package.
62:
63: [gr] Tells LIBBUILD whether or not you want the graphics-
64: library package added to your library. Type GR if you
65: do; otherwise, omit this argument.
66:
67: <dest> Directory where the initial (release-disk) .LIB
68: files can be found. This is also the directory
69: where your combined library will reside. Type a
70: complete path name, including a drive designation.
71:
72: LIBBUILD asks if you want to build the combined library from components
73: that reside on your hard disk or from components on the C disk set.
74: If you specify the C disk set, LIBBUILD prompts you to insert
75: the C 5.10 diskettes as needed.
76:
77: See Chapter 2 of the Microsoft C Optimizing Compiler User's Guide for more
78: information about combined libraries.
79:
80: Compiling and Linking Combined Libraries
81: ----------------------------------------
82: If you link with the CL driver, giving the /Lc or /Lp option, then CL will
83: automatically link in the correct libraries. However, if you link separately
84: by directly invoking LINK, then you must specify the name of your combined
85: library in the LINK command line. If you link a protected mode program,
86: then you need to specify both the name of the library, and the file
87: DOSCALLS.LIB in the LINK command line. Examples:
88:
89: LINK sample.obj,,SLIBC3.LIB;
90: LINK psample.obj,,MLIBCP.LIB+DOSCALLS.LIB;
91:
92:
93:
94: DIFFERENCES FROM VERSION 4.0
95:
96: memcpy function
97: ----------------
98: As noted in the Microsoft C Run-Time Library Reference, in Version 5.10 of
99: Microsoft C the memcpy function does NOT ensure that overlapping regions
100: are copied before they are overwritten. The memmove function should be
101: used in cases where overlapping regions of memory must be copied.
102:
103: If you need to ensure that memcpy exhibits its original behavior, include the
104: following #define directive in your source program:
105:
106: #define memcpy(d,s,n) memmove(d,s,n)
107:
108: MSC Driver
109: ----------
110: The MSC compiler driver is not supported in Version 5.10 of the Microsoft C
111: Optimizing Compiler. If you have batch files in which you use the MSC
112: command, you can make the following global changes to the MSC command lines
113: to ensure that your programs will be compiled the same:
114:
115: 1. Replace any MSC command with a CL command.
116:
117: 2. Replace the terminating semicolon on the MSC command line with the /c
118: (compile-only) CL option.
119:
120: 3. If commas appear on the MSC command line:
121:
122: Replace the first comma (preceding the object-file name) with /Fo.
123: (This step is not required if no file name follows the first comma;
124: that is, if the comma is simply used as a placeholder.)
125:
126: Replace the second comma (preceding the source-listing-file name)
127: with /Fs.
128:
129: Replace the third comma (preceding the object-listing-file name)
130: with /Fc.
131:
132: Note that each of these options must appear immediately before the
133: corresponding file name, with no intervening spaces.
134:
135: For example, to convert the MSC command line
136:
137: MSC test.c,,,;
138:
139: to a CL command line, follow these steps:
140:
141: 1. Replace the MSC command with a CL command, giving
142:
143: CL test.c,,,;
144:
145: 2. Replace the semicolon with the /c option, giving
146:
147: CL test.c,,src.lst, /c
148:
149: 3. Since no object-file name follows the first comma, you do not need to
150: add an /Fo option. Replace the first comma with a blank and the second
151: comma with an /Fs option, giving
152:
153: CL test.c /Fssrc.lst, /c
154:
155: 4. Replace the second comma with an /Fc option, giving
156:
157: CL test.c /Fssrc.lst /Fc /c
158:
159: Parameter-Type Lists in Function Prototypes
160: -------------------------------------------
161: To conform with the ANSI standard, parameter-type lists in a function prototype
162: must match the corresponding function definition in types and number of
163: parameters and in the use of ellipsis terminators. Thus, code such as the
164: following, which was legal in Version 4.0, generates warning messages in
165: Version 5.10:
166:
167: int func(int,...); /* prototype: ellipsis terminator */
168:
169: int func(x, y, z) /* definition: no ellipsis terminator */
170: int x, y, z;
171: {
172: }
173:
174: Function Prototypes/Definitions with Float Arguments
175: ----------------------------------------------------
176: In Version 4.0 of Microsoft C, the following code fragment apparently specified
177: a function that expected an argument of type float:
178:
179: void takesfloat(float);
180: .
181: .
182: .
183: void takesfloat(f)
184: float f;
185: {
186: .
187: .
188: .
189: }
190:
191: However, C as defined by Kernighan and Ritchie did not actually support float
192: (single-precision) arithmetic (unless double and float were both
193: single-precision). Therefore, the argument was assumed to be of type double
194: in both cases and the compiler simply made the change.
195:
196: Under ANSI C, which specifically allows single-precision arithmetic,
197: you can now pass single-precision actual arguments. However, a change
198: made to support this feature in Version 5.10 of Microsoft C may require
199: you to change existing code and recompile.
200:
201: When compiled with Version 5.10, the code fragment above causes a warning
202: about a parameter mismatch between the prototype and the definition of the
203: takesfloat function. ALTHOUGH THIS IS A WARNING RATHER THAN AN ERROR, THE
204: RESULTING CODE WILL NOT WORK CORRECTLY.
205:
206: The problem is that ANSI C considers old- and new-style function definitions
207: to be different. In particular, old-style definitions, such as the definition
208: in the fragment above, are forced to widen type-float arguments to type
209: double. Thus, the fragment generates the parameter-mismatch error because
210: the prototype specifies a type-float argument and the definition specifies a
211: type-double argument. However a new-style definition, such as
212:
213: void takesfloat(float f)
214: {
215: .
216: .
217: .
218: }
219:
220: accepts the narrower argument type.
221:
222: If you have code of this kind that causes parameter-mismatch problems,
223: you have two possible solutions, depending on whether the desired
224: argument type is actually float or double:
225:
226: 1. If you want type-double arguments, then change argument types in the
227: prototype to double. (Also change the definition if you use the /Zg option
228: to generate the prototypes and you want to clarify the change for anyone
229: who will read the code later.)
230:
231: 2. If you want type-float arguments, change the definition to use the
232: new-style format illustrated above.
233:
234: If the code must be portable to other (non-ANSI) C compilers, you must use
235: solution 1, since such compilers will not handle the new-style definitions.
236:
237:
238: NEW AND CHANGED FEATURES
239:
240: The following notes describe important new and changed features in the
241: Microsoft C Optimizing Compiler and in the software provided with the compiler.
242:
243:
244: Start-Up Code
245:
246: Assembling Start-Up Files
247: -------------------------
248: The start-up files provided with Version 5.10 of Microsoft C should be assembled
249: with Version 4.0 or later of the Microsoft Macro Assembler (MASM).
250:
251: Open File Handles
252: -----------------
253: Version 5.10 of Microsoft C supports more than 20 open file handles. This
254: feature can be used beginning with DOS Version 3.3.
255:
256: Use the following procedure to set a larger upper limit on the number of
257: file handles:
258:
259: 1. Edit the startup source file CRT0DAT.ASM, which is provided in
260: the product, and change the line
261:
262: _NFILE_ = 20
263:
264: so that _NFILE_ is set to the new upper limit. For example, for an
265: upper limit of 40 files, change the line to read as follows:
266:
267: _NFILE_ = 40
268:
269: 2. Assemble the newly edited CRT0DAT.ASM.
270:
271: 3. Either explicitly link with this new CRT0DAT.OBJ, or use the new object
272: file to replace the CRT0DAT.OBJ module in the C run-time library for
273: the appropriate memory model.
274:
275: Note that this changes the number of integer file handles that can be used by
276: or returned by functions such as open(), read(), write(), lseek(), and dup().
277: However, the number of "FILE *" standard I/O streams is not affected by
278: this change; this number remains fixed at 20 in all cases.
279:
280: Mouse Driver
281:
282: If you will be using the Microsoft Mouse with the Microsoft CodeView debugger
283: or the Microsoft QuickC Compiler, you must have Version 6.0 or later of the
284: Microsoft Mouse. If you do not, use the version of the MOUSE.COM driver
285: provided in Disk 9 of the package. Copy MOUSE.COM to the appropriate mouse
286: directory. When you are ready to use the mouse, type
287:
288: mouse
289:
290: at the DOS command level. If you want to install the mouse driver automatically
291: every time you reboot, insert the "mouse" command in your AUTOEXEC.BAT file.
292:
293: Note that in earlier releases of Microsoft C, both the MOUSE.SYS and the
294: MOUSE.COM driver were provided. If you have been using an earlier version
295: of the MOUSE.SYS driver, delete the following line from your CONFIG.SYS file:
296:
297: device=\<directory>\mouse.sys
298:
299: where <directory> is the directory where the earlier mouse driver resides.
300:
301:
302: Compiler
303:
304: Function Prototypes
305: -------------------
306: When a call to a function precedes its declaration or definition,
307: the default function prototype that is constructed does not specify
308: the number or type(s) of the arguments.
309:
310: Converting unsigned long to double
311: ----------------------------------
312: Unsigned long items are now converted directly to type double. They are not
313: first converted to type long.
314:
315: The interrupt Attribute
316: ------------------------
317: The interrupt attribute can be applied to a function to tell the compiler that
318: the function is an interrupt handler. This attribute tells the compiler to
319: generate entry and exit sequences that are appropriate for an interrupt-
320: handling function, including saving and restoring all registers and executing
321: an IRET instruction to return.
322:
323: You can access the registers that are saved before the normal entry sequence
324: by declaring the function with a parameter list containing a formal
325: parameter for each register saved. The following example illustrates
326: such a declaration:
327:
328: void interrupt cdecl far int_handler(es,ds,di,si,bp,sp,bx,dx,cx,ax,
329: ip,cs,flags)
330: unsigned es, ds, di, si, bp, sp, bx, dx, cx, ax, ip, cs, flags;
331: {
332: .
333: .
334: .
335: }
336:
337: Note that the formal parameters must appear in the opposite order from
338: the order in which the registers are pushed onto the stack; that is, the
339: parameter representing the first register pushed must appear last in the
340: list, and so on.
341:
342: Observe the following precautions when using interrupt functions:
343:
344: 1. In general, it is not a good idea to call standard-library functions,
345: especially functions that rely on DOS INT 21H system calls, within an
346: interrupt function. (Functions that rely on INT 21H calls include
347: stream- and low-level-I/O functions.) Functions that do not rely
348: on INT 21H, such as string-handling functions, may be safe to use.
349: Before using a standard-library function in an interrupt function,
350: be sure that you are familiar with the library function and what it does.
351:
352: 2. If you change any of the parameters of an interrupt function while the
353: function is executing, the corresponding register will contain the changed
354: value when the function returns. For example,
355:
356: void interrupt cdecl far int_handler(es,ds,di,si,bp,sp,bx,dx,cx,ax,
357: ip,cs,flags)
358: unsigned es, ds, di, si, bp, sp, bx, dx, cx, ax,ip,cs,flags;
359: {
360: .
361: .
362: .
363: ax = -1;
364: .
365: .
366: .
367: }
368:
369: causes the AX register to contain -1 when the int_handler function
370: returns. In general, it is not a good idea to modify the values of
371: the parameters representing the IP, CS, and flags registers in interrupt
372: functions.
373:
374: Limit on Nested Include Files
375: -----------------------------
376: The limit given in Section E.3.4 for nested include files refers to the total
377: number of open files that the compiler allows. Since the original source
378: file counts as an open file, a total of nine files (in addition to the
379: original file) may have #include directives.
380:
381:
382: CL Driver
383:
384: C1L.EXE
385: -------
386: An alternate form of compiler pass 1 named C1L.EXE is provided for compiling
387: programs that get "out of near/far heap space" errors. Invoke C1L.EXE
388: by entering the CL command with the /B1 <path> option as illustrated
389: below:
390:
391: cl /B1 <path>\c1l.exe <sourcefile>.c
392:
393: where <path> is the path (including drive and directory) where C1L.EXE resides
394: and <sourcefile> is the name of the C source file you are compiling.
395:
396: Specifying Overlays
397: -------------------
398: You can now specify overlays on the CL command line. Simply enclose the names
399: of the overlay source or object files in parentheses. For example, if you
400: enter the command line
401:
402: cl src_1.c (src_2.c obj_1) obj_2
403:
404: then the SRC_2.OBJ and OBJ_1.OBJ modules are overlays in the SRC_1.EXE
405: file and are read into memory from disk only if and when they are needed.
406:
407: Expanding Wild-Card Arguments
408: ----------------------------
409: If you are linking your program with the SETARGV.OBJ file to expand
410: wild-card arguments, you must specify the /NOE linker option, which tells
411: the linker not to use the extended dictionary in searching libraries.
412: (See the description of the /NOE option under the heading "Linker Options"
413: later in this document.)
414:
415: The correct form for compiling a program WILDCARD.C that uses wild-card
416: expansion is shown below:
417:
418: CL wildcard.c \lib\setargv /link /NOE
419:
420: or
421:
422: QCL wildcard.c \lib\setargv /link /NOE
423:
424: This procedure is not necessary if you have used LIB to place the wild-card
425: expansion routines in the standard C combined library (mLIBCf.LIB).
426:
427: /Fa Option
428: ----------
429: You must use Version 5.10 of the Microsoft Macro Assembler to assemble
430: output from the /Fa option. Earlier versions of the Macro Assembler do not
431: support the new communal variables generated by the /Fa option.
432:
433: /D Option
434: ---------
435: Note that the /Didentifier= and /Didentifier=string forms of this option
436: cannot be defined in the CL environment variable. This is because the SET
437: command does not accept the equal sign (=), which is a special character
438: in the environment.
439:
440: Predefined Identifiers
441: ----------------------
442: The compiler now defines the following new identifiers:
443:
444: Identifier Function
445: ---------- --------
446: M_I8086 Identifies the target processor as an 8086. Defined by
447: default or when the /G0 option is given explicitly.
448:
449: M_I286 Identifies the target processor as an 80286. Defined
450: when the /G1 or /G2 option is given.
451:
452: You can still give the same number of /D options on the CL command line.
453:
454: Note that the /u option no longer removes the definition of the predefined
455: identifier M_I86mM, which identifies the memory model. You can use the
456: /U option to remove the definition of M_I86mM; however, if you do,
457: the NULL constant will not be defined automatically in the program
458: (since the definition of NULL in the stdio.h and stddef.h files depends
459: on the memory model in use). If you compile a program with the /UM_I86mM
460: option, be sure to define NULL explicitly if you use it in the program.
461:
462: /J Option
463: ---------
464: When the /J option is given on the CL command line, a new predefined
465: identifier, _CHAR_UNSIGNED, is defined. This identifier is used with #ifndef
466: in the limits.h file to define the range of the default char type. Note that
467: compiling with /J reduces by 1 the number of constant and macro definitions
468: that can be given on the command line.
469:
470: /Oi Option/#pragma intrinsic
471: ----------------------------
472: In addition to the functions listed in Section 3.3.13 under "Generating
473: Intrinsic Functions," the following functions have intrinsic forms:
474:
475: Floating-point functions:
476: -------------------------
477: pow, log, log10, exp
478: sin, cos, tan
479: asin, acos, atan, atan2
480: sinh, cosh, tanh
481: sqrt
482: fabs, fmod
483:
484: Other functions:
485: ----------------
486: _enable, _disable
487: inpw, outpw
488:
489: If you use intrinsic forms of the floating-point functions listed above (that
490: is, if you compile with the /Oi option or specify any of the functions in an
491: intrinsic pragma), you cannot link with an alternate-math library
492: (mLIBCA.LIB). Any attempt to do so will cause unresolved-external errors
493: at link time. Note that this restriction applies even if you link with an
494: alternate-math library after compiling with the /FPc or /FPc87 option.
495:
496: If you want to compile with /Oi (to use the intrinsic forms of
497: non-floating-point functions) and then link with an alternate-math library,
498: specify any floating-point functions that appear in a program in a function
499: pragma.
500:
501: /Ox Option
502: ----------
503: For Version 5.10 of Microsoft C, the /Ox option performs more optimizations than
504: in previous versions, including loop optimizations and generation of intrinsics
505: for certain library functions. If you have problems compiling programs with the
506: /Ox (maximum optimization) option, try breaking the option down to its
507: component parts and removing either the "i" (generate intrinsics) or the "l"
508: (perform loop optimizations) from the option string; then try recompiling the
509: program. For Version 5.10, the "expanded" version of the /Ox option is
510:
511: /Oailt /Gs
512:
513: Disabling Unsafe Loop Optimizations: The /On Option
514: ----------------------------------------------------
515: The new /On option disables potentially unsafe loop optimizations in programs
516: compiled with the /Ol or /Ox option. When the /On option is used, the compiler
517: does not perform the following types of loop optimizations:
518:
519: o Hoisting division operations out of loops. This type of optimization can
520: cause problems in code such as the following:
521:
522: for (i=0; i<=99; i+=10)
523: {
524: if (denom != 0)
525: {
526: array[i] += (numer/denom);
527: printf("%f ", array[i]);
528: }
529: }
530:
531: When loop optimizations are turned on, the compiler knows that numer/denom
532: does not change within the loop. Therefore, it calculates numer/denom
533: only once: before the start of the loop and before the if statement
534: within the loop can check for division by zero. Compiling with the /On
535: option helps to avoid "divide by zero" errors that may result from code
536: like that shown above.
537:
538: o Loop-induction optimizations. When loop optimizations are turned on,
539: this code
540:
541: int larray[400];
542: unsigned char k, top_val, inc_val, var;
543:
544: for( k = 3; k < top_val; k += 8 )
545: {
546: larray[k*4] = k*4;
547: }
548:
549: is optimized to code such as the following:
550:
551: unsigned char t;
552: for( t = 12; t < top_val*4; t += 32 )
553: {
554: larray[t] = t;
555: }
556:
557: If the loop-control variable top_val in the original code is 64, the
558: induction expression top_val*4 overflows the limit for type unsigned
559: char, and the loop never terminates. To avoid this problem, the code is
560: optimized as shown below when the /On option is used:
561:
562: unsigned char t;
563: for( t = 12, k=3; k < top_val; k += 8, t += 32 )
564: {
565: larray[t] = t;
566: }
567:
568: The /On option can be used to solve similar overflow problems in cases
569: where induction variables result from array or pointer references and the
570: offset part of the address is close to wrapping.
571:
572: In general, you may want to compile with /On if your programs use arrays that
573: are larger than 32K, or if divide-by-zero or infinite-loop errors occur in
574: programs compiled with the /Ol option.
575:
576: /Za and /Ze Options
577: -------------------
578: Two new Microsoft extensions have been added to the list in Section 3.3.14:
579:
580: (1) Casting data pointers to function pointers, as in the following example:
581:
582: int *ip;
583: int foo();
584:
585: ((int (*)())ip)();
586:
587: (2) Casting function pointers to data pointers, as in the following example:
588:
589: int *ip;
590: int foo();
591:
592: ip = (int *)foo;
593:
594: Casts like these generate error C2068, "illegal cast," in programs compiled
595: with the /Za option. Otherwise, they generate warning C4074, "non standard
596: extension used," at warning level 3 or higher.
597:
598: The ANSI-standard way to cast from data pointers to function pointers, and
599: from function pointers to data pointers, is to
600:
601: (1) Cast to an integral type (int or long depending on pointer size)
602:
603: (2) Cast to the final pointer type
604:
605: For example, in a small-model program, the examples above could be rewritten
606: as follows to conform to the ANSI convention:
607:
608: ip = (int *)(int)foo; /* cast function pointer to data pointer */
609:
610: ((int (*)())(int)ip)(); /* cast data pointer to function pointer */
611:
612: Examples like those above work correctly whether or not the program is compiled
613: with the /Za option.
614:
615: Segment Setup for Memory Models
616: -------------------------------
617: The primary segments of a C program are ordered in memory as shown below,
618: from the highest memory location to the lowest:
619:
620: Segment Contents
621: ------- --------
622: (Heap) Area of unallocated memory that is available for dynamic
623: allocation by the program. Its size varies, depending on the
624: program's other storage requirements.
625:
626: STACK User's stack, used for all local data items
627:
628: _BSS All uninitialized static data items except those that are
629: explicitly declared as far or huge.
630:
631: c_common
632: Uninitialized global data items for small- and medium-model
633: programs. In compact- or large-model programs, this type of
634: data item is placed in a data segment with class FAR\_BSS.
635:
636: CONST Read-only constants, including floating-point constants,
637: string literals, and segment values for data items declared far
638: or huge or forced into their own segments by use of the /Gt
639: option.
640:
641: _DATA Default data segment: initialized global and static data
642: except data explicitly declared far or huge, or data forced
643: into different segments by use of the /Gt option.
644:
645: NULL Special-purpose segment at the beginning of DGROUP that
646: contains the compiler copyright notice. This segment is
647: checked before and after the program executes. If its
648: contents change during program execution, the program has
649: written to this area, usually by an inadvertent assignment
650: through a null pointer. The error message "Null pointer
651: assignment" appears to warn of this error.
652:
653: (Data
654: segments)
655: Initialized static and global data items, placed in their own
656: segments with class name FAR_DATA, allowing the linker to
657: combine these items so that they precede DGROUP. Uninitialized
658: static and global far data items are placed in segments that
659: have class FAR_BSS, allowing the linker to place these items
660: between the _TEXT segment(s) and DGROUP. Uninitialized huge
661: items are placed in segments with class FAR_DATA. In large-
662: and huge-model programs, global uninitialized data are
663: treated as though declared far (unless specifically declared
664: near) and given class FAR_BSS.
665:
666: _TEXT In small and compact model, segment containing code for all
667: modules. In medium, large, and huge models, each module has
668: its own text segment with the name of the module plus the
669: suffix _TEXT.
670:
671: When you look at a map file produced by linking a C program, you may notice
672: other segments in addition to the names listed below. These additional
673: segments have specialized uses for Microsoft languages and should not be used
674: by other programs.
675:
676: alloc_text Pragma
677: -----------------
678: No more than 10 alloc_text pragmas may appear in the same compilation unit.
679:
680: The alloc_text pragma MUST appear after the declarations of any functions
681: given in the pragma. Functions given in an alloc_text pragma may be
682: implicitly near (because the small or compact memory model is used) or
683: explicitly near (declared with the near keyword), provided that they are
684: called only by functions in the same segment.
685:
686: Functions referenced in an alloc_text pragma should be defined in the same
687: module as the pragma. If this is not done, and an undefined function is
688: later compiled into a different text segment, the error may or may not be
689: caught. Although the program will usually run correctly, the function
690: will not be allocated in the intended segments. The following example
691: shows code that may cause these problems:
692:
693: Module 1
694: --------
695: #pragma alloc_text(SEG1, foo, bar)
696:
697: int foo(int i)
698: {
699: i = bar(10);
700: }
701:
702: Module 2
703: --------
704: int bar(int i)
705: {
706: return(i*i);
707: }
708:
709: In the example above, the definitions of the functions foo and bar should
710: appear in the same module to avoid problems.
711:
712:
713: Include Files
714:
715: float.h
716: -------
717: For conformance with the ANSI C standard, the following constants defined in
718: the include file float.h refer to a base-2 exponent in Version 5.10 of
719: Microsoft C:
720:
721: DBL_MIN_EXP
722: DBL_MAX_EXP
723: FLT_MIN_EXP
724: FLT_MAX_EXP
725: LDBL_MIN_EXP
726: LDBL_MAX_EXP
727:
728: In Version 4.0, these constants refer to a base-10 exponent. The base-10
729: versions of these constants are now named DBL_MIN_10_EXP, DBL_MAX_10_EXP,
730: and so on.
731:
732: graph.h
733: -------
734: See the current version of the file for the most recent constant names and
735: definitions related to graphics functions.
736:
737:
738:
739: Graphics-Library Functions
740:
741: Graphics Functions
742: ------------------
743: Several new elements have been added to the graph.h file, including
744: elements in the videoconfig structure and manifest constants that allow you
745: to test the adapter and monitor information in the videoconfig
746: structure.
747:
748: Colors in Graphics and Text Modes
749: ---------------------------------
750: In a color text mode (such as _TEXTC80), _setbkcolor accepts (and
751: _getbkcolor returns) an attribute, or pixel value. The value for the
752: default colors is given by the table in Section 4.4 of the QuickC Programmer's
753: Guide. For example, _setbkcolor(2L) sets the background color to pixel
754: value 2. The actual color displayed depends on the palette mapping for
755: pixel value 2. The default is green in a color text mode.
756:
757: In a color graphics mode (such as _ERESCOLOR), _setbkcolor accepts (and
758: _getbkcolor returns) a color (as used in _remappalette). The value for the
759: background color is given by the manifest constants defined in the graph.h
760: include file. For example, _setbkcolor(_GREEN) sets the background color
761: in a graphics mode to green. These manifest constants are provided as a
762: convenience in defining and manipulating the most common colors. The
763: actual range of colors is, in general, much greater.
764:
765: The function _setcolor accepts an int value as an argument. It is an attribute
766: or pixel value.
767:
768: In general, whenever an argument is long, it refers to a color, and
769: whenever it is short, it refers to an attribute or pixel value. The two
770: exceptions are _setbkcolor and _getbkcolor described above.
771:
772:
773: Other Library Functions
774:
775: The following notes refer to the reference pages in the Microsoft C
776: Run-Time Library Reference.
777:
778: _amblksiz
779: ---------
780: In Chapter 3 of the Library Reference, _amblksiz should be defined with type
781: unsigned int rather than type int.
782:
783: atof, strtod
784: ------------
785: In compact- and large-model programs, the string argument to these functions
786: can be a maximum of 100 characters in length.
787:
788: _bios_keybrd, _bios_printer
789: ---------------------------
790: The return value from the functions _bios_keybrd and _bios_printer
791: should be unsigned int.
792:
793: cputs, fputs, puts
794: ------------------
795: The return value from the cputs, fputs, or puts function is 0 if the
796: function returns normally or a nonzero value if an error occurs.
797:
798: ctime, gmtime, localtime, mktime
799: --------------------------------
800: Calls to the mktime and ctime functions modify the single statically allocated
801: buffer used by gmtime and localtime. Thus, a mktime or ctime call
802: destroys the results of any previous localtime or gmtime call.
803:
804: The parameter to the localtime function should be declared as
805:
806: const time_t *time;
807:
808: The documentation of the TZ environment variable should appear in the
809: description of the gmtime function rather than the localtime function.
810:
811: _dos_findfirst, _dos_findnext
812: -----------------------------
813: If the attributes argument to either of these functions is _A_RDONLY, _A_HIDDEN,
814: _A_SYSTEM, or _A_SUBDIR, the function also returns any "normal" files (that is,
815: any files that are not read-only, hidden, or system files or subdirectories)
816: that match the path argument.
817:
818: _dos_open
819: ---------
820: The argument to the _dos_open function should be *handle. Also, the constant
821: O_RDONLY is defined in the fcntl.h header file, which should be included
822: if O_RDONLY is used as the mode argument.
823:
824: exec*, spawn* functions
825: -----------------------
826: Because of a bug in DOS Versions 2.0 and 2.1, child processes generated by
827: the exec family of routines (or by the equivalent spawn routines with the
828: P_OVERLAY argument) may cause fatal system errors when they exit. If you are
829: running under these versions of DOS, you must upgrade to DOS Version 3.0
830: to use these functions in your programs.
831:
832: fclose
833: ------
834: This function takes one parameter, which is declared as
835:
836: int fclose(stream);
837: FILE *stream;
838:
839: FP_OFF, FP_SEG
840: --------------
841: The argument to these functions should be declared as a void far pointer rather
842: than a char far pointer.
843:
844: In models that use near data pointers (small and medium), the FP_SEG and
845: FP_OFF macros work only if the far-pointer argument is stored in the default
846: data segment. If the far pointer is stored in a far data segment, the macros
847: will not work correctly.
848:
849: fopen
850: -----
851: The parameters should be declared as
852:
853: const char *path;
854: const char *type;
855:
856: _fpreset
857: --------
858: In the example, the second to last line should read
859:
860: longjmp(mark, -1);
861:
862: fwrite
863: ------
864: The first parameter should be declared as
865:
866: const void *buffer;
867:
868: int86x
869: ------
870: Under "Return Values," the second paragraph should refer to the cflag field
871: in the outregs union.
872:
873: malloc, _fmalloc, _nmalloc
874: --------------------------
875: The second paragraph under "Return Value" should read, "To get a pointer to a
876: type other than void, use a type cast on the return value."
877:
878: In the entry for malloc, delete the sentence that reads, "The resulting pointer
879: can be passed to the realloc function to adjust the size at any time."
880:
881: To ensure compatibility a recent change to the ANSI C standard,
882: malloc(0) now returns a non-null pointer. In this regard, malloc works the
883: same as it did under Version 4.0 of Microsoft C.
884:
885: memccpy
886: -------
887: The dest and src arguments should have type void * rather than
888: const void *.
889:
890: memchr
891: ------
892: The c argument should have type int rather than size_t, and the count
893: argument should have type size_t rather than unsigned.
894:
895: memmove
896: -------
897: This function should be added to the list of functions (in Section 2.12) that
898: support the use of huge pointers.
899:
900: This function returns the value of the dest parameter, not the src parameter.
901:
902: open and sopen
903: --------------
904: Certain calls to the open or sopen function may set the global variable errno
905: to EINVAL. For example, a call to sopen with an invalid shflag argument
906: (for example, 6) or a call to open with an invalid oflag argument (for
907: example, O_RDWR|O_WRONLY) return a value of -1 and set errno to EINVAL.
908:
909: outpw
910: -----
911: The return value from this function should have type unsigned rather than
912: type void.
913:
914: printf
915: ------
916: In Table R.3, the "Default" column for the "f" format type should read as
917: follows:
918:
919: Default precision is 6;
920: if precision is 0 or the period (.)
921: appears without a number following
922: it, no decimal point is printed.
923:
924: In the same table (R.3), in the "Default" column for the "g" format type,
925: the statement
926:
927: All significant digits are printed.
928:
929: should read
930:
931: Six significant digits are printed, less
932: any trailing zeros that are truncated.
933:
934: realloc
935: -------
936: First paragraph under "Return Value" should read, "The realloc function
937: returns a void pointer to the reallocated memory block." Third paragraph
938: should read, "To get a pointer to a type other than void, use a type cast
939: on the return value."
940:
941: scanf
942: -----
943: The "D," "O," "X," and "I" type characters, which represented long-integer
944: input fields, are no longer supported.
945:
946: setvbuf
947: -------
948: The setvbuf function can be used for an open stream only if that stream has NOT
949: yet been read from or written to.
950:
951: strlen
952: ------
953: The string parameter should have type const char * rather than char *.
954:
955: tmpnam
956: ------
957: The description of this function under "Summary" should read "Create temporary
958: file in the directory defined by P-tmpdir." Also, the sentence beginning
959: "The tmpnam function uses malloc to allocate space..." actually describes the
960: tempnam function rather than the tmpnam function.
961:
962: ungetc
963: ------
964: In the first paragraph under "Description," the second sentence should
965: read, "The stream must be open for reading."
966:
967:
968: Microsoft CodeView Debugger
969:
970: CVPACK Utility
971: --------------
972: A new utility named CVPACK.EXE is provided with this version of Microsoft C.
973: CVPACK can be used to pack the debug information in an executable file that
974: has been compiled with the /Zi option or linked with the /CO option.
975: Packing information allows CodeView to load larger programs without
976: running out of memory.
977:
978: The CVPACK utility has the following command line:
979:
980: CVPACK [/p] <exefile>
981:
982: If you invoke CVPACK without the /p option, the packed debug information is
983: appended to the executable file, so that the file is larger. CodeView
984: uses only the packed debug information.
985:
986: If you invoke CVPACK with the /p option, unused debug information is discarded,
987: and the packed information is written to the executable file, resulting in
988: a smaller executable file.
989:
990: Running CVPACK without the /p option is slightly faster than with the option.
991:
992: To use packed debugging information, you must use Version 2.10 or later of the
993: CodeView debugger.
994:
995: Compiling BASIC Programs for CodeView Debugger
996: ----------------------------------------------
997: To compile BASIC programs for use with the CodeView debugger, specify the
998: /Zi option rather than the /D option.
999:
1000: Expression Evaluator for BASIC Programs
1001: ---------------------------------------
1002: In the BASIC expression evaluator, "+" is not supported for string
1003: concatenation.
1004:
1005: Microsoft Pascal Programs
1006: -------------------------
1007: Microsoft Pascal programs cannot be debugged with the CodeView debugger for
1008: this release.
1009:
1010: The Pascal example on pg. 61 should read
1011:
1012: PAS1 /Z TEST;
1013:
1014: rather than
1015:
1016: PAS1 /Zi TEST;
1017:
1018: Exit Codes for Utilities
1019:
1020: The exit codes for LINK and the utilities in the Microsoft CodeView
1021: and Utilities Guide should appear as follows:
1022:
1023: LINK
1024: ----
1025: Code Meaning
1026:
1027: 0 No error.
1028:
1029: 2 Program error--something was wrong with the commands
1030: or files input to the linker.
1031:
1032: 4 System error. The linker
1033:
1034: - ran out of space on output files
1035: - was unable to reopen the temporary file
1036: - experienced an internal error
1037: - was interrupted by the user
1038:
1039: LIB, EXEPACK, EXEMOD, MAKE, and SETENV
1040: ---------------------------------------
1041: Code Meaning
1042:
1043: 0 No error.
1044:
1045: 2 Program error--something was wrong with the commands
1046: or files input to the utility.
1047:
1048: 4 System error. The utility ran out of memory, was
1049: interrupted by the user, or experienced an internal
1050: error.
1051:
1052: Microsoft LINK Linker
1053:
1054: Linker Options
1055: --------------
1056: The following new options have been added to the linker:
1057:
1058: /NOE[XTDICTIONARY]
1059: Tells the linker not to use the extended dictionary in
1060: searching libraries. Use this option if you redefine a
1061: standard-library routine (such as _setargv or _nullcheck)
1062: in a program module, or if you get linker error L2044 during
1063: linking (see the section titled "Linker Errors" later in this
1064: file for more information). This option may slow the linking
1065: process on some programs.
1066:
1067: The "extended dictionary" is a block of data telling the
1068: linker about interlibrary dependencies; that is, for each
1069: module in the library, the extended dictionary tells the
1070: linker which other modules in the same library are also
1071: required. Although the linker can process libraries faster
1072: with this information, it has trouble in processing if
1073: you redefine symbols (such as the names of standard-library
1074: routines) that otherwise would have been defined in one of
1075: the modules described in the extended dictionary.
1076:
1077: Overlay Restrictions
1078: --------------------
1079: You cannot use long jumps (using the longjmp library function) or indirect
1080: calls (through a function pointer) to pass control to an overlay. When a
1081: function is called through a pointer, the called function must be in the same
1082: overlay or in the root.
1083:
1084:
1085: MAKE Program-Maintenance Utility
1086:
1087: Backslash (\) As Continuation Character
1088: ---------------------------------------
1089: Note that MAKE considers a backslash immediately followed by a new-line
1090: character to be a continuation character. When it finds this combination
1091: in a description file, MAKE concatenates the line immediately following
1092: the combination with the line where the combination appears.
1093:
1094: If you define a macro that ends in a backslash, make sure that you put a
1095: space after the terminating backslash. For example, if you want to define
1096: macros for the path C:\SRC\BIN and C:\SRC\LIB, you must use the format
1097: illustrated below:
1098:
1099: BINPATH=C:\SRC\BIN\<space><new-line>
1100: LIBPATH=C:\SRC\LIB\<space><new-line>
1101:
1102: To illustrate the problems that can result if you do not put a space before the
1103: new-line character, assume that the macros above appear as shown below
1104: instead:
1105:
1106: BINPATH=C:\SRC\BIN\<new-line>
1107: LIBPATH=C:\SRC\LIB\<new-line>
1108:
1109: Because a new-line character appears immediately after the backslash at the end
1110: of the first macro, MAKE assumes that you are defining the single macro shown
1111: below:
1112:
1113: BINPATH=C:\SRC\BIN\LIBPATH=C:\SRC\LIB\
1114:
1115: New /X Option
1116: -------------
1117: The new /X option has the following syntax:
1118:
1119: /X <filename>
1120:
1121: This option redirects errors output by MAKE, or by any programs that MAKE
1122: runs, to the given file. If the <filename> argument is a dash (-), MAKE
1123: redirects error output to the standard output device.
1124:
1125: You may send both error output and standard output to the same file by
1126: combining the "/X -" form of this option with DOS redirection, as in the
1127: following example:
1128:
1129: MAKE /X - project.mak >make.log
1130:
1131: DO NOT specify the same filename to /X as the file following the redirection
1132: symbol (>).
1133:
1134:
1135: ERROUT Standard-Error Redirection Utility
1136:
1137: The ERROUT utility does not accept batch files. To redirect standard-error
1138: output from a batch file, you must enter a command of the following form:
1139:
1140: ERROUT COMMAND /c <batchcommand>
1141:
1142: If no /f option is given, then ERROUT redirects standard-error output to
1143: the standard-output device.
1144:
1145:
1146: Mixed-Language Programming
1147:
1148: C Naming Conventions
1149: --------------------
1150: C recognizes the first 31 characters of a symbolic name.
1151:
1152: Accessing Parameters on the Stack
1153: ---------------------------------
1154: In Section 6.1.5 of the Mixed Languages Programming Guide, the instruction
1155:
1156: mov bx, [bp+6]
1157:
1158: loads the argument into the BX register rather than the BP register.
1159:
1160: Setting Up Calls to High-Level Languages
1161: ----------------------------------------
1162: Section 6.6 of the Mixed Languages Programming Guide gives instructions
1163: for setting up a call to a high-level language from assembly language. Before
1164: you execute a call to a BASIC, Pascal, or FORTRAN routine, remember to declare
1165: an additional parameter if the return value is noninteger. This additional
1166: parameter must contain the offset address of the return value, for which
1167: you must allocate room within the stack segment (normally DGROUP, the same
1168: as the default data segment).
1169:
1170: BASIC Return Values
1171: -------------------
1172: BASIC functions use the FORTRAN/Pascal conventions, rather than the C
1173: conventions, for receiving return values.
1174:
1175: Passing C Strings to BASIC
1176: --------------------------
1177: In Section 8.4.3 of the Mixed Languages Programming Guide, in the example
1178: illustrating how C passes string arguments to BASIC functions, the sd_len
1179: field should be declared as shown below:
1180:
1181: int sd_len
1182:
1183: BASIC Array Declarations
1184: ------------------------
1185: The sample BASIC array declaration in Table 9.1 should read
1186:
1187: DIM x(c-1, r-1)
1188:
1189: Linking with MASM Files
1190: -----------------------
1191: If you are linking C modules with modules created by the Microsoft Macro
1192: Assembler (MASM), either assemble the MASM modules with the /MX
1193: option to preserve case sensitivity in these modules, or use the LINK
1194: command to link in a separate step and do NOT specify the /NOI linker
1195: option.
1196:
1197: Linking Mixed-Language Programs
1198: -------------------------------
1199: This section explains how to link Microsoft C modules with modules created
1200: by other Microsoft languages. The discussions assume that you are linking
1201: with Version 3.61 of the Microsoft Overlay Linker, LINK. (This is the version
1202: of LINK provided with Version 5.10 of the Microsoft C Optimizing Compiler.)
1203:
1204: 1. C 5.10 / FORTRAN 4.0
1205:
1206: To link object modules created using the Microsoft C Compiler, Version 5.10,
1207: with those created using Microsoft FORTRAN Version 4.00 or 4.01, you must
1208: create a special version of each of the FORTRAN libraries you intend to use.
1209: Create one FORTRAN library to correspond to each C library you are using;
1210: that is, create a FORTRAN library that supports the same memory-model/math-
1211: option combination as the corresponding C library. Be sure that you choose
1212: the "C compatibility" option when you build each
1213: FORTRAN library.
1214:
1215: Next, use the SETUP program provided with Microsoft C, Version 5.10, to
1216: create all the combined C 5.10 libraries that you will need. SETUP creates
1217: a subdirectory named \MIXLANG under the C 5.10 base directory.
1218:
1219: Place the FORTRAN libraries you have created in this directory. Then make the
1220: \MIXLANG directory the current directory and run F4COMPAT, which brings the
1221: FORTRAN libraries up to date and makes them compatible with C 5.10. F4COMPAT
1222: takes two arguments: one specifying the memory model and one specifying the
1223: floating-point-math package that the library supports. For example,
1224:
1225: F4COMPAT L 7
1226:
1227: makes a C 5.10-compatible version of LLIBFOR7.LIB.
1228:
1229: Once the libraries are built, use the following LINK command line to
1230: link the appropriate C library with the FORTRAN library that you
1231: converted in the previous example:
1232:
1233: LINK objs,,,LLIBC7.LIB LLIBFOR7.LIB /NOE;
1234:
1235: The LINK command lines for other memory models and floating-point math packages
1236: are similar. Note that the C library must be given first on the command line.
1237: Specify the \MIXLANG subdirectory either in the LIB environment variable
1238: or on the LINK command line so that the linker can find the FORTRAN
1239: library. Use only large- and medium-model libraries. Huge-model programs
1240: use large-model libraries.
1241:
1242:
1243: 2. C 5.10 / QuickBASIC 4.0
1244:
1245: To create a program whose components are built using Microsoft C 5.10 and
1246: Microsoft QuickBASIC 4.0, you should compile your C source files using the
1247: /AL option (large memory model). The QuickBASIC source files can be compiled
1248: either with or without the /o option of the BC command, depending on whether you
1249: want to use the BCOM40.LIB or BRUN40.LIB run-time library. The LLIBCE.LIB
1250: version of the C library is recommended. The main program must be written
1251: in BASIC, and the BASIC run-time library must be given before the C
1252: library on the LINK command line.
1253:
1254: Two recommended compile-and-link sequences are
1255:
1256: (a) CL /AL /c cmodule.c
1257: BC /o bmain.bas;
1258: LINK bmain cmodule,,,BCOM40.LIB LLIBCE.LIB /NOE;
1259:
1260: (b) CL /AL /c cmodule.c
1261: BC bmain.bas;
1262: LINK bmain cmodule,,,BRUN40.LIB LLIBCE.LIB /NOE;
1263:
1264:
1265: 3. C 5.10 / Pascal 4.0
1266:
1267: To create a program whose components are built using Microsoft C 5.10 and
1268: Microsoft Pascal 4.0, compile your C source files with the /AL option
1269: (large memory model). When you give the run-time libraries on the LINK
1270: command line, use a single math package, and use only
1271: large-model C libraries.
1272:
1273: The three recommended combinations of libraries are
1274:
1275: (a) LINK objs,,,LLIBC7.LIB LIBPAS7.LIB /NOE;
1276:
1277: (b) LINK objs,,,LLIBCE.LIB LIBPASE.LIB /NOE;
1278:
1279: (c) LINK objs,,,LLIBCA.LIB LIBPASA.LIB /NOE;
1280:
1281:
1282: LIBRARY MANAGER (LIB)
1283:
1284: There is a new option for LIB: /NOIGNORECASE (abbreviated as /N).
1285: This option tells LIB to not ignore case when comparing symbols.
1286: names. By default, LIB ignores case. Multiple symbols which are
1287: the same except for case can be put in the same library. For
1288: example: "_Open" and "_open". Normally you could not add both
1289: these symbols to the same library.
1290:
1291: Note that if a library is built with /NOI, the library is
1292: internally "marked" to indicate /NOI. All libraries built
1293: with earlier versions of LIB are not marked.
1294:
1295: If you combine multiple libraries, and any one of them is
1296: marked /NOI, then /NOI is assumed for the output library.
1297:
1298: In addition we just added a new option, /IGNORECASE (abbr. /I) which is
1299: completely analagous to /NOIGNORECASE. /I is the default. The only
1300: reason to use it would be if you had an existing library marked /NOI
1301: which you wanted to combine with other libraries which were not marked,
1302: and have the output library be not marked. If you didn't use
1303: /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.