intel c++ compiler user's manualmvtool.co.kr/hb/data/pds/ccxsc.pdfintel® c++ compiler user’s...

Intel® C++ CompilerUser’s Manual

October 2003

Revision 2.0

Order Number: 278496-006

Intel® C++ Compiler User’s Manual

Information in this document is provided in connection with Intel® Products. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel's Terms and Conditions of Sale for such products, Intel assumes no liability whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not intended for use in medical, life saving, or life sustaining applications.

Intel may make changes to specifications and product descriptions at any time, without notice.

Designers must not rely on the absence or characteristics of any features or instructions marked “reserved” or “undefined.” Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.

This document and the software described in it are furnished under license and may only be used or copied in accordance with the terms of the license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation.

Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.

Copies of documents which have an ordering number and are referenced in this document, or other Intel literature may be obtained by calling 1-800-548-4725 or by visiting Intel's website at http://www.intel.com.

Copyright © Intel Corporation, 2003

Copyright (c) 1982-1994 Kinetech, Inc. [or its assignee].

Copyright (c) 1994-2001 by Dinkumware. ALL RIGHTS RESERVED.

Intel and Intel XScale are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

*Other names and brands may be claimed as the property of others.

Contents

Contents1 Introduction..................................................................................................................................21

1.1 About this Manual ...............................................................................................................221.2 Related Documentation ......................................................................................................241.3 Requirements .....................................................................................................................251.4 Compiler Limits ...................................................................................................................261.5 Conventions........................................................................................................................27

2 General Usage .............................................................................................................................29

2.1 Command Line Syntax .......................................................................................................302.2 Thumb* Mode .....................................................................................................................312.3 Input Files ...........................................................................................................................322.4 Output Files ........................................................................................................................332.5 Using the Intel® C++ Compiler Within the Intel® Integrated Development Environment ....342.6 Default Behavior of the Intel® C++ Compiler ......................................................................35

2.6.1 General Default Behavior ......................................................................................352.6.2 Default Options ......................................................................................................35

3 Compiler Options and Pragmas Quick Reference ...................................................................37

3.1 Option Reference................................................................................................................383.2 Pragma Reference..............................................................................................................44

4 Customizing Compilation Environment ....................................................................................47

4.1 Configuration Files..............................................................................................................484.2 Environment Variables........................................................................................................49

4.2.1 Setting Environment Variables in the Command Line ...........................................494.2.2 Setting Environment Variables in Windows* 2000.................................................494.2.3 Setting Environment Variables on Windows* XP...................................................50

4.3 Response Files ...................................................................................................................514.4 Include Files........................................................................................................................52

4.4.1 Specifying an Include Directory .............................................................................524.4.2 Preventing Search in Default Path.........................................................................52

5 Customizing the Compilation Process ......................................................................................53

5.1 Preprocessing.....................................................................................................................545.1.1 Preprocessing only ................................................................................................555.1.2 Searching for Include Files ....................................................................................565.1.3 Defining Macros.....................................................................................................57

5.2 Compiling............................................................................................................................595.2.1 Specifying Compilation Output ..............................................................................60

5.2.1.1 Default Output Files ...............................................................................605.2.1.2 Specifying a Multifile Object...................................................................615.2.1.3 Using Non-standard Source File Extensions .........................................625.2.1.4 Specifying Executable Files ...................................................................625.2.1.5 Specifying Object Files ..........................................................................635.2.1.6 Specifying Output Directories ................................................................635.2.1.7 Using Standard ANSI C Code only ........................................................645.2.1.8 Generating a Function Prototype List ....................................................64

Intel® C++ Compiler User’s Manual 3

Contents

5.2.2 Using the Intel® Assembler to Produce Object Code ............................................ 645.3 Linking ................................................................................................................................ 655.4 Debugging .......................................................................................................................... 66

5.4.1 Parsing for Syntax Only ......................................................................................... 665.4.2 Support for Symbolic Debugging ........................................................................... 665.4.3 Symbolic Debugging and Optimizations ................................................................ 67

6 Compiler Options ........................................................................................................................ 69

6.1 Introduction ......................................................................................................................... 706.2 Command Line Environment .............................................................................................. 716.3 Overview of Options ........................................................................................................... 72

6.3.1 Language Options ................................................................................................. 736.3.2 Preprocessor Options ............................................................................................746.3.3 Precompiled Header Options................................................................................. 756.3.4 Optimization Options ............................................................................................. 766.3.5 Interprocedural Optimizations................................................................................ 77

6.3.5.1 Multifile IPO............................................................................................786.3.6 Error Handling Options .......................................................................................... 806.3.7 Code Generation Options ......................................................................................816.3.8 Output File Options................................................................................................ 826.3.9 Debugging Options ................................................................................................ 836.3.10 Options which Interrupt the Compilation Process.................................................. 846.3.11 Miscellaneous Options........................................................................................... 85

6.4 Option -? ............................................................................................................................. 866.5 Option -Ba........................................................................................................................... 876.6 Option -Bd........................................................................................................................... 886.7 Option -Bl............................................................................................................................ 896.8 Option -Bz........................................................................................................................... 906.9 Option -C ............................................................................................................................ 916.10 Option -c ............................................................................................................................. 926.11 Option -D ............................................................................................................................ 936.12 Option -E............................................................................................................................. 946.13 Option -EP .......................................................................................................................... 956.14 Option -Fa........................................................................................................................... 966.15 Option -FD .......................................................................................................................... 976.16 Option -Fe........................................................................................................................... 986.17 Option -FI............................................................................................................................ 996.18 Option -Fo......................................................................................................................... 1006.19 Option -Fp......................................................................................................................... 1016.20 Option -Gy ........................................................................................................................ 1026.21 Option -H .......................................................................................................................... 1036.22 Option -HELP....................................................................................................................1046.23 Option -help ...................................................................................................................... 1056.24 Option -I ............................................................................................................................ 1066.25 Option -J ........................................................................................................................... 1076.26 Option -Kc++eh................................................................................................................. 1086.27 Option -LD ........................................................................................................................ 1096.28 Option -LDd ...................................................................................................................... 1106.29 Option -noBool.................................................................................................................. 1116.30 Option -nologo .................................................................................................................. 112

4 Intel® C++ Compiler User’s Manual

Contents

6.31 Option -O ..........................................................................................................................1136.32 Option -o ...........................................................................................................................1146.33 Option -Oa ........................................................................................................................1156.34 Option -Ob ........................................................................................................................1166.35 Option -Od ........................................................................................................................1176.36 Option -Og ........................................................................................................................1186.37 Option -Oi .........................................................................................................................1196.38 Option -Op ........................................................................................................................1206.39 Option -Os ........................................................................................................................1216.40 Option -Ot .........................................................................................................................1226.41 Option -Ow........................................................................................................................1236.42 Option -Ox ........................................................................................................................1246.43 Option -Oy ........................................................................................................................1256.44 Option -P...........................................................................................................................1266.45 Option -QA........................................................................................................................1276.46 Option -QAname ...............................................................................................................1286.47 Option -Qansi....................................................................................................................1296.48 Option -QH........................................................................................................................1306.49 Option -Qip .......................................................................................................................1316.50 Option -Qip_no_inlining ....................................................................................................1326.51 Option -Qipo .....................................................................................................................1336.52 Option -Qipo_c..................................................................................................................1346.53 Option -Qipo_obj...............................................................................................................1356.54 Option -Qipo_S .................................................................................................................1366.55 Option -Qlocation..............................................................................................................1376.56 Option -QM .......................................................................................................................1386.57 Option -Qnobss_init ..........................................................................................................1396.58 Option -Qoption ................................................................................................................1406.59 Option -Qprec ...................................................................................................................1416.60 Option -Qprec_div.............................................................................................................1426.61 Option -QRinterwork-return ..............................................................................................1436.62 Option -Qropi ....................................................................................................................1446.63 Option -Qrwpi....................................................................................................................1456.64 Option -QRxscale .............................................................................................................1466.65 Option -Qsox.....................................................................................................................1476.66 Option -QTP......................................................................................................................1486.67 Option -Qunroll .................................................................................................................1496.68 Option -Qvec_report .........................................................................................................1506.69 Option -Qwd......................................................................................................................1516.70 Option -Qwe......................................................................................................................1526.71 Option -Qwn......................................................................................................................1536.72 Option -Qwp_ipo...............................................................................................................1546.73 Option -Qwr ......................................................................................................................1556.74 Option -Qww .....................................................................................................................1566.75 Option -rtti .........................................................................................................................1576.76 Option -S...........................................................................................................................1586.77 Option -TC ........................................................................................................................1596.78 Option -Tc .........................................................................................................................1606.79 Option -TP ........................................................................................................................1616.80 Option -Tp.........................................................................................................................162


Contents

6.81 Option -U .......................................................................................................................... 1636.82 Option -u ........................................................................................................................... 1646.83 Option -V........................................................................................................................... 1656.84 Option -W.......................................................................................................................... 1666.85 Option -WX ....................................................................................................................... 1676.86 Option -w .......................................................................................................................... 1686.87 Option -X........................................................................................................................... 1696.88 Option -Yc......................................................................................................................... 1706.89 Option -Yu......................................................................................................................... 1726.90 Option -YX ........................................................................................................................ 1746.91 Option -Za......................................................................................................................... 1766.92 Option -Zd......................................................................................................................... 1776.93 Option -Ze......................................................................................................................... 1786.94 Option -Zg......................................................................................................................... 1796.95 Option -Zi .......................................................................................................................... 1806.96 Option -Zp......................................................................................................................... 1816.97 Option -Zs ......................................................................................................................... 182

7 Pragmas ..................................................................................................................................... 183

7.1 Introduction ....................................................................................................................... 1847.2 Microsoft* Compatible Pragmas ....................................................................................... 185

7.2.1 Pragma alloc_text ................................................................................................ 1857.2.2 Pragma bss_seg.................................................................................................. 1867.2.3 Pragma code_seg................................................................................................ 1877.2.4 Pragma comment ................................................................................................ 1887.2.5 Pragma component ............................................................................................. 1897.2.6 Pragma const_seg............................................................................................... 1907.2.7 Pragma data_seg ................................................................................................ 1917.2.8 Pragma function................................................................................................... 1927.2.9 Pragma hrdstop ................................................................................................... 1937.2.10 Pragma include_alias ..........................................................................................1947.2.11 Pragma intrinsic ................................................................................................... 1957.2.12 Pragma message.................................................................................................1977.2.13 Pragma optimize.................................................................................................. 1987.2.14 Pragma pack........................................................................................................ 1997.2.15 Pragma warning................................................................................................... 200

7.3 ARM* Compatible Pragmas.............................................................................................. 2017.3.1 Pragma check_stack ........................................................................................... 2017.3.2 Pragma debug ..................................................................................................... 2027.3.3 Pragma ospace.................................................................................................... 2037.3.4 Pragma otime ...................................................................................................... 2047.3.5 Pragma onum ...................................................................................................... 2057.3.6 Pragma softfp_linkage ......................................................................................... 206

7.4 GNU Compatible Pragmas ............................................................................................... 2077.4.1 Pragma align........................................................................................................ 2077.4.2 Pragma isr ........................................................................................................... 2087.4.3 Pragma section (C mode only) ............................................................................ 209

8 Assembly Language Output File.............................................................................................. 211

8.1 Creating an Assembly Language Output File ................................................................... 212


Contents

8.2 Example............................................................................................................................214

9 Optimizations .............................................................................................................................217

9.1 Optimization Levels ..........................................................................................................2189.1.1 Optimization Levels Overview..............................................................................2189.1.2 Setting Optimization Levels .................................................................................2189.1.3 Restricting Optimization .......................................................................................219

9.2 Floating Point Arithmetic Optimizations ............................................................................2209.2.1 Floating Point Arithmetic Precision ......................................................................2209.2.2 Restricting Floating Point Arithmetic Precision ....................................................220

9.3 Interprocedural Optimizations...........................................................................................2229.3.1 Multifile IPO Overview .........................................................................................2229.3.2 Creating a Multi-file IPO Executable with Compiler Commands..........................2239.3.3 Analyzing the Effects of Multifile IPO...................................................................224

9.4 Inline Expansion of Library Functions...............................................................................2259.4.1 Controlling Inline Expansion of User Functions ...................................................2259.4.2 Criteria for Inline Function Expansion ..................................................................226

9.4.2.1 Minimum Call-site Criteria....................................................................2269.4.2.2 Minimum Criteria for the Caller ............................................................2269.4.2.3 Minimum Criteria for the Callee ...........................................................2279.4.2.4 Selecting Routines for Inlining .............................................................227

9.5 High-level Language Optimizations ..................................................................................2289.5.1 Loop Unrolling......................................................................................................228

9.5.1.1 How to Enable Loop Unrolling .............................................................2289.5.1.2 How to Disable Loop Unrolling.............................................................2289.5.1.3 Effect of the Default .............................................................................228

10 Vectorization ..............................................................................................................................229

10.1 Vectorizer Quick Reference..............................................................................................23010.2 Vectorization Key Programming Guidelines .....................................................................231

10.2.1 Guidelines for loop bodies ...................................................................................23110.2.2 Preparing Your Code for Vectorization ................................................................23110.2.3 Restrictions ..........................................................................................................232

10.2.3.1 Style .....................................................................................................23210.3 Data Dependence.............................................................................................................233

10.3.1 Data Dependence Theory....................................................................................23410.4 Loop Constructs................................................................................................................235

10.4.1 Loop Exit Conditions............................................................................................23610.4.2 Types of Loops Vectorized ..................................................................................23710.4.3 Stripmining and Cleanup .....................................................................................23810.4.4 Statements in the Loop Body...............................................................................239

10.4.4.1 Integer Array Operations......................................................................23910.4.4.2 Other Operations .................................................................................239

10.5 Language Support and Directives ....................................................................................24010.5.1 Language Support ...............................................................................................24010.5.2 Multi-version Code...............................................................................................24010.5.3 Pragma Scope .....................................................................................................240

10.5.3.1 vector always .......................................................................................24110.5.3.2 ivdep ....................................................................................................24110.5.3.3 vector ...................................................................................................24210.5.3.4 novector ...............................................................................................244


Contents

10.5.4 Dynamic Dependence Testing.............................................................................24510.6 Some Vectorization Examples......................................................................................... 246

10.6.1 Argument Aliasing: A Vector Copy ...................................................................... 24610.6.2 Data Alignment .................................................................................................... 24710.6.3 Data Alignment Examples ................................................................................... 24910.6.4 Loop Interchange and Subscripts: Matrix Multiplication ...................................... 250

11 Language Conformance Options............................................................................................. 251

11.1 Conformance to the C Standard ....................................................................................... 25211.1.1 Understanding the Extensions to ANSI/ISO Standard C Dialect ......................... 25311.1.2 How to Set the Compiler for Extended C Dialect................................................. 25411.1.3 Macros Included with the Compiler...................................................................... 255

11.2 Conformance to the C++ Standard................................................................................... 256

12 The Intel® Library System......................................................................................................... 257

12.1 Introduction to the Intel® Library System .......................................................................... 25812.2 Naming of Libraries and Startup Modules ........................................................................ 259

12.2.1 Filename Encoding .............................................................................................. 25912.3 Examples .......................................................................................................................... 263

13 The C Standard Library............................................................................................................. 265

13.1 Introduction to the C Standard Library.............................................................................. 26613.2 Global Symbols................................................................................................................. 268

13.2.1 ANSI-Defined Reentrant Functions ..................................................................... 26813.2.2 ANSI-Defined Non-Reentrant Functions.............................................................. 27013.2.3 Internal Library Symbols ...................................................................................... 27413.2.4 Additional Library Functions ................................................................................ 27513.2.5 System Interface Functions ................................................................................. 276

13.3 Data Symbols of the Library ............................................................................................. 27713.3.1 errno ....................................................................................................................27713.3.2 stderr....................................................................................................................27713.3.3 stdin ..................................................................................................................... 27713.3.4 stdout ................................................................................................................... 278

13.4 Header Files ..................................................................................................................... 27913.4.1 Header File assert.h ............................................................................................ 28013.4.2 Header File ctype.h.............................................................................................. 28013.4.3 Header File errno.h.............................................................................................. 28113.4.4 Header File float.h ............................................................................................... 28213.4.5 Header File limits.h .............................................................................................. 28313.4.6 Header File locale.h............................................................................................. 28413.4.7 Header File math.h .............................................................................................. 28513.4.8 Header File setjmp.h............................................................................................ 28613.4.9 Header File signal.h............................................................................................. 28713.4.10 Header File stdarg.h ........................................................................................... 28813.4.11 Header File stddef.h ............................................................................................ 28913.4.12 Header File stdio.h............................................................................................... 29013.4.13 Header File stdlib.h.............................................................................................. 29313.4.14 Header File string.h ............................................................................................. 29613.4.15 Header File time.h ............................................................................................... 29813.4.16 Header File version.h........................................................................................... 299

13.5 Macros.............................................................................................................................. 300


Contents

13.5.1 Macro assert ........................................................................................................30013.5.2 Macro va_arg.......................................................................................................30113.5.3 Macro va_copy ....................................................................................................30213.5.4 Macro va_end ......................................................................................................30313.5.5 Macro va_start .....................................................................................................304

13.6 Library Functions ..............................................................................................................30513.6.1 _sbrkblockfree .....................................................................................................30513.6.2 abort.....................................................................................................................30613.6.3 abs .......................................................................................................................30713.6.4 acos .....................................................................................................................30813.6.5 asctime ................................................................................................................30913.6.6 asin ......................................................................................................................31013.6.7 atan......................................................................................................................31113.6.8 atan2....................................................................................................................31213.6.9 atexit ....................................................................................................................31313.6.10 atof .......................................................................................................................31413.6.11 atoi .......................................................................................................................31613.6.12 atol .......................................................................................................................31713.6.13 atoll ......................................................................................................................31813.6.14 bsearch ................................................................................................................31913.6.15 calloc....................................................................................................................32113.6.16 ceil .......................................................................................................................32213.6.17 clearerr.................................................................................................................32313.6.18 clock.....................................................................................................................32413.6.19 cos .......................................................................................................................32513.6.20 cosh .....................................................................................................................32613.6.21 ctime ....................................................................................................................32713.6.22 difftime .................................................................................................................32813.6.23 div ........................................................................................................................32913.6.24 exit .......................................................................................................................33013.6.25 exp .......................................................................................................................33213.6.26 fabs ......................................................................................................................33313.6.27 fclose ...................................................................................................................33413.6.28 feof .......................................................................................................................33513.6.29 ferror ....................................................................................................................33713.6.30 fflush ....................................................................................................................33813.6.31 fgetc .....................................................................................................................33913.6.32 fgetpos .................................................................................................................34113.6.33 fgets .....................................................................................................................34313.6.34 floor ......................................................................................................................34513.6.35 fmod.....................................................................................................................34613.6.36 fopen....................................................................................................................34713.6.37 fprintf ....................................................................................................................35013.6.38 fputc .....................................................................................................................35413.6.39 fputs .....................................................................................................................35613.6.40 fread.....................................................................................................................35813.6.41 free.......................................................................................................................36013.6.42 freopen.................................................................................................................36113.6.43 frexp.....................................................................................................................36313.6.44 fscanf ...................................................................................................................364


Contents

13.6.45 fseek ....................................................................................................................36813.6.46 fsetpos ................................................................................................................. 37113.6.47 ftell ....................................................................................................................... 37313.6.48 fwrite ....................................................................................................................37513.6.49 getc ...................................................................................................................... 37713.6.50 getchar................................................................................................................. 37913.6.51 getenv .................................................................................................................. 38013.6.52 gets ...................................................................................................................... 38113.6.53 gmtime ................................................................................................................. 38213.6.54 isalnum ................................................................................................................ 38313.6.55 isalpha ................................................................................................................. 38413.6.56 iscntrl ................................................................................................................... 38513.6.57 isdigit....................................................................................................................38713.6.58 isgraph ................................................................................................................. 38913.6.59 islower.................................................................................................................. 39113.6.60 isprint ................................................................................................................... 39313.6.61 ispunct ................................................................................................................. 39513.6.62 isspace................................................................................................................. 39713.6.63 isupper ................................................................................................................. 39913.6.64 isxdigit.................................................................................................................. 40113.6.65 itoa ....................................................................................................................... 40313.6.66 labs ...................................................................................................................... 40413.6.67 ldexp ....................................................................................................................40513.6.68 ldiv ....................................................................................................................... 40613.6.69 llabs ..................................................................................................................... 40713.6.70 lltoa ...................................................................................................................... 40813.6.71 localeconv............................................................................................................ 40913.6.72 localtime............................................................................................................... 41213.6.73 log ........................................................................................................................ 41313.6.74 log10 ....................................................................................................................41413.6.75 longjmp ................................................................................................................ 41513.6.76 ltoa ....................................................................................................................... 41713.6.77 malloc .................................................................................................................. 41813.6.78 memchr................................................................................................................ 42013.6.79 memcmp ..............................................................................................................42113.6.80 memcpy ............................................................................................................... 42313.6.81 memmove ............................................................................................................ 42413.6.82 memset ................................................................................................................ 42513.6.83 mktime ................................................................................................................. 42613.6.84 modf..................................................................................................................... 42913.6.85 perror ................................................................................................................... 43013.6.86 pow ...................................................................................................................... 43113.6.87 pow10 .................................................................................................................. 43213.6.88 printf..................................................................................................................... 43313.6.89 putc ...................................................................................................................... 43513.6.90 putchar................................................................................................................. 43713.6.91 puts ...................................................................................................................... 43913.6.92 qsort..................................................................................................................... 44013.6.93 raise ..................................................................................................................... 44213.6.94 rand...................................................................................................................... 444


Contents

13.6.95 realloc ..................................................................................................................44513.6.96 remove.................................................................................................................44713.6.97 Function rename..................................................................................................44813.6.98 rewind ..................................................................................................................44913.6.99 scanf ....................................................................................................................45113.6.100setbuf ..................................................................................................................45413.6.101setjmp .................................................................................................................45513.6.102setlocale..............................................................................................................45713.6.103setvbuf ................................................................................................................45813.6.104signal ..................................................................................................................46013.6.105sin .......................................................................................................................46213.6.106sinh .....................................................................................................................46313.6.107sprintf ..................................................................................................................46413.6.108sqrt ......................................................................................................................46613.6.109srand...................................................................................................................46713.6.110sscanf .................................................................................................................46813.6.111strcat ...................................................................................................................47013.6.112strchr...................................................................................................................47113.6.113strcmp .................................................................................................................47213.6.114strcoll ..................................................................................................................47413.6.115strcpy ..................................................................................................................47513.6.116strcspn ................................................................................................................47713.6.117strerror ................................................................................................................47813.6.118strftime ................................................................................................................47913.6.119strlen ...................................................................................................................48113.6.120strncat .................................................................................................................48213.6.121strncmp ...............................................................................................................48313.6.122strncpy ................................................................................................................48513.6.123strpbrk.................................................................................................................48713.6.124strrchr..................................................................................................................48813.6.125strspn ..................................................................................................................48913.6.126strstr ....................................................................................................................49013.6.127strtod...................................................................................................................49113.6.128strtok ...................................................................................................................49313.6.129strtol ....................................................................................................................49513.6.130strtoll ...................................................................................................................49713.6.131strtoul ..................................................................................................................49913.6.132strtoull .................................................................................................................50113.6.133strxfrm.................................................................................................................50313.6.134system ................................................................................................................50513.6.135tan.......................................................................................................................50613.6.136tanh.....................................................................................................................50713.6.137time .....................................................................................................................50813.6.138tmpfile .................................................................................................................50913.6.139tmpnam...............................................................................................................51013.6.140tolower ................................................................................................................51113.6.141toupper................................................................................................................51313.6.142ungetc .................................................................................................................51513.6.143vfprintf .................................................................................................................51713.6.144vprintf ..................................................................................................................519


Contents

13.6.145vsprintf ................................................................................................................ 52113.7 The Intel® Run-time Library .............................................................................................. 523

13.7.1 General Remarks.................................................................................................52413.7.2 Summary of the Functions................................................................................... 52513.7.3 __adddf3..............................................................................................................52813.7.4 __addsf3 ..............................................................................................................52913.7.5 __ashldi3 ............................................................................................................. 53013.7.6 __ashrdi3 ............................................................................................................. 53113.7.7 __divdf3 ............................................................................................................... 53213.7.8 __divdi3 ............................................................................................................... 53313.7.9 __divsf3 ............................................................................................................... 53413.7.10 __divsi3................................................................................................................ 53513.7.11 __eqdf2................................................................................................................ 53613.7.12 __eqsf2 ................................................................................................................ 53813.7.13 __extendsfdf2 ...................................................................................................... 54013.7.14 __fixdfdi ............................................................................................................... 54213.7.15 __fixdfsi................................................................................................................ 54313.7.16 __fixsfdi................................................................................................................ 54413.7.17 __fixsfsi................................................................................................................ 54613.7.18 __fixunsdfdi.......................................................................................................... 54713.7.19 __fixunsdfsi.......................................................................................................... 54913.7.20 __fixunssfdi.......................................................................................................... 55013.7.21 __fixunssfsi .......................................................................................................... 55113.7.22 __floatdidf ............................................................................................................ 55213.7.23 __floatdisf ............................................................................................................ 55313.7.24 __floatsidf ............................................................................................................ 55413.7.25 __floatsisf............................................................................................................. 55513.7.26 __floatunsdidf ...................................................................................................... 55613.7.27 __floatunsdisf.......................................................................................................55713.7.28 __floatunssidf.......................................................................................................55813.7.29 __floatunssisf.......................................................................................................55913.7.30 __gedf2................................................................................................................ 56013.7.31 __gesf2 ................................................................................................................ 56213.7.32 __gtdf2................................................................................................................. 56413.7.33 __gtsf2 ................................................................................................................. 56613.7.34 __ledf2 ................................................................................................................. 56813.7.35 __lesf2 ................................................................................................................. 57013.7.36 __lshrdi3 ..............................................................................................................57213.7.37 __ltdf2 .................................................................................................................. 57313.7.38 __ltsf2 .................................................................................................................. 57513.7.39 __moddi3 ............................................................................................................. 57713.7.40 __modsi3 ............................................................................................................. 57813.7.41 __muldf3 ..............................................................................................................57913.7.42 __mulsf3 ..............................................................................................................58013.7.43 __nedf2................................................................................................................ 58113.7.44 __negdf2..............................................................................................................58313.7.45 __negsf2 ..............................................................................................................58413.7.46 __nesf2 ................................................................................................................ 58513.7.47 __subdf3 ..............................................................................................................58713.7.48 __subsf3 ..............................................................................................................588


Contents

13.7.49 __truncdfsf2 .........................................................................................................58913.7.50 __udivdi3 .............................................................................................................59113.7.51 __udivsi3..............................................................................................................59213.7.52 __umoddi3 ...........................................................................................................59313.7.53 __umodsi3 ...........................................................................................................59413.7.54 _lmul ....................................................................................................................59513.7.55 _memcopy ...........................................................................................................59613.7.56 ftp8 .......................................................................................................................597

14 Library-Target System Interface ..............................................................................................599

14.1 Introduction to the Library-Target System Interface .........................................................60014.2 Startup Module .................................................................................................................603

14.2.1 exit() .....................................................................................................................60414.2.2 Setting the Environment ......................................................................................605

14.3 ANSI-Defined System Interface Functions .......................................................................60614.3.1 clock.....................................................................................................................60614.3.2 getenv ..................................................................................................................60714.3.3 remove.................................................................................................................60814.3.4 rename.................................................................................................................60914.3.5 system .................................................................................................................61014.3.6 time ......................................................................................................................611

14.4 Non-ANSI System Interface Functions .............................................................................61214.4.1 _blocksizebrk .......................................................................................................61314.4.2 _exit .....................................................................................................................61414.4.3 _freebrk................................................................................................................61514.4.4 _gettz ...................................................................................................................61614.4.5 _isdaylight ............................................................................................................61714.4.6 _isdev ..................................................................................................................61814.4.7 _isdst ...................................................................................................................61914.4.8 _sblockcontrbrk....................................................................................................62014.4.9 _sbrk ....................................................................................................................62114.4.10 _strerror ...............................................................................................................62214.4.11 _tmpnampfx .........................................................................................................62314.4.12 AngelSWI.............................................................................................................62414.4.13 ARMSystemCall...................................................................................................62514.4.14 close ....................................................................................................................62614.4.15 creat .....................................................................................................................62714.4.16 ioctl ......................................................................................................................62814.4.17 lseek ....................................................................................................................62914.4.18 open.....................................................................................................................63014.4.19 read......................................................................................................................63114.4.20 write .....................................................................................................................632

15 The C++ Run-Time Library........................................................................................................633

15.1 Global Symbols.................................................................................................................63415.1.1 C++ Defined Library Functions ............................................................................63415.1.2 C++ Support Functions........................................................................................63515.1.3 C++ Internal Library Symbols ..............................................................................636

15.2 Thread-Local Exception Handling.....................................................................................64015.2.1 Implementation ....................................................................................................640


Contents

15.2.2 Access to the C++ TLS........................................................................................ 64215.3 Thread-Safe I/O Stream Library ....................................................................................... 64315.4 C++ Header Files..............................................................................................................644

15.4.1 C++ Header File exception.h ............................................................................... 64515.4.2 C++ Header File libcxx.h ..................................................................................... 64615.4.3 C++ Header File libfatal.h ....................................................................................64815.4.4 C++ Header File new.h........................................................................................ 65015.4.5 C++ Header File rtti.h ..........................................................................................65115.4.6 C++ Header File stdexcept.h ............................................................................... 65215.4.7 C++ Header File typeinfo.h.................................................................................. 653

15.5 Run-Time Library Functions ............................................................................................. 65415.5.1 __cxx_disable_critical_section_lock .................................................................... 65415.5.2 __cxx_enable_critical_section_lock..................................................................... 65515.5.3 __cxx_enter_critical_section................................................................................ 65615.5.4 __cxx_exit_critical_section .................................................................................. 65715.5.5 __cxx_share_critical_section_lock ...................................................................... 65815.5.6 __cxx_tls_alloc_hook........................................................................................... 65915.5.7 __cxx_tls_delete .................................................................................................. 66015.5.8 __cxx_tls_delete_hook ........................................................................................ 66115.5.9 __cxx_tls_delete_root_hook ................................................................................ 66215.5.10 __cxx_tls_exit_hook ............................................................................................ 66315.5.11 __cxx_tls_free_hook............................................................................................ 66415.5.12 __cxx_tls_get_hook ............................................................................................. 66515.5.13 __cxx_tls_get_root............................................................................................... 66615.5.14 __cxx_tls_init .......................................................................................................66715.5.15 __cxx_tls_init_hook ............................................................................................. 66815.5.16 __cxx_tls_set .......................................................................................................66915.5.17 __cxx_tls_set_hook ............................................................................................. 67015.5.18 __cxx_tls_setup ................................................................................................... 67115.5.19 __cxx_tls_size ..................................................................................................... 67215.5.20 __lib_assert__ ..................................................................................................... 67315.5.21 __lib_fatal__ ........................................................................................................ 67415.5.22 __lib_fatal_default_terminate_routine.................................................................. 67515.5.23 __pure_virtual_called........................................................................................... 67615.5.24 _main ................................................................................................................... 67715.5.25 operator delete, operator delete [ ] ...................................................................... 67815.5.26 operator new, operator new [ ].............................................................................67915.5.27 set_new_handler .................................................................................................68015.5.28 set_terminate .......................................................................................................68115.5.29 set_unexpected ................................................................................................... 68215.5.30 terminate..............................................................................................................68315.5.31 uncaught_exception............................................................................................. 68415.5.32 unexpected .......................................................................................................... 685

15.6 Callout Functions ..............................................................................................................68615.6.1 __cxx_tls_create_callout ..................................................................................... 68615.6.2 __cxx_tls_kill_callout ........................................................................................... 68715.6.3 __cxx_tls_restart_callout ..................................................................................... 68815.6.4 __cxx_tls_switch_callout ..................................................................................... 689


Contents

16 Intel® Wireless MMX™ Technology Intrinsic Support ...........................................................691

16.1 Intel® Wireless MMX™ Technology Data Types ..............................................................69216.1.1 New Data Types Usage Guidelines.....................................................................692

16.2 Naming and Usage Syntax ...............................................................................................69316.2.1 Intrinsic Syntax ....................................................................................................693

16.3 Intel® Wireless MMX™ Technology Arithmetic Intrinsics .................................................69416.3.1 _mm_add_pi8 ......................................................................................................69516.3.2 _mm_add_pi16 ....................................................................................................69616.3.3 _mm_add_pi32 ....................................................................................................69616.3.4 _mm_adds_pi8 ....................................................................................................69616.3.5 _mm_adds_pi16 ..................................................................................................69616.3.6 _mm_adds_pi32 ..................................................................................................69616.3.7 _mm_adds_pu8 ...................................................................................................69716.3.8 _mm_adds_pu16 .................................................................................................69716.3.9 _mm_adds_pu32 .................................................................................................69716.3.10 _mm_sub_pi8 ......................................................................................................69716.3.11 _mm_sub_pi16 ....................................................................................................69716.3.12 _mm_sub_pi32 ....................................................................................................69816.3.13 _mm_subs_pi8 ....................................................................................................69816.3.14 _mm_subs_pi16 ..................................................................................................69816.3.15 _mm_subs_pi32 ..................................................................................................69816.3.16 _mm_subs_pu8 ...................................................................................................69816.3.17 _mm_subs_pu16 .................................................................................................69916.3.18 _mm_subs_pu32 .................................................................................................69916.3.19 _mm_madd_pi16 .................................................................................................69916.3.20 _mm_madd_pu16................................................................................................69916.3.21 _mm_mulhi_pi16 .................................................................................................69916.3.22 _mm_mulhi_pu16 ................................................................................................70016.3.23 _mm_mullo_pi16 .................................................................................................70016.3.24 _mm_mac_pi16 ...................................................................................................70016.3.25 _mm_mac_pu16 ..................................................................................................70116.3.26 _mm_macz_pi16 .................................................................................................70116.3.27 _mm_macz_pu16 ................................................................................................70116.3.28 _mm_acc_pu8 .....................................................................................................70116.3.29 _mm_acc_pu16 ...................................................................................................70116.3.30 _mm_acc_pu32 ...................................................................................................70216.3.31 _mm_mia_si64 ....................................................................................................70216.3.32 _mm_miaph_si64 ................................................................................................70216.3.33 _mm_miabb_si64 ................................................................................................70216.3.34 _mm_miabt_si64 .................................................................................................70216.3.35 _mm_miatb_si64 .................................................................................................70316.3.36 _mm_miatt_si64 ..................................................................................................703

16.4 Intel® Wireless MMX™ Technology Shift Intrinsics ..........................................................70416.4.1 _mm_sll_pi16.......................................................................................................70516.4.2 _mm_slli_pi16......................................................................................................70516.4.3 _mm_sll_pi32.......................................................................................................70516.4.4 _mm_slli_pi32......................................................................................................70516.4.5 _mm_sll_si64.......................................................................................................70516.4.6 _mm_slli_si64 ......................................................................................................70516.4.7 _mm_sra_pi16 .....................................................................................................706


Contents

16.4.8 _mm_srai_pi16 .................................................................................................... 70616.4.9 _mm_sra_pi32 ..................................................................................................... 70616.4.10 _mm_srai_pi32 .................................................................................................... 70616.4.11 _mm_sra_si64 ..................................................................................................... 70616.4.12 _mm_srai_si64 .................................................................................................... 70616.4.13 _mm_srl_pi16 ...................................................................................................... 70716.4.14 _mm_srli_pi16 ..................................................................................................... 70716.4.15 _mm_srl_pi32 ...................................................................................................... 70716.4.16 _mm_srli_pi32 ..................................................................................................... 70716.4.17 _mm_srl_si64 ...................................................................................................... 70716.4.18 _mm_srli_si64...................................................................................................... 70716.4.19 _mm_ror_pi16...................................................................................................... 70816.4.20 _mm_ror_pi32...................................................................................................... 70816.4.21 _mm_ror_si64...................................................................................................... 70816.4.22 _mm_rori_pi16..................................................................................................... 70816.4.23 _mm_rori_pi32..................................................................................................... 70816.4.24 _mm_rori_si64 ..................................................................................................... 708

16.5 Intel® Wireless MMX™ Technology Logical Intrinsics...................................................... 70916.5.1 _mm_and_si64 .................................................................................................... 70916.5.2 _mm_andnot_si64 ............................................................................................... 70916.5.3 _mm_or_si64 .......................................................................................................70916.5.4 _mm_xor_si64 ..................................................................................................... 709

16.6 Intel® Wireless MMX™ Technology Compare Intrinsics .................................................. 71016.6.1 _mm_cmpeq_pi8 .................................................................................................71016.6.2 _mm_cmpeq_pi16 ............................................................................................... 71016.6.3 _mm_cmpeq_pi32 ............................................................................................... 71116.6.4 _mm_cmpgt_pi8 .................................................................................................. 71116.6.5 _mm_cmpgt_pi16 ................................................................................................ 71116.6.6 _mm_cmpgt_pi32 ................................................................................................ 71116.6.7 _mm_cmpgt_pu8 .................................................................................................71116.6.8 _mm_cmpgt_pu16 ............................................................................................... 71216.6.9 _mm_cmpgt_pu32 ............................................................................................... 712

16.7 Intel® Wireless MMX™ Technology PACK/UNPACK Intrinsics .......................................71316.7.1 _mm_packs_pi16.................................................................................................71416.7.2 _mm_packs_pi32.................................................................................................71416.7.3 _mm_packs_pu16 ............................................................................................... 71416.7.4 _mm_unpackhi_pi8.............................................................................................. 71416.7.5 _mm_unpackhi_pi16............................................................................................ 71416.7.6 _mm_unpackhi_pi32............................................................................................ 71516.7.7 _mm_unpacklo_pi8.............................................................................................. 71516.7.8 _mm_unpacklo_pi16............................................................................................ 71516.7.9 _mm_unpacklo_pi32............................................................................................ 71516.7.10 _mm_packs_si64.................................................................................................71516.7.11 _mm_packs_su64................................................................................................ 71616.7.12 _mm_packs_pu32 ............................................................................................... 71616.7.13 _mm_unpackeh_pi8 ............................................................................................ 71616.7.14 _mm_unpackeh_pi16 ..........................................................................................71616.7.15 _mm_unpackeh_pi32 ..........................................................................................71616.7.16 _mm_unpackeh_pu8 ........................................................................................... 71716.7.17 _mm_unpackeh_pu16 ......................................................................................... 717


Contents

16.7.18 _mm_unpackeh_pu32 .........................................................................................71716.7.19 _mm_unpackel_pi8..............................................................................................71716.7.20 _mm_unpackel_pi16............................................................................................71716.7.21 _mm_unpackel_pi32............................................................................................71716.7.22 _mm_unpackel_pu8 ............................................................................................71816.7.23 _mm_unpackel_pu16 ..........................................................................................71816.7.24 _mm_unpackel_pu32 ..........................................................................................718

16.8 Intel® Wireless MMX™ Technology Set Intrinsics ............................................................71916.8.1 _mm_setzero_si64 ..............................................................................................72016.8.2 _mm_set_pi32 .....................................................................................................72016.8.3 _mm_set_pi16 .....................................................................................................72016.8.4 _mm_set_pi8 .......................................................................................................72116.8.5 _mm_set1_pi32 ...................................................................................................72116.8.6 _mm_set1_pi16 ...................................................................................................72116.8.7 _mm_set1_pi8 .....................................................................................................72216.8.8 _mm_setr_pi32 ....................................................................................................72216.8.9 _mm_setr_pi16 ....................................................................................................72216.8.10 _mm_setr_pi8 ......................................................................................................72316.8.11 _mm_setwcx........................................................................................................72316.8.12 _mm_getwcx........................................................................................................723

16.9 Intel® Wireless MMX™ Technology General Support Intrinsics .......................................72416.9.1 _mm_extract_pi8 .................................................................................................72516.9.2 _mm_extract_pi16 ...............................................................................................72616.9.3 _mm_extract_pi32 ...............................................................................................72616.9.4 _mm_extract_pu8 ................................................................................................72616.9.5 _mm_extract_pu16 ..............................................................................................72716.9.6 _mm_extract_pu32 ..............................................................................................72716.9.7 _mm_insert_pi8 ...................................................................................................72716.9.8 _mm_insert_pi16 .................................................................................................72816.9.9 _mm_insert_pi32 .................................................................................................72816.9.10 _mm_max_pi8 .....................................................................................................72816.9.11 _mm_max_pi16 ...................................................................................................72916.9.12 _mm_max_pi32 ...................................................................................................72916.9.13 _mm_max_pu8 ....................................................................................................72916.9.14 _mm_max_pu16 ..................................................................................................73016.9.15 _mm_max_pu32 ..................................................................................................73016.9.16 _mm_min_pi8 ......................................................................................................73016.9.17 _mm_min_pi16 ....................................................................................................73116.9.18 _mm_min_pi32 ....................................................................................................73116.9.19 _mm_min_pu8 .....................................................................................................73116.9.20 _mm_min_pu16 ...................................................................................................73216.9.21 _mm_min_pu32 ...................................................................................................73216.9.22 _mm_movemask_pi8...........................................................................................73216.9.23 _mm_movemask_pi16.........................................................................................73316.9.24 _mm_movemask_pi32.........................................................................................73316.9.25 _mm_shuffle_pi16 ...............................................................................................73316.9.26 _mm_avg_pu8 .....................................................................................................73416.9.27 _mm_avg_pu16 ...................................................................................................73416.9.28 _mm_avg2_pu8 ...................................................................................................73516.9.29 _mm_avg2_pu16 .................................................................................................735


Contents

16.9.30 _mm_sad_pu8 ..................................................................................................... 73616.9.31 _mm_sad_pu16 ................................................................................................... 73616.9.32 _mm_sada_pu8 ................................................................................................... 73616.9.33 _mm_sada_pu16 .................................................................................................73716.9.34 __mm_align_si64.................................................................................................73716.9.35 _mm_cvtsi64_m64............................................................................................... 73716.9.36 _mm_cvtm64_si64............................................................................................... 73816.9.37 _mm_cvtsi64_si32 ............................................................................................... 73816.9.38 _mm_cvtsi32_si64 ............................................................................................... 738

17 Diagnostics and Messages.......................................................................................................739

17.1 Overview........................................................................................................................... 74017.2 Diagnostics ....................................................................................................................... 741

17.2.1 Command Line Diagnostics................................................................................. 74117.2.2 Language Diagnostics ......................................................................................... 74217.2.3 Controlling the Severity of the Diagnostics ..........................................................743

17.3 Messages ........................................................................................................................ 74517.3.1 Compiler Information Messages .......................................................................... 74517.3.2 Diagnostic Messages..........................................................................................746

17.3.2.1 Remark Messages ............................................................................... 74617.3.2.2 Warning Messages .............................................................................. 74717.3.2.3 Error Messages....................................................................................747

Index ..................................................................................................................................................... 749

Tables1 Arguments for the Compiler........................................................................................................ 302 Input Files ................................................................................................................................... 323 Output files ................................................................................................................................. 334 Option Reference ....................................................................................................................... 385 Overview of Microsoft* Compatible Pragmas ............................................................................. 446 Overview of ARM* Compatible Pragmas.................................................................................... 447 Overview of GNU Compatible Pragmas ..................................................................................... 458 Environment Variables ............................................................................................................... 499 Options with Respect to Preprocessing......................................................................................5410 Defining Macros.......................................................................................................................... 5711 Predefined Macros ..................................................................................................................... 5812 Option Reference ....................................................................................................................... 6013 Effects of Option -Zi Combined with Optimization Options......................................................... 6714 Categories of Options................................................................................................................. 7215 Language Options ......................................................................................................................7316 Preprocessor Options................................................................................................................. 7417 Precompiled Header Options ..................................................................................................... 7518 Optimization Options .................................................................................................................. 7619 Interprocedural Optimization Options ......................................................................................... 7720 Interprocedural Optimizations..................................................................................................... 7721 Error Handling Options ............................................................................................................... 8022 Code Generation Options........................................................................................................... 8123 Output File Options..................................................................................................................... 82


Contents

24 Debugging Options.....................................................................................................................8325 Options which Interrupt the Compilation Process.......................................................................8426 Miscellaneous Options................................................................................................................8527 Option -Qvec_report Parameters..............................................................................................15028 Optimization Options ................................................................................................................21829 Optimization Levels ..................................................................................................................21830 Optimization Restrictions ..........................................................................................................21931 Optimization Restrictions for Floating Point Arithmetic.............................................................22032 Interprocedural Optimizations..................................................................................................22233 Vectorization Options................................................................................................................23034 Language Support ....................................................................................................................24035 Extensions to ANSI/ISO Standard C Dialect ............................................................................25336 Macros Included with the Compiler...........................................................................................25537 Bit Position................................................................................................................................26138 Symbols being Used by Functions ...........................................................................................27339 Header Files .............................................................................................................................27940 Macros......................................................................................................................................27941 Functions for 32-bit Floating Point Numbers (float) ..................................................................52542 Functions for 64-bit Floating Point Numbers (double) ..............................................................52643 Functions for Integer Arithmetic................................................................................................52744 C++ Defined Library Functions .................................................................................................63445 C++ Support Functions.............................................................................................................63546 C++ Internal Library Symbols ...................................................................................................63647 Overview of Intel® Wireless MMX™ Technology Arithmetic Intrinsics .....................................69448 Overview of Intel® Wireless MMX™ Technology Shift Intrinsics ..............................................70449 Overview of Intel® Wireless MMX™ Technology Logical Intrinsics ..........................................70950 Overview of Intel® Wireless MMX™ Technology Compare Intrinsics ......................................71051 Overview of Intel® Wireless MMX™ Technology PACK/UNPACK Intrinsics ...........................71352 Overview of Intel® Wireless MMX™ Technology Set Intrinsics ................................................71953 Intel® Wireless MMX™ Technology General Support Intrinsics ..............................................72454 Soft Error Severity Changes.....................................................................................................743

Revision History

Date Revision Description

April 2003 1.3 Release for the Intel® C++ Compiler version 1.1 or higher.

October 2003 2.0 Release for the Intel® C++ Compiler version 1.2 or higher.


Contents

This page intentionally left blank.


Introduction 1

The Intel® C++ Compiler is designed to build C/C++ embedded applications for the Intel® XScale™ Microarchitecture. The compiler processes C/C++ files and converts these files into the ELF/DWARF object format. The Intel® C++ Compiler supports the following features:

• C and C++ language.

• Creation of the ELF/DWARF object format.

• Command line options to control the compilation process.

• Creation of debug information.

The Intel® C++ Compiler is part of the Intel® C++ Development Tool Suite consisting of the following tools:

• Intel® Integrated Development Environment.

• Intel® C++ Compiler.

• Intel® Assembler.

• Intel® Linker.

• Intel® Library Manger.

• Intel® Object Converters.

• Intel® XDB Debugger.


Introduction

1.1 About this Manual

This is a user’s manual explaining how to use the Intel® C++ Compiler on Windows* host platforms. It provides information on how to get started with the Intel® C++ Compiler, how this compiler operates, and what capabilities it offers for high performance. You learn how to use the standard and advanced compiler optimizations to gain maximum performance of your application.

User Group This manual assumes that you are familiar with the C/C++ programming language and with the Intel® XScale™ Microarchitecture. You should also be familiar with the host computer’s operating system.

The manual contains the following chapters:

• Chapter 1, “Introduction” is this chapter. It also provides an overview of related documentation, requirements, and the manual’s conventions.

• Chapter 2, “General Usage” offers a brief description on how to use the Intel® C++ Compiler. The chapter describes the command line syntax, input and output files, the usage of the compiler, and the default behavior of the Intel® C++ Compiler.

• Chapter 3, “Compiler Options and Pragmas Quick Reference” provides a quick reference of options and pragmas supported by the Intel® C++ Compiler, which are listed in alphabetical order. For a functional grouping of the options refer to Chapter 6, “Compiler Options”.

• Chapter 4, “Customizing Compilation Environment” explains configuration files and response files. It also includes a description of used environment variables and the usage of include files.

• Chapter 5, “Customizing the Compilation Process” describes the compilation process when using the Intel® C++ Compiler, and how this can be customized. This includes using alternate tools and locations. The chapter contains many examples that underline the explanations.

• Chapter 6, “Compiler Options” describes all supported options in detail. The chapter provides an overview of options sorted with respect to their function. The main part of this chapter describes each option including an example in alphabetical order.

• Chapter 7, “Pragmas” describes all supported pragmas. Since the pragmas are all Microsoft* compatible only the syntax, a short description, and an example for each pragma is given.

• Chapter 8, “Assembly Language Output File” describes the creation of assembly language output files using the Intel® C++ Compiler

• Chapter 9, “Optimizations” contains the description of optimization features of the Intel® C++ Compiler.

• Chapter 10, “Vectorization” contains the description of the vectorizer (i.e. loop optimization).

• Chapter 11, “Language Conformance Options” describes the options controlling the C/C++ language conformance of the Intel® C++ Compiler.


Introduction

• Chapter 12, “The Intel® Library System” describes the startup modules together with the Intel® Libraries and their naming conventions.

• Chapter 13, “The C Standard Library” describes the C Standard Library used by the Intel® C++ Compiler. This library also includes the C Run-Time library.

• Chapter 14, “Library-Target System Interface” describes the target-dependent part of the libraries.

• Chapter 15, “The C++ Run-Time Library” describes the C++ Library used by the Intel® C++ Compiler.

• Chapter 16, “Intel® Wireless MMX™ Technology Intrinsic Support” describes the intrinsic support given for the wireless MMXTM Technology, which includes single instruction multiple data instructions.

• Chapter 17, “Diagnostics and Messages” describes command line as well as language diagnostics and all type of messages that might appear during compilation.


Introduction

1.2 Related Documentation

This section provides an overview of documents which supplement this manual. These are:

• Intel® Assembler Reference Manual, order number 278586

• Intel® Linker Manual, order number 278467

• Intel® Library Manager Manual, order number 278468

• Intel® Integrated Development Environment User’s Manual, order number 278469

Furthermore, Release Notes are provided. Release Notes contain features or changes of the product that are not documented in the corresponding manual. Release Notes are included in the documentation set of your installation.

There are a few other documents which provide related information. These are:

• ISO/IEC 9989:1990, Programming Languages–C

• ISO/IEC 14882:1998, Programming Languages–C++.

• The Annotated C/C++ Reference Manual, 3rd edition, Ellis, Margaret; Stroustrup, Bjarne, Addison Wesley, 1991.

• The C/C++ Programming Language, 3rd edition, 1997: Addison-Wesley Publishing Company, One Jacob Way, Reading, MA 01867.

• The C Programming Language, 2nd edition, Kernighan, Brian W.; Ritchie, Dennis W., Prentice Hall, 1988.

• C: A Reference Manual, 3rd edition, Harbison, Samual P.; Steele, Guy L., Prentice Hall, 1991.


Introduction

1.3 Requirements

To use the Intel® C++ Compiler, the following environment is required:

• Microsoft* Windows XP* Professional or Windows* 2000 Professional as host platform


Introduction

1.4 Compiler Limits

The table below shows the maximum size or number of each item that the Intel® C++ Compiler can process. All capacities shown in the table are tested values; the actual number could be greater than that shown.

Item Tested Values

Control structure nesting (block nesting). 512

Conditional compilation nesting. 512

Declarator modifiers. 512

Parenthesis nesting levels. 512

Significant characters, internal identifier. 2048

External identifier name length. 64K

Number of external identifiers/file. 128K

Number of identifiers in a single block. 2048

Number of macros simultaneously defined. 128K

Number of parameters to a function call. 512

Number of parameters per macro. 512

Number of characters in a string. 128K

Bytes in an object. 512K

Include file nesting depth. 512

Case labels in a switch. 32K

Members in one structure or union. 32K

Enumeration constants in one enumeration. 8192

Levels of structure nesting. 320


Introduction

1.5 Conventions

This manual uses several notational and typographical conventions to visually differentiate text, as shown in the following table.

Convention Description

Italics Italics identify variables and introduce new terminology. Titles of manuals are in italic font. Italics are used for emphasis.

Bold Used to specify something important.

Plain Courier Used to specify written code, options, and commands.

Italic Courier Used to specify parameters.

GUI-elements Elements of the graphical user interface are written in this style.

<> Filenames and function names to be defined are delimited by <>.

| Used to specify an alternative between several items.

,... Used to specify an item which may be repeated.

[ ] Used to specify optional items.

{ } Used to specify an optional item which may be repeated.

"[" "]" "{" "}" "|" Writing a metacharacter in quotation marks negates the syntactical meaning stated above; the character is taken as a literal. For example, the line"[" X "]" [ Y ]denotes the letter X enclosed in brackets, optionally followed by the letter Y.


Introduction



General Usage 2

This chapter contains a description on how to use the Intel® C++ Compiler. The chapter contains the following topics:

• Section 2.1, “Command Line Syntax” on page 30 describes how the Intel® C++ Compiler is called.

• Section 2.2, “Thumb* Mode” on page 31 describes how to invoke the compiler in Thumb* mode.

• Section 2.3, “Input Files” on page 32 provides an overview of input files that are recognized by the Intel® C++ Compiler.

• Section 2.4, “Output Files” on page 33 summarizes the compiler output files.

• Section 2.5, “Using the Intel® C++ Compiler Within the Intel® Integrated Development Environment” on page 34 describes the use of the Intel® C++ Compiler within the Intel® Integrated Development Environment.

• Section 2.6, “Default Behavior of the Intel® C++ Compiler” on page 35 describes all the defaults used by the Intel® C++ Compiler.


General Usage

2.1 Command Line Syntax

The compiler call may contain two types of command line arguments: source file arguments and option arguments. The Intel® C++ Compiler is started using the following command line syntax:

ccxsc {option} sourcefile {sourcefile}

The compiler arguments option and sourcefile must be separated by spaces. The order of the arguments is not mandatory. The following table describes the compiler arguments:

Table 1. Arguments for the Compiler

Compiler Argument Description Example

sourcefile Indicates an input file to be processed by the compiler.

The following rules apply to input files:

• You can specify an arbitrary number of input files.

• If you specify more than one input file, you must separate them with a space.

• The compiler recognizes input files with the extensions .c, .cc, .cpp, .cxx, .lib, .i, .o, and .s.

For further information on input files refer to Section 2.3, “Input Files” on page 32.

ccxsc x.c y.cpp z.o

option A string of one or more alphanumeric characters preceded by a dash (-).

The following rules apply to compiler options:

• Options are not required when invoking the compiler. Some options are set by default when you invoke the compiler.

• You can specify an arbitrary number of options.

• If you specify more than one option, you must separate each of them using spaces.

• Option names are case-sensitive.

• Options specified on the command line apply to all files.

• Options can take arguments in the form of filenames, strings, letters, or numbers.

• If a string includes spaces, it must be enclosed in quotation marks.

• Some compiler options can be turned off when the option is appended with a dash (-).

For further information on compiler options refer to Section 3.1, “Option Reference” on page 38 and Chapter 6, “Compiler Options”.

ccxsc -c -o outfile.o src.cpp


General Usage

2.2 Thumb* Mode

To invoke the Intel® C++ Compiler in Thumb* mode, use the invocation command ccxscthb instead of ccxsc. In this case, the preprocessor macro __thumb is defined and the default structure alignment is set to 1 byte for thumb.


General Usage

2.3 Input Files

The Intel® C++ Compiler recognizes files with the extensions listed in the table below:

Where only the compilation process takes place, see further information below, then an unrecognized file extension will result in an error message. Should the process go on to call the linking stage then files with unrecognized extensions are passed directly to the linker with no action being taken by the compiler.

Further Information:Section 6.3.10, “Options which Interrupt the Compilation Process” on page 84

Table 2. Input Files

Filename Interpretation Action

sourcefile.c C source file. Processed by the compiler.

sourcefile.ccsourcefile.cppsourcefile.cxx

C++ source file. Processed by the compiler.

file.a object library. Passed to the linker.

sourcefile.i C or C++ source preprocessed and expanded by the C++ preprocessor.

Processed by the compiler.

sourcefile.o compiled object file. Passed to the linker.

sourcefile.s assembly file. Passed to the assembler.


General Usage

2.4 Output Files

During the compilation of the file sourcefile, the Intel® C++ Compiler produces, or indirectly causes the production of, the following output files if the respective options are set:

Further Information:Section 3.1, “Option Reference” on page 38Chapter 6, “Compiler Options”

Table 3. Output files

Filename Contents Options

sourcefile.i Preprocessed C/C++ source file. -P

sourcefile.obj COFF object file. The option -c stops the compiling process upon producing the object file and linking is suppressed. The option -Fofilename specifies the alternate name filename for the object file.

-c, -Fofilename

sourcefile.o ELF/DWARF object file. The option -c stops the compiling process upon producing the object file and linking is suppressed. The option -ofilename specifies the alternate name filename for the object file.

-c -ofilename

sourcefile.map Linker map file. The option -Fm[filename] specifies the alternate name filename for the map file.

-Fm[filename]

sourcefile.x Executable file. The option -Fe[filename] specifies the alternate name filename for the executable file.

-Fe[filename]


General Usage

2.5 Using the Intel® C++ Compiler Within the Intel® Integrated Development Environment

Within the Intel® Integrated Development Environment (IDE), the Intel® C++ Compiler and the Intel® Assembler are used as single tools within a tool chain.This means the compiling process is stopped upon producing the an object file. After the object file has been produced, it is used as an input file for the next process in the Intel® IDE process list using the appropriate tool, for example the Intel® Linker.

Warning: Stopping the compilation process upon generating the object file is realized by using the compiler option -c. Do not remove the compiler option -c from the options list in the Build Manager dialog of the Intel® IDE, unless you know what you are doing, as this may produce unpredictable results!

Further Information:Intel® Integrated Development Environment User’s Manual


General Usage

2.6 Default Behavior of the Intel® C++ Compiler

This section provides an overview of the default behavior of the Intel® C++ Compiler.

2.6.1 General Default Behavior

If you do not specify any options on the command line when you invoke the Intel® C++ Compiler, the compiler behaves as follows:

• The compiler invokes default settings of all its options and sets any options specified in any configuration file. See Section 4.1, “Configuration Files” on page 48.

• The compiler searches for any “include” files.

• The compiler processes the source file(s) according to the filename extension (see Section 2.3, “Input Files” on page 32).

• The compiler uses ANSI with extensions (/Ze) for C/C++ source files.

• The compiler performs standard optimizations using the default /O2 option.

• The compiler displays error and warning messages.

• The compiler produces an executable file as output.

Note: If the compiler does not recognize any options, that option is ignored and a warning is displayed. See Chapter 17, “Diagnostics and Messages” for detailed descriptions about system messages.

2.6.2 Default Options

For all options set by default, please refer to Table 4, “Option Reference” on page 38.


General Usage

Figure 1. Compilation Process

source filesheader files

Intel® Compiler

= Source files = Tools

assembly files

Intel® Assembler

object files libraries

Intel® Linker

executable file

target system

downloaded

assembly files

*.cpp*.cxx

*.cc*.c

*.h

*.s

*.s

*.o *.a

*.x


Compiler Options and Pragmas Quick Reference 3

This chapter provides a quick overview of all supported options and pragmas of the Intel® C++ Compiler.

The chapter comprises the following sections:

• Section 3.1, “Option Reference” on page 38 lists the options in alphabetical order.

• Section 3.2, “Pragma Reference” on page 44 lists the pragmas in alphabetical order.


Compiler Options and Pragmas Quick Reference

3.1 Option Reference

This section provides a short reference of the options which are recognized by the Intel® C++ Compiler. All options are sorted in alphabetical order followed by a short description and the default. A detailed description of the most important options is provided in Chapter 6, “Compiler Options”.

Table 4. Option Reference

Option Description Default

-? Displays compiler options summary. See also Section 6.4, “Option -?” on page 86.

OFF

-Ba filename Used to specify the directory and filename of an alternative Assembler which is to be invoked from the compiler. By default this is set to be the standard Assembler within the Intel® C++ Software Development Tool Suite. See also Section 6.5, “Option -Ba” on page 87.

ON

-Bd The option -Bd outputs to the standard output “stdout” all the command line calls and options before execution. See also Section 6.6, “Option -Bd” on page 88.

OFF

-Bl Used to specify the directory and filename of an alternative Linker which is to be invoked from the compiler. By default this is set to be the standard Linker within the Intel® C++ Software Development Tool Suite. See also Section 6.7, “Option -Bl” on page 89.

ON

-Bz Outputs all the command line calls and options including those set within the configuration file, only. Does not continue with the Compilation process. See also Section 6.8, “Option -Bz” on page 90.

OFF

-C Places comments in preprocessed source output. See also Section 6.9, “Option -C” on page 91.

OFF

-c Stops the compilation process after an object file has been generated. See also Section 6.10, “Option -c” on page 92.

OFF

-Dname[=value] Defines a macro name and, optionally, associates it with the specified value. See also Section 6.11, “Option -D” on page 93.

n/a

-E Stops the compilation process after the C or C++ source files have been preprocessed, and writes the results to stdout. See also Section 6.16, “Option -Fe” on page 98.

OFF

-EP Stops the compilation process after the C or C++ source files have been preprocessed and writes the results to stdout. The #line directives are stripped (that is, not included in the output). Use -EP -P to preprocess to a file, omitting #line directives. See also Section 6.13, “Option -EP” on page 95.

OFF

-Fa[filename] Produces an assembly file with the specified name filename. See also Section 6.14, “Option -Fa” on page 96.

OFF

-FD Generates file dependencies. See also Section 6.15, “Option -FD” on page 97.

OFF

-Fe[filename] Produces an executable output file with the specified filename (or the default name a.out). Use this option to specify a filename other than that of the first source or object file on the command line. See also Section 6.16, “Option -Fe” on page 98.

ON



-FI{filenames} Instructs the preprocessor to include the filenames specified as header files. See also Section 6.17, “Option -FI” on page 99.

OFF

-Fo[filename] Specifies the name to be given to the object file. Only valid where a single source file occurs in the command line. See also Section 6.18, “Option -Fo” on page 100.

OFF

-Fp[filename] Provides an alternate filename for precompiled header files. See also Section 6.19, “Option -Fp” on page 101.

OFF

-Gy Packages functions to enable linker optimization. See also Section 6.20, “Option -Gy” on page 102.

ON

-H Defines the number of significant characters for public identifiers. See also Section 6.21, “Option -H” on page 103.

OFF

-HELP Displays compiler options summary. See also Section 6.16, “Option -Fe” on page 98.

OFF

-help Displays compiler options summary. See also Section 6.16, “Option -Fe” on page 98.

OFF

-Idirectory Specifies an additional directory to search for include files. See also Section 6.24, “Option -I” on page 106.

OFF

-J Makes the default char type unsigned. See also Section 6.25, “Option -J” on page 107.

OFF

-Kc++eh Enables C++ exception handling, also turns on option -rtti.See also Section 6.26, “Option -Kc++eh” on page 108.

OFF

-LD Generates a DLL. See also Section 6.27, “Option -LD” on page 109.

OFF

-LDd Generates a debug DLL. See also Section 6.28, “Option -LDd” on page 110.

OFF

-noBool Switch off data type bool. See also Section 6.29, “Option -noBool” on page 111.

OFF

-nologo Do not display compiler version information. See also Section 6.30, “Option -nologo” on page 112.

OFF

-O1 Optimizes for speed, but disables some optimizations that increase code size for small speed benefit. See also Section 6.31, “Option -O” on page 113.

OFF

-O2 Optimizes for speed. See also Section 6.31, “Option -O” on page 113.

ON

-O3 Enables high-level optimization. See also Section 6.31, “Option -O” on page 113.

OFF

-ofilename Defines the alternate name filename for the object file. See also Section 6.32, “Option -o” on page 114.

OFF

-Oa[-] Assume [not assume] no aliasing. See also Section 6.33, “Option -Oa” on page 115.

OFF





-Obnum Controls the compiler's inline expansion. The amount of inline expansion performed varies with the value of num as follows:

0: Disables inlining.

1: Enables inlining of functions declared with the __inline keyword. Also enables inlining according to the C++ language.

2: Enables inlining of any function.

However, the compiler decides which functions to inline. Enables interprocedural optimizations and has the same effect as -Qip. See also Section 6.34, “Option -Ob” on page 116.

-Ob1

-Od Disables optimizations. See also Section 6.35, “Option -Od” on page 117.

OFF

-Og Enables global optimizations. See also Section 6.36, “Option -Og” on page 118.

ON

-Oi[-] Enables [disables] inline expansion of standard library functions. See also Section 6.37, “Option -Oi” on page 119.

ON

-Op[-] Enables [disables] conformance to the ANSI C and IEEE 754 standards for floating point arithmetic. See also Section 6.38, “Option -Op” on page 120.

OFF

-Os Enables speed optimizations that do not increase code size. See also Section 6.39, “Option -Os” on page 121.

OFF

-Ot Enables all speed optimizations. See also Section 6.40, “Option -Ot” on page 122.

OFF

-Ow[-] Assumes no cross-function aliasing. See also Section 6.41, “Option -Ow” on page 123.

OFF

-Ox Enables maximum speed optimizations. See also Section 6.42, “Option -Ox” on page 124.

OFF

-Oy[-] Suppresses use of frame pointer. See also Section 6.43, “Option -Oy” on page 125.

OFF

-P Stops the compilation process after C or C++ source files have been preprocessed and writes the results to files named according to the compiler's default file-naming conventions. See also Section 6.44, “Option -P” on page 126.

OFF

-QA[-] Enables all predefined macros and assertions. See also Section 6.45, “Option -QA” on page 127.

ON

-QAname Associates a symbol name with the specified sequence of values. See also Section 6.46, “Option -QAname” on page 128.

OFF

-Qansi[-] Assumes conformance to the ANSI standard for C++. See also Section 6.47, “Option -Qansi” on page 129.

OFF

-QH Outputs list of include files in the order in which they occur, then stops the compilation process. See also Section 6.48, “Option -QH” on page 130.

OFF

-Qip Enables interprocedural optimizations for single file compilation. See also Section 6.49, “Option -Qip” on page 131.

OFF

-Qip_no_inlining Disables some inlining that would be assumed using group optimization options such as -Ob2 and -Qip. See also Section 6.50, “Option -Qip_no_inlining” on page 132.

OFF

-Qipo Enables multifile interprocedural optimizations over entire program. See also Section 6.51, “Option -Qipo” on page 133.

OFF





-Qipo_c Generates a multifile object file from the given source files. See also Section 6.52, “Option -Qipo_c” on page 134.

OFF

-Qipo_obj Forces the compiler to create real object files when used with -Qipo. See also Section 6.53, “Option -Qipo_obj” on page 135.

OFF

-Qipo_S Generates a multifile assembly file from the given source files. See also Section 6.54, “Option -Qipo_S” on page 136.

OFF

-Qlocation,tool,path Specifies alternative directory and filenames for the Assembler and Linker components to be invoked from the compiler. See also Section 6.55, “Option -Qlocation” on page 137.

OFF

-QM Generate lines of Makefile dependency information onto its standard output. See also Section 6.56, “Option -QM” on page 138.

OFF

-Qnobss_init Places variables initialized with 0 into DATA section within the assembly code. See also Section 6.57, “Option -Qnobss_init” on page 139.

OFF

-Qoption,tool,optlist Passes an option list to another tool in the compilation chain. See also Section 6.58, “Option -Qoption” on page 140.

OFF

-Qprec Improves floating point precision. See also Section 6.59, “Option -Qprec” on page 141

OFF

-Qprec_div Disables the floating point division-to-multiplication optimization. See also Section 6.60, “Option -Qprec_div” on page 142.

OFF

-QRinterwork-return Specifies that mixed ARM* and Thumb* functions are to be used. See also Section 6.61, “Option -QRinterwork-return” on page 143.

ON

-Qropi Enables position independent code PIC. See also Section 6.62, “Option -Qropi” on page 144.

OFF

-Qrwpi Enables position independent data (PID). See also Section 6.63, “Option -Qrwpi” on page 145.

OFF

-QRxscale Specifies that the application is to be run on the Intel® XScale™ Microarchitecture. See also Section 6.64, “Option -QRxscale” on page 146.

ON

-Qsox Adds settings of the compiler options and its version number into the executable file. See also Section 6.65, “Option -Qsox” on page 147.

OFF

-QTP Specifies the target processor for the compilation. See also Section 6.66, “Option -QTP” on page 148.

xsc1

-Qunroll[n] Specifies the maximum number of times to unroll a loop. Use n = 0 to disable unrolling. If n is not specified, the compiler automatically chooses the maximum number of times to unroll a loop. See also Section 6.67, “Option -Qunroll” on page 149.

ON

-Qvec_report Controls the vectorizer's level of diagnostic messages. See also Section 6.68, “Option -Qvec_report” on page 150.

1

-Qwd[num{,num}] Disables the specified warnings and remarks. See also Section 6.69, “Option -Qwd” on page 151.

OFF

-Qwe[num{,num}] Changes the specified warnings and remarks to errors. See also Section 6.70, “Option -Qwe” on page 152.

OFF

-Qwnnum Limits the number of errors displayed prior to aborting compilation. See also Section 6.71, “Option -Qwn” on page 153.

100





-Qwp_ipo Enables multifile interprocedural optimizations over entire program. See also Section 6.72, “Option -Qwp_ipo” on page 154.

OFF

-Qwr[num{,num}] Changes the specified warnings to remarks. See also Section 6.73, “Option -Qwr” on page 155.

OFF

-Qww[num{,num}] Changes the specified remarks to warnings. See also Section 6.74, “Option -Qww” on page 156.

OFF

-rtti Enables [disables] C++ Run-Time Type Information (RTTI).See also Section 6.75, “Option -rtti” on page 157.

OFF

-S Generates assembly files with .s suffix. See also Section 6.76, “Option -S” on page 158.

OFF

-TC Compiles all source or unrecognized file types as C source files. See also Section 6.77, “Option -TC” on page 159.

OFF

-Tcfilename Treats filename as a C source file. See also Section 6.78, “Option -Tc” on page 160.

OFF

-TP Compiles all source or unrecognized file types as C++ source files. See also Section 6.79, “Option -TP” on page 161.

OFF

-Tpfilename Treats filename as a C++ source file. See also Section 6.80, “Option -Tp” on page 162.

OFF

-Uname Suppresses any definition of a macro name. See also Section 6.81, “Option -U” on page 163.

n/a

-u Disables all predefined macros (other than those starting with "__") and assertions. See also Section 6.82, “Option -u” on page 164.

OFF

-Vstring Embeds version string in executable. See also Section 6.83, “Option -V” on page 165.

OFF

-W0 Displays only errors. See also Section 6.84, “Option -W” on page 166.

OFF

-W1,-W2,-W3 Specifies that error and warning messages are to be displayed. See also Section 6.84, “Option -W” on page 166.

ON

-W4 Specifies that error, warning, and remark messages are to be displayed. See also Section 6.84, “Option -W” on page 166.

OFF

-WX Changes all warnings to errors. See also Section 6.85, “Option -WX” on page 167.

OFF

-w Disables all warnings. Section 6.86, “Option -w” on page 168. OFF

-X Removes the standard directories from the list of directories to be searched for include files. See also Section 6.87, “Option -X” on page 169.

OFF

-Yc[hfile] Creates a precompiled header file. See also Section 6.88, “Option -Yc” on page 170.

OFF

-Yu[hfile] Uses a precompiled header file. See also Section 6.89, “Option -Yu” on page 172.

OFF

-YX Enables automatic precompiled header file creation and usage. See also Section 6.90, “Option -YX” on page 174.

OFF

-Za Enforces strict conformance to the ANSI standard for C. See also Section 6.91, “Option -Za” on page 176.

OFF

-Zd Adds line number information in the object file (for debugging). See also Section 6.92, “Option -Zd” on page 177.

OFF





Further Information:Chapter 6, “Compiler Options”

-Ze Accepts extended C language. See also Section 6.93, “Option -Ze” on page 178.

ON

-Zg Instructs the compiler to output the list of function prototypes for all the functions found within the source files to be compiled. See also Section 6.94, “Option -Zg” on page 179.

OFF

-Zi Generates symbolic debugging information in the object code for use by source-level debuggers. See also Section 6.95, “Option -Zi” on page 180.

OFF

-Zpnum Specifies alignment of structure members. See also Section 6.96, “Option -Zp” on page 181.

8

-Zs Checks the syntax of a program and stops the compilation process after the source files have been parsed. Generates no code and produces no output files. Warnings and messages appear on stderr. See also Section 6.97, “Option -Zs” on page 182.

OFF





3.2 Pragma Reference

Some options may be passed as pragma directives to the Intel® C++ Compiler. Pragma directives look like C/C++ preprocessor directive lines. They must be contained in the source file or in an include file. Hence, pragmas are very closely connected to the source. They should be used if a correct compilation of the source depends on the pragma.

The following tables provide an overview ARM* compatible and GNU compatible pragmas.

Table 5. Overview of Microsoft* Compatible Pragmas

Pragma Description

#pragma alloc_text Specifies a text section where function definitions are located.

#pragma bss_seg Specifies a default section for uninitialized data.

#pragma code_seg Specifies a default code section for functions.

#pragma comment Puts a comment into an object file or executable file.

#pragma component Specifies the collecting of browse information.

#pragma const_seg Specifies a default section for constant data.

#pragma data_seg Specifies a default section for initialized and uninitialized data.

#pragma function Generates calls to the functions listed in the argument list.

#pragma hrdstop The compilation status up to the pragma location will be saved.

#pragma include_alias Enabled to use a short filename instead of a long filename.

#pragma intrinsic Generates calls to functions listed in the argument list.

#pragma message Sends a literal string to the standard output at compile time.

#pragma optimize Specifies compiler optimizations.

#pragma pack Specifies packing alignment for structure and union members.

#pragma warning Controls the behavior of warning messages.

Table 6. Overview of ARM* Compatible Pragmas

Pragma Description

#pragma check_stack

#pragma debug

#pragma ospace

#pragma otime

#pragma onum

#pragma softp_linkage



Table 7. Overview of GNU Compatible Pragmas

Pragma Description

#pragma align

#pragma isr

#pragma section


Customizing Compilation Environment4

The Intel® C++ Compiler allows you customize the environment used during compilation. This chapter includes the following:

• Section 4.1, “Configuration Files” on page 48 describes the files for storing frequently used option sets.

• Section 4.2, “Environment Variables” on page 49 describes each environment variable which is used by the compiler.

• Section 4.3, “Response Files” on page 51 describes how Response files could be used for storing specific options for various projects.

• Section 4.4, “Include Files” on page 52 describes the path and options to use for Include Files.


Customizing Compilation Environment

4.1 Configuration Files

The configuration files contain important settings of the Intel® C++ Compiler. The configuration files are read every time you run the compiler.

Warning: It is strongly recommend not to modify the supplied configuration files of the Intel® C++ Compiler. If you have varying option requirements for different projects, use response files to store these option settings (see Section 4.3, “Response Files” on page 51).

The configuration files provided with the Intel® C++ Compiler are as follows:

ccxsc.cfg

ccxscthb.cfg

These files are located in the same directory as the compiler executable file ccxsc.exe.



4.2 Environment Variables

You can customize your environment by specifying paths where the compiler can search for special files such as libraries, include files, and configuration files. This can be done by setting specific environment variables. Environment variables are variables of the shell/command interpreter from which the Intel® C++ Compiler is called.

The following table provides an overview of the environment variables used by the Intel® C++ Compiler.

4.2.1 Setting Environment Variables in the Command Line

To set environment variables, enter the command set on the command line followed by the variable and the path, for example:

set Path=c:\installation-directory\bin

4.2.2 Setting Environment Variables in Windows* 2000

To set and view environment variables on Windows* 2000, perform the following steps:

1. Select Settings from the Windows* Start menu.

2. Select Control Panel.

The Control Panel is opened.

3. Double-click System.

The System Properties dialog is opened.

4. Select the Advanced tab.

5. Click the Environment Variables button.

Now you can view and alter the environment variables.

Table 8. Environment Variables

Environment Variable Description

INCLUDE Specifies the directory search path for the include files.

LIB Specifies the directory search path for the libraries.

PATH Specifies the directory search path for the compiler itself.

TMP Specifies the directory for temporary file storage. If the directory specified by TMP does not exist, the compiler places the temporary files in the current directory.



4.2.3 Setting Environment Variables on Windows* XP

To set and view environment variables on Windows* XP, perform the following steps:

1. Select Control Panel from the Windows* Start menu.

The Control Panel is opened.

2. Double-click System.

The System Properties dialog is opened.

3. Select the Advanced tab.

4. Click the Environment Variables button.

Now you can view and alter the environment variables.



4.3 Response Files

Response files contain often-used command line options. This is useful to decrease the time for entering command line options and to ensure consistency of options.

The following rules apply to response files:

• You may write any valid command line option into a response file.

• You may also add comments to the response file. A line preceded by a pound (#) character is recognized as a comment.

• To use a response file, the compiler option @filename must be specified when invoking the compiler.

• You may use an unlimited number of response files, each filename of which must be preceded by an @.

When the compiler is run, it first replaces the response files with their contents. Then, the compiler processes the options in the order of appearance on the altered command line.

The following example illustrates the usage of a response file.

Example 1. Response File

The following command lines have the same effect:

ccxsc -Fomyfile -Zi hello.c

and one using a response file:

ccxsc @myresponsefile hello.c

where the response file myresponsefile has the following contents:

#Creating debug information-Zi

#Renaming object file to myfile-Fomyfile

Further Information:Section 3.1, “Option Reference” on page 38



4.4 Include Files

You can indicate the location of include files in the configuration file.

4.4.1 Specifying an Include Directory

Use the -Idirectory option to specify an additional directory in which to search for include files. For multiple search directories, multiple -Idirectory commands must be used.

For information on how the compiler handles file inclusion, please refer to Section 5.1.2, “Searching for Include Files” on page 56.

4.4.2 Preventing Search in Default Path

You can use the -X option with the -I option to prevent the compiler from searching the default path for include files and direct it to use an alternate path.

Example 2. Set Path for Include Files

To direct the compiler to search the path \alt\include instead of the default path, do the following:

ccxsc -X -I\alt\include newmain.cpp


Customizing the Compilation Process 5

This chapter describes how to customize the environment during compilation. The chapter comprises the following sections:

• Section 5.1, “Preprocessing” on page 54 describes how you can customize the preprocessing phase. You might set up comments in preprocessed files, stop compilation after preprocessing, set specific include paths, or specify macros for preprocessing.

• Section 5.2, “Compiling” on page 59 describes the Intel® C++ Compiler options that determine the compilation process and its output. The chapter contains examples demonstrating how you control compilation, monitor data settings, specify compilation output, and use the Intel® Assembler for code generation.

• Section 5.3, “Linking” on page 65 describes how you can customize the linking process.

• Section 5.4, “Debugging” on page 66 describes how you can customize your environment for debugging. This includes symbolic debugging as well as symbolic debugging in conjunction with optimization.


Customizing the Compilation Process

5.1 Preprocessing

The Intel® C++ Compiler provides several options to customize the preprocessing. You can define:

• Comments in preprocessed files

• Stop of compilation process after preprocessing

• Specific include paths

• Macros to be used during preprocessing

The table below lists all available options with respect to preprocessing. For a detailed description of each option, refer to Chapter 6, “Compiler Options”.

Table 9. Options with Respect to Preprocessing

Option Description

-C Preserves the comments in preprocessed source output.

-Dname[=value] Defines a macro name and associates it, optionally, with the specified value.

-E Stops the compilation process after the C or C++ source files have been preprocessed, and writes the results to stdout.

-EP Stops the compilation process after the C or C++ source files have been preprocessed and writes the results to stdout. The #line directives are stripped (that is, not included into the output). Use -EP -P to preprocess to a file, omitting #line directives.

-Idirectory Specifies an additional directory to search for include files.

-P Stops the compilation process after C or C++ source files have been preprocessed and writes the results to files named according to the compiler's default file-naming conventions.

-Uname Suppresses any previous definition of a macro name.

-u Disables all predefined macros (other than those starting with __ ) and assertions. See also Section 6.82, “Option -u” on page 164.



5.1.1 Preprocessing only

Both options -E and -P cause the Intel® C++ Compiler to stop after the preprocessing phase. When you specify the -E option, the compiler’s preprocessor expands your source module and writes the result to standard output. The preprocessed source contains #line directives, which the compiler uses to determine the source file name and line number during its next pass. For example, to preprocess two source files and write them to stdout, enter the following command:

ccxsc -E prog1.cpp prog2.cpp

When you specify the -P option, the preprocessor expands your source module and stores the result in a file in the current directory. The preprocessor uses the name of each source file with the .i extension (unless the output name is changed by the option -Fo). For example, the following command creates two files named prog1.i and prog2.i, which you can use as input to another compilation:

ccxsc -P prog1.cpp prog2.cpp

Warning: When you use the -P option, any existing files with the same name and extension are overwritten.

The -EP option can be used in combination with -E or -P. It directs the preprocessor to not include #line directives in the output. Specifying -EP alone is the same as specifying -E -EP.

The option -C preserves comments in the preprocessed source output. This option is useful only in connection with the option -E, -P or -EP.



5.1.2 Searching for Include Files

Include files can be specified in the source file using the #include preprocessor directive in one of the two following ways:

• #include <filename>

• #include "filename"

The compiler searches directories for include files in the following order:

For "filename" (implicit):

1. The compiler searches the include files in the source file directory.

2. The compiler searches the include files in all directories defined with the option -Idirectory. For multiple search directories, multiple -Idirectory commands must be used. Directories will be searched in the order given on the command line.

3. The compiler searches the include files in the compiler default include directory specified in the configuration file.

For <filename> (explicit):

1. The compiler searches the include files in all directories defined with the option -Idirectory. For multiple search directories, multiple -Idirectory commands must be used. Directories will be searched in the order given on the command line.

2. The compiler searches the include files in the compiler default include directory specified in the configuration file.

If you wish to change the standard directory to be searched for included files to another directory, use the following command line example:

Example 3. Change the Include Path

ccxsc -Ic:\incfiles -Ic:\alternative -X src\alpha.cpp

The C++ source file alpha.cpp is being compiled. Any include files specified within the source file are searched in the following order:

1. The source file directory src

2. The first directory specified by the -I option c:\incfiles

3. The second directory specified by the -I option c:\alternative

The default directory which is normally searched last for included files is ignored due to the use of the -X option.



5.1.3 Defining Macros

The Intel® C++ Compiler provides options to define macros as well as to disable previously defined macros. Table 11, “Predefined Macros” on page 58 lists all available options with respect to macro definition. For a detailed description of each option, refer to Chapter 6, “Compiler Options”.

The -Dname=[value] option defines the assertion and macro names to be used during preprocessing. This option has the same functionality as the #define preprocessor directive at the beginning of the source file. If you do not enter a value, name is set to 1. value should be enclosed in quotes if it contains spaces or special characters. Preprocessing replaces every occurrence of name with the specified value. For example, to define a macro called SIZE with the value 100, use the following command:

ccxsc -DSIZE=100 prog1.c

Suppose the program contains the declaration

float vector(SIZE);

Before the code is sent to the compiler, the value 100 replaces SIZE in this declaration, and in every other occurrence of the name SIZE.

The -Uname option suppresses any macro definition currently in effect for the specified name. The -U option performs the same function as an #undef preprocessor directive. For example, to suppress a macro called SIZE that was defined earlier, use the following command:

ccxsc -DSIZE=100 @optfile -USIZE prog1.c

The macro SIZE is defined to 100 while the response file optfile is being processed, but it is undefined while the source file prog1.c is being processed.

The -u option disables almost all of predefined macros listed in Table 11.

Table 10. Defining Macros

Option Description

Dname[=value] Defines a macro name and associates it with the specified value.

Uname Suppresses any definition of a macro name.

u Disables all predefined macros (other than those starting with __ ) and assertions.



All predefined macros are listed in Table 11. The Default column describes whether the macro is enabled (ON) or disabled (OFF) by default, plus a default value where applicable. The Disable column lists the option which disables the macro.

Table 11. Predefined Macros

Macro Name Default Disable Description / When Used

_CHAR_UNSIGNED OFF -u Makes the default character type unsigned. This macro is enabled if you specify the -J option.

__cplusplus ON/OFF Defined when compiling C++ source.

_CPPRTTI OFF -u Enables run-time type information. This macro is enabled when you specify -rtti.

_CPPUNWIND OFF -u Enables C/C++ exception handling. This macro is enabled if you specify the -Kc++eh option.

__EDG__ 1 Defined to have the value of 1.

_MT OFF -u Defined when using the C version of the multithread run-time library.

__INTEL_COMPILER version Defines the compiler version. Defined as, e.g., 600 for the Intel C/C++ Compiler 6.0. Always defined.

_WCHAR_T_DEFINED OFF -u This macro is defined whenever the wchar_t type is defined. This could be as a result of a definition in the compiled source.



5.2 Compiling

This section describes the Intel® C++ Compiler options that control the compilation process and its output. By default, the compiler converts source code to an object file. Appropriate options enable you to control the process and obtain the desired output file produced by the compiler.

Having control of the compilation process means, for example, that you can create an output file at any of the compilation phases with the -c, -E or -S options. Furthermore, you can name the output file or designate a set of options that are passed to the linker with the -Fe and -Fo options. If you specify a phase-limiting option, the compiler produces a separate output file representing the output of the last phase that completes for each primary input file.

The options in this section provide you with the following capabilities:

• Specifying compilation output

• Using the Intel® Assembler for code generation

Further Information:Section 2.3, “Input Files” on page 32Section 2.4, “Output Files” on page 33Section 2.6, “Default Behavior of the Intel® C++ Compiler” on page 35Section 5.3, “Linking” on page 65



5.2.1 Specifying Compilation Output

You can customize the compilation output depending on options you set or you do not set. The following options are available:

Further Information:Section 2.3, “Input Files” on page 32Section 2.4, “Output Files” on page 33

5.2.1.1 Default Output Files

The default command line does not include any options and has a C or C++ source file as its input argument:

ccxsc x.c

You can compile more than one input file:

ccxsc x.c y.c z.c

The above command will do the following:

• Compile and link three input source files.

• Produce three object files and assign the names of the respective source files: x.o, y.o, and z.o.

• Produce an executable file and assign the name of the first file in the command line to it, x.x.

• Place all the files in the current directory.



-Fe[filename] Produces an executable output file with the specified filename or the default name a.out if the filename is not specified.Use this option to specify filename other than that of the first source or object file in the command line. See also Section 6.16, “Option -Fe” on page 98.

ON

-Fo[filename] Specifies the name to be given to the object file. Only valid where a single source file occurs in the command line. See also Section 6.18, “Option -Fo” on page 100.

OFF

-TC Compiles all source file extensions as C source files. See also Section 6.77, “Option -TC” on page 159.

OFF

-TP Compiles all source file extensions as C++ source files. See also Section 6.79, “Option -TP” on page 161.

OFF

-Za Enforces strict conformance to the ANSI Standard for C. See also Section 6.91, “Option -Za” on page 176.

OFF



5.2.1.2 Specifying a Multifile Object

To produce a single relocatable object file from multiple sources and to give a specific name to this object file a specific name, use the following example command:

ccxsc -c -Qipo_c one.cpp two.cpp three.cpp

The produced relocatable multifile is named ipo_out.o, and can be used in the further linking stage by invoking the compiler again, with this example:

ccxsc ipo_out.o

Here the compiler recognizes that the given file is an object file and passes it to the linker.

If the several multifiles are required for a single project the name of previously generated multifile must be changed. Then they can be simply all linked together.



5.2.1.3 Using Non-standard Source File Extensions

To mix C/C++ source files having non-standard extension names with C++ source files having standard .cpp extension names, use the following example command:

ccxsc -calpha.px -TCbeta.qy -Tpgamma.cpp -TPdelta.cpp

The -TC option instructs the Intel® C++ Compiler to treat all given source files as C source files. This would include the given source files of gamma.cpp and delta.cpp both of which are actually C++ source file. To ensure that these two are treated as C++ sources and not as C sources the option -Tp is used twice, once for each source file.

The source files alpha.px and beta.qy are treated as if they were alpha.c and beta.c. The option -c interrupts the compilation process after relocatable object files are generated for each source file. This command assigns the base names of the source files to the object files generated followed by the extension .o. The result names will be alpha.o, beta.o, gamma.o and delta.o.

These files can be linked then by the following command line:

ccxsc alpha.o beta.o gamma.o delta.o

This command produces an executable file whose base name is the same as the first source file. The result name of the executable file is alpha.x.

Alternatively the executable could be generated directly with a single command line by leaving out the -c option.

ccxsc -TC alpha.px beta.qy -Tpgamma.cpp -Tpdelta.cpp

5.2.1.4 Specifying Executable Files

You can use the -Fe[filename] option to specify an alternate name for an executable file. This is especially useful when compiling and linking a set of input files. You can use the -Fe[filename] option to give the resulting file a name other than that formed from the base name of the first input file (source or object) in the command line, with an extension .o. In the example below, the command produces an executable file named outfile.exe as a result of compiling and linking three files: one object file and two C source files.

ccxsc -Feoutfile.exe file1.o file2.c file3.c

Without the -Fefilename option, the command above produces an executable file named file1.x.



5.2.1.5 Specifying Object Files

By default, the compiler always generates and stores object files in the current directory. You can use the -Fo[filename] option to specify an alternate name for an object file. For example:

ccxsc -Fofile.obj x.c

In the above example, -Fo assigns the name file.obj to an output object file rather than the default x.o.

If the filename is not specified, the -Fo option tells the compiler to use the base name of the source file with an extension of .o as the default object output filename.

5.2.1.6 Specifying Output Directories

Use the -Fe[filename] and -Fo[filename] options to specify a directory location for executable and object files.

To distinguish from the filename, the directory name must end in a backslash (\) character, and must name an existing directory. For example, -Femyexes\, -Fomyobjs\, -Famyasms\.

When directory name is specified, the compiler uses the default convention in naming the executable, assembly, and object files, and creates a corresponding file in the specified directory.

In the example below, the -Fe option causes the compiler to create the executable myprog.exe in the current directory. The -Fofilename option causes the compiler to create the object files a.obj, b.obj, and c.obj and place them in the directory obj_dir.

ccxsc -Femyprog -Foobj_dir\ a.c b.c c.c

You can specify alternate directory name arguments for each of the -Fe and -Fo options.

Note: If you specify both -Fefilename and -Fedirname\ in the same command line, the last -Fe option overrides previous -Fe options.



5.2.1.7 Using Standard ANSI C Code only

To produce object code from multiple source files which adhere strictly to the ANSI C standards, use the option -Za.

ccxsc -c -Za alpha.c beta.c gamma.c delta.c

The four C source files alpha.c, beta.c, gamma.c and delta.c are each taken in turn and compiled into individual object files. These object files will take the base names of their source files with an extension of .obj. These are alpha.obj, beta.obj, gamma.obj, and delta.obj.

These object files can then be linked when required using the command line below.

ccxsc alpha.obj beta.obj gamma.obj delta.obj

When a number of source files are to be linked together it is recommended that any strict adherence to the ANSI C standards be consistently applied to all the source files, not just to some of them. This prevents extension structures in one source file from attempting to be serviced by another source file where they are not allowed.

5.2.1.8 Generating a Function Prototype List

This section explains how to produce a list of function prototypes for all functions within the source file. The option to be used is -Zg. The list is written to the standard output stout and is useful to verify that the actual arguments and formal parameters of a function are compatible. The list can be saved by redirecting stout to a file.

ccxsc -Zg alpha.cpp

Function prototypes for all functions within the C++ source file alpha.cpp are generated, but compilation does not take place.

5.2.2 Using the Intel® Assembler to Produce Object Code

By default, the Intel® C++ Compiler automatically calls the Intel® Assembler and the Intel® Linker. The Intel® Assembler is called to generate the object file with the .o extension. The Intel® Assembler may be also used to assembly other assembler files to be added to your application. For more information on using the Intel® Assembler, refer to the Intel® Assembler Reference Manual.

If you want to stop the compilation after generating the assembly file, use the /S or /Qipo_S option.

Further Information:Intel® Assembler Reference Manual



5.3 Linking

Please refer to the linker documentation for a description of the supported options.



5.4 Debugging

This section describes the basic command line options that you can use to prove your compilation. The options in this section describe:

• Parsing for syntax only

• Support for symbolic debugging

• Debugging and optimizations

5.4.1 Parsing for Syntax Only

Use the -Zs option to stop processing source files after they have been parsed according to C/C++ language syntax rules. This option gives you a way to check quickly whether sources are syntactically correct. The compiler creates no output file. In the following example, the compiler checks a file named prog1.c. Any diagnostics appear on stdout.

ccxsc -Zs prog1.c

5.4.2 Support for Symbolic Debugging

Use the -Zi option to direct the compiler to generate code to support symbolic debugging. For example:

ccxsc -Zi prog1.c

Note: The compiler does not support the generation of debugging information in assembly files. If you specify the -Zi option with -Fa, the resulting object file will contain debugging information, but the assembly file will not. If you specify the -Zi option and later assemble the resulting assembly file, the resulting object file will not contain debugging information.



5.4.3 Symbolic Debugging and Optimizations

The -Zi option implicitly disables optimization, as if -Od was specified. You can overrun this by explicitly setting an optimization option.

Note: If you specify the -O1 or -O2 option with the -Zi option, some of the generated debug information may be inaccurate as a side-effect of optimization.

Table 13. Effects of Option -Zi Combined with Optimization Options

Option Combination Result

-Zi Debugging information produced, -Od and -Oy- set.

-Zi -O2 Debugging information produced, -O2 optimizations enabled.

-Zi -O2 -Oy Debugging information produced, -O2 optimizations enabled.

-Zi -Qip Limited debugging information produced, -Qip option enabled.


Compiler Options 6

This chapter provides a detailed description of the many compiler options supported by the Intel® C++ Compiler.

The chapter is divided into several parts:

• Section 6.1, “Introduction” on page 70 gives an introduction to options and where the options are introduced within the command line environment.

• Section 6.2, “Command Line Environment” on page 71 is used to explain the various locations where options may be found within the command line.

• Section 6.3, “Overview of Options” on page 72 gives a brief overview of the available options. These are grouped in categories, whose overall purpose is described, and any peculiarities explained. A list of options for each category is also given.

• Section 6.4-Section 6.97 describe each of the compiler options in detail. The options are listed in alphabetical order.


Compiler Options

6.1 Introduction

The Intel® C++ Compiler is invoked by a command line whose syntax is explained in Section 2.1, “Command Line Syntax” on page 30 and carries out the compilation process as detailed in Section 2.6, “Default Behavior of the Intel® C++ Compiler” on page 35. The command line includes arguments of source files and options which control the activity of this compilation process. However options may also occur in a number of other places within the command line environment; these are mentioned in Section 6.2, “Command Line Environment” on page 71.

There is a wide range of options available which include those for debugging, language interpretation, preprocessing and pre-compiled headers. As well as the normally expected optimization options there are a number of advanced options, for example, interprocedural optimizations. This powerful set of options allows the programmer to instruct the Intel® C++ Compiler to more exactly create an executable program, tailored to the hardware being used and the application required.


Compiler Options

6.2 Command Line Environment

The command line environment includes not only the actual command line itself but also the configuration file and any command files placed upon the command line. Options may occur in any one of these.

As well as source files the command line may also include response files, which are used to hold options. By this means overlong command lines with many options may be avoided, and often used options may be placed together in a single file for repeated use. The response file also has the advantage of being able to document what each option included within it is for. See also Section 4.3, “Response Files” on page 51.

There is also a configuration file, detailed in Section 4.1, “Configuration Files” on page 48, which is automatically invoked whenever the Intel® C++ Compiler is called. This file also holds options which are required when processing applications to make them compatible to the Intel® C++ Software Development Tool Suite. The configuration file is provided with the Intel® C++ Compiler.

When stating that an option is in the command line environment the option may occur in any one of the above locations; that is in the command line itself, a response file which is in the command line, or in the configuration file.

The Intel® C++ Compiler sets up its options in the order they appear in the command line environment. Therefore it is possible to turn certain defaults OFF and then ON again. For example the optimization option -O2 turns ON a number of specific optimization options. Should the user require some, but not all, to be set as OFF then the option for no optimization can be selected followed by those specifically required.

The order of evaluation is as follows:

1. The options setting in the configuration file is evaluated first.

2. The command line is then read from left to right. Any option file specified in the command line is treated as if its contents are written in the command line at the position of the filename.


Compiler Options

6.3 Overview of Options

The command line options of the Intel® C++ Compiler alter the behavior of the compilation process. The options can be grouped into a number of categories as shown in the table below:

The following sections describe the main features of each category, together with a list of category options.

Table 14. Categories of Options

Category Activities carried out by this category

Code Generation Modifies how code is to be generated.

Debugging Specifies any debugging information.

Error Handling Specifies the diagnostic behavior.

Interprocedural Optimizations Carries out Interprocedural Optimizations.

Language Specifies how the C/C++ language is to be interpreted.

Miscellaneous Miscellaneous options, which do not fit into any other category.

Optimization Enables any optimizations of the generated code.

Output Files Directs what output files are to be generated.

Pre-Compiled Headers Generates precompiled header files.

Preprocessor Directs how to handle the preprocessing stage.

Process Interrupt Interrupts the compilation process after a particular stage.


Compiler Options

6.3.1 Language Options

This category of options is available to specify how the C/C++ source files are to be interpreted. The -Zs option is used to check the syntax of given source files only; it quits the compilation process after the syntax check.

Table 15. Language Options

Option Activity Default

-noBool Disables the predefined type bool. OFF

-Qansi Assumes conformance to the ANSI standard for C++. OFF

-TC Specifies all source files on command line as C source. OFF

-Tc Specifies a given file to be treated as if it were a C source file. OFF

-TP Specifies all source files on command line as C++ source. OFF

-Tp Specifies a given file to be treated as if it were a C++ source file. OFF

-Za Enforces strict conformance to the ANSI standard for C. OFF

-Ze Accepts extended C language. ON

-Zg Instructs the compiler to output the list of function prototypes for all the functions found within the source files to be compiled.

OFF

-Zs Checks the syntax of a program and stops the compilation process after the source files have been parsed. Generates no code and produces no output files. Warnings and messages appear on sterr.

OFF


Compiler Options

6.3.2 Preprocessor Options

The preprocessor options specify how the preprocessor has to work. Options in this category are used to define or disable macro definitions, set up alternative include file directories, and to include header files into the source.

Table 16. Preprocessor Options


-C Places comments in preprocessed source output. OFF

-D Defines named macro, symbol, or constant. OFF

-E Stops compilation process after all C/C++ source files have been preprocessed, results are sent to the standard output stdout.

OFF

-EP Stops compilation process after all C/C++ source files have been preprocessed, results are sent to the standard output stdout. With #line directives stripped out.

OFF

-P Stops compilation process after all C/C++ source files have been preprocessed, results are sent to a file.

OFF

-QA Enables all predefined macros and assertions. ON

-QAname Associates a symbol name with the specified sequence of values. OFF

-FI Instructs preprocessor to treat the given filename as though it were an include file on the first line of every source file in the command line.

OFF

-I Specifies additional directories to be searched when resolving include statements. OFF

-U Disables named macro, symbol, or constant. OFF

-u Disables all macros, symbols, and constants. OFF

-X Removes standard directories from being searched when trying to resolve include statements.

OFF


Compiler Options

6.3.3 Precompiled Header Options

These options direct the generation and usage of precompiled header files.

Table 17. Precompiled Header Options


-Yc Creates a precompiled header file. OFF

-Yu Uses a precompiled header file. OFF

-YX Enables automatic precompiled header file creation and usage. OFF


Compiler Options

6.3.4 Optimization Options

This category has a number of options for directing the Intel® C++ Compiler on optimizing the resultant compiled code. As well as the normally expected optimizations within the code, such as eliminating unused variables, there are a number of others. These include the option -Ob which controls any inline expansion activity, where function calls are replaced with their contents when appropriate.

The option -Onum has several groups of optimization options preset to be ON. For example, -O1 sets a number of optimization options which will minimize generated code-size, and -O2 has a preset number of options set to optimize the speed of the generated code. By default, the option -O2 (optimize for speed) is set, together with several other optimizing options as shown in the table below.

If any optimization option is specifically selected in the command line environment then default optimizations are turned OFF, and if required must be specifically turned ON individually. This is true even if one of the default ON options is specified, all the other default ON options will be assumed OFF unless individually specified as ON.

Optimization can also be turned OFF by selecting the option -Od. Since options are set up in the order in which they are specified in the command line environment it is possible to use option -Od, to turn OFF optimization, and then to specify other individual optimization options as ON. This ensures that the user is setting the exact optimization regime that is required.

The last column of Table 18 shows ON if this option is switched on by default, or OFF if the option is switched off by default. However, the default settings of some options can be changed by other options. For example, the optimization option -O, is normally set to -O2 as default. However, should debugging information be required by setting option -Zd, or -Zi, the optimization option -Od (no optimization) is taken as the default optimization setting instead.

Table 18. Optimization Options


-O1 Optimizes for speed, but disables some optimizations that increase code size for small speed benefit. See also Section 6.31, “Option -O” on page 113.

OFF

-O2 Optimizes for speed. See also Section 6.31, “Option -O” on page 113.

ON

-O3 Enables high-level optimization. See also Section 6.31, “Option -O” on page 113.

OFF

-Ob Controls the inline expansion. ON option -Ob1

-Od Disables optimizations. OFF

(ON if option -Zi set)

-Og Enables global optimizations. ON

-Oi Enables inline expansion of standard library functions. ON

-Op Improves Floating Point consistency. OFF

-Os Enables speed optimizations that do not increase code size. OFF

-Ot Enables speed optimizations that might increase code size. ON


Compiler Options

6.3.5 Interprocedural Optimizations

A feature of the Intel® C++ Compiler is its ability to carry out optimizations across several procedures and functions within the program being compiled. This reduces unnecessary code and can create faster code. These options include:

The -Qip and -Qipo options enable interprocedural optimizations (IPO) to analyze your code to determine where you can benefit from the optimizations listed in tables that follow.

-Oa Assumes no Aliasing. OFF

-Ow Assumes no aliasing within functions. OFF

-Ox Uses maximum optimization. OFF

-Oy Omits frame pointers. OFF

-Qprec Improves floating point precision. OFF

-Qprec_div Disables the floating point division-to-multiplication optimization. OFF

-Qunroll Specifies maximum depth to unroll loops. ON



Table 19. Interprocedural Optimization Options


-Qip Single file interprocedural optimizations. Procedures within each source file are optimized across functions but only within each individual source file.

OFF

-Qipo Multiple file interprocedural optimizations. Procedures within all source files within the command line environment are optimized across functions.

OFF

-Qwp_ipo Synonym of option -Qipo. OFF

-Qipo_obj Multifile interprocedural optimizations must produce real object files. OFF

Table 20. Interprocedural Optimizations

Optimization Affected Aspect of Program

Inline function expansion Calls, jumps, branches, and loops.

Interprocedural constant propagation Arguments, global variables, and return values.

Monitoring module-level static variables Further optimizations, loop invariant code.

Dead code elimination Code size.

Propagation of function characteristics Call deletion and call movement.

Passing arguments in registers Calls, register usage.

Loop-invariant code motion Further optimizations, loop invariant code.

Multifile optimization Affects the same aspects as -Qip, but across multiple files.


Compiler Options

Inline function expansion is one of the main optimizations performed by the interprocedural optimizer. For function calls that the compiler believes are frequently executed, the compiler might decide to replace the instructions of the call with code for the function itself.

With -Qip, the compiler performs inline function expansion for calls to procedures defined within the current source file. However, when you use -Qipo to specify multifile IPO, the compiler performs inline function expansion for calls to procedures defined in separate files.

Caution: The -Qip, -Qipo and -Qwp_ipo options can in some cases significantly increase compile time and code size.

6.3.5.1 Multifile IPO

Multifile IPOs obtain potential optimization information from individual program modules of multifile programs. Using this information, the compiler performs optimizations across modules.

Building a program is divided into two phases: compilation and linkage. Multifile IPO performs different work depending on whether the compilation or linkage is being performed.

1. Compilation Phase. As each source file is compiled, multifile IPO stores an intermediate representation (IR) of the source code in a mock object file in a special comment section. Each mock object file contains the IR for its corresponding source file, but no real code or data. These mock objects must be linked using the -Qipo option with the compiler.

2. Linkage Phase. When you specify -Qipo, the compiler looks for the IR information in the mock object files.

6.3.5.1.1 Creating a Multifile IPO Executable with Compiler Command

This topic explains how to create a multifile IPO executable as follows in the examples below:

Compile your modules with -Qipo as follows:

1. Enter

ccxsc -Qipo -c a.c b.c c.c

The option -c stops the compilation after generating .o files. Each object file has the IR for the corresponding source file. With preceding results, you can now optimize interprocedurally:

2. Enter

ccxsc -Fenu_ipo_file -Qipo a.o b.o c.o

The -Fe option stores the executable in nu_ipo_file.exe. Multifile IPO is applied only to modules that have an IR, otherwise the object file passes to the link stage.


Compiler Options

For efficiency, combine steps 1 and 2:

ccxsc -Qipo -Fenu_ipo_file a.c b.c c.c

6.3.5.1.2 Analyzing the Effects of Multifile IPO

The -Qipo_c and -Qipo_S options are useful for analyzing the effects of multifile IPO, or when experimenting with multifile IPO between modules that do not make up a complete program.

Use the -Qipo_c option to optimize across files and produce an object file. This option performs optimizations as described for -Qipo, but stops prior to the final link stage, leaving an optimized object file. The default name for this file is ipo_out.o. You can use the -Fe option to specify a different name. For example:

ccxscce -Qipo_c -Fefile a.c b.c c.c

Use the -Qipo_S option to optimize across files and produce an assembly file. This option performs optimizations as described for -Qipo, but stops prior to the final link stage, leaving an optimized assembly file. The default name for this file is ipo_out.s. You can use the -Fe option to specify a different name. For example:

ccxsccw -Qipo_S -Fefile a.c b.c c.c


Compiler Options

6.3.6 Error Handling Options

These options specify how the Intel® C++ Compiler handles errors, warnings, and remarks.

Table 21. Error Handling Options


-Qvec_report Controls the vectorizer's level of diagnostic messages. 1

-Qwd Disables the specified warnings and remarks. OFF

-Qwe Changes the specified warnings and remarks to errors. OFF

-Qwn Limits the number of errors displayed prior to aborting compilation. 100

-Qwr Changes the specified warnings to remarks. OFF

-Qww Changes the specified remarks to warnings. OFF

-W Specifies what levels of warning messages to be generated. ON 1

-WX Changes all remarks to errors. OFF

-w Turns off all warning messages. OFF


Compiler Options

6.3.7 Code Generation Options

These options direct the Intel® C++ Compiler to modify the generated code.

Table 22. Code Generation Options


-rtti Enables C/C++ Run-Time Type Information (RTTI). OFF

-Kc++eh Enables C/C++ exception handling. OFF

-Gy Reorders functions at link time for efficiency. ON

-Qnobss_init Places variables initialized with 0 into DATA section within the assembly code.

OFF

-QRinterwork-return Specifies mixed ARM* and Thumb* instructions. OFF

-QRxscale Specifies that the application is to be run on the Intel XScale® microarchitecture.

ON

-Zp Specifies alignment of structure members 8 ON


Compiler Options

6.3.8 Output File Options

This category has options which manage output files. Some of these options direct output files to be generated, while others specify what output file names are to be used.

The options -Fa, -Fe, -Fo, and -Fp can optionally specify a filename, otherwise a default filename is used. Options -Qipo_c and -Qipo_S only use default filenames.

Option -Fo is unique and is used to specify the output filename, but its contents and default extension depend on how far the compilation process has progressed. For example if the compilation process completes then the file named is an executable file. If the compilation process is halted after relocatable object code has been generated the file named becomes an object file.

Options -Fa and -Fo relate to a single source file and cannot be used where multiple source files occur on the command line.

Table 23. Output File Options


-FD Generates file dependencies. OFF

-Fa Produces an assembly language listings file from the given source file. OFF

-Fe Specifies the name to be given to the executable file. OFF

-Fo Specifies the name to be given to the object file. Only valid where a single source file occurs in the command line.

OFF

-Fp Specifies the name to be given to a precompiler header. OFF

-LD Generates a DLL. OFF

-LDd Generates a debug DLL. OFF

-o Specifies the name of the output file. OFF

-Qipo_c Generates a multifile object file from the given source files. OFF

-Qipo_S Generates a multifile assembly file from the given source files. OFF


Compiler Options

6.3.9 Debugging Options

This category of options is available to enable debugging information to be generated by the Intel® C++ Compiler during the compilation process. The debugging information is included within the generated code, or within a special program database, and can be used by a debugger. The option -Zi includes the option -Zd so the two need not be used together. Selecting the option -Zi for complete symbolic debugging information also causes the optimization defaults to be altered.

Table 24. Debugging Options


-Zd Generates line number information in the object file (for debugging). OFF

-Zi Generates symbolic debugging information in the object code for use by source-level debuggers.

OFF


Compiler Options

6.3.10 Options which Interrupt the Compilation Process

By default the entire compilation process of Compiling-Assembling-Linking is carried out to produce an executable file. However, there are a number of options which can stop this sequence before it is completed, these are:

These options should not be used in combination with each other. However, if -c and -S are used together, the -S overrides -c. Indeterminate results occur with other combinations.

Table 25. Options which Interrupt the Compilation Process


-Bz Outputs the command line calls and options only, no output file is generated. OFF

-c Stops compilation after relocatable object code has been generated. OFF

-E Stops compilation process after all C/C++ source files have been preprocessed; results are sent to the standard output, stdout, with #line directives added.

OFF

-EP Stops compilation process after all C/C++ source files have been preprocessed; results are sent to the standard output, stdout.

OFF

-P As option -E, but the output is sent to an output file. OFF

-QH Outputs list of include file names only, no compilation carried out. OFF

-QM Generates include dependency information only (makefile style), no compilation is carried out.

OFF

-S Stops compilation after assembly code has been generated. OFF

-Zg Outputs list of function prototypes only, no compilation carried out. OFF

-Zs Checks syntax of source files only, no compilation carried out. OFF


Compiler Options

6.3.11 Miscellaneous Options

This category includes a diverse set of options which do not naturally belong to any other category. They include options to specify alternative assemblers and linkers, change the default source extensions and set warning message levels.

Table 26. Miscellaneous Options


-? Outputs a summary of the compiler options. OFF

-Ba Specifies directory and filename of the Assembler to be invoked from the compiler. By default this is set to be the standard assembler within the Intel® C++ Software Development Tool Suite.

ON

-Bd Outputs all the command line calls and options including those set within the configuration file. Carries out the compilation process.

OFF

-Bl Specifies which directory and filename of the linker to be invoked from the compiler. By default this is set to be the standard linker within the Intel® C++ Software Development Tool Suite.

ON

-H Sets maximum number of characters in symbol names. OFF

-HELP Outputs a summary of the compiler options. OFF

-help Outputs a summary of the compiler options. OFF

-J Makes default character types unsigned. OFF

-nologo Suppresses the display of compiler version information. ON

-Qlocation Specifies alternative directory and filenames for the assembler and linker components to be invoked from the compiler.

OFF

-QM Generates makefile dependency information for each source file. OFF

-Qoption Passes an option list to another tool in the compilation chain. OFF

-Qsox Adds settings of the compiler options and its version number into the executable file.

ON

-QTP Specifies the target processor for the compilation. xsc1

-S Stops the compilation process after assembly code has been generated. Does not go on to invoke assembler and linker.

OFF

-V Sets version string. OFF


Compiler Options

6.4 Option -?

Syntax: -?

Description: The option -? will generate an extensive list of all the Intel® C++ Compiler options currently available.

Alternative forms of this option are -HELP and -help.

This option is switched OFF by default.

Example 4. Option -?

To generate the usage information, use the following command:

ccxsc -?


Compiler Options

6.5 Option -Ba

Syntax: -Bafilename

Description: The option -Ba allows an alternative filename filename to be declared to the assembler. The filename can include a directory path.

By default the Intel® C++ Compiler is set up to point to the Intel® C++ Software Development Tool Suite.

Example 5. Option -Ba

To produce a relocatable object file using the alternative assembler of Brooks.exe use a command line of:

ccxsc -c -Bac:\binasms\Brooks.exe testing.c

Further Information:Section 6.7, “Option -Bl” on page 89Section 6.55, “Option -Qlocation” on page 137


Compiler Options

6.6 Option -Bd

Syntax: -Bd

Description: The option -Bd outputs to the standard output stdout all the command line calls and options, before execution. These include all options within the default configuration file as well.


Example 6. Option -Bd

To produce an executable file from the group of source files one.c, two.c and three.c, use the following command. Use of option -Bd causes all option settings to be sent out to stdout first, before execution.

ccxsc -Bd one.c two.c three.c

Further Information:Section 6.8, “Option -Bz” on page 90


Compiler Options

6.7 Option -Bl

Syntax: -Blfilename

Description: The option -Bl allows an alternative filename filename to be declared to the linker. The filename can include a directory path.

By default the Intel® C++ Compiler is set up to point to the Intel® C++ Software Development Tool Suite.

Example 7. Option -Bl

To produce an executable file Josepht.exe using the alternative linker Linkarbus.exe use a command line of:

ccxsc -FeJosepht -Blc:\linkers\Linkarbus.exe testing.c

Further Information:Section 6.5, “Option -Ba” on page 87Section 6.55, “Option -Qlocation” on page 137


Compiler Options

6.8 Option -Bz

Syntax: -Bz

Description: The option -Bz outputs to the standard output stdout all the command line calls and options, but does not execute them. These include all options within the default configuration file as well. This allows the user to check exactly what command calls and options are being applied before compiling.


Example 8. Option -Bz

To check what options are set, without actually carrying out the compilation, use the following command. Both the response file and default configuration files also hold option settings. The option settings are sent to stdout.

ccxsc -Bz @commandf.cmd one.c two.cpp

Further Information:Section 6.6, “Option -Bd” on page 88Section 6.10, “Option -c” on page 92Section 6.16, “Option -Fe” on page 98Section 6.48, “Option -QH” on page 130Section 6.56, “Option -QM” on page 138Section 6.76, “Option -S” on page 158Section 6.97, “Option -Zs” on page 182


Compiler Options

6.9 Option -C

Syntax: -C

Description: The option -C is used to preserve comment lines within the preprocessed output which is generated by using the -E, -EP or -P options. These options preprocess the original source file and place the result into either the standard output, or an output file. By default the comment lines are removed. If the -C option is set, the comment lines are kept.

This option is useful only in connection with the -E, -EP or -P options.


Further Information:Section 6.16, “Option -Fe” on page 98Section 6.13, “Option -EP” on page 95Section 6.44, “Option -P” on page 126


Compiler Options

6.10 Option -c

Syntax: -c

Description: The option -c stops the compilation process after an object file has been generated for each source file on the command line. This suppresses the implicit call to the linker, which must be called later to produce an executable file. Each generated object file takes on the name of the source file from which it was produced with an extension of .o.

Alternatively, should the Intel® C++ Compiler find a source file with an extension of .s then this is assumed to be an assembly file. In this case the Intel® C++ Compiler will invoke the Intel® Assembler to produce the object file.

The option -S overrides the option -c to generate assembly files only, with extensions of .s, from C/C++ source files only.

The -TC, -Tc, -TP, -Tp options can be used to force acceptance of source files as C/C++ sources with extensions other than .c and .cpp.

The option -c is switched OFF by default.

The -c option overrides the following options:

Example 9. Option -c

This command produces an object file named testing.o from a C source file of the same name:

ccxsc -c testing.c

Further Information:Section 6.6, “Option -Bd” on page 88Section 6.16, “Option -Fe” on page 98Section 6.48, “Option -QH” on page 130Section 6.56, “Option -QM” on page 138Section 6.76, “Option -S” on page 158Section 6.97, “Option -Zs” on page 182

-E -QH

-EP -QM

-P -Zs

-Fe (set by default, therefore -S and -Fe should not be used together)


Compiler Options

6.11 Option -D

Syntax: -Dname[=value]

Description: The option -D defines a macro name name and associates it with a specified value value, if given.


Multiple use of this option is allowed to define several macro names. The macro definitions on the command line and in the source file are processed in the following order:

1. All macro definitions on the command line, in the order of appearance

2. The macro definitions in the source file, as it is being processed

Example 10. Option -D

To produce an executable file from a C++ source file of trying.cpp where two macros need to be defined, use a command line of:

ccxsc @commandf.cmd trying.cpp

Where the response file commandf.cmd has the following contents:

#define macro named circle -Dcircle#define macro named parabola, and give it a value -Dparabola=45

Further Information:Section 6.17, “Option -FI” on page 99Section 6.24, “Option -I” on page 106Section 6.81, “Option -U” on page 163Section 6.82, “Option -u” on page 164Section 6.87, “Option -X” on page 169


Compiler Options

6.12 Option -E

Syntax: -E

Description: The option -E stops the compilation process after the C/C++ source files have been preprocessed, with the result being written out to the standard output device stdout. The output is identical to the original source, except that all preprocessor directives are carried out, conditional compilation resolved, and macros expanded. In addition, the -E option adds #line directives around those lines removed from the original source file, as being comments or conditionally not required, and around lines added from included files. This ensures that should the preprocessed output be submitted for final compilation any error and other messages will refer to line numbers within the original source.

To stop #line directives from being included, the -EP option can be used instead.

To place the preprocessing output lines within an output file, use the -P option.

All comments are removed from the output, unless option -C is used to preserve them.

This option stops the compilation process before it has completed and should not be used in combination with others which behave similarly such as -c, -QH, -QM and -S.


Example 11. Option -E

To preprocess a group of source files, with #line directives included, use the following command. No compilation is carried out.

ccxsc -E one.c two.cpp three.c

Further Information:Section 6.9, “Option -C” on page 91Section 6.16, “Option -Fe” on page 98Section 6.13, “Option -EP” on page 95Section 6.44, “Option -P” on page 126


Compiler Options

6.13 Option -EP

Syntax: -EP

Description: The option -EP stops the compilation process after the C/C++ source files have been preprocessed, with the result being written out to the standard output device stdout. The output is identical to the original source file except that all preprocessor directives are carried, conditional compilation resolved and macros expanded. Should the precompiled output be required to be resubmitted for final compilation then use -E option instead, which puts #line directives within the file.

To place the preprocessed output lines within an output file, use the -P option.




Further Information:Section 6.9, “Option -C” on page 91Section 6.16, “Option -Fe” on page 98Section 6.44, “Option -P” on page 126


Compiler Options

6.14 Option -Fa

Syntax: -Fa[filename]

Description: The option -Fa is used to specify the filename, and optionally the directory, of the assembly listings file as filename. If an extension is not given, the default of .s is used instead. The filename is optional and may be omitted, in which case the file takes up the default filename of the source file from which it was generated.

This option is not allowed where multiple source files are used on the command line.

If this option is not used and the compilation process is stopped after the compiler stage, the Intel® C++ Compiler will generate an assembly file with the extension of .s from each source file it finds on the command line. These assembly files take up the names of the source files from which they were generated.


Example 12. Option -Fa

To produce a relocatable object file named triangle.obj from the C source file trumpet.c, where an assembly listings file of triangle.lis is also required, use the following command. Should the listings file not be given an extension the default .s would be assumed.

ccxsc -c -Fatriangle.lis -Fotriangle.obj trumpet.c

Further Information:Section 6.76, “Option -S” on page 158Section 6.16, “Option -Fe” on page 98Section 6.18, “Option -Fo” on page 100Section 6.19, “Option -Fp” on page 101Section 6.32, “Option -o” on page 114Section 6.33, “Option -Oa” on page 115Section 6.52, “Option -Qipo_c” on page 134Section 6.54, “Option -Qipo_S” on page 136


Compiler Options

6.15 Option -FD

Syntax: -FD[filename]

Description: The option -FD is used to ensure that the most reliable dependency information is used when the executable is built.


Further Information:Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.18, “Option -Fo” on page 100Section 6.19, “Option -Fp” on page 101


Compiler Options

6.16 Option -Fe

Syntax: -Fe[filename]

Description: The option -Fe is used to specify the filename, and optionally the directory, of the output executable file as filename. If an extension is not given, the default of .exe is used instead. The filename is optional and may be omitted, in which case the file takes up the default filename a.out.

If this option is not used, the Intel® C++ Compiler will generate an executable file with a default filename having the same name as the first source file, or object file, it finds on the command line but with the extension of .exe.

Should the compile process not be taken to the executable stage, this option has no effect.

This option is switched ON by default.

Example 13. Option -Fe

To produce an executable file named warp.exe from several C/C++ source files, use the following command. The extension .exe in the executable filename is optional as this is the default extension.

ccxsc -Fewarp.exe one.c two.cpp three.c

Further Information:Section 6.8, “Option -Bz” on page 90Section 6.10, “Option -c” on page 92Section 6.14, “Option -Fa” on page 96Section 6.18, “Option -Fo” on page 100Section 6.19, “Option -Fp” on page 101Section 6.32, “Option -o” on page 114Section 6.33, “Option -Oa” on page 115Section 6.48, “Option -QH” on page 130Section 6.52, “Option -Qipo_c” on page 134Section 6.54, “Option -Qipo_S” on page 136Section 6.56, “Option -QM” on page 138Section 6.76, “Option -S” on page 158Section 6.97, “Option -Zs” on page 182


Compiler Options

6.17 Option -FI

Syntax: -FI[filename]

Description: The option -FI is used to instruct the preprocessor of the Intel® C++ Compiler to include the specified file filename as a header file at the top of every C/C++ source file in the command line environment. The filename can include a directory path, and may be used a multiple number of times on the same command line. Where multiple uses occur they are included in the order that they appear within the command line environment


Example 14. Option -FI

To produce an executable file named triangle.exe from several C source files, where an additional include file is required to be inserted at the top of all of them, use the following command. The header file insert.h is placed at the top of the source files one.c, two.c and three.c.

ccxsc -Fetriangle -FIinsert.h one.c two.c three.c

Further Information:Section 6.11, “Option -D” on page 93Section 6.24, “Option -I” on page 106Section 6.33, “Option -Oa” on page 115Section 6.81, “Option -U” on page 163Section 6.82, “Option -u” on page 164Section 6.87, “Option -X” on page 169


Compiler Options

6.18 Option -Fo

Syntax: -Fo[filename]

Description: The option -Fo is used to specify the filename, and optionally the directory, of the relocatable object file as filename. If an extension is not given, the default of .o is used instead. The filename is optional and may be omitted, in which case the file takes up the filename of the source file from which it was generated.


If this option is not used and the compilation process is stopped after the assembler stage, the Intel® C++ Compiler will generate an object file with the extension of .o from each source file it finds on the command line. These object files take up the names of the source files from which they were generated.


Example 15. Option -Fo

To produce a relocatable object file named triangle.o from a C source file of elipse.c the following command line will be required.

ccxsc -c -Fotriangle elipse.c

Further Information:Section 6.10, “Option -c” on page 92Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.19, “Option -Fp” on page 101Section 6.52, “Option -Qipo_c” on page 134Section 6.54, “Option -Qipo_S” on page 136


Compiler Options

6.19 Option -Fp

Syntax: -Fp[filename]

Description: The option -Fp is used to specify the filename, and optionally the directory, of a precompiled header file which is created by use of the debug options -YX, -Yc, and -Yu. If an extension is not given, the default of .pchi is used instead.



Example 16. Option -Fp

To produce a precompiled header file of infdat.pch from a source file of trumpet.c use the following command:

ccxsc -Zi -Yc -Fpinfdat.pch trumpet.c

Further Information:Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.18, “Option -Fo” on page 100Section 6.88, “Option -Yc” on page 170Section 6.89, “Option -Yu” on page 172Section 6.90, “Option -YX” on page 174


Compiler Options

6.20 Option -Gy

Syntax: -Gy

Description: The option -Gy is used to instruct the compiler to individually package functions. This allows the linker to exclude and order individual functions in an executable file (.EXE) or dynamic link library (DLL). Such packaged functions are referred to as COMDATs.


Example 17. Option -Gy

To generate an executable with ordered functions use the following command:

ccxsc -Gy alpha.cpp

Further Information:Section 6.75, “Option -rtti” on page 157Section 6.57, “Option -Qnobss_init” on page 139


Compiler Options

6.21 Option -H

Syntax: -Hnum

Description: The option -H sets the number of significant characters for public identifiers to its integer parameter, num. Public (i.e., external) identifiers may be longer than this limit, but only the first num characters are regarded and the rest of the identifier is ignored.

Note: The compiler may add characters like ’@’ or ’_’ to identifiers. These characters are counted as part of the name. C++ name mangling can also increase the name length. The limit num is compared against the name length after these changes took place.

By default, there is no length limit for public identifiers.

Example 18. Option -H

To set the limit for public identifiers to 20 characters, use the following command:

ccxsc - sourcefile.cpp


Compiler Options

6.22 Option -HELP

Syntax: -HELP

Description: The option -HELP will generate an extensive list of all the Intel® C++ Compiler options currently available.

Alternative forms of this option are -help and -?.


Example 19. Option -HELP

To generate the help information use the following command. Several pages of information are produced.

ccxsc -HELP

Further Information:Section 6.30, “Option -nologo” on page 112


Compiler Options

6.23 Option -help

Syntax: -help

Description: The option -help will generate an extensive list of all the Intel® C++ Compiler options currently available.

Alternative forms of this option are -HELP and -?.


Example 20. Option -help

To generate the help information use the following command. Several pages of information are produced.

ccxsc -help

Further Information:Section 6.30, “Option -nologo” on page 112


Compiler Options

6.24 Option -I

Syntax: -Idirectory

Description: The option -I specifies an additional directory directory in which to search for include files. There can be multiple instances of this option in the same command line environment.

When the Intel® C++ Compiler encounters an include reference within one of the source files the order of search is as follows:

• First search the directory of the source file containing the include.

• Then search the directories specified by the -I option.

• Finally search the default directories specified by the INCLUDE environment variable.


Example 21. Option -I

The following will first look into directory c:\installation-directory\incand for any include files before searching the default include directory. Note that in this example by default the Intel® C++ Compiler will invoke the linker to produce an executable file.

ccxsc -Ic:\installation-directory\incand test.cpp

Further Information:Section 6.11, “Option -D” on page 93Section 6.17, “Option -FI” on page 99Section 6.81, “Option -U” on page 163Section 6.82, “Option -u” on page 164Section 6.87, “Option -X” on page 169


Compiler Options

6.25 Option -J

Syntax: -J

Description: The option -J specifies that the Intel® C++ Compiler uses a default character type of unsigned char and not the usual character type of signed char.

Character data which are explicitly declared as signed will not be affected.

If this option is set, the preprocessor macro _CHAR_UNSIGNED is defined.


Example 22. Option -J

To produce a relocatable object file named hyper.o from a C++ source file hyper.cpp, where all default characters are to be of unsigned type, use the command line shown below. Note that a listings file is also produced as hyper.lis.

ccxsc -c -Fahyper.lis -J hyper.cpp

Further Information:Section 6.57, “Option -Qnobss_init” on page 139


Compiler Options

6.26 Option -Kc++eh

Syntax: -Kc++eh

Description: The option -Kc++eh enables C/C++ exception handling.

If this option is set, the preprocessor macro _CPPUNWIND is defined.

If this option is set, the option -rtti is also set.


Further Information:Section 6.75, “Option -rtti” on page 157Section 6.75, “Option -rtti” on page 157


Compiler Options

6.27 Option -LD

Syntax: -LD

Description: If the option -LD is set, the compiler tries to generate a DLL (Dynamic Link Library) from the source.

This option is switched off by default.

Example 23. Option -LD

To generate a DLL from the file dll.cpp, use the following command:

ccxsc -LD dll.cpp

Further Information:Section 6.28, “Option -LDd” on page 110


Compiler Options

6.28 Option -LDd

Syntax: -LDd

Description: If the option -LDd is set, the compiler tries to generate a debug DLL (Dynamic Link Library) from the source.


Example 24. Option -LDd

To generate a debug DLL from the file dll.cpp, use the following command:

ccxsc -LDd dll.cpp

Further Information:Section 6.27, “Option -LD” on page 109


Compiler Options

6.29 Option -noBool

Syntax: -noBool

Description: By default, the data type bool is predefined. The option -noBool switches off this predefinition; the type bool can be used only if explicitly defined.


Example 25. Option -noBool

To switch off the predefined type bool, use the following command:

ccxsc -noBool sourcefile.cpp


Compiler Options

6.30 Option -nologo

Syntax: -nologo

Description: The option -nologo suppresses the Intel® C++ Compiler declarative information which is normally generated at the start of any output. This information would include compiler version number and date of the compiler.


Example 26. Option -nologo

To produce an executable file named felix.exe from a C source file testing.c, where no logo information is required in the executable file, use a command line of:

ccxsc -Fefelix -nologo testing.c

Further Information:Section 6.65, “Option -Qsox” on page 147Section 6.84, “Option -W” on page 166Section 6.86, “Option -w” on page 168


Compiler Options

6.31 Option -O

Syntax: -O{1|2|3}

Description: The option -O specifies a predefined set of options which control any optimization of the compilation procedure for speed and size of code. The degree of optimization is controlled by the specified number as follows:

Optimization default condition depends on whether the debugging option -Zi is set:

• If -Zi is not set, optimization is set by default to be -O2.

• If -Zi is set, then optimization is turned off by default to be -Od.

Note: If more than one of the options -Od, -O1, -O2, -O3 is set, the compiler issues a warning message.

Example 27. Option -O

To produce an executable file named geometrics from a C source file of trying.c where optimization is required other than default -O2, use a command line of:

ccxsc -ogeometrics -O3 trying.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124

Number Description

1 Optimizes for speed, but disables some optimizations that increase code size for small speed benefits. This setting has the same effect as specifying the options -Og, -Oi, -Os, -Ob1,-Oy, -Gy.

2 Optimizes for speed. The Intel® C++ Compiler may re-associate floating point expressions to improve application performance. This setting has the same effect as specifying the options of -Og, -Oi, -Ot, -Ob1, -Gy, -Oy.

3 Enables high-level optimization, but this does not guarantee higher performance.


Compiler Options

6.32 Option -o

Syntax: -ofilename

Description: The option -o is used to specify the output file name (and path) filename which is either:

• If the option -S is specified, an assembly language file with an extension of .s.

• If the option -c is specified, a relocatable object file with an extension of .o.

• If neither option -S nor -c are specified, an executable file.

Alternatively, if the parameter filename includes an extension, the output file will take that extension. If this option is not set, then the output file takes the name of the source file with the appropriate extension.


Warning: If the Compiler generates more than one output file, all of them get the same name! In other words, the last one to be generated overwrites the other files!

Example 28. Option -o

To produce an executable file named geometrics from a C source file of trying.c, with debugging and run time information, use a command line of:

ccxsc -ogeometrics -Zi trying.c

Further Information:Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.52, “Option -Qipo_c” on page 134Section 6.54, “Option -Qipo_S” on page 136


Compiler Options

6.33 Option -Oa

Syntax: -Oa

Description: The option -Oa switches aliasing off. Aliasing is a technique whereby the compiler looks for variables which are redundant. For example they are not required since they only carry an intermediate temporary value within a set of calculations. Or two or more variables refer to the same value. Aliasing also looks for repeated assignment of variables with the same value within a loop, these would be assigned once outside the loop. Aliasing can slow down the run-time of your program by reducing variables and optimizing loops.

By default Aliasing is assumed on, so this option is by default OFF.

Example 29. Option -Oa

To produce an executable file named newoutput.exe from a C source file where aliasing is to be switched off, use a command line of:

ccxsc -Fenewoutput.exe -Oa scalding.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.34 Option -Ob

Syntax: -Obnum

Description: The option -Ob specifies the amount, if any, of function inline expansion which the Intel® C++ Compiler will carry out during its compilation procedure. Inline expansion is where the function call is replaced by the contents of the function itself. This saves having to call the function with all its inherent overheads in terms of time and code. The degree, if any, of inline expansion to be carried out is controlled by the specified parameter num as follows:

Should the number be omitted then this option is ignored.

The default condition for this option is -Ob1: Carry out inline expansion only on those functions specifically marked.

Example 30. Option -Ob

To produce an executable file named arithmetic.exe from a C++ source file of maths.cpp where inline expansion other than default -Ob1 is required, use a command line of:

ccxsc -Fearithmetic.exe -Ob2 maths.cpp

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124

0 Disables inline expansion. No inline expansion is carried out.

1 Compiler inlines only those functions declared with the __inline keyword, or as defined according to the C/C++ language. This is the default condition for this option.

2 Enables inline expansion of any function, although the Intel® C++ Compiler itself decides which functions to expand. This normally includes any that are specifically marked to be expanded by the __inline keyword.

This option also enables the interprocedural optimizations and has the same effect as -Qip.


Compiler Options

6.35 Option -Od

Syntax: -Od

Description: The option -Od specifies that there be no optimization within the compilation procedure.

To set up for a specific optimization regime it is necessary first to disable the default optimization settings before specifying the exact optimization options required. In this case the option -Od can be used followed by those optimization options required.

If the -Od and -O options are not specified, then the default optimization condition depends on whether the debugging option -Zi is set:

• If -Zi is not set, optimization is set by default to be -O2.

• If -Zi is set, then optimization is turned off by default to be -Od.

Note: If more than one of the options -Od, -O1, -O2, -O3 is set, the compiler issues a warning message.

Example 31. Option -Od

To produce an object file named geometrics from a C++ source file of trying.cpp where no optimization is to be used, use a command line of:

ccxsc -ogeometrics -Od trying.cpp

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.36 Option -Og

Syntax: -Og

Description: The option -Og enables global optimizations.With this option set the Intel® C++ Compiler eliminates multiple copies of common sub-expressions, removes invariant sub-expressions from the body of loops, and stores frequently used variables in registers wherever possible.


Example 32. Option -Og

To produce an executable file named arithmetic.exe from a C++ source file of maths.cpp where only global optimization is required, use the command line below. Note that use of option -Od turns off all optimizations including the option -Og, therefore -Og needs to be reset back ON.

ccxsc -Fearithmetic.exe -Od -Og maths.cpp

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.37 Option -Oi

Syntax: -Oi[-]

Description: The option -Oi enables the Intel® C++ Compiler to carry out inline expansion of the standard library functions. Inline expansion is where the function call is replaced by the contents of the function itself. This saves having to call the function with all its inherent overheads in terms of time and code.

Use of the -Op option disables this option, standard library functions being used instead.


Example 33. Option -Oi

To produce a relocatable object file total.obj from a C source file of mailing.c where only global and inline expansion optimizations are required, use the command line below. Note that use of option -Od turns off all optimizations including the options required, which must therefore be specifically turned back ON.

ccxsc -c -Fototal.obj -Od -Og -Oi mailing.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.38 Option -Op

Syntax: -Op[-]

Description: The option -Op improves the consistency of floating point tests for equality and inequality by disabling optimizations that could change the precision of floating point calculations.

Using the -Op option forces the compiler to load data from memory before each floating point operation, and if required store data back to memory at its end. Such actions ensure that the extra bits which would be held in an intermediate result are eliminated. This increases the code length of the program and reduces its speed.

Use of the -Op option disables any inline generation of floating point library functions which may have been enabled by the -Oi option. Instead standard library functions are used.

Setting the -Za option (disable language extensions) automatically sets the -Op option ON, however it may be disabled again by using the -Op- option after the -Za option on the command line.

Otherwise this option is switched OFF by default.

Example 34. Option -Op

To produce a relocatable object file purist.obj from a C source file selected.c where language extensions are turned off, as are any improved floating point consistency activities, use the command line below.

ccxsc -c -Fopurist.obj -Za -Op- selected.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.39 Option -Os

Syntax: -Os

Description: The option -Os enables the Intel® C++ Compiler to make speed optimizations which favor reduced code size. Some speed optimizations increase the code size, others do not. This option enables only optimizations which do not increase the code size.

Normally default optimization is handled by using the group optimization option -O2 which does not include -Os, so this option is switched OFF by default.

Example 35. Option -Os

To produce a relocatable object file total.obj from a C source file of mailing.c where speed optimizations which favor size of code are required, use the command line below. Note that use of option -Os automatically cancels all other default optimization options, so only the size option is set ON.

ccxsc -c -Fototal.obj -Os mailing.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.40 Option -Ot

Syntax: -Ot

Description: The option -Ot enables the Intel® C++ Compiler to make optimizations which favor speed of program execution. In general the compiler can make optimizations within its generated code which can favor either program speed or program size. This option allows the programmer to select in favor of program speed.

Normally default optimization is handled by using the group optimization option -O2 which includes -Ot, so this option is switched ON by default.

Example 36. Option -Ot

To produce an executable file random.exe from a C++ source file of numbers.cpp where optimizations which favour speed of code are required, use the command line below. Note that use of option -Ot automatically cancels all other default optimization options, so only the speed option is set ON.

ccxsc -Ferandom.exe -Ot numbers.cpp

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.41 Option -Ow

Syntax: -Ow[-]

Description: The option -Ow instructs the compiler not to assume aliasing across function calls. Aliasing is a technique whereby the compiler looks for variables which are redundant. For example they are not required since they only carry an intermediate temporary value within a set of calculations. Or two or more variables refer to the same value. Aliasing also looks for repeated assignment of variables with the same value within a loop, these would be assigned once outside the loop. Aliasing can reduce the run-time of your program by reducing variables and optimizing loops.

This option can be explicitly switched off by adding the optional - sign after it. The -Ow- option assumes no aliasing takes place within functions, but may take place across function calls. Pointer variables must be reloaded from memory after each function call.


Example 37. Option -Ow

To produce an executable file named fearless.exe from a C source file of geometry.c where cross function aliasing is required, use a command line of:

ccxsc -Fefearless.exe -Ow- geometry.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.42, “Option -Ox” on page 124


Compiler Options

6.42 Option -Ox

Syntax: -Ox

Description: The option -Ox instructs the Intel® C++ Compiler to use maximum optimizations to produce the fastest possible program.

This option has the same effect as combining the following optimization options:

• -Ob1 enables inlining of source functions

• -Og enables global optimizations

• -Oi enables inlining of library functions

• -Ot enables all speed optimizations

• -Oy omits frame pointer


This option is the same as /O2 without -Gy.

Example 38. Option -Ox

To produce an executable called purist.exe from a C source file of selected.c where the fastest possible program is required, use the command line below.

ccxsc -c -Fepurist.exe -Ox selected.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123


Compiler Options

6.43 Option -Oy

Syntax: -Oy[-]

Description: The option -Oy suppresses creation of frame pointers on the call stack, thereby speeding up the program since no frame pointers need to be created and deleted during function calls. Instead the normal stack pointer is used to store and fetch data.

This option is set ON by default when using -Ox,-O1 and -O2 optimization options (frame pointers are not created). But the option can be set to OFF by using -Oy- (frame pointers are being created). If optimizations are not required, this option is OFF, which means that frame pointers are created.

Example 39. Option -Oy

To produce an executable called purist.exe from the C source file selected.c where frame pointers are required to be omitted, use the command line below.

ccxsc -c -Fepurist.exe -Oy selected.c

Further Information:Section 6.3.4, “Optimization Options” on page 76Section 6.31, “Option -O” on page 113Section 6.33, “Option -Oa” on page 115Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.38, “Option -Op” on page 120Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.41, “Option -Ow” on page 123Section 6.42, “Option -Ox” on page 124


Compiler Options

6.44 Option -P

Syntax: -P

Description: The option -P stops the compilation process after the C/C++ source files have been preprocessed, with the result being written to an output file. This output file has the same name as the source file from which it is derived, but with an extension .i. All preprocessor directives are carried out, conditional compilation is resolved, and macros are expanded. In addition the -P option adds #line directives around those lines removed from the original source file, as being comments or conditionally not required, and around lines added from included files. This ensures that should the preprocessed output be submitted for final compilation any error and other messages will refer to line numbers within the original source. To stop #line directives from being included within the output, file the -EP option should be added.




Example 40. Option -P

To preprocess a group of source files, without #line directives included, but with comments restored, use the following command. No compilation is carried out.

ccxsc -P -EP -C one.c two.cpp three.c

The precompiled output is placed within the files one.i, two.i and three.i.

Further Information:Section 6.9, “Option -C” on page 91Section 6.16, “Option -Fe” on page 98Section 6.13, “Option -EP” on page 95


Compiler Options

6.45 Option -QA

Syntax: -QA[-]

Description: If the option -QA is set, the predefined preprocessor macros and all assertions are enabled. Predefined macros starting with "__" (two underscores) are not affected by this option; they are always enabled.

This option is set by default. To disable it, use -QA-.

Example 41. Option -QA

To disable the predefined macros during the compilation of the file sourcefile.cpp, use the following command. Note that predefined macros starting with two underscores are still enabled.

ccxsc -QA- sourcefile.cpp

Further Information:Section 5.1.3, “Defining Macros” on page 57


Compiler Options

6.46 Option -QAname

Syntax: -QAname value

Description: The option -QA creates an assertion with the name name and the value value.

By default, this option is not set.

Note: If the parameter value is not specified, the compiler silently ignores the option.

Example 42. Option -QA

To set the symbol pi to the numeric value 3.14159, use the following command:

ccxsc -QApi 3.14159 sourcefile.cpp


Compiler Options

6.47 Option -Qansi

Syntax: -Qansi[-]

Description: If the option -Qansi is set, the Intel® C++ Compiler assumes the source to be in conformance with the ANSI standard. Aberrations of this standard will cause diagnostic messages.

By default, this option is not set.

Example 43. Option -Qansi

To test a source file for ANSI conformance, use the following command:

ccxsc -Qansi -Zs sourcefile.cpp

Further Information:Chapter 11, “Language Conformance Options”


Compiler Options

6.48 Option -QH

Syntax: -QH

Description: The option -QH causes the Intel® C++ Compiler to output a list of all the include files declared within the source files. The compilation process does not take place. Full path and filename of each included file is output to the standard output stream stdout.

This option stops the compilation process before it has completed and should not be used in combination with others which behave similarly such as -c, -E, -QH, -QM, and -S.


Example 44. Option -QH

To produce an output list of all included files directly or indirectly referenced by the source files given, use the command line below. No compilation of the four given files takes place, and output is to the standard output stream stdout.

ccxsc -QH one.c two.cpp three.c four.cpp

Further Information:Section 6.8, “Option -Bz” on page 90Section 6.10, “Option -c” on page 92Section 6.16, “Option -Fe” on page 98Section 6.56, “Option -QM” on page 138Section 6.76, “Option -S” on page 158Section 6.97, “Option -Zs” on page 182


Compiler Options

6.49 Option -Qip

Syntax: -Qip

Description: The option -Qip enables interprocedural optimizations within the same source file. When this option is selected, the Intel® C++ Compiler attempts to optimize across all the functions within a single source file. Where several source files are specified within a command line environment each file is optimized separately.


Example 45. Option -Qip

To produce an executable file named geometric.exe from a C++ source file trying.cpp where interprocedural optimizations are required within the source file, together with full debugging information, use the command line below.

ccxsc @commandf.cmd trying.cpp

Where the response file commandf.cmd has been used purely for convenience, and for its ability to add comments. This response file has the following contents:

#create full debug information -Zi#specify interprocedural optimization within each single file -Qip#rename output executable file -Fegeometric.exe

Further Information:Section 9.3, “Interprocedural Optimizations” on page 222Section 6.50, “Option -Qip_no_inlining” on page 132Section 6.51, “Option -Qipo” on page 133Section 6.52, “Option -Qipo_c” on page 134Section 6.68, “Option -Qvec_report” on page 150


Compiler Options

6.50 Option -Qip_no_inlining

Syntax: -Qip_no_inlining

Description: The option -Qip_no_inlining disables inlining that would result from the -Qip or -Ob2 interprocedural optimizations, but has no effect on other interprocedural optimizations. This option has no effect on user-directed inlining using option -Ob1. When inlining is enabled the Intel® C++ Compiler is directed to replace the calls of functions with their contents where appropriate. This form of optimization avoids unnecessary function calls with all the inherent overheads associated with such calls.


Example 46. Option -Qip_no_inlining

To produce an executable file named hyper.exe from source files hyper.c and bolic.c, with small code optimizations but no inlining, use the following command line.

ccxsc -O1 -Qip_no_inlining hyper.c bolic.c

Further Information:Section 9.3, “Interprocedural Optimizations” on page 222Section 6.49, “Option -Qip” on page 131Section 6.51, “Option -Qipo” on page 133Section 6.68, “Option -Qvec_report” on page 150


Compiler Options

6.51 Option -Qipo

Syntax: -Qipo

Description: The option -Qipo enables interprocedural optimizations across all source files of a program. To accomplish this the Intel® C++ Compiler creates a mock object code file for all source files specified on the command line. These mock files are then used at the linking stage which must be called indirectly through the compiler using the -Qipo option.


Example 47. Option -Qipo

To produce an executable file named geometric.exe from C++ source files where interprocedural optimizations are required across all functions within all given source files, together with several selected optimization options, use the command line below.

ccxsc -Fegeometrix.exe @commandf.cmd one.cpp two.cpp three.cpp

Where the response file commandf.cmd has been used so that many optimizations can be selected and comments on their actions added. This response file has the following contents:

#disable all optimization defaults -Od#specify inline expansion of all functions #within the discretion of the compiler -Ob2#specify interprocedural optimization across all files -Qipo#specify fast code optimizations -Ot#specify global optimizations -Og

Further Information:Section 9.3, “Interprocedural Optimizations” on page 222Section 6.49, “Option -Qip” on page 131Section 6.50, “Option -Qip_no_inlining” on page 132Section 6.68, “Option -Qvec_report” on page 150


Compiler Options

6.52 Option -Qipo_c

Syntax: -Qipo_c

Description: The option -Qipo_c causes the Intel® C++ Compiler to generate a single output object file regardless as to how many input source files were specified within the command line environment. The object code generated from the compilation of all the specified input source files are placed within a single output file which has a pre-defined name of ipo_out.o. This object file can then be used in further linking steps.

Should the compilation process be halted before any object code is generated (for example by the use of the -S option) then no multifile object file is generated.

This option implicitly sets -Qipo.

Note: If the command line option -Qip is set, -Qipo_c should be set, too. Otherwise, the compiler sets -Qipo_c implicitly and issues a warning message.


Example 48. Option -Qipo_c

To produce a single relocatable object file from several source files, use the following command line. The output file is named ipo_out.o by default.

ccxsc -Qipo_c one.cpp two.cpp three.cpp

Further Information:Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.18, “Option -Fo” on page 100Section 6.32, “Option -o” on page 114Section 6.33, “Option -Oa” on page 115Section 6.51, “Option -Qipo” on page 133Section 6.54, “Option -Qipo_S” on page 136


Compiler Options

6.53 Option -Qipo_obj

Syntax: -Qipo_obj

Description: The option -Qipo_obj is used in conjunction with the -Qipo option to produce real object files during the compilation stage when interprocedural optimizations are implemented.

Normally to accomplish interprocedural optimizations across all source files of a program the Intel® C++ Compiler creates mock object files which are later linked in a special linking stage.

Should it be required that the linker be directly called then this -Qipo_obj option should be specified in conjunction with the -Qipo option, to produce real object files.



Example 49. Option -Qipo_obj

To produce real object files from C++ source files where multifile interprocedural optimizations are required across all the functions within the given source files, use the command line below.

ccxsc -c -Qipo -Qipo_obj alpha.cpp beta.cpp gamma.cpp

Further Information:Section 9.3, “Interprocedural Optimizations” on page 222Section 6.49, “Option -Qip” on page 131Section 6.50, “Option -Qip_no_inlining” on page 132Section 6.51, “Option -Qipo” on page 133Section 6.68, “Option -Qvec_report” on page 150


Compiler Options

6.54 Option -Qipo_S

Syntax: -Qipo_S

Description: The option -Qipo_S causes the Intel® C++ Compiler to generate a single output assembly file regardless as to how many input source files were specified within the command line environment. The assembly language code generated from the compilation of all the specified input source files are placed within a single output file which has a pre-defined name of ipo_out.s. This assembly file can then be used in further linking steps.

Should the compilation process be halted before any object code is generated (for example by the use of the -Zs option) then no multifile assembly file is generated.



Example 50. Option -Qipo_S

To produce a single assembly file from several source files, use the following command line. The output file is named ipo_out.s by default.

ccxsc -Qipo_S one.cpp two.cpp three.cpp

Further Information:Section 6.14, “Option -Fa” on page 96Section 6.16, “Option -Fe” on page 98Section 6.18, “Option -Fo” on page 100Section 6.32, “Option -o” on page 114Section 6.33, “Option -Oa” on page 115Section 6.51, “Option -Qipo” on page 133Section 6.52, “Option -Qipo_c” on page 134


Compiler Options

6.55 Option -Qlocation

Syntax: -Qlocation,tool,path

Description: The option -Qlocation is used to specify alternative tools to be used by the Intel® C++ Compiler, such as the assembler and the linker. By default the Intel® C++ Compiler is set up to use tools from the Intel® C++ Software Development Tool Suite, but these may be changed by using this option where tool takes the options of:

The parameter path specifies the directory path and tool filename.


Example 51. Option -Qlocation

To produce a relocatable object file testing.o from source file testing.c, using the alternative assembler alt_asm.exe, use a command line of:

ccxsc -Qlocation,asm,c:\binasms\alt_asm.exe -c testing.c

Further Information:Section 6.5, “Option -Ba” on page 87Section 6.7, “Option -Bl” on page 89Section 6.58, “Option -Qoption” on page 140

Tool Description

asm Selects the assembler.

c Selects the compiler.

cpp Selects the preprocessor.

link Selects the linker.


Compiler Options

6.56 Option -QM

Syntax: -QM

Description: The option -QM causes the Intel® C++ Compiler to generate lines of Makefile dependency information onto its standard output stdout. These can be redirected into a Makefile file. The information is based on the include statements found within the source files. This allows any Integrated Development Environment to identify what source files need to be recompiled should any of these include files be altered.

This option stops the compilation process before it has completed and should not be used in combination with others which behave similarly such as -c, -E, -QH, and -S.


Example 52. Option -QM

To produce lines of Makefile dependency information based upon the source files given, use the command line below. No compilation of the four given files takes place, and information is sent to the standard output stream stdout.

ccxsc -QM one.c two.cpp three.c four.cpp

Further Information:Section 6.3.10, “Options which Interrupt the Compilation Process” on page 84Section 6.8, “Option -Bz” on page 90Section 6.10, “Option -c” on page 92Section 6.16, “Option -Fe” on page 98Section 6.48, “Option -QH” on page 130Section 6.76, “Option -S” on page 158Section 6.97, “Option -Zs” on page 182


Compiler Options

6.57 Option -Qnobss_init

Syntax: -Qnobss_init

Description: The option -Qnobss_init causes the Intel® C++ Compiler to place variables that are initialized with zero into the DATA section of the assembly code. Normally such variables are placed in the bss section of the assembly code.


Example 53. Option -Qnobss_init

To produce an assembly listing file folder.s from the source file one.cpp, where zero initialized variables are placed into the DATA section, use the following command line.

ccxsc -S -Fafolder -Qnobss_init one.cpp


Compiler Options

6.58 Option -Qoption

Syntax: -Qoption,tool,optionlist

Description: The option -Qoption can be used to pass options to a subsequent tool in the compilation process. Depending on the tools used in the compilation process, the parameter tool can be, for example, asm for the assembler. The list of options, optionlist, is passed as command line to the tool. For a description of these options, please refer to the documentation of the specified tool.

The following values for tool are supported:

Note: If the list of options contains white space, the list must be enclosed in double quotes.


Example 54. Option -Qoption

To pass the option -o outfile to the assembler asm, use the following command:

ccxsc -Qoption,asm,"-o outfile" sourcefile.cpp

Further Information:Section 6.55, “Option -Qlocation” on page 137

Value Description

asm The assembler.

link The linker.


Compiler Options

6.59 Option -Qprec

Syntax: -Qprec

Description: The option -Qprec disables the floating point optimization. This optimization would speed up the execution and reduce the floating point precision. Setting the option therefore improves the precision and slows down the execution.

This option is set OFF by default.

Example 55. Option -Qprec

To produce an executable file named hiprecision.exe from the C++ source file calculus.cpp, with improved floating point precision, use a command line of:

ccxsc -Fehiprecision.exe -Qprec calculus.cpp

Further Information:Section 6.31, “Option -O” on page 113Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.49, “Option -Qip” on page 131Section 6.50, “Option -Qip_no_inlining” on page 132Section 6.51, “Option -Qipo” on page 133Section 6.60, “Option -Qprec_div” on page 142Section 6.68, “Option -Qvec_report” on page 150Section 6.95, “Option -Zi” on page 180


Compiler Options

6.60 Option -Qprec_div

Syntax: -Qprec_div

Description: The option -Qprec_div disables the floating point division to multiplication optimization. This normally ON optimization replaces any divisions which use a constant with the multiplication of the inverse of that constant. This is normally done because divisions take longer than multiplications.

This option is switched OFF by default which means that the optimization effect is ON.

Example 56. Option -Qprec_div

To produce an executable file named felix.exe from C++ source file algebra.cpp, with selected optimizations including -Qprec_div, use a command line of:

ccxsc -Fefelix.exe @commandf.cmd algebra.cpp

Where the response file commandf.cmd has been used so that many optimizations can be selected and comments on their actions added. This response file has the following contents:

#specify optimization of floating point division to multiplication-Qprec_div

#specifying any optimization option will disable all optimization#defaults. Extra optimizations cannot be simply added#So need to replace the defaulted optimizations-O2

Further Information:Section 6.31, “Option -O” on page 113Section 6.34, “Option -Ob” on page 116Section 6.35, “Option -Od” on page 117Section 6.36, “Option -Og” on page 118Section 6.37, “Option -Oi” on page 119Section 6.39, “Option -Os” on page 121Section 6.40, “Option -Ot” on page 122Section 6.49, “Option -Qip” on page 131Section 6.50, “Option -Qip_no_inlining” on page 132Section 6.51, “Option -Qipo” on page 133Section 6.59, “Option -Qprec” on page 141Section 6.68, “Option -Qvec_report” on page 150Section 6.95, “Option -Zi” on page 180


Compiler Options

6.61 Option -QRinterwork-return

Syntax: -QRinterwork-return

Description: The option -QRinterwork-return specifies that mixed ARM* and Thumb* functions are to be used within the application.


Note: This option cannot be switched off.

Further Information:Section 6.64, “Option -QRxscale” on page 146


Compiler Options

6.62 Option -Qropi

Syntax: -Qropi

Description: The option -Qropi enables position independent access to text segments.

The implementation of position independent code (PIC) obeys the ARM-THUMB Procedure Call Standard (ATPCS).

Note: This option must be set together with the Option -Qrwpi which enables position independent data (PID).RTTI must be disabled.Exception handling does not work with this option.

To enable PIC and PID in an executable file, link the corresponding library and startup module to the application. Additionally you need to specify a specific linker build file as well as specific linker options. These are:

To enable PIC and PID in your assembly code, follow the rules below:

• Do not modify the static base register R9.

• Data accesses need to be R9 relative.

• Read-only accesses need to be PC relative.

• Relocation type needs to be SBREL32 or PCREL.

Further Information:Section 6.63, “Option -Qrwpi” on page 145ARM ELFThe ARM-THUMB Procedure Call Standard

Option Library Startup Module Linker Build File

-Qropi -Qrwpi

-- -- X0__ac00.aX0__ax00.aX0__as00.a

X0__a000.a X0__b00.bld

set -- X0__ac01.aX0__ax01.aX0__as01.a

X0__a001.a X0__b01.bld

-- set X0__ac02.aX0__ax02.aX0__as02.a

X0__a002.a X0__b02.bld

set set X0__ac03.aX0__ax03.aX0__as03.a

X0__a003.a X0__b03.bld


Compiler Options

6.63 Option -Qrwpi

Syntax: -Qrwpi

Description: The option -Qrwpi enables position independent access to data segments.

The implementation of position independent data (PID) obeys the ARM-THUMB Procedure Call Standard (ATPCS).

Note: This option must be set together with the Option -Qropi which enables position independent code (PIC).RTTI must be disabled.Exception handling does not work with this option.

To enable PIC and PID in an executable file, link the corresponding library and startup module to the application. Additionally you need to specify a specific linker build file as well as specific linker options. These are:

To enable PID and PIC in your assembly code, follow the rules below:

• Do not modify the static base register R9.

• Data accesses need to be R9 relative.

• Read-only accesses need to be PC relative.

• Relocation type needs to be SBREL32 or PCREL.

Further Information:Section 6.62, “Option -Qropi” on page 144

Option Library Startup Module Linker Build File

-Qropi -Qrwpi

-- -- X0__ac00.aX0__ax00.aX0__as00.a

X0__a000.a X0__b00.bld

set -- X0__ac01.aX0__ax01.aX0__as01.a

X0__a001.a X0__b01.bld

-- set X0__ac02.aX0__ax02.aX0__as02.a

X0__a002.a X0__b02.bld

set set X0__ac03.aX0__ax03.aX0__as03.a

X0__a003.a X0__b03.bld


Compiler Options

6.64 Option -QRxscale

Syntax: -QRxscale

Description: The option -QRxscale specifies that the application is to be run on the Intel XScale® microarchitecture.

This option is set ON by default.

Note: This option cannot be switched off.

Further Information:Section 6.61, “Option -QRinterwork-return” on page 143


Compiler Options

6.65 Option -Qsox

Syntax: -Qsox[-]

Description: The option -Qsox enables, or disables by introducing the trailing minus sign, the saving of compiler options and version information in the executable file.

This option is switched off by default, so the information is not saved in the executable file.

Example 57. Option -Qsox

To produce an executable file named felix.exe from a C source files of non-standard extension testing.hat, where no compiler version information is required in the executable file, use a command line of:

ccxsc -Fefelix.exe -Qsox- -Tctesting.hat


Compiler Options

6.66 Option -QTP

Syntax: -QTP[target]

Description: The option -QTP specifies the target processor for the compilation. The parameter target can have the following values:

This option is set to xsc1 by default.

Value Description

xsc1 Intel XScale® microarchitecture 80200

xsc2 Intel® PXA210/250

xsc3 Intel® PXA210/250 with Wireless MMX™ technology


Compiler Options

6.67 Option -Qunroll

Syntax: -Qunroll[num]

Description: The option -Qunroll specifies the maximum number of times to unroll a loop. This number is set by the optional number num. If num is omitted then the compiler decides itself on the number, taking into account the complexity and size of the loop. A value of num=0 disables this unroll feature.

Loop unrolling is where the contents of the loop are repeated several times. This gets rid of the loop structure with its jumps and checking code, which is important in RISC pipeline processing. The resulting code runs faster, but the code size increases.

This option is switched ON by default, with number num omitted. So the compiler decides on the maximum number of times to unroll a loop.

Example 58. Option -Qunroll

To produce an executable file named rolling.exe from a C source file with unrolling maximum value of 4, use a command line of:

ccxsc -Qunroll4 -Ferolling.exe alpha.c


Compiler Options

6.68 Option -Qvec_report

Syntax: -Qvec_reportnum [reportfile]

Description: The option -Qvec_report controls the vectorizer's level of diagnostic messages. The report is being written to the file reportfile. The parameter num specifies the report level:

By default, this option is set to num=1. If reportfile is not specified, the report is written to standard output.

Further Information:Chapter 10, “Vectorization”

Table 27. Option -Qvec_report Parameters

num Description

0 No diagnostic information is displayed.

1 Display diagnostics indicating loops successfully vectorized.

2 Same as num=1, plus diagnostics indicating loops not successfully vectorized.

3 Same as num=2, plus additional information about any proven or assumed dependences

4 Same as num=2, but only non-vectorized loops are regarded

5 Same as num=3, but only non-vectorized loops are regarded


Compiler Options

6.69 Option -Qwd

Syntax: -Qwd[num{,num}]

Description: The option -Qwd disables the diagnostic messages specified by the parameter (or list of parameters), num, which denotes the message number. If more than one parameter is specified, they must be separated by commas.

Note: This option works on soft diagnostics (warnings and remarks) only. Hard diagnostics (error messages) cannot be switched off.


Example 59. Option -Qwd

To suppress the warning message 945, "Type qualifier ignored", use the following command:

ccxsc -Qwd945 sourcefile.cpp

Further Information:Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.70 Option -Qwe

Syntax: -Qwe[num{,num}]

Description: The option -Qwe promotes the diagnostic messages specified by the parameter (or list of parameters), num, to error messages. If more than one parameter is specified, they must be separated by commas. The number num denotes the message number.


Example 60. Option -Qwe

To change the warning messages 170 and 945 to error messages, use the following command:

ccxsc -Qwe170,945 sourcefile.cpp

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.71 Option -Qwn

Syntax: -Qwn num

Description: The option -Qwn limits the number of hard diagnostic (error) messages to the specified value, num. If more error messages are to be issued, the Intel® C++ Compiler stops parsing.

This option is switched on by default, with a limit of 100.

Example 61. Option -Qwn

To abort compilation when the third error occurs, use the following command:

ccxsc -Qwn2 sourcefile.cpp

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.72 Option -Qwp_ipo

Syntax: -Qwp_ipo

Description: The option -Qwp_ipo is identical to -Qipo.


Further Information:Section 6.51, “Option -Qipo” on page 133


Compiler Options

6.73 Option -Qwr

Syntax: -Qwr[num{,num}]

Description: The option -Qwr demotes the warning messages specified by the parameter (or list of parameters), num, to remark messages. If more than one parameter is specified, they must be separated by commas. The number num denotes the message number.

Note: This option works on warnings only. Hard diagnostics (error messages) cannot be changed.


Example 62. Option -Qwr

To change the warning messages 170 and 945 to remark messages, use the following command:

ccxsc -Qwr170,945 sourcefile.cpp

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.74 Option -Qww

Syntax: -Qww[num{,num}]

Description: The option -Qww promotes the remark messages specified by the parameter (or list of parameters), num, to warning messages. If more than one parameter is specified, they must be separated by commas. The number num denotes the message number.

Note: This option works on remarks only. Hard diagnostics (error messages) cannot be changed.


Example 63. Option -Qww

To change the remark messages 193 and 577 to warning messages, use the following command:

ccxsc -Qww193,577 sourcefile.cpp

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.75 Option -rtti

Syntax: -rtti

Description: The option -rtti enables run-time type information to be added to the object code. This information enables data object type checking to be carried out during run-time, and makes implicit use of the RTTI preprocessing macro.

If this option is set, the preprocessor macro _CPPRTTI is defined.


Further Information:Section 6.20, “Option -Gy” on page 102Section 6.57, “Option -Qnobss_init” on page 139


Compiler Options

6.76 Option -S

Syntax: -S

Description: The option -S stops the compilation process after an assembly file has been generated for each source file on the command line. This suppresses the implicit call to the Assembler and Linker, which must be called later to produce an executable file. The Intel® C++ Compiler accepts C/C++ source files, usually with default extensions of .c and .cpp, or pre-processed files with an extension of .i. The generated assembly files take on the name of the source file from which it was produced with an extension of .s.


Use of the -TC, -Tc, -TP, -Tp options can be used to force acceptance of source files as C/C++ sources with extensions other than .c and .cpp.

The option -S overrides the option -c which is used to generate object files.

The -S option also overrides the following options if they are set:

Example 64. Option -S

To produce an assembly file named testing.s from a C source file of trying.cpp use a command line of:

ccxsc -S -atesting trying.cpp

Further Information:Section 6.3.10, “Options which Interrupt the Compilation Process” on page 84Section 6.8, “Option -Bz” on page 90Section 6.10, “Option -c” on page 92Section 6.16, “Option -Fe” on page 98Section 6.48, “Option -QH” on page 130Section 6.56, “Option -QM” on page 138Section 6.78, “Option -Tc” on page 160Section 6.77, “Option -TC” on page 159Section 6.80, “Option -Tp” on page 162Section 6.79, “Option -TP” on page 161Section 6.97, “Option -Zs” on page 182

-E -QH

-Fe (set by default, therefore -S and -Fe should not be used together)

-QM

-P -Zs


Compiler Options

6.77 Option -TC

Syntax: -TC

Description: The option -TC instructs the Intel® C++ Compiler to treat all source files on the command line as though they were C source files, regardless as to their extensions, the only exceptions being files specifically typed by the -Tp option.

Normally only files with .c or .C extensions would be accepted as C source files.


Obviously this option cannot be used in conjunction with the -TP option.

Example 65. Option -TC

To produce an executable file named optrix.exe from a C source file of none standard extension testing.hat, use a command line of:

ccxsc -Feoptrix.exe -TC testing.hat

Further Information:Section 6.10, “Option -c” on page 92Section 6.76, “Option -S” on page 158Section 6.78, “Option -Tc” on page 160Section 6.80, “Option -Tp” on page 162Section 6.79, “Option -TP” on page 161


Compiler Options

6.78 Option -Tc

Syntax: -Tcfilename

Description: The option -Tc instructs the Intel® C++ Compiler to treat the given source file filename as a C source file regardless as to its name and extension. Normally only files with .c or .C extensions would be accepted as C source files.

This option can be used in conjunction with the global source options -TC and -TP if required.

There can be multiple occurrences of this option.


Example 66. Option -Tc

To produce an executable file named felix.exe from C source files of none standard extension testing.hat, and standard extension tried.c, use a command line of:

ccxsc -Fefelix.exe -Tctesting.hat tried.c

Further Information:Section 6.10, “Option -c” on page 92Section 6.76, “Option -S” on page 158Section 6.77, “Option -TC” on page 159Section 6.80, “Option -Tp” on page 162Section 6.79, “Option -TP” on page 161


Compiler Options

6.79 Option -TP

Syntax: -TP

Description: The option -TP instructs the Intel® C++ Compiler to treat all source files on the command line as though they were C++ source files, regardless as to their extensions, the only exceptions being files specifically typed by the -Tc option.

Normally only files with .cpp or .CPP extensions would be accepted as C++ source files.


Obviously this option cannot be used in conjunction with the -TC option.

Example 67. Option -TP

To produce an executable file named optrix.exe from a C++ source file of none standard extension testing.hat, use a command line of:

ccxsc -Feoptrix.exe -TP testing.hat

Further Information:Section 6.10, “Option -c” on page 92Section 6.76, “Option -S” on page 158Section 6.78, “Option -Tc” on page 160Section 6.77, “Option -TC” on page 159Section 6.80, “Option -Tp” on page 162


Compiler Options

6.80 Option -Tp

Syntax: -Tpfilename

Description: The option -Tp instructs the Intel® C++ Compiler to treat the given source file filename as a C++ source file regardless as to its name and extension.

This option can be used in conjunction with the global source options -TC and -TP if required. Normally only files with .cpp or .CPP extensions would be accepted as C++ source files.

There can be multiple occurrences of this option.


Example 68. Option -Tp

To produce an executable file named felix.exe from C++ source files of none standard extension testing.hat, and standard extension tried.cpp, use a command line of:

ccxsc -Fefelix.exe -Tptesting.hat tried.cpp

Further Information:Section 6.10, “Option -c” on page 92Section 6.76, “Option -S” on page 158Section 6.78, “Option -Tc” on page 160Section 6.77, “Option -TC” on page 159Section 6.79, “Option -TP” on page 161


Compiler Options

6.81 Option -U

Syntax: -Uname

Description: The option -U suppresses any previous definition of the given macro name. It is equivalent to the use of the directive #undef.

Multiple uses of this option is allowed if several macro names need to be suppressed.


Example 69. Option -U

To produce an executable file named geometrics from a C source file of trying.c where it is necessary to suppress the macro tools, use a command line of:

ccxsc -Fogeometrics -Dtools trying.cccxsc -Fogeometrics -Utools trying.c

Further Information:Section 6.11, “Option -D” on page 93Section 6.17, “Option -FI” on page 99Section 6.24, “Option -I” on page 106Section 6.82, “Option -u” on page 164Section 6.87, “Option -X” on page 169


Compiler Options

6.82 Option -u

Syntax: -u

Description: The option -u suppresses all previously defined macro names, other than those starting with __. It is equivalent to a global -U option.


Example 70. Option -u

To produce an executable file from the C source file paramb.c, where all macro names are suppressed, use the command line shown below.

ccxsc -u paramb.c

Further Information:Section 6.11, “Option -D” on page 93Section 6.17, “Option -FI” on page 99Section 6.24, “Option -I” on page 106Section 6.81, “Option -U” on page 163Section 6.87, “Option -X” on page 169


Compiler Options

6.83 Option -V

Syntax: -Vstring

Description: The option -V embeds the text string string within any generated object file. Usually this text string is used to label the object file with a version number or copyright notice.

The text string is normally terminated by the first white space (spaces or tabs). However these can be accommodated by enclosing a multi-word text string in double quotes. Should a double quote be required as part of the string it must be preceded by a backslash (\).


Example 71. Option -V

To produce object files with embedded copyright declarations within them use the following command line.

ccxsc -c -V"copyrighted by megalith studios" alpha.cpp beta.cpp gamma.cpp

Compilation stops before linking due to the -c option, to produce the resultant object files of alpha.o, beta.o and gamma.o, each having the copyright declaration within it.

Further Information:Section 6.10, “Option -c” on page 92


Compiler Options

6.84 Option -W

Syntax: -W{0|1|2|3|4}

Description: The option -W specifies the level, if any, of warning messages to be generated when compiling the source files. This is controlled by the specified number as follows:

Should the number be omitted then this option is treated as if -W0, no warning messages are generated.

The default condition for this option is W1, generate only severe warning messages.

Example 72. Option -W

To produce a relocatable object file only from the C source file square.c, where severe warning messages only are to be generated, use the command line shown below.

ccxsc -W1 -c square.c

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.85, “Option -WX” on page 167Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”

Number Description

0 No warning messages are generated.

1 Severe warning messages only are generated. This is the default condition for this option.

2 Less severe warning messages are generated, as well as those of level -W1.

3 Generates warnings that are less severe than those at setting -W2 and includes such warnings about making function calls before declaring their prototypes. It also generates warning messages of level -W2. This level is recommended for normal use.

4 Generates informational warnings, as well as those of level -W3.


Compiler Options

6.85 Option -WX

Syntax: -WX

Description: The option -WX promotes all warning messages to error messages.


Example 73. Option -Qwr

To change any warning into an error message, use the following command:

ccxsc -WX sourcefile.cpp

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.86, “Option -w” on page 168Chapter 17, “Diagnostics and Messages”


Compiler Options

6.86 Option -w

Syntax: -w

Description: The option -w specifies that no warning messages are to be generated when compiling the source files. This is the same as setting option -W0.

The default condition for this option is OFF.

Example 74. Option -w

To produce an assembly file only from the C source file square.c, where no warning messages are to be generated, use the command line shown below.

ccxsc -w -S square.c

Further Information:Section 6.69, “Option -Qwd” on page 151Section 6.70, “Option -Qwe” on page 152Section 6.71, “Option -Qwn” on page 153Section 6.73, “Option -Qwr” on page 155Section 6.74, “Option -Qww” on page 156Section 6.84, “Option -W” on page 166Section 6.85, “Option -WX” on page 167Chapter 17, “Diagnostics and Messages”


Compiler Options

6.87 Option -X

Syntax: -X

Description: The option -X is used to stop the Intel® C++ Compiler from searching standard directories for the include files. These standard directories are specified by the environment variables PATH and INCLUDE. Searching can be redirected from the standard directories to non-standard directories by using the -I option in conjunction with this -X option.


Example 75. Option -X

To produce an executable file from the C source file square.c, where the standard include directory has been replaced by the directory /new_incdir, use the command line shown below. Any include files specified within the source file will be searched for in the current directory and then the new directory only.

ccxsc -X -I/new_incdir square.c

Further Information:Section 6.11, “Option -D” on page 93Section 6.17, “Option -FI” on page 99Section 6.24, “Option -I” on page 106Section 6.81, “Option -U” on page 163Section 6.82, “Option -u” on page 164


Compiler Options

6.88 Option -Yc

Syntax: -Yc[filename]

Description: The option -Yc is used to create a precompiled header file whose name by default is vc50.pch, but which can be changed by use of the -Fp option. The optional filename refers to a header file name and is explained further below.

Without the optional filename the Intel® C++ Compiler will precompile through the source file until its end or until a #pragma hdrstop directive is reached. The precompiled code being placed within the precompiled header file.

With a given header filename the Intel® C++ Compiler will precompile through to and including the given header file.

The precompiled header can subsequently be used through use of the -Yu option. Should both options -Yc[filename] and -Yu[filename] be used on the same command line with the same filenames then -Yc takes precedent. See example for -Yu.



Example 76. Option -Yc

To create a precompiled header file named Head.pch from a source file alpha.cpp use the following command line.

ccxsc -Ycfuture.h -FpHead.pch alpha.cpp

Where the precompilation will take place through the source file alpha.cpp until the included header file future.h is encountered. This may be at the start of the source file, for example,

#include <stdio.h>#include <string.h>#include "future.h"

int main(void){ ... ... ...}

Here the precompiled header file Head.pch will include all the preprocessing information in the three given include files, and will stop at the end of the include file "future.h" or the include file "future.h" may be encountered within the source file later on, if so preprocessing will ocurr until that file inclusion is reached.


Compiler Options

Further Information:Section 6.19, “Option -Fp” on page 101Section 6.89, “Option -Yu” on page 172Section 6.90, “Option -YX” on page 174


Compiler Options

6.89 Option -Yu

Syntax: -Yu[filename]

Description: The option -Yu is used to instruct the compiler to use an existing precompiled header within the current compilation. That precompiled header, having been created by a previous use of the -Yc option on the command line, has the default name of vc50.pch unless another name is specified by use of the -Fp option. The optional filename refers to a header file name and is explained further below.

Without the optional filename the Intel® C++ Compiler uses the contents of the precompiled file in place of any source code occurring up to the first #pragma hdrstop directive it meets, and continues to compile the source code following. Failure to find such a pragma within the source code will lead to an error message and the compilation being unsuccessful.

With a given header filename the Intel® C++ Compiler uses the contents of the precompiled file in place of any source code occurring up to and including the included header file filename. The remaining source code is then compiled from this location onwards.

Should both options -Yc[filename] and -Yu[filename] be used on the same command line with the same filenames then -Yc takes precedence.



Example 77. Option -Yu

To create an executable file from source file alpha.cpp using a previously created precompiled header file named Head.pch use the following command line.

ccxsc -Yufuture.h -FpHead.pch alpha.cpp

Where the contents of the precompiled header file Head.pch will be used in place of any source code before, and including, the include file future.h. Further compilation of the source will then take place after the location of the include file future.h. This may be at the start of the source file, for example,

#include <stdio.h>#include <string.h>#include "future.h"

int main(void){ ... ... ...}


Compiler Options

Here the precompiled header file Head.pch will be used instead of the contents of the three include files stdio, string and future. Compilation of the remaining source will then take place at the start of the main function.

Or the include file "future.h" may be encountered within the source file later on, if so further compilation occurs of any more source code following it.

Once compilation is complete, the process goes on to produce an executable file, via the linker.

Further Information:Section 6.19, “Option -Fp” on page 101Section 6.88, “Option -Yc” on page 170Section 6.90, “Option -YX” on page 174


Compiler Options

6.90 Option -YX

Syntax: -YX[filename]

Description: The option -YX is used to instruct the compiler to either create or use an existing precompiled header file within the current compilation. Its activities are the same as the -Yc and -Yu options, with the compiler automatically deciding whether to create or use a precompiled header. The name of the precompiled header file used is either the default name of vc50.pch or another that is specified by the use of the -Fp option upon the command line. The filename associated with the -YX option is optional and refers to the name of a header file, this will be clarified below.

If no precompiled header file exists then one will be created, the Intel® C++ Compiler carrying out the activities of the -Yc option. Should no filename be given then the compiler will precompile the source code until a #pragma hdrstop directive is encountered.

Should a filename be given it will be that of an included header file; in which case precompilation will take place upon the source code until this included header file is reached, the header file being included within the precompiled file. Precompilation then ends.

If a precompiled header file already exists then the Intel® C++ Compiler will include this precompiled header file within the current compilation, following the same rules as the -Yu option. Should no filename be given then the compiler will include the contents of the existing precompiled header file in the current compilation in place of the source code up until the first #pragma hdrstop directive is encountered. Compilation will then continue of the source code following that directive.

Should a filename be given it will be that of an included header file; in which case the compiler will include the contents of the existing precompiled header file in the current compilation in place of the source code up until the inclusion of that header file. Compilation will then continue of the source code following that inclusion.



Compiler Options

Example 78. Option -YX

To create a precompiled header file Head.pch from source file alpha.cpp the following command line can be used.

ccxscce -YX -FpHead.pch alpha.cpp

Where the precompilation will take place through the source file alpha.cpp until a #pragma hdrstop directive is reached.

To use an existing precompiled header file with default name vc50.pch the following command line can be used.

ccxscce -/YXfuture.h alpha.cpp

Where the precompiled header file vc50.pch must exist. The compiler takes the precompiled information from the precompiled header file in place of source code up to and including the first occurrance of the include file "future.h". For example if the source code was:

#include <stdio.h>#include <string.h>#include "future.h"#include "twice.h"

int main(void){ ... ... ...}

Then compilation would continue from the #include "twice.h" statement.

Or the include file "future.h" may be encountered within the source file later on, if so further compilation occurs only on any more source code following it.

Once compilation is complete, the process goes on to produce an executable file, via the linker.

Further Information:Section 6.19, “Option -Fp” on page 101Section 6.88, “Option -Yc” on page 170Section 6.89, “Option -Yu” on page 172


Compiler Options

6.91 Option -Za

Syntax: -Za

Description: By default the compiler accepts certain extensions to the standard C language. The option -Za directs the Intel® C++ Compiler to adhere strictly to the ANSI standard for C(90) / C++(xxx).

When this option is set, some floating point operations will have their consistency improved by automatically setting option -Op.

If this option is set, the preprocessor macro _MSC_EXTENSIONS is undefined.


Example 79. Option -Za

To produce an executable file, with full debugging information from a C source file of the name cylinder.c, using only standard C language interpretation the command line shown below.

ccxsc -Zi -Za cylinder.c

Further Information:Section 6.38, “Option -Op” on page 120Section 6.93, “Option -Ze” on page 178


Compiler Options

6.92 Option -Zd

Syntax: -Zd

Description: The option -Zd specifies the Intel® C++ Compiler to generate symbol and line number information within the object code for use by the source-level debugger.

This option is a subset of the more powerful -Zi option which is used to produce full debugging information. If the option -Zi is set, there is no need to also set option -Zd.

The option -Zd is switched OFF by default.

Example 80. Option -Zd

To produce an executable file, with symbol and line number information, from a C source file of the name trying.c, use the command line shown below.

ccxsc -Zd trying.c

Further Information:Section 6.95, “Option -Zi” on page 180


Compiler Options

6.93 Option -Ze

Syntax: -Ze

Description: The option -Ze directs the Intel® C++ Compiler to accept extensions to the ANSI standard C.

These extensions to the standard C language contain a number of useful features and can be found elsewhere in this manual.

If this option is set, the preprocessor macro _MSC_EXTENSIONS is defined.


Example 81. Option -Ze

To produce an executable file from a C++ source file of the name cylinder.cpp, use the command line shown below. Since option -Ze is ON by default, the result would be the same if the -Ze was omitted.

ccxsc -Ze cylinder.cpp

Further Information:Section 6.91, “Option -Za” on page 176Section 6.92, “Option -Zd” on page 177


Compiler Options

6.94 Option -Zg

Syntax: -Zg

Description: The option -Zg instructs the Intel® C++ Compiler to output the list of function prototypes for all the functions found within the source files to be compiled. This list is sent to the standard output stdout, which may be redirected into a file. Such a list is useful for verification purposes to ensure their functionality is correct. No further action takes place once the list is generated, the source files are not compiled.


Example 82. Option -Zg

To produce an output list of function prototypes for all functions within the program testf.c, use the command line shown below. No compilation of the source file takes place.

ccxsc -Zg testf.c


Compiler Options

6.95 Option -Zi

Syntax: -Zi

Description: The option -Zi specifies the Intel® C++ Compiler to generate full symbolic debugging information for use by the source-level debugger. This symbolic debugging information is placed within a special program database file and includes the names and types of variables and functions, as well as source line numbers.

Since line numbers are included in the information the option -Zd need not be set at the same time.

The default optimization condition while compilation takes place depends on whether this debugging option is set or not:

• If option -Zi is not set, the default optimization is set to be -O2.

• If option -Zi is set, the default optimization is turned off to be -Od.

The option -Zi is switched OFF by default.

Example 83. Option -Zi

To produce an executable file from a C source file of the name trying.c, use the command line shown below. Note that in this case, optimization is disabled by default:

ccxsc -Zi trying.c

Further Information:Section 6.31, “Option -O” on page 113Section 6.35, “Option -Od” on page 117Section 6.92, “Option -Zd” on page 177


Compiler Options

6.96 Option -Zp

Syntax: -Zpnum

Description: The option -Zp defines the default alignment of structure members. The parameter num can have the following values:

By default, structure members are being aligned to 8-byte boundaries.

Example 84. Option -Zp

To align all structure members to 16-byte boundaries, use the following command:

ccxsc -Zp16 sourcefile.cpp

Value Description

1 The structure members are packed (no gap between members).

2 The structure members are being aligned to even addresses (2-byte boundaries).

4 The structure members are being aligned to 4-byte boundaries.




Compiler Options

6.97 Option -Zs

Syntax: -Zs

Description: The option -Zs instructs the Intel® C++ Compiler to only check the syntax of all the source files specified within the command line environment, but not to compile them. Any errors are sent to the standard error output stream. This is useful for syntax checking of the source prior to actual compilation.


Example 85. Option -Zs

To run a syntax check on the source file testf.c, use the command line shown below. No compilation of the source file takes place, and any errors are sent to the standard error stream.

ccxsc -Zs testf.c


Pragmas 7

This chapter provides a detailed description of all pragmas supported by the Intel® C++ Compiler.


• Section 7.1, “Introduction” on page 184 covers the usage of Intel® C++ Compiler pragmas.

• Section 7.2, “Microsoft* Compatible Pragmas” on page 185 describes all pragmas that are supported due to Microsoft* compatibility. The pragmas are listed in alphabetical order.

• Section 7.3, “ARM* Compatible Pragmas” on page 201 describes all ARM* compatible compiler pragmas in detail; these are listed in alphabetical order.

• Section 7.4, “GNU Compatible Pragmas” on page 207 describes all GNU compatible compiler pragmas in detail; these are listed in alphabetical order.


Pragmas

7.1 Introduction

Pragmas are a portable method of passing options within the source file to the compiler.

The syntax of pragmas is as follows:

Syntax: #pragma pragma_name { tokens }

pragma_name is the name of the pragma that may be specified in upper case or lower case letters. Pragmas that are unknown to the Intel® C++ Compiler are ignored.

The tokens following the keyword #pragma are processed by the C/C++ preprocessor according to the ANSI standard.


Pragmas

7.2 Microsoft* Compatible Pragmas

The following section lists Microsoft* pragmas which are supported by the Intel® C++ Compiler. For compatibility, all unsupported Microsoft pragmas can be called without error. However, they have no effect on the compilation process.

7.2.1 Pragma alloc_text

Syntax: #pragma alloc_text( "textsection", func1, ... )

Description: The pragma alloc_text specifies a text section textsection where function definitions of functions func1, ... are allocated.

Example 86. Pragma alloc_text

double funct1(int );char funct2(int );

#pragma alloc_text("testname",funct1,funct2)

double funct1(int a){ return(a*a);}

char funct2(int a){ return((char)a);}

Further Information:MSDN Library


Pragmas

7.2.2 Pragma bss_seg

Syntax: #pragma bss_seg( ["sectionname"[,"sectionclass"]] )

Description: The pragma bss_seg specifies a section sectionname that is to be used as default section for uninitialized data. The default value for sectionname is .bss.

Note: The parameter sectionclass is ignored. It is accepted for compatibility reasons.

Example 87. Pragma bss_seg

#pragma bss_seg("testsection")

int a=0;char b='\0';

int main(){ return(0);}

Further Information:Section 7.2.7, “Pragma data_seg” on page 191MSDN Library


Pragmas

7.2.3 Pragma code_seg

Syntax: #pragma code_seg ( ["sectionname"[,"sectionclass"]])

Description: The pragma code_seg specifies a code section sectionname that is to be used as default section for functions. The default value for sectionname is .text.


Example 88. Pragma code_seg

#pragma code_seg("Testsection")int funct1(){ char* a="Testsection"; return(a[0]);}




Pragmas

7.2.4 Pragma comment

Syntax: #pragma comment( type [, string] )

Description: The pragma comment puts a comment into an object file or executable file.

Example 89. Pragma comment

#pragma comment(user,"You will find this text as a comment in the object file")



Pragmas

7.2.5 Pragma component

Syntax: #pragma component( browser, { on | off }[, references [, name ]] )#pragma component( minrebuild, on | off )

Description: The pragma component is used to turn the collecting of browse information on or off. By the argument references, you can specify if references are to be ignored. The parameter name specifies the name of the references to be ignored.minrebuild prevents the compiler from collecting any class dependency information.

Example 90. Pragma component

#pragma component(browser,on)#include<stdio.h>

int main(){ int i; int *ri=&i;

int j; int *rj=&j;

*ri=5; *rj=25;

printf("Hello world!\n%d%d",i,j); return(0);}



Pragmas

7.2.6 Pragma const_seg

Syntax: #pragma const_seg( ["sectionname"[, "sectionclass"] ] )

Description: The pragma const_seg specifies a section sectionname that is to be used as default section for constant data.The default value for sectionname is ".const".


Example 91. Pragma const_seg

#pragma const_seg("testsection")const char a='T';const int b=12;


Further Information:Section 7.2.7, “Pragma data_seg” on page 191MSDN Library


Pragmas

7.2.7 Pragma data_seg

Syntax: #pragma data_seg( ["sectionname"[, "sectionclass"] ] )

Description: The pragma data_seg specifies a section sectionname that is to be used as default section for initialized and uninitialized data.

Example 92. Pragma data_seg

#pragma data_seg("testsection")

int a=0;char b='\0';


Further Information:Section 7.2.2, “Pragma bss_seg” on page 186Section 7.2.6, “Pragma const_seg” on page 190MSDN Library


Pragmas

7.2.8 Pragma function

Syntax: #pragma function( func1 [, func2, ...] )

Description: The pragma function generates calls to the functions listed in the argument list.

Example 93. Pragma function

#include<string.h>#pragma function(strcpy)int main(){ char b[6]; strcpy(b,"Hello"); return(0);}


Pragmas

7.2.9 Pragma hrdstop

Syntax: #pragma hdrstop [( "headerfile" )]

Description: If a source code contains the pragma hdrstop, the compilation status up to the pragma location is saved. The compilation status is saved into the precompiled header file headerfile.

The default value for headerfile is the source file name with extension ".pch".

Example 94. Pragma hrdstop

#pragma hdrstop( "c:\myprojects\include\myheader.pch" )



Pragmas

7.2.10 Pragma include_alias

Syntax: #pragma include_alias( "filenamel", "filenames" )#pragma include_alias( <filenamel>, <filenames> )

Description: The pragma include_alias enables to use the short filename filenames instead of the long filename filenamel.

Example 95. Pragma include

#pragma include_alias("myheader.h","include_alias.h")#pragma include_alias(<mystdio.h>,<stdio.h>)

#include"myheader.h"#include<mystdio.h>

int main(){ int a; a=funct1(90,'D'); printf("%s",var1); return(0);}

int funct1(int a, char b){

return(a-(int)b);}


Pragmas

7.2.11 Pragma intrinsic

Syntax: #pragma intrinsic( func1 [, func2, ...] )

Description: The pragma intrinsic generates calls to functions listed in the argument list. The functions in the argument list are intrinsic functions.

Example 96. Pragma intrinsic

#include<string.h>#include<stdlib.h>#include<string.h>#include<math.h>#pragma intrinsic(_lrotl,_lrotr,_rotl,_rotr,_strset,abs,fabs,labs,memcmp,memcpy,memset,strcat,strcmp,strcpy,strlen,acos,asin,cosh,fmod,pow,sinh,tanh,atan,exp,log10,sqrt,atan2,log,sin,tan,cos)

int main(){ char varchar1[10]="Hello",varchar2[10]="world"; int varint;

double vardouble; long varlong; unsigned int varunin; unsigned short varunsh; unsigned long varunlo;

varunlo=_lrotl(0x00acaca,1); varunlo=_lrotr(0x00acaca,1);

varunin=_rotl(0x00aca,1); varunin=_rotr(0x00aca,1);

_strset(varchar1,2);

varint=abs(-5); vardouble=fabs(-5.6); varlong=labs(-5);

memcpy(varchar1,varchar2,5); varint=memcmp(varchar1,varchar2,5); memset(varchar1,'*',5);

strcpy(varchar1,varchar2); strcat(varchar1,"*"); varint=strcmp(varchar1,varchar2); varint=strlen(varchar1);

vardouble=acos(3); vardouble=asin(3); vardouble=cosh(3); vardouble=fmod(3,4); vardouble=pow(3,5); vardouble=sinh(3);


Pragmas

vardouble=tanh(3); vardouble=atan(3); vardouble=exp(3); vardouble=log10(3); vardouble=sqrt(3); vardouble=atan2(3,2); vardouble=log(3); vardouble=sin(3); vardouble=tan(3); vardouble=cos(3);

return(0);}


Pragmas

7.2.12 Pragma message

Syntax: #pragma message( messagestr )

Description: The pragma message sends a literal string messagestr to the standard output at compile time.

Example 97. Pragma message

#pragma message("This is a test message")




Pragmas

7.2.13 Pragma optimize

Syntax: #pragma optimize( "[optlist]", {on | off} )

Description: The pragma optimize specifies compiler optimizations. The parameters on or off specify whether options of the optimization list optlist are turned on or off.

Example 98. Pragma optimize

#pragma optimize("s",on)#include<stdio.h>

int main(){ int i = -100; while( i < 0 ) { i += 1; }

return(0);}



Pragmas

7.2.14 Pragma pack

Syntax: #pragma pack( [n] )

Description: The pragma pack specifies packing alignment for structure and union members. n is one of 1, 2, 4, 8, or 16.

Example 99. Pragma pack

#pragma pack(1)

struct structure //Declaration of struct { short j; char a; int n; short k; double x; }structure;

int main(){ int c; char buff1[3];

structure.j=32766; structure.a='X'; structure.n=147483644; structure.k=32222; structure.x=999999999999999;

return(0);}



Pragmas

7.2.15 Pragma warning

Syntax: #pragma warning( specifier : numlist {;specifier : numlist} )#pragma warning( push[ , n ] )#pragma warning( pop )

Description: The pragma warning controls the behavior of warning messages. The parameter specifier is a warning specifier. The parameter numlist is a list containing warning numbers.

Example 100. Pragma warning

pragma warning(disable: 810 69; once: 144; error:120)

int main(){ char c0[5]="Hello world!"; char c1[5]="Hello world!"; char c2[5]="Hello world!"; char c3[5]="Hello world!"; char c4[5]="Hello world!"; char c5[5]="Hello world!"; char c6[5]="Hello world!"; char c7[5]="Hello world!"; char c8[5]="Hello world!"; char c9[5]="Hello world!";

char d0="q"; char d1="w";

return(&d0);}



Pragmas

7.3 ARM* Compatible Pragmas

7.3.1 Pragma check_stack

Syntax: #pragma check_stack

Description: The pragma check_stack is used to regenerate code that checks stack limit violation.

Further Information:ARM Developer Suite, Compiler, Linker, and Utilities Guide


Pragmas

7.3.2 Pragma debug

Syntax: #pragma debug

Description: The pragma debug turns the generation of debug tables on or off.



Pragmas

7.3.3 Pragma ospace

Syntax: #pragma ospace

Description: The pragma ospace turns on the optimization for space.



Pragmas

7.3.4 Pragma otime

Syntax: #pragma otime

Description: The pragma otime turns on the optimization for time.



Pragmas

7.3.5 Pragma onum

Syntax: #pragma onum

Description: The pragma onum is used to change the level of optimization. num can be one of the values 1, 2, or 3.



Pragmas

7.3.6 Pragma softfp_linkage

Syntax: #pragma softp_linkage

Description: If the pragma softp_linkage is specified, all functions declared up to the next pragma no_softp_linkage use software floating point linkage.



Pragmas

7.4 GNU Compatible Pragmas

7.4.1 Pragma align

Syntax: #pragma align

Description: The pragma align is used to control the alignment of structures and structure members.


Pragmas

7.4.2 Pragma isr

Syntax: #pragma isr

Description: The pragma isr indicates certain functions as interrupt service routines. For these functions the compiler generates appropriate code for saving or restoring registers, uses banked registers whenever possible, and generates the appropriate code sequence for returning from this function.


Pragmas

7.4.3 Pragma section (C mode only)

Syntax: #pragma section

Description: The pragma section groups selected text and data objects into sections so that they can be allocated together in memory.


Pragmas



Assembly Language Output File 8

This chapter describes the creation of assembly language output files using the Intel® C++ Compiler.

The generation of an assembly language output file is an intermediate step in generating the object file. By default, the assembly language output file is deleted when the Intel® C++ Compiler has finished with it, although a command line option can prevent this.

An assembly language output file may be used as an additional compile listing, a production document, a debugging aid, or as the basis for an assembly language subroutine for the application.

The chapter contains the following sections:

• Section 8.1, “Creating an Assembly Language Output File” on page 212 describes how the assembly language output file is created using the Intel® C++ Compiler. Additionally, it describes the output file’s contents.

• Section 8.2, “Example” on page 214 provides an example demonstrating how an assembly language output file is generated.


Assembly Language Output File

8.1 Creating an Assembly Language Output File

If the command line option -S is set, the Intel® C++ Compiler generates an assembly language output file.

The assembly language output file is created in the current working directory. If the source file has for example the name name.c, the assembly language output file by default has the base name name but with an extension .s, giving name.s. If the command line option -ooutfile is set to specify the output file name, the assembly language output file is named outfile. In this case the output file takes on any extension given with outfile, or it assumes the extension .s if none is included, giving outfile.s.

Every assembly language output file starts with a header consisting of a series of comment lines. The first line contains the name and version of the program that generated the file. The next line specifies when and by whom this version was created. For example, a typical header might start like this:

@ ident "Intel(R) C++ Compiler for 32-bit applications, Version num";@ ident "Built Dec 3 2001 14:51:12 by name on computer in drive/path";

The following comment lines specify internal options and definitions:

@ ident "-B -D__XSCALE__ -D__APCS_3";@ ident "2__ -D__ARMEL__ -Darm_elf -D__ELF__";

The assembly language output file comprises the actual assembler text:

.file "hello.c"

.text

.align 4

.

.

. @ -- Begin main @ mark_begin;.B1.1: @ Preds .B1.0 .align 2 .global mainmain: stmfd sp!, {r14} @ 4.1 sub r13, r13, #8 @ 4.1 ldr r0, .L0 @ __STRING.0.extern printf bl printf @ 5.4.B1.2: @ Preds .B1.1 mov r0, #0 @ 6.1 add r13, r13, #8 @ 6.1 ldmfd sp!, {pc} @ 6.1.L0: .word __STRING.0 @ mark_end;...



Further Information:Section 6.31, “Option -O” on page 113Section 6.32, “Option -o” on page 114Section 6.76, “Option -S” on page 158



8.2 Example

This section provides an example of generating an assembly language output file.

Consider the source file hello.c:

#include <stdio.h>

int main(void){ printf("hello, world");}

If the compiler is called with the following command line, the assembly language output file shown below is generated:

ccxsc -S hello.c

The compiler generates the assembly language output file hello.s. The following is an excerpt:

@ mark_description "Intel(R) C++ Compiler for 32-bit applications, Version 6.0 Beta Build x";....data.section .text @ -- Begin main @ mark_begin;.B1.1: @ Preds .B1.0 .align 2 .global mainmain: stmfd sp!, {r14} @ 4.1 sub r13, r13, #8 @ 4.1 ldr r0, .L0 @ __STRING.0.extern printf bl printf @ 5.4.B1.2: @ Preds .B1.1 mov r0, #0 @ 6.1 add r13, r13, #8 @ 6.1 ldmfd sp!, {pc} @ 6.1.L0: .word __STRING.0 @ mark_end;.section .data1.align 2__STRING.0:.byte 104 @ s8.byte 101 @ s8.byte 108 @ s8.byte 108 @ s8.byte 111 @ s8.byte 44 @ s8.byte 32 @ s8.byte 119 @ s8



.byte 111 @ s8

.byte 114 @ s8

.byte 108 @ s8

.byte 100 @ s8

.byte 0 @ s8

.data @ -- End main.data.extern printf# End


Optimizations 9

This chapter describes the optimization features of the Intel® C++ Compiler.

• Section 9.1, “Optimization Levels” on page 218 provides an overview of optimization levels, options used for optimization, and options to restrict optimization during compilation.

• Section 9.2, “Floating Point Arithmetic Optimizations” on page 220 summarizes floating point arithmetic precision.

• Section 9.3, “Interprocedural Optimizations” on page 222 describe interprocedural optimizations (IPOs).

• Section 9.4, “Inline Expansion of Library Functions” on page 225 describes inline expansion of functions.

• Section 9.5, “High-level Language Optimizations” on page 228 describes high-level language optimizations


Optimizations

9.1 Optimization Levels

9.1.1 Optimization Levels Overview

The table below shows the optimizations that the compiler applies when you invoke the optimization in the "Option" column.

9.1.2 Setting Optimization Levels


Option Optimization Affected Aspect of Program

-O1, -O2, -O3 constant propagation constants and expression evaluation

-O1, -O2, -O3 copy propagation mov/fmov instructions

-O1, -O2, -O3 dead-code elimination code size

-O1, -O2, -O3 global register allocation register use

-O1, -O2, -O3 instruction scheduling instruction reordering

-O1, -O2, -O3 loop unrolling loop overhead/structure

-O1, -O2, -O3 loop-invariant code movement instruction sequencing

-O1, -O2, -O3 partial redundancy elimination constants and expression evaluation

-O1, -O2, -O3 strength reduction/induction variable simplification

instruction selection/sequencing constants and expression evaluation

-O1, -O2, -O3 variable renaming register use

Table 29. Optimization Levels

Option Effect

-O1 Code size optimization. Enable options -Og, -Oi, -Os, -Oy, -Ob1, and -Gy.

-O2 Code speed optimization. Enable options -Og, -Oi, -Ot, -Oy, -Ob1, and -Gy.

-Ox Same as -O2, except that -Ox does not include -Gy.


Optimizations

9.1.3 Restricting Optimization

The options that restrict or preclude the compiler's ability to optimize your program are listed in the table below.

Table 30. Optimization Restrictions

Option Description

-Od Disables optimizations -O1, -O2, and/or -O3.

-Oi- Suppresses automatic inline expansion of math library functions such as sin.

-Op Restricts optimizations that cause some minor loss or gain of precision in floating point arithmetic to maintain a declared level of precision and to ensure that floating point arithmetic more nearly conforms to the ANSI and IEEE standards.


Optimizations

9.2 Floating Point Arithmetic Optimizations

9.2.1 Floating Point Arithmetic Precision

9.2.2 Restricting Floating Point Arithmetic Precision

The -Op option restricts optimization to maintain declared precision and to ensure that floating point arithmetic conforms more closely to the ANSI and IEEE standards. For most programs, specifying this option adversely affects performance. If you are not sure whether your application needs this option, try compiling and running your program both with and without it to evaluate the effects on performance versus precision. Specifying this option has the following effect on program compilation:

• Floating point user variables are not assigned to registers.

• The expressions are evaluated using precision of source operands. The compiler will not use Floating Point Multiply and Add (FMA) to contract multiply and add/subtract operations in a single operation. The contractions can be enabled by using -QIPF_fma option. The compiler will not speculate on floating point operations that may affect the floating point state of the machine.

• Floating point arithmetic comparisons conform to IEEE 754 except for NaN behavior.

• The exact operations specified in the code are performed. For example, division is never changed to multiplication by the reciprocal. The compiler performs floating point operations in the order specified without reassociation. The compiler does not perform the constant folding on floating point values. Constant folding also eliminates any multiplication by 1, division by 1, and addition or subtraction of 0. For example, code that adds 0.0 to a number is executed exactly as written. Compile-time floating point arithmetic is not performed to ensure that floating point exceptions are also maintained.

Table 31. Optimization Restrictions for Floating Point Arithmetic

Option Description

-Op The -Op option restricts optimization to maintain declared precision and to ensure that floating point arithmetic conforms more closely to the ANSI and IEEE standards. See Section 9.2.2, “Restricting Floating Point Arithmetic Precision” on page 220.

-Qlong_double Use -Qlong_double to change the size of the long double type to 80 bits. For compatibility with the Microsoft* compiler, the Intel® C++ Compiler’s default long double type is 64 bits in size, the same as the double type. This option introduces a number of incompatibilities with other files compiled without this option and with calls to library routines. Therefore, it is recommended that the use of long double variables be local to a single file when you compile with this option.


Optimizations

• Whenever an expression is spilled, it is spilled as 80 bits (EXTENDED PRECISION), not 64 bits (DOUBLE PRECISION).

• When assignments to type REAL and DOUBLE PRECISION are made, the precision is rounded from 80 bits (EXTENDED) down to 32 bits (REAL) or 64 bits (DOUBLE PRECISION). When you do not specify -Op, the extra bits of precision are not always rounded away before the variable is reused.

• Even if vectorization and other loop transformations are enabled by the -QxK option, the compiler does not vectorize reduction loops (loops computing the dot product) and loops with mixed precision types. Similarly, the compiler does not enable certain loop transformations. For example, the compiler will not transform reduction loops to perform partial summation or loop interchange.


Optimizations

9.3 Interprocedural Optimizations

The -Qip and -Qipo options enable interprocedural optimizations (IPO) to analyze your code to determine where you can benefit from the optimizations listed in tables that follow.

Inline function expansion is one of the main optimizations performed by the interprocedural optimizer. For function calls that the compiler believes are frequently executed, the compiler might decide to replace the instructions of the call with code for the function itself.

With -Qip, the compiler performs inline function expansion for calls to procedures defined within the current source file. However, when you use -Qipo to specify multifile IPO, the compiler performs inline function expansion for calls to procedures defined in separate files.

Caution: The -Qip and -Qipo options can in some cases significantly increase compile time and code size.

9.3.1 Multifile IPO Overview

Multifile IPOs obtain potential optimization information from individual program modules of multi-file programs. Using this information, the compiler performs optimizations across modules.

The process of program building is divided into two phases: compilation and linkage. Multifile IPO performs different work depending on whether the compilation or linkage is being performed.

• Compilation Phase — As each source file is compiled, multifile IPO stores an intermediate representation (IR) of the source code in a mock object file in a special comment section. Generation pseudo-object files instead of real object files reduces the time spent in the multifile IPO compilation phase. Each mock object file contains the IR for its corresponding source file, but no real code or data. These mock objects must be linked using the -Qipo option with the compiler. (See Creating a Multifile IPO Executable Using a Project Makefile.)

Table 32. Interprocedural Optimizations

Optimization Affected Aspect of Program

inline function expansion eliminates overhead of calls, jumps, branches and loops

interprocedural constant propagation

improves usage of arguments, global variables and return values

monitoring module-level static variables

provides further optimizations, loop invariants elimination

dead code elimination reduces code size

propagation of function characteristics

eliminates extra overhead of function calls

multifile optimization affects the same aspects as -Qip, but across multiple files

passing arguments in registers

provides better function calls and better register usage

loop invariant code motion further optimizations, loop invariant code


Optimizations

Note: Failure to link “mock” objects with -Qipo will result in linkage errors. There are situations where mock object files cannot be used. See the following section, “Option -Qipo” on page 133 for more information.

• Linkage Phase — When you specify -Qipo, the compiler looks for the IR information in the mock object files.

Note: The compiler does not support multifile IPO for static libraries (.lib files). See the following section, “Option -Qipo” on page 133 for more information.

9.3.2 Creating a Multi-file IPO Executable with Compiler Commands

This topic explains how to create a multifile IPO executable as follows in the examples below:

Example 101. IPO Executable

Compile your modules with -Qipo as follows:

1. Enter

ccxsc -Qipo -c a.c b.c c.c

on the command prompt.Use -c to stop compilation after generating .o files. Each object file has the IR for the corresponding source file. With preceding results, you can now optimize interprocedurally:

2. Enter

ccxsc -Fo nu_ipo_file -Qipo a.o b.o c.o

on the command prompt. The -Fo option stores the executable in nu_ipo_file.exe. Multifile IPO is applied only to modules that have an IR, otherwise the object file passes to link stage.

For efficiency, combine steps 1 and 2:

Enter

ccxsc -Qipo -Fo nu_ipo_file a.c b.c c.c

on the command prompt.

Another IPO related option that can be used is:

-Qwp_ipo

This creates a whole program IPO, for optimizing procedures across all files.


Optimizations

9.3.3 Analyzing the Effects of Multifile IPO

The -Qipo_c and -Qipo_S options are useful for analyzing the effects of multifile IPO, or when experimenting with multifile IPO between modules that do not make up a complete program.

Use the -Qipo_c option to optimize across files and produce an object file. This option performs optimizations as described for -Qipo, but stops prior to the final link stage, leaving an optimized object file. The default name for this file is ipo_out.o. You can use the -Fe option to specify a different name. For example:

ccxsc -Qipo_c -Fefile a.c b.c c.c

Use the -Qipo_S option to optimize across files and produce an assembly file. This option performs optimizations as described for -Qipo, but stops prior to the final link stage, leaving an optimized assembly file. The default name for this file is ipo_out.s. You can use the -Fe option to specify a different name. For example:

ccxsc -Qipo_S -Fefile a.c b.c c.c

For more information on inlining and the minimum inlining criteria, see Inline Expansion of Library Functions.


Optimizations

9.4 Inline Expansion of Library Functions

By default, the compiler automatically expands (inlines) a number of standard and math library functions at the point of the call to that function, which usually results in faster computation.

However, the inlined library functions do not set the errno variable when being expanded inline. For code that relies upon the setting of the errno variable, you should use the -Oi- option. Also, if one of your functions has the same name as one of the compiler-supplied library functions, then when this function is called, the compiler assumes that the call is to the library function and replaces the call with an inlined version of the library function.

So, if the program defines a function with the same name as one of the known library routines, you must use the -Oi- option to ensure that the user-supplied function is used. The option -Oi- disables inlining of all intrinsics.

Your results can vary slightly using the preceding optimizations.

9.4.1 Controlling Inline Expansion of User Functions

The compiler lets you control the amount of inline function expansion with the options shown in the following summary.

Option Effect

-Ob0 Disables inline expansion of user-defined functions.

-Ob1 Disables inlining unless -Qip or -Ob2 is specified (default is ON).

-Ob2 Enables inlining of any function. However, the compiler decides which functions are inlined. This option enables interprocedural optimizations and has the same effect as specifying the -Qip option.

-Qip_no_inlining This option is only useful if -Qip or -Qipo is also specified. In such case, -Qip_no_inlining disables inlining that would result from the -Qip or -Ob2 interprocedural optimizations, but has no effect on other interprocedural optimizations.

-Qip_no_pinlining Disables partial inlining; can be used if -ip or -ipo is also specified.

-Qinline_debug_info Keeps source information for inlined functions.


Optimizations

9.4.2 Criteria for Inline Function Expansion

For a routine to be considered for inlining, it has to meet certain minimum criteria. There are three main components of a call:

• Call-site is the site of the call to the function that might be inlined.

• Caller is the function that contains the call-site.

• Callee is the function being called that might be inlined.

9.4.2.1 Minimum Call-site Criteria

• The number of actual arguments must match the number of formal arguments of the callee.

• The number of return values must match the number of return values of the callee.

• The data types of the actual and formal arguments must be compatible.

• No multi-lingual inlining is valid. Caller and callee must be written in the same source language.

9.4.2.2 Minimum Criteria for the Caller

• At most, 2000 intermediate statements will be inlined into the caller from all the call-sites. The function must be called if it is declared as static. Otherwise, it will be deleted.


Optimizations

9.4.2.3 Minimum Criteria for the Callee

• Does not have variable argument list.

• Is not considered infrequent due to the name. Routines which contain the following substrings in their names are not inlined:

• Is not considered unsafe for other reasons.

9.4.2.4 Selecting Routines for Inlining

• Once these criteria are met, the compiler picks the routines whose inline expansions will provide the greatest benefit to program performance. This is done using the following default heuristics:

— The default heuristic focuses on call-sites in loops or calls to functions containing loops.

— The compiler will not inline functions with more than 230 intermediate statements. The default inline heuristic will stop inlining when direct recursion is detected.

— The default heuristic will always inline very small functions that meet the minimum inline criteria. The default is: ip_ninl_min_stats = 7.

abort interrupt

alloca invalid

denied quit

err rare

exit stop

fail timeout

fatal trace

fault trap

halt warn

init


Optimizations

9.5 High-level Language Optimizations

These optimizations include loop transformations and loop unrolling techniques. The generic option required to turn on the high-level optimizations is -O3.

9.5.1 Loop Unrolling

You can unroll loops and specify the maximum number of times you want the compiler to do so.

9.5.1.1 How to Enable Loop Unrolling

You can use the -Qunroll[n] option to unroll loops. The n variable you enter determines the maximum number of times for the unrolling operation. This applies only to loops that the compiler determines should be unrolled. Omit n to let the compiler decide whether to perform unrolling or not.

Example 102. Unrolling a Lop at Most Four Times

ccxsc -Qunroll4 a.cpp

9.5.1.2 How to Disable Loop Unrolling

Disable loop unrolling by setting the n variable to 0.

Example 103. Disabling Loop Unrolling:

ccxsc -Qunroll0 a.cpp

9.5.1.3 Effect of the Default

The default for loop unrolling is ON. However, since n is not specified, the compiler automatically chooses the maximum number of times to unroll a loop based on internal optimization algorithms. You can also omit n to allow the compiler to decide whether or not to perform loop unrolling. In these cases there is no limit to the number of times a loop may be unrolled.

-/O3 Enable -O2 option plus more aggressive optimizations, for example, loop transformation and prefetching.The option -O3 optimizes for maximum speed, but may not improve performance for some programs.


Vectorization 10

This chapter describes the vectorizer of the Intel® C++ Compiler.

The vectorizer is a component of the Intel® C++ Compiler that automatically uses SIMD instructions in the Intel® Wireless MMX™ technology instruction set. The vectorizer detects operations in the program that can be done in parallel, and then converts the sequential program to process 2, 4, or 8 elements in one operation, depending on the data type.

This chapter provides guidelines, option descriptions, and examples for the Intel® C++ Compiler vectorization on Intel XScale® microarchitecture systems only. The following list summarizes this section's contents.

• Section 10.1, “Vectorizer Quick Reference” on page 230 provides a quick reference of compiler options to control vectorization.

• Section 10.2, “Vectorization Key Programming Guidelines” on page 231 provides a list of general guidelines and restrictions.

• Section 10.3, “Data Dependence” on page 233 describes data dependence relations.

• Section 10.4, “Loop Constructs” on page 235 provides information on loop constructs, loop exit conditions, types of loops, stripmining and cleanup, and statements in the loop body.

• Section 10.5, “Language Support and Directives” on page 240 addresses language features that help to vectorize code.

• Section 10.6, “Some Vectorization Examples” on page 246 provides several examples demonstrating typical vectorization issues and resolutions.


Vectorization

10.1 Vectorizer Quick Reference

Table 33. Vectorization Options

Option Description

-Qvec_reportn file

Controls the vectorizer's level of diagnostic messages:

• n =0 no diagnostic information is displayed.

• n =1 display diagnostics indicating loops successfully vectorized.

• n =2 same as n =1, plus diagnostics indicating loops not successfully vectorized.

• n =3 same as n =2, plus additional information about any proven or assumed dependences.

The information is written to the file file.


Vectorization

10.2 Vectorization Key Programming Guidelines

The goal of vectorizing compilers is to exploit single-instruction multiple data (SIMD) processing automatically. Review these guidelines and restrictions, see code examples in further topics, and check them against your code to eliminate ambiguities that prevent the compiler from achieving optimal vectorization.

10.2.1 Guidelines for loop bodies

• Use straight-line code (a single basic block)

• Use vector data only; that is, arrays and invariant expressions on the right hand side of assignments. Array references can appear on the left hand side of assignments.

• Use only assignment statements.

• Avoid function calls.

• Avoid unvectorizable operations.

• Avoid mixing vectorizable types in the same loop.

• Avoid data-dependent loop exit conditions.

10.2.2 Preparing Your Code for Vectorization

To make your code vectorizable, you will often need to make some changes to your loops. However, you should make only the changes needed to enable vectorization and no others. In particular, you should obey the following guidelines:

• Do not unroll your loops, the compiler does this automatically.

• Do not decompose one loop with several statements in the body into several single-statement loops.

Intel® C++ CompilerUser’s Manual 231

Vectorization

10.2.3 Restrictions

10.2.3.1 Style

The style in which you write source code can inhibit optimization. For example, a common problem with global pointers is that they often prevent the compiler from being able to prove two memory references at distinct locations. Consequently, this prevents certain reordering transformations.

Many stylistic issues that prevent automatic vectorization by compilers are found in loop structures. The ambiguity arises from the complexity of the keywords, operators, data references, and memory operations within the loop bodies.

However, by understanding these limitations and by knowing how to interpret diagnostic messages, you can modify your program to overcome the known limitations and enable effective vectorizations. The subsequent topic summarize the capabilities and restrictions of the vectorizer with respect to loop structures.


Vectorization

10.3 Data Dependence

Data dependence relations represent the required ordering constraints on the operations in serial loops. Because vectorization rearranges the order in which operations are executed, any auto-vectorizer must have at its disposal some form of data dependence analysis. The "Data-dependent Loop" example below shows some code that exhibits data dependence. The value of each element of an array is dependent on itself and its two neighbors.

Example 104. Data-dependent Loop

int data[N];

int i;

for (i=1; i<N-1; i++)

{

data[i] = data[i-1]*0.25 + data[i]*0.5 + data[i + 1]*0.25;

}

The loop in the example above is not vectorizable, because the write to the current element data[i] is dependent on the use of the preceding element data[i-1], which has already been written to and changed in the previous iteration. To see this, look at the access patterns of the array for the first two iterations as shown in the following example:

Example 105. Data Dependence Vectorization Patterns

i=1: READ data[0]

READ data[1]

READ data[2]

WRITE data[1]

i=2: READ data[1]

READ data[2]

READ data[3]

WRITE data[2]

In the normal sequential version of the loop shown, the value of data[1] read from during the second iteration was written to in the first iteration. For vectorization, the iterations must be done in parallel, without changing the semantics of the original loop.


Vectorization

10.3.1 Data Dependence Theory

Data dependence analysis involves finding the conditions under which two memory accesses may overlap. Given two references in a program, the conditions are defined by:

• whether the referenced variables may be aliases for the same (or overlapping) regions in memory,

• for array references, the relationship between the subscripts.

For array references, the Intel® C++ Compiler's data dependence analyzer is organized as a series of tests that progressively increase in power as well as time and space costs. First, a number of simple tests are performed in a dimension-by-dimension manner, since independence in any dimension will exclude any dependence relationship. Multi-dimensional arrays references that may cross their declared dimension boundaries can be converted to their linearized form before the tests are applied. Some of the simple tests used are the fast GCD test, proving independence if the greatest common divisor of the coefficients of loop indices cannot evenly divide the constant term, and the extended bounds test, which tests potential overlap for the extreme values of subscript expressions.

If all simple tests fail to prove independence, the compiler will eventually resort to a powerful hierarchical dependence solver that uses Fourier-Motzkin elimination to solve the data dependence problem in all dimensions.


Vectorization

10.4 Loop Constructs

Loops can be formed with the usual for and while-do, or repeat-until constructs or by using a goto and a label. However, the loops must have a single entry and a single exit to be vectorized.

Example 106. Correct Usage of Loop Constructs

while (i < n)

{

/* if branch inside body of loop */

a[i] = b[i] * c[i];

if (a[i] < 0.0)

{

a[i] = 0.0;

}

i++;

}

Example 107. Incorrect Usage of Loop Constructs

while (i < n)

{

if (condition) break;

/* 2nd exit */

++i;

}


Vectorization

10.4.1 Loop Exit Conditions

Loop exit conditions determine the number of iterations that a loop executes. For example, fixed indexes for loops determine the iterations. The loop iterations must be countable; that is, the number of iterations must be expressed as one of the following:

• a constant

• a loop invariant term

• a linear function of outermost loop indices

Loops whose exit depends on computation are not countable. Examples below show countable and non-countable loop constructs.

Example 108. Correct Usage for Countable Loop

count = N; /* exit condition specified by "N - 1b + 1" */

...

while (count != 1b)

{

/* 1b is not affected within loop */

a[i] = b[i] * x;

b[i] = c[i] + sqrt(d[i]);

--count;

}

Example 109. Correct Usage for Countable Loop

/* exit condition is "(n-m+2)/2" */

i = 0;

for (l=m; l<n; l+=2)

{

a[i] = b[i] * x;

b[i] = c[i] + sqrt(d[i]);

++i;

}


Vectorization

Example 110. Incorrect Usage for Non-countable Loop

i = 0;

/* iterations dependent on a[i] */

while (a[i] > 0.0)

{

a[i] = b[i] * c[i];

++i;

}

10.4.2 Types of Loops Vectorized

For integer loops, the Intel® Wireless MMX™ coprocessor provides SIMD instructions for most arithmetic and logical operators on 32-bit, 16-bit, and 8-bit integer data types. Vectorization may proceed if the final precision of integer wrap-around arithmetic will be preserved. A 32-bit shift-right operator, for instance, is not vectorized if the final stored value is a 16-bit integer. Also, note that because the Intel® Wireless MMX™ instruction set is not fully orthogonal (byte shifts, for instance, are not supported), not all integer operations can actually be vectorized.


Vectorization

10.4.3 Stripmining and Cleanup

The compiler automatically stripmines your loop and generates a cleanup loop. This means you do not need to unroll your loops, and, in most cases, this will also enable more vectorization.

Example 111. Stripmining and Cleanup

Before vectorization:

i = 0;

while (i < n)

{

/* original loop code */

a[i] = b[i] + c[i];

++i;

}

After Vectorization:

/* the vectorizer generates the following two loops */

i = 0;

while (i < (n - n%4) )

{

/* vector strip-mined loop */

/* subscript [i:i+3] denotes SIMD execution */

a[i:i+3] = b[i:i+3] + c[i:i+3];

i = i + 4;

}

while (i < n)

{

/* scalar clean-up loop */

a[i] = b[i] + c[i];

}


Vectorization

10.4.4 Statements in the Loop Body

The vectorizable operations are supported only on integer data. The vectorizable operations are not supported on floating point data yet.

10.4.4.1 Integer Array Operations

The statements within the loop body may contain char, unsigned char, short, unsigned short, int, and unsigned int. Calls to functions such as sqrt and fabs are also supported. Arithmetic operations are limited to addition, subtraction, bitwise AND, OR, and XOR operators, division (16-bit only), multiplication (16-bit only), min, and max. You can mix data types only if the conversion can be done without a loss of precision. Some example operators where you can mix data types are multiplication, shift, or unary operators.

10.4.4.2 Other Operations

No statements other than the preceding integer operations are allowed. In particular, note that the special __m64 datatype is not vectorizable. The loop body cannot contain any function calls.


Vectorization

10.5 Language Support and Directives

This topic addresses language features that better help to vectorize code. The declspec(align(n)) declaration enables you to overcome hardware alignment constraints. The restrict qualifier and the pragmas address the stylistic issues due to lexical scope, data dependence, and ambiguity resolution.

10.5.1 Language Support

10.5.2 Multi-version Code

Multi-version code is generated by the compiler in cases where data dependence analysis fails to prove independence for a loop due to the occurrence of pointers with unknown values. This functionality is referred to as dynamic dependence testing.

10.5.3 Pragma Scope

These pragmas control the vectorization of only the subsequent loop in the program, but the compiler does not apply them to any nested loops. Each nested loop needs its own pragma preceding it in order for the pragma to be applied. You must place a pragma only before the loop control statement.

Table 34. Language Support

Option Description

__declspec(align(n)) Directs the compiler to align the variable to an n-byte boundary. Address of the variable is address mod n=0.

__declspec(align(n,off)) Directs the compiler to align the variable to an n-byte boundary with offset off within each n-byte boundary. Address of the variable is address mod n = off.

restrict Permits the disambiguator flexibility in alias assumptions, which enables more vectorization.

__assume_aligned(a,n) Instructs the compiler to assume that array a is aligned on an n-byte boundary; used in cases where the compiler has failed to obtain alignment information.

#pragma ivdep Instructs the compiler to ignore assumed vector dependencies.

#pragma vector {aligned | unaligned | always}

Specifies how to vectorize the loop and indicates that efficiency heuristics should be ignored.

#pragma novector Specifies that the loop should never be vectorized.


Vectorization

10.5.3.1 vector always

Syntax: #pragma vector always

Description: This pragma instructs the compiler to override any efficiency heuristic during the decision to vectorize or not. #pragma vector always will vectorize non-unit strides or very unaligned memory accesses.

Example 112. #pragma vector always

for(i = 0; i <= N; i++)

{

a[32*i] = b[99*i];

}

10.5.3.2 ivdep

Syntax: #pragma ivdep

Description: This pragma instructs the compiler to ignore assumed vector dependences. To ensure correct code, the compiler treats an assumed dependence as a proven dependence, which prevents vectorization. This pragma overrides that decision. Only use this when you know that the assumed loop dependences are safe to ignore.

The loop in this example will not vectorize with the ivdep pragma, since the value of k is not known (vectorization would be illegal if k<0).

Example 113. #pragma ivdep

#pragma ivdep

for (i = 0; i < m; i++)

{

a[i] = a[i + k] * c;

}


Vectorization

10.5.3.3 vector

Syntax: #pragma vector{aligned | unaligned}

Description: The vector loop pragma means the loop should be vectorized, if it is legal to do so, ignoring normal heuristic decisions about profitability. When the aligned (or unaligned) qualifier is used with this pragma, the loop should be vectorized using aligned (or unaligned) operations. Specify one and only one of aligned or unaligned.

Caution: If you specify aligned as an argument, you must be absolutely sure that the loop will be vectorizable using this instruction. Otherwise, the compiler will generate incorrect code.

The loop in the example below uses the aligned qualifier to request that the loop be vectorized with aligned instructions, as the arrays are declared in such a way that the compiler could not normally prove this would be safe to do so.

Example 114. #pragma vector

void foo (int *a)

{

#pragma vector aligned

for (i = 0; i < m; i++)

{

a[i] = a[i] * c;

}

}

The compiler has at its disposal several alignment strategies in case the alignment of data structures is not known at compile-time. A simple example is shown below (but several other strategies are supported as well). If, in the loop shown below, the alignment of a is unknown, the compiler will generate a prelude loop that iterates until the array reference that occurs the most hits an aligned address. This makes the alignment properties of a known, and the vector loop is optimized accordingly.


Vectorization

Example 115. Alignment Strategies Example

int *a;

/* alignment unknown */

for (i = 0; i < 100; i++)

{

a[i] = a[i] + 1.0f;

}

/* dynamic loop peeling */

p = a & 0x0f;

if (p != 0)

{

p = (16 - p) / 4;

for (i = 0; i < p; i++)

{

a[i] = a[i] + 1.0f;

}

}

/* loop with a aligned (will be vectorized accordingly) */

for (i = p; i < 100; i++)

{

a[i] = a[i] + 1.0f;

}


Vectorization

10.5.3.4 novector

Syntax: #pragma novector

Description: The novector loop pragma specifies that the loop should never be vectorized, even if it is legal to do so.

In this example, suppose you know the trip count (ub - lb) is too low to make vectorization worthwhile. You can use #pragma novector to tell the compiler not to vectorize, even if the loop is considered vectorizable.

Example 116. #pragma novector S

void foo (int lb, int ub)

{

#pragma novector

for (j = lb; j < ub; j++)

{

a[j] = a[j] + b[j];

}

}


Vectorization

10.5.4 Dynamic Dependence Testing

Example 117. Dynamic Dependence Testing

int *p, *q;

for (i = L; I <= U; i++)

{

p[i] = q[i];

}

...

pL = p * 4*L;

pH = p + 4*U;

qL = q + 4*L;

qH = q + 4*U;

if (pH < qL || pL > qH)

{

/* loop without data dependence */

for (i = L; i <= U; i++)

{

p[i] = q[i];

} else {

for (i = L; i <= U; i++)

{

p[i] = q[i];

}

}


Vectorization

10.6 Some Vectorization Examples

This section contains a few simple examples of some common issues in vector programming.

10.6.1 Argument Aliasing: A Vector Copy

The loop in the example below, a vector copy operation, vectorizes because the compiler can prove dest[i] and src[i] are distinct.

Example 118. Vectorizable Copy Due to Unproven Distinction

void vec_copy(int *dest, int *src, int len)

{

int i;

for (i = 0; i < len; i++;)

{

dest[i] = src[i];

}

}

The restrict keyword in the example below indicates that the pointers refer to distinct objects. Therefore, the compiler allows vectorization without generation of multi-version code.

Example 119. Using restrict to Prove Vectorizable Distinction

void vec_copy(int *restrict dest, int *restrict src, int len)

{

int i;

for (i = 0; i < len; i++)

{

dest[i] = src[i];

}

}


Vectorization

10.6.2 Data Alignment

An 8-byte or greater data structure or array should be aligned so that the beginning of each structure or array element is aligned in a way that its base address is a multiple of eight.

Figure 2, “Misaligned Data Crossing 8-Byte Boundary” on page 247 shows the effect of a data cache unit (DCU) split due to misaligned data. The code loads the misaligned data across an 8-byte boundary, which results in an additional memory access causing stall. You can avoid the stalls if you know that the data is aligned and you specify to assume alignment.

Figure 2. Misaligned Data Crossing 8-Byte Boundary

For example, if you know that elements a[0] and b[0] are aligned on an 8-byte boundary, then the following loop can be vectorized with the alignment option on (#pragma vector aligned):

Example 120. Alignment of Pointers is Known

short *a, *b;

int i;

for (int i = 0; i < 10; i++)

{

a[i] = b[i];

}

After vectorization, the loop is executed as shown here:

Figure 3. Vector and Scalar Clean-up Iterations

Both the vector iterations a[0:3] = b[0:3]; and a[4:7] = b[4:7]; can be implemented with aligned moves if both the elements a[0] and b[0] (or, likewise, a[4] and b[4]) are 8-byte aligned.


Vectorization

Caution: If you specify the vectorizer with incorrect alignment options, the compiler will exhibit unexpected behavior. Specifically, using aligned moves on unaligned data will result in an illegal instruction exception.


Vectorization

10.6.3 Data Alignment Examples

The example below contains a loop that vectorizes but only with unaligned memory instructions. The compiler can align the local arrays, but because lb is not known at compile-time. The correct alignment cannot be determined.

Example 121. Unaligned Loop (Unknown Variable Value at Compile Time)

void f(int lb)

{

int z2[N], a2[N], y2[N], x2;

for (i = lb; i < N; i++)

{

a2[i] = a2[i] * x2 + y2[i];

}

}

If you know that lb is a multiple of 4, you can align the loop with #pragma vector aligned as shown in the example that follows:

Example 122. Assertion of Variable as Multiple of 4

void f(int lb)

{

int z2[N], a2[N], y2[N], x2;

assert(lb%4==0);

#pragma vector aligned

for (i = lb; i < N; i++)

{

a2[i] = a2[i] * x2 + y2[i];

}

}

The use of assert checks that lb is a multiple of 4.


Vectorization

10.6.4 Loop Interchange and Subscripts: Matrix Multiplication

Matrix multiplication is commonly written as shown in the example below:

Example 123. Typical Matrix Multiplication

for (i = 0; i < N; i++){

for (j = 0; j < n; j++){

for (k = 0; k < n; k++){

c[i][j] = c[i][j] + a[i][k] * b[k][j];}

}}

The use of b[k][j] is not a stride-1 reference and therefore will not normally be vectorizable. If the loops are interchanged, however, all the references will become stride-1 as shown in the "Matrix Multiplication With Stride-1" example.

Caution: Interchanging is not always possible because of dependencies, which can lead to different results.

Example 124. Matrix Multiplication With Stride-1

for (i = 0; i < N; i++){

for (k = 0; k < n; k++){

for (j = 0; j < n; j++){

c[i][j] = c[i][j] + a[i][k] * b[k][j];}

}}


Language Conformance Options 11

This chapter describes the language conformance of the Intel® C++ Compiler. The chapter comprises the following sections:

• Section 11.1, “Conformance to the C Standard” on page 252 describes the Intel® C++ Compiler’s conformance to the ANSI/ISO standard for C language compilation.

• Section 11.2, “Conformance to the C++ Standard” on page 256 describes the Intel® C++ Compiler’s conformance to the ANSI/ISO standard for the C++ language.


Language Conformance Options

11.1 Conformance to the C Standard

You can set the Intel® C++ Compiler to accept either

• strict ANSI conformance dialect using the -Za option, or

• extended ANSI C dialect using the -Ze option

The compiler is set by default to accept extensions and not be limited to the ANSI/ISO standard.

The Intel® C++ Compiler provides conformance to the ANSI/ISO standard for C language compilation (ISO/IEC 9899:1999). This standard requires that conforming C compilers accept minimum translation limits. This compiler exceeds all of the ANSI/ISO requirements for minimum translation limits.

You set the compiler to accept only ANSI/ISO standard C code by using the -Za option. When you set the compiler to accept only ANSI/ISO standard C code, the compiler will flag nonstandard code it encounters during the translation process with warning and error messages.



11.1.1 Understanding the Extensions to ANSI/ISO Standard C Dialect

When you set the compiler to accept extensions to the ANSI/ISO standard, the compiler can process the following extensions.

Table 35. Extensions to ANSI/ISO Standard C Dialect

Extension Type Description

Files and data storage • Input files with no text.

• Incomplete array types for the last member of a structure, except when this is the only member of the structure.

• Incomplete struct or union type file-scope arrays.

Note: The struct and union types must be completed before the array is subscripted. In addition, if the array is defined in the compilation, these types must be subscripted by the end of the compilation.

• The enum tag names you define. You can declare an enum tag name and then define it later in the source file.

• Initializer expressions not enclosed in braces though they initialize any of the following: a full static array, structure, or union. (Standard C requires the braces.)

Pointers • In initializers, pointer constant values cast to an integral type if the integral type is large enough to contain it.

• In integral constant expressions, integer constants cast to a pointer type and then cast back to an integral type.

• Assignments of pointers to integers and to other incompatible pointer types without explicit casts.

• Fields selected in the form p->m when the p variable is a pointer, including when p does not point to a struct or union that contains m. (All definitions of field must have the same type and offset within their structure or union.)

• Fields selected in the form x.m, including when x is not a structure or union containing m when: 1. variable x is not a struct or union containing m and2. the x variable is an Ivalue. (All definitions of field must have the same type and offset within their structure or union.)

Types and syntax • Bitfields with enum base types or integral types other than int and unsigned int.

• The type long float as a synonym for double.

• Arbitrary text at the end of preprocessing directives.

• Numbers that do not comply with the pp-number syntax, because numbers are scanned according to the syntax for numbers when extensions are allowed.

Example: The compiler would scan 0x123e+1 as three tokens. Under strict ANSI conformance mode, the compiler would use the pp-number syntax and scan this number as one invalid token.



11.1.2 How to Set the Compiler for Extended C Dialect

You set the compiler to accept extensions to the ANSI/ISO standard C code by using the -Ze option.

Predicates The macros #assert and #unassert to define and test predicate names.

Syntax with warnings Note: When you have set the compiler to accept extensions, the compiler will accept the following tags and syntax but will tag them with a warning message.

• An extra comma at the end of an enum list.

• Omission of the final semicolon preceding the closing brace "}" of a struct or union.

• A right brace immediately following a label definition. (Normally, a statement must follow a legal definition.)

• An empty declaration, a semicolon with nothing preceding it.

Semantics with warnings • Differences in assignments and pointers between pointers to types that are interchangeable but not identical, such as unsigned char* and char*. (The compiler will issue a warning in this case.)

• A string constant assigned to a pointer to any kind of character.

• Comparison using >, >=, <, or <= operators between pointers to voids and other kinds of pointers, without using an explicit type cast. (Strict ANSI dialect mode requires such comparisons using == or != and issues no warnings.)

• Inline assembly code inserted using the asm keyword. (Strict ANSI dialect mode requires the __asm keyword.)

• Freestanding tag declarations in the parameter declaration list for a function with old-style parameters.

Table 35. Extensions to ANSI/ISO Standard C Dialect

Extension Type Description



11.1.3 Macros Included with the Compiler

The ANSI/ISO standard for C language requires that certain predefined macros be supplied with conforming compilers. The following table lists the macros that the Intel® C++ Compiler supplies in accordance with this standard.

The compiler provides predefined macros in addition to the predefined macros required by the standard. For a list of these macros see Predefined Macros and the section on the preprocessor category in the Microsoft* Visual C++* User's Guide.

Table 36. Macros Included with the Compiler

Macro Description

__cplusplus Defines C++ programs only.

__DATE__ The date of compilation. As a string literal in the form Mmm dd yyyy.

__FILE__ A string literal representing the name of the file being compiled.

__LINE__ The current line number as a decimal constant.

__STDC__ The constant 1 when you set the compiler to accept only standard ANSI conformance. This macro is not defined when you set the compiler to accept extensions.

__TIME__ The time of compilation. As a string literal in the form hh:mm:ss.

__TIMESTAMP__ The date and time of the last modification of the current source file in the form: Day Mon dd hh:mm:ss yyyy.



11.2 Conformance to the C++ Standard

The Intel® C++ Compiler conforms to the ANSI/ISO standard (ISO/IEC 14882:1998) for the C++ language, with the following exceptions:

• Putting a try/catch around the initializers and body of a constructor is not implemented.

• Universal character set escapes (for example, \uabcd) are not implemented.

• The export keyword for templates is not implemented.

For compatibility with Microsoft* Visual C++*, the compiler also supports many extensions to the C++ language. For more information, see the Microsoft* Visual C++* documentation.


The Intel® Library System 12

This chapter covers a general overview of the Intel® Library System, which consists of the C Standard Library and the C++ Library.

The chapter contains the following topics:

• Section 12.1, “Introduction to the Intel® Library System” on page 258 provides an overview of the library system’s structure and describes each library in detail.

• Section 12.2, “Naming of Libraries and Startup Modules” on page 259 explains the filename encoding which depends on several parameters.

• Section 12.3, “Examples” on page 263 provides examples demonstrating the use of libraries and startup modules.


The Intel® Library System

12.1 Introduction to the Intel® Library System

The Intel® Library System supports various specific libraries as depicted in Figure 4. The System contains a C Standard Library and a C++ Library.

The C Standard Library, which is provided for ANSI C support, consists of two main parts. The first part is the C Library which is target independent. The second part of the C Standard Library is target dependent, consisting of the System Library and the startup module. The C Library contains ANSI C functions, C run-time functions, and additional library functions. The functions of the C Library are described in Chapter 12, “The Intel® Library System”. The System Library contains the system interface functions, described in Chapter 14, “Library-Target System Interface”.

The C++ Library is provided for C++ support. It contains run-time support functions, functions used for exception handling, input and output services, and templates. The C++ Library does not replace the C Standard Library. When a C++ application is linked, both the C Standard Library and the C++ Library are required.

The communication between the Intel® Library System, user applications and operating system is as follows. A user application calls functions of the Intel® Library System. The C++ Library might call functions of the C Library, whereas the C Library might call functions of the System Library. The System Library might call functions of the operating system. The startup module and the operating system might call functions reciprocally.

Figure 4. The Intel® Library System and its Communication with the User Application and Operating system

targetindependent

targetdependent

C StandardLibrary

Startup module System Library

Operating system

C Library

C++ Library

User

app

licat

ion



12.2 Naming of Libraries and Startup Modules

The Intel® Library system supports various libraries and startup modules as mentioned in the previous section. All of these libraries and startup modules depend on the memory model and address sizes chosen by the user.

12.2.1 Filename Encoding

Libraries and startup modules are differentiated by the extensions of their filenames. Filenames of libraries have extensions .a, whereas filenames of startup modules have extensions .o .

The filename of libraries and startup modules consists of eight characters which are not case-sensitive. Figure Figure 5 shows an example explaining each character position.

The following tables describe possible values of each item of a library or startup module filename.

X0__A000.o Specifies a startup module.

X0__AC00.a Specifies a library.

Figure 5. Structure of Filenames of Libraries and Startup Modules

1 2 3 4 5 6 7 8

X 0 _ _ A C 0 0

CPU family

memory model

library type

library flag

character position:

core version coprocessor

CPU Family

Character Position: 1

Values Description

X Intel® XScale™



Core Version


Values Description

0 Intel® XScale™ core version

Coprocessor

Character Position: 3-4

Values Description

__ not available

Memory Model


Values Description

A ARM* instructions, little endian, 32-bit

T Thumb* instruction, little endian, 32-bit

B ARM* instructions, big endian, 32-bit

U Thumb* instruction, big endian, 32-bit

Library Type


Values Description

0 Startup module

C ANSI-C Library

X C++ Library

S System Library



The two characters at position 7 and 8, the library flag, are treated as 5-bit numbers for encoding special extensions. The bit encoding is as follows:

Table 37. Bit Position

Symbol at Character Position

Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Hexadecimal Value

0 00

1 X 01

2 X 02

3 X X 03

4 X 04

5 X X 05

6 X X 06

7 X X X 07

8 X 08

9 X X 09

A X X 0A

B X X X 0B

C X X 0C

D X X X 0D

E X X X 0E

F X X X X 0F

G X 10

H X X 11

I X X 12

J X X X 13

K X X 14

L X X X 15

M X X X 16

N X X X X 17

O X X 18

P X X X 19

Q X X X 1A

R X X X X 1B

S X X X 1C

T X X X X 1D

U X X X X 1E

V X X X X X 1F



The library flag can be interpreted as follows:

Example 125. Library Name and Character Encoding

The library has the name X0__AC00.a. The library is interpreted as follows:

Character Position Bit Description

7 4 Not assigned.

3 Task Local Storage Function Support (thread independency, reentrancy of I/O functions)

2 Not assigned.

1 Not assigned.

0 Little Endian “Double” support.

8 4 Not assigned.

3 Not assigned.

2 Note assigned.

1 PID, option -Qrwpi

0 PIC, option -Qropi

Character Position Description

1: X Library for the Intel® XScale™ CPU

2: 0 Core version is 0

3-4: __ No information on coprocessor

5: A Memory model: ARM* instruction set, little endian, 32-bit

6: C The library is the ANSI-C standard library

7: 0 library includes wide-character support and full I/0

8: 0 signed char is set



12.3 Examples

This section provides two examples demonstrating the use of libraries and startup modules.

The linking order of libraries must be as follows:

1. C++ Run-Time Library

2. C Library

3. System Library

Example 126. C Application for the Intel® XDB Simulator Debugger

This example demonstrates how the C application mysource.c is compiled and linked to run on the Intel® XDB Simulator Debugger (xdbsimxs) and how debug information is generated.

Note: It is assumed the working directory containing mysource.c is in the same directory as the directory \lib of the Intel® C++ Compiler, for example:

installation-directory\lib

and

installation-directory\working-directory\mysource.c.

1. Start the compiler using the following command line:

ccxsc -Zi mysource.c

This generates the outputfile mysource.o. The option -Zi generates debug information.

2. Start the Intel® Linker using the following command line:

ldxsc mysource.o ..\lib\simxs\X0__A000.o ..\lib\X0__AC00.a ..\lib\simxs\X0__AS00.a

where:

Note: The order of the files is mandatory!

The linker generates the file mysource.x.

..\lib\simxs\X0__A000.o Specifies the startup module.

..\lib\X0__AC00.a Specifies the C Library.

..\lib\simxs\X0__AS00.a Specifies the System Library.



Example 127. C++ Application for the Intel® XDB Simulator Debugger

This example demonstrates how the C++ application mysource.cpp is compiled and linked to run on the Intel® XDB Simulator Debugger (simxs) and how debug information is generated.

Note: The working directory containing mysource.cpp has to be in the same directory as the directory \lib of the Intel® C++ Compiler, for example:


and

installation-directory\working-directory\mysource.cpp.


ccxsc -Zi mysource.cpp

This generates the outputfile mysource.o. The compiler option -Zi generates debug information.


ldxsc -CPLUS mysource.o ..\lib\simxs\X0__A000.o ..\lib\X0__AX00.a ..\lib\X0__AC00.a ..\lib\simxs\X0__AS00.a

where:



-CPLUS Is a required linker option for linking C++ applications.


..\lib\X0__AX000.a Specifies the C++ Library.

..\lib\X0__AC00.a Specifies the C-Library.

..\lib\simxs\X0__AS00.a Specifies the System Library


The C Standard Library 13

This chapter describes the C Standard Library as supported by the Intel® C++ Compiler.

The chapter covers the following topics:

• Section 13.1, “Introduction to the C Standard Library” on page 266 provides a brief introduction to the C Standard Library, which consists of two main parts: a target-independent part, named the C Library, and a target-dependent part which is further sub-divided into the System Library and startup module. An example demonstrates the usage of these libraries.

• Section 13.2, “Global Symbols” on page 268 provides a summary of all global symbols that are exported by the C Standard Library.

• Section 13.3, “Data Symbols of the Library” on page 277 describes all data symbols which are exported by the C Standard Library.

• Section 13.4, “Header Files” on page 279 describes all header files associated with the library. These header files are designed to be used in conjunction with the libraries supplied with the Intel® C++ Compiler.

• Section 13.5, “Macros” on page 300 describes several macros such as assert, va_arg, va_copy, va_end, and va_start.

• Section 13.6, “Library Functions” on page 305 provides a detailed description of the library functions. The functions are listed in alphabetical order.

• Section 13.7, “The Intel® Run-time Library” on page 523 describes the functions of the run-time library.


The C Standard Library

13.1 Introduction to the C Standard Library

The C Standard Library which is provided by Intel consists of two main parts which are the C Library which is target independent, and a further C library which is target dependent. This latter target dependent library consists of the System Library and the startup module.

The C Library contains the following sets of functions:

• ANSI C functions

• Floating point functions

• C run-time functions

• Additional library functions

The System Library contains the system interface functions. The C Library itself calls functions of the System Library, which in turn together with the startup module, call functions of the operating system.

Note: If the System Library has to be adapted to the user’s target system, it recommended to read Chapter 14, “Library-Target System Interface”.

All C libraries (target independent, memory model dependent) which are supplied by Intel are installed in the following directory:

<installation-directory>\lib

Figure 6. The C Standard Library

targetindependent

targetdependent

C StandardLibrary


Operating system

C Library



Example 128. Usage of Libraries Linking a C Application

This example demonstrates how the C application mysource.c is compiled and linked to run on the Intel® XDB Simulator Debugger (xdbsimxs) and how debug information is generated.

Note: It is assumed that the working directory containing mysource.c is located in the same directory as the directory \lib of the Intel® C++ Compiler,for example: installation-directory\liband installation-directory\working-directory\mysource.c.


ccxsc -c mysource.c

This generates the object outputfile mysource.o.


ldxsc mysource.o ..\lib\simxs\X0__A000.o ..\lib\X0__AC00.a ..\lib\simxs\X0__AS00.a

where:


Further Information:Intel® Linker User’s ManualSection 12.2, “Naming of Libraries and Startup Modules” on page 259Chapter 14, “Library-Target System Interface”.



..\lib\simxs\X0__AS00.a Specifies the System Library.



13.2 Global Symbols

This section gives a summary of all global symbols that are exported by the library, these are classified as follows:

• ANSI-defined reentrant and non-reentrant library functions

• internal library symbols

• additional library functions

• system interface functions

• emulation library functions

13.2.1 ANSI-Defined Reentrant Functions

This table lists all ANSI-defined library functions which are reentrant. Reentrant functions do not reference global or static data. These symbols are explicitly exported by the library and are recommended for general use. They are highly portable due to ANSI compliance.

Reentrant Functions

Symbol Name Name of Defining Module

Name of Include File with Prototype

abs ABS stdlib.h

atan ATAN math.h

atof ATOF stdlib.h

atoi ATOI stdlib.h

atol ATOL stdlib.h

atoll ATOLL stdlib.h

bsearch BSEARCH stdlib.h

ceil CEIL math.h

clock CLOCK time.h

difftime CTIME time.h

div DIV stdlib.h

fabs FABS math.h

floor FLOOR math.h

fmod MODF math.h

getenv GETENV stdio.h

isalnum ISALNUM ctype.h

isalpha ISALPHA ctype.h

iscntrl ISCNTRL ctype.h



isdigit ISDIGIT ctype.h

isgraph ISGRAPH ctype.h

islower ISLOWER ctype.h

isprint ISPRINT ctype.h

ispunct ISPUNCT ctype.h

isspace ISSPACE ctype.h

isupper ISUPPER ctype.h

isxdigit ISXDIGIT ctype.h

itoa ITOA stdlib.h

labs ABS stdlib.h

ldiv DIV stdlib.h

longjmp SETJMP_LONGJMP setjmp.h

memchr MEMCHR string.h

memcmp MEMCMP string.h

memcpy MEMCPY string.h

memmove MEMMOVE string.h

memset MEMSET string.h

mktime CTIME time.h

qsort QSORT stdlib.h

remove REMOVE stdio.h

rename RENAME stdio.h

setjmp SETJMP_LONGJMP setjmp.h

setlocale LOCALE locale.h

sprintf PRINTF stdio.h

sscanf SCANF stdio.h

strcat STRCAT string.h

strchr STRCHR string.h

strcmp STRCMP string.h

strcoll STRCOLL string.h

strcpy STRCPY string.h

strcspn STRCSPN string.h

strlen STRLEN string.h

strncat STRNCAT string.h

strncmp STRNCMP string.h

strncpy STRNCPY string.h

strpbrk STRPBRK string.h

strrchr STRRCHR string.h

Reentrant Functions





13.2.2 ANSI-Defined Non-Reentrant Functions

This table lists all ANSI-defined library functions which are non-reentrant. These symbols are explicitly exported by the library and are recommended for general use. They are highly portable due to ANSI compliance. The second table of this section explains why the following functions are non-reentrant.

strspn STRSPN string.h

strstr STRSTR string.h

strxfrm STRXFRM string.h

tolower TOLOWER ctype.h

toupper TOUPPER ctype.h

Reentrant Functions



Non-reentrant Functions



abort ABORT stdlib.h

acos ACOS math.h

asctime ASCTIME time.h

asin ASIN math.h

atan2 ATAN2 math.h

atexit EXIT stdlib.h

calloc CALLOC stdlib.h

clearerr CLEARERR stdio.h

cos COS math.h

cosh COSH math.h

ctime CTIME time.h

exit EXIT stdlib.h

exp EXP math.h

fclose FCLOSE stdio.h

feof FEOF stdio.h

ferror FERROR stdio.h

fflush FFLUSH stdio.h

fgetc FGETC stdio.h

fgetpos FGETPOS stdio.h

fgets FGETS stdio.h

fopen FOPEN stdio.h



fprintf PRINTF stdio.h

fputc FPUTC stdio.h

fputs FPUTS stdio.h

fread FREAD stdio.h

free MALLOC stdlib.h

freopen FREOPEN stdio.h

frexp MODF math.h

fscanf SCANF stdio.h

fseek FSEEK stdio.h

fsetpos FSETPOS stdio.h

ftell FTELL stdio.h

fwrite FWRITE stdio.h

getc GETC stdio.h

getchar GETCHAR stdio.h

gets GETS stdio.h

gmtime CTIME time.h

ldexp MODF math.h

localeconv LOCALE locale.h

localtime CTIME time.h

log LOG math.h

log10 LOG10 math.h

malloc MALLOC stdlib.h

modf MODF math.h

perror PERROR stdio.h

pow POW math.h

printf PRINTF stdio.h

putc PUTC stdio.h

putchar PUTCHAR stdio.h

puts PUTS stdio.h

raise SIGNAL signal.h

rand RAND stdlib.h

realloc MALLOC stdlib.h

rewind REWIND stdio.h

scanf SCANF stdio.h

setbuf SETBUF stdio.h

setvbuf SETBUF stdio.h

signal SIGNAL signal.h






sin SIN math.h

sinh SINH math.h

sqrt SQRT math.h

srand RAND stdlib.h

strerror STRERROR string.h

strftime ASCTIME time.h

strtod STRTOD stdlib.h

strtok STRTOK string.h

strtol STRTOL stdlib.h

strtoll STRTOLL stdlib.h

strtoul STRTOUL stdlib.h

strtoull STRTOULL stdlib.h

tan TAN math.h

tanh TANH math.h

tmpfile TMPFILE stdio.h

tmpnam TMPNAM stdio.h

ungetc UNGETC stdio.h

vfprintf PRINTF stdio.h

vprintf PRINTF stdio.h

vsprintf PRINTF stdio.h






Table 38. Symbols being Used by Functions

Name of Variable,Structure, or Array

(type)Functions Using Global or Static Data Function Type

errno(global int)

acos, asin, atan2, cos, cosh, exp, frexp, ldexp, log, log10, modf, pow, sin, sinh, sqrt, tan, tanh mathematical functions

strtoul, strtoull, strtol, strtoll, strtod transformation functions

fopen, fflush, perror, tmfile, fclose, freopen, setbuf, setvbuf, ungetc, scanf, fscanf, vfprintf, vprintf, vsprintf

I/O functions

exit exit function

signal signal function

_fp [ ](global FILE * array)

clearerr, feof, ferror, fgetc, fgetpos, fgets, fopen, fclose, fprintf, fputc, fputs, fread, fseek, fsetpos, ftell, fwrite, getc, rewind, vfprintf, tmpfile

I/O functions

exit exit function

_stderr(global structure of type FILE)

fclose, perror I/O functions

exit exit function

_stdin(global structure of type FILE)

fclose, getchar, gets, scanf, ungetc, fscanf, putc, puts I/O functions

exit exit function

_stdout(global structure of type FILE)

fclose, putchar, setbuf, setvbuf, ungetc, printf, fscanf, vprintf I/O functions

exit exit function

outbuf(static char array) ungetc, scanf, fscanf, sscanf I/O functions

inbuf(static char array) ungetc, scanf, fscanf, sscanf I/O functions

_a_arena(static alloc_t * )

malloc, free, realloc, calloc allocate functions

setbuf, setvbuf, fclose, fopen, freopen, tmpfile, ungetc, scanf, fscanf, sscanf I/O functions

exit exit function

tm(static structure of type tm) gmtime, localtime, ctime time functions

tzname(static char array) strftime time function

timestr(static char array) asctime, ctime time functions

__locale__(static structure of type lconv) localeconv locale function

currlocale(static structure of type lconv) localeconv locale function

seed(static long) srand, rand random generators

lib_count(static long) tmpfile I/O function



13.2.3 Internal Library Symbols

The internal library symbols which are shown in the following table should not be used by applications.

user_count(static long) tmpnam I/O function

buffer(static char array) tmpnam I/O function

func_count(static int) atexit, exit exit functions

func_tab(static func_t array) atexit, exit exit functions

sigtab(static sigfunc_t array) abort, signal, raise signal functions

buf(static char array) strerror string function

oldcp(static char * ) strtok string function

Table 38. Symbols being Used by Functions

Name of Variable,Structure, or Array

(type)Functions Using Global or Static Data Function Type

Symbol Name Symbol Type Name of Defining Module Name of Accessing Library Module(s)

_ctype const data CTYPEISALNUM, ISALPHA, ISCNTRL, ISDIGIT, ISGRAPH, ISLOWER, ISPRINT, ISPUNCT, ISSPACE, ISUPPER, ISXDIGIT, TOLOWER, TOUPPER

_dbl_indef const data MATHDATA ACOS, ASIN, ATAN2, COS, LOG, LOG10, MODF, POW, SIN, SQRT, TAN

_exp function EXP EXP, COSH, POW, SINH, TANH

_fac_tab const data LOG LOG, ATAN,

_fclose function FCLOSE FCLOSE, FREOPEN

_fgetb function _FGETB FINIT, SETBUF, UNGETC

_fgetc function _FGETC FINIT, SETBUF, UNGETC

_fgetstr function _STROPEN PRINTF, SCANF

_fginit function FINIT FINIT, _FOPEN, _FP, UNGETC

_finish function FINIT FINIT, EXIT

_fopen function _FOPEN FOPEN, FREOPEN

_fp data _FP FINIT, FOPEN

_fpinit function FINIT FINIT, _FOPEN, _FP, UNGETC

_fpseek function _FPSEEK _FPUTB, _FPUTC, FSEEK



13.2.4 Additional Library Functions

The table below lists additional library functions contained in the library. They can be considered as an implementation specific supplement to the ANSI-defined functions. They are designed to be used by the user’s applications.

_fputb function _FPUTB FINIT, SETBUF, UNGETC

_fputc function _FPUTC FINIT, SETBUF, UNGETC

_fputeos function __STROPEN _FPUTB, _FPUTC

_fputexs function _STROPEN _FPUTB, _FPUTC

_fputt function _FPUTT _FGETB, _FGETC, FINIT, SETBUF

_mktmpnam function TMPNAM FCLOSE

_speed_exp function FAST_EXP EXP

_stderr data _FP FINIT, PERROR

_stdin data _FP _FGETB, _FGETC

_stdout data _FP FINIT, PUTCHAR, PRINTF

_stropen function _STROPEN PRINTF, SCANF

_strtod function STRTOD ATOF, STRTOD

_strtol function STRTOL ATOL, STRTOL

_strtoll function STRTOL ATOL, STRTOL

_tmpnam function TMPNAM TMPFILE

Symbol Name Symbol Type Name of Defining Module Name of Accessing Library Module(s)


Name of Include File with Prototype Reentrance

_sbrkblockfree MALLOC stdlib.h non-reentrant

llabs ABS stdlib.h reentrant

lltoa ITOA stdlib.h reentrant

ltoa ITOA stdlib.h reentrant

pow10 POW10 math.h reentrant

streq STREQ string.h reentrant



13.2.5 System Interface Functions

The table below is a listing of all none ANSI system interface functions which are described in Chapter 14, “Library-Target System Interface”. The system interface functions are used within the library and should not be used directly by applications.


ANSI-Defined?

_blocksizebrk SBRK No

_exit _EXIT No

_freebrk SBRK No

_gettz _GETTZ No

_isdev _ISDEV No

_isdaylight daylight No

_isdst _ISDST No

_sblockcontrbrk SBRK No

_sbrk SBRK No

_stderror _STDERR No

_strerror _STDERR No

_tmpnampfx _TMPNAM No

AngleSWI STARTUP No

ARMSystemCall SYSCALL No

clock CLOCK Yes

close CLOSE No

creat CREATE No

getenv GETENV Yes

ioctl IOCTL No

lseek LSEEK No

open OPEN No

read READ No

remove REMOVE Yes

rename RENAME Yes

system SYSTEM No

system SYSTEM Yes

time TIME Yes

write WRITE No



13.3 Data Symbols of the Library

This sections provides a description of data symbols contained in the library.

13.3.1 errno

Description: errno has the value 0 as long as no error occurs; otherwise, errno contains a value specifying the error type.

13.3.2 stderr

Syntax: #include <stdio.h>fprintf(stderr,...)

Description: stderr is a file pointer which opens the standard error file when a C program is started. stderr is connected to the screen even if the standard output has been redirected.

Diagnostics: stderr is created automatically at the start of a C program and closed automatically at the end.

Note: As ARM* semihosting does not support stderr, this file pointer cannot be used with AngelSWI!

Further Information:Section 13.3.3, “stdin” on page 277Section 13.3.4, “stdout” on page 278

13.3.3 stdin

Syntax: #include <stdio.h>fscanf(stdin,...) /* equivalent to scanf(...) */

Description: stdin is a file pointer which opens the standard input file when a C program is started. Normally, stdin is connected to the keyboard and reads from the screen but may be redirected to files or pipes. stdin may be used as a file pointer in any function that uses a variable of type FILE* (in four capital letters).

Diagnostics: stdin is created automatically at the start of a C program and closed automatically at the end.



Further Information:Section 13.3.2, “stderr” on page 277Section 13.3.4, “stdout” on page 278

13.3.4 stdout

Syntax: #include <stdio.h>fprintf(stdout,...)/* equivalent to printf(...) */

Description: stdout is a file pointer which opens the standard input file when a C program is started. Normally, stdout is connected to the keyboard and writes to the screen but may be redirected to files or pipes. stdout may be used as a file pointer in any function that uses a variable of type FILE* (in four capital letters).

Diagnostics: stdout is created automatically at the start of a C program and closed automatically at the end.

Further Information:Section 13.3.2, “stderr” on page 277Section 13.3.3, “stdin” on page 277



13.4 Header Files

This chapter describes header files of the C Standard Library. These header files are designed to be used in conjunction with the libraries supplied with the Intel® C++ Compiler. If functions of the C Standard Library are used, the appropriate header file must be included. The table below provides an overview of all supplied header files.

The following pages describe the contents of every header file and are in alphabetical order. Every description contains information with respect to particular standards. Every header file is protected against multiple inclusion.

Some of these header files contain the following general macro definitions:

Table 39. Header Files

Header File Description Standard

assert.h Defines the assert macro. ANSI

ctype.h Defines functions used for classifying and mapping characters. ANSI

errno.h Defines macros used for error handling. ANSI

float.h Defines maximum and minimum values used for floating point types. ANSI

limits.h Defines maximum and minimum values of integer types. ANSI

locale.h Defines one type, functions, and macros with respect to localization. ANSI

math.h Defines types and mathematical functions as well as constants. ANSI

setjmp.h Defines types and functions used for non-local jumps. ANSI

signal.h Defines types, functions and macros used for signal handling. ANSI

stdarg.h Defines one type and macros with respect to variable argument lists. ANSI

stddef.h Defines common types and macros. ANSI

stdio.h Defines types, macros, and functions used for input and output. ANSI

stdlib.h Defines types, macros, and functions of general utility. ANSI

string.h Defines functions used for string handling. ANSI

time.h Defines types, macros, and functions used for date and time. ANSI

version.h Defines the library version. none

Table 40. Macros

Macro Definition

__FIXEDPARAMS__ Internal macro definition.

__LONGLONG__ 64-bit long type is supported.

__STDC__ ANSI standard

__VARPARAMS__ Internal macro definition.

_T_SIZE Log mechanism; required for the type definition size_t (ANSI standard).

_T_WCHAR_ The type wchar is supported



13.4.1 Header File assert.h

The header file assert.h defines the assert macro.

The assert macro itself may be defined in source files using the following syntax:

#include <assert.h>void assert (int expression);

assert checks the validity of expression at run-time. If expression is false (0), an error message is printed and abort is called. In this case, the assert macro has the following definition:

#define assert (p) (!(p) && (printf("%s: %d: assert(%s) failed.\n",\ __FILE__, __LINE__, #p), abort(),0))

If the macro NDEBUG is defined using the compiler option -DNDEBUG, the assert macro is defined as follows:

#define assert(p) (void)0

Further Information:Section 13.5.1, “Macro assert” on page 300

13.4.2 Header File ctype.h

The header file ctype.h declares the following functions used for classifying and mapping character:

Type Function Description

int isalnum(int c); Test for alphanumeric character.

int isalpha(int c); Test for alphabetic character.

int iscntrl(int c); Test for control character.

int isdigit(int c); Test for decimal digit.

int isgraph(int c); Test for printable character (no space).

int islower(int c); Test for lower case character.

int isprint(int c); Test for printable character.

int ispunct(int c); Test for punctuation character.

int isspace(int c); Test for whitespace character.

int isupper(int c); Test for upper case character.

int isxdigit(int c); Test for hexadecinal digit.

int tolower(int c); Convert upper case character to lower case character.

int toupper(int c); Convert lower case character to upper case character.



13.4.3 Header File errno.h

The header file errno.h contains definitions of macros used for error handling. It defines also the symbol errno.

The table lists all defined macros in alphabetical order:

Macro Description Macro Description

E2BIG Argument list too long EMLINK Too many links

EACCES Permission denied ENFILE File table overflow

EAGAIN No more processes ENODEV No such device

EBADF Bad file number ENOENT No such file or directory

EBADFMT Bad format ENOEXEC System exec format error

EBUSY Device busy ENOLOAD Driver not loaded

ECHILD No child processes ENOMEM Not enough space

EDATTN Device needs attention ENOSPC No space left on device

EDBUSY Device busy ENOTBLK Block device required

EDOM Argument out of domain ENOTDIR Not a directory

EEXIST File exists ENOTTY Not a terminal

EFAULT Bad address ENXIO No such device or address

EFBIG File too large EPERM Not owner

EILSEQ Illegal multibyte sequence EPIPE Broken pipe

EINTR Interrupted system call ERANGE Result too large

EINVAL Invalid argument EROFS Read-only file system

EIO I/O error ESPIPE Illegal seek on a pipe

EISDIR Is a directory ESRCH No such process

EKSPACE Out of kernel space ETXTBSY Text file busy

EMFILE Too many open files EXDEV Cross-device link



13.4.4 Header File float.h

The header file float.h defines maximum and minimum values used for floating point types.

Macro Value

FLT_ROUNDS 1

FLT_RADIX 2

FLT_MANT_DIG 24

FLT_EPSILON ((float)1.19209290E-07)

FLT_DIG 6

FLT_MIN_EXP (-125)

FLT_MIN ((float)1.17549435E-38)

FLT_MIN_10_EXP (-37)

FLT_MAX_EXP 128

FLT_MAX ((float)3.40282347E+38)

FLT_MAX_10_EXP 38

DBL_MANT_DIG 53

DBL_EPSILON 2.2204460492503131E-16

DBL_DIG 15

DBL_MIN_EXP (-1021)

DBL_MIN (2.2250738585072015e-308)

DBL_MIN_10_EXP (-308)

DBL_MAX (1.7976931348623158e+308)

DBL_MAX_EXP 1024

DBL_MAX_10_EXP 308

LDBL_MANT_DIG 64

LDBL_EPSILON 1.0842021724855044340075E-19L

LDBL_DIG 18

LDBL_MIN_EXP (-16381)

LDBL_MIN 3.3621031431120935062627E-4932L

LDBL_MIN_10_EXP (-4931)

LDBL_MAX_EXP (+16384)

LDBL_MAX 1.1897314953572317650213E+4932L

LDBL_MAX_10_EXP (+4932)



13.4.5 Header File limits.h

The header file limits.h defines maximum and minimum values of integer and character types. These values are listed in the tables below.

Macro Value Description

CHAR_BIT 8 Number of bits in a char

CHAR_MAX 127 (255) Maximum value of a char (unsigned)

CHAR_MIN –128 (0) Minimum value of a char (unsigned)

LLONG_MAX 9223372036854775807L Maximum value of a long

LLONG_MIN -9223372036854775808L Minimum value of a long

LONG_MAX 2147483647L Maximum value of a long

LONG_MIN –2147483648L Minimum value of a long

MB_LEN_MAX 2 Number of bytes of a multibyte character

SCHAR_MAX 127 Maximum value of a signed char

SCHAR_MIN –128 Minimum value of a signed char

SHRT_MAX 32767 Maximum value of a short

SHRT_MIN –32768 Minimum value of a short

UCHAR_MAX 255 Maximum value of an unsigned char

ULLONG_MAX 0xFFFFFFFFFFFFFFFFUL Maximum value of an unsigned long

ULONG_MAX 4294967295UL Maximum value of an unsigned long

USHRT_MAX 65535 Maximum value of an unsigned short



13.4.6 Header File locale.h

The header file locale.h defines an new type struct lconv as follows:

struct lconv { char *decimal_point; /* "." */ char *thousands_sep; /* "" */ char *grouping; /* "" */ char *int_curr_symbol; /* "" */ char *currency_symbol; /* "" */ char *mon_decimal_point; /* "" */ char *mon_thousands_sep; /* "" */ char *mon_grouping; /* "" */ char *positive_sign; /* "" */ char *negative_sign; /* "" */ char int_frac_digits; /* CHAR_MAX */ char frac_digits; /* CHAR_MAX */ char p_cs_precedes; /* CHAR_MAX */ char p_sep_by_space; /* CHAR_MAX */ char n_cs_precedes; /* CHAR_MAX */ char n_sep_by_space; /* CHAR_MAX */ char p_sign_posn; /* CHAR_MAX */ char n_sign_posn; /* CHAR_MAX */};

The header file locale.h also defines the following two functions:

char *setlocale(int category, const char *locale);struct lconv *localeconv(void);

Local specific features of the standard library can be changed with setlocale. Local specific information can be obtained using localeconv.

The parameter category of setlocale may have the following values:

The macro NULL is defined as well:

#define NULL 0

Further Information:Section 13.6.102, “setlocale” on page 457


LC_ALL 0x1F Change behavior generally.

LC_COLLATE (1<<0) Change behavior of strcoll and strxfrm.

LC_CTYPE (1<<1) Change behavior of all ctype functions.

LC_MONETARY (1<<2) Change monetary information.

LC_NUMERIC (1<<3) Change decimal point notation, thousands separator etc.

LC_TIME (1<<4) Change behavior of strftime.



13.4.7 Header File math.h

The header file math.h defines the type struct __cpx. This structure is designed to declare entities of complex type. The structure is declared as follows:

typedef struct __cpx { double z_r; double z_i;} __CPX;

Besides this declaration, math.h contains the following prototypes (ANSI standard).

Further Information:Section 13.6, “Library Functions” on page 305

Type Function Function Result

double acos(double x); Arc cosine of x

double asin(double x); Arc sine of x

double atan(double x); Arc tangent of x

double atan2(double y, double x); Arcus tangent of y/x

double ceil(double x); Smallest integer not less than x

double cos(double x); Cosine of x

double cosh(double x); Hyperbolic cosine of x

double exp(double x); Exponential function of x

double fabs(double x); Absolute value of x

double floor(double x); Largest integer not greater than x

double fmod(double x, double y); Floating point remainder of x/y

double frexp(double value, int *exp); Break a floating point number into anormalized fraction and an integral power of 2

double ldexp(double x, int exp); Multiply x by 2exp

double log(double x); Natural logarithm of x

double log10(double x); Logarithm (base 10) of x

double modf(double value, double *iptr); Break a floating point number into an integral and an fractional part

double pow(double x,double y); x raised to the power of y

double pow10(int i); 10 raised to the power of i

double sin(double x); Sine of x

double sinh(double x); Hyperbolic sine of x

double sqrt(double x); Square root of x

double tan(double x); Tangent of x

double tanh(double x); Hyperbolic tangent of x



13.4.8 Header File setjmp.h

The header file setjmp.h defines the type jmp_buf as follows:

typedef int jmp_buf[16]

Besides this type definition, the following functions are defined in setjmp.h:


void longjmp(jmp_buf env, int val); Non-local jump

int setjmp(jmp_buf env); Save the calling environment in a jmp_buf data structure.



13.4.9 Header File signal.h

The header file signal.h defines the type sig_atomic_t as follows:

typedef int sig_atomic_t;

Besides this type definition, it contains the following function prototypes:

In addition to these user-defined signal handling functions, the following macros may be used for the func parameter of signal:

The following macros are also supplied by signal.h and may be used as the sig parameter of signal and raise:


int raise(int sig); Raise a signal.

void (*signal(int sig, void (*func)(int)))(int); Specify an action when a signal occurs.

Macro Value

SIG_DFL ((void (*)(int)) 0)

SIG_IGN ((void (*)(int)) 1)

SIG_ERR ((void (*)(int)) (-1))

Macro Value Macro Value Macro Value

SIGHUP 1 SIGABRT 6 SIGSEGV 11

SIGINT 2 SIGUNUSED 7 SIGUSR2 12

SIGQUIT 3 SIGFPE 8 SIGPIPE 13

SIGILL 4 SIGKILL 9 SIGALRM 14

SIGTRAP 5 SIGUSR1 10 SIGTERM 15



13.4.10 Header File stdarg.h

The header file stdarg.h defines one type and macros with respect to variable argument lists. The following macros are defined:

#define va_end(list) (void)0/* Facilitates a normal return. */

#define _arg_size_on_stack_(type) ((sizeof(type)+sizeof(int)-1) & (~(sizeof(int)-1)))/* Argument size. */

# define va_arg(ap,type) *((type *)(void*)(((ap+=_arg_size_on_stack_(type))- _arg_size_on_stack_(type) + swap_size(type)))/* Expands to an expression that has the specified type and the value of the next argument in the call. */

#define va_start(list,lstprm) (list) = (va_list) (void *) (&___ansiarg)/* Initializes list for subsequent use by the va_arg and va_end macros. */

#define va_copy(dest, src) ((dest) = (src))/* Initializes dest as a copy of src. */

Besides these macro definitions, it contains the type definition of va_list:

typedef char *va_list;

Further Information:Section 13.5, “Macros” on page 300



13.4.11 Header File stddef.h

The header file stddef.h contains the standard type definitions and the definition of the macros NULL and offsetof.

The following type definitions are supplied:

/**mapping types*/typedef unsigned amap_t; /* Auxiliary map */typedef unsigned aold_t; /* Auxiliary map save */typedef unsigned bmap_t; /* Buffer map */typedef unsigned bold_t; /* Buffer map save */typedef unsigned cmap_t; /* Clist map */typedef unsigned cold_t; /* Clist map save */typedef unsigned dmap_t; /* Driver map */typedef unsigned dold_t; /* Driver map save *//**system types*/typedef unsigned comp_t; /* Accounting */typedef long daddr_t; /* Disk address */typedef unsigned dev_t; /* Device */typedef unsigned ino_t; /* Inode number */typedef long paddr_t; /* Physical memory address */typedef unsigned saddr_t; /* Segmenation address */typedef int sig_t; /* Signal bits (32-bit) */typedef long sig_t; /* Signal bits (16-bit)*/typedef unsigned int size_t;typedef int ptrdiff_t; /* Pointer diff.*/typedef unsigned short wchar_t; /* wide characters*/typedef unsigned int vaddr_t; /* Virtual address type (32-bit)*/typedef unsigned long vaddr_t; /* Virtual address type */typedef unsigned int uaddr_t; /* Universal memory address (32-bit) */typedef unsigned long uaddr_t; /* Universal memory address */

The macros are defined as follows:

/* C++ mode */#define NULL 0

#define offsetof(Type,Id) (((char*)&(((Type*)NULL)->Id))-((char*)NULL))

/* C mode */#define NULL (void *) 0

#define offsetof(t, memb) ((size_t)__INTADDR__(&(((t *)0)->memb)))



13.4.12 Header File stdio.h

The header file stdio.h defines types, macros, and functions used for input and output. The following types are defined:

typedef struct FILE { unsigned char *_cp; /* current char ptr */ unsigned char *_dp; /* start of data in buffer */ unsigned char *_bp; /* buffer pointer */ int _cc; /* character count */ int (*_gt)(struct FILE *); /* getc function */ int (*_pt)(int,struct FILE *); /* putc function */ int_ff; /* flags */ char _fd; /* file descriptor */ int _uc; /* ungot char */ int _na; /* id number of temp file */ int _bufsiz; /* size of buffer */}FILE;

typedef long fpos_t;

typedef unsigned int size_t;

typedef char *var_list;

The following macros are defined:



#define EOF (-1) /* end of file */#define BUFSIZ (1<<9) /* I/O buffer size */#define CTRLZ 26#define FILENAME_MAX 24 /* max length of filename */#define FOPEN_MAX 32 /* max number of open files */#define L_tmpnam 32 #define TMP_MAX 0xfffffff /* max number of unique*/ /* filenames generated */ /* by tmpnam */#define SEEK_SET 0 /* fseek */#define SEEK_CUR 1 /* fseek */#define SEEK_END 2 /* fseek */#define stdin (&_stdin) /* provides a FILE pointer */#define stdout (&_stdout) /* provides a FILE pointer */#define stderr (&_stderr) /* provides a FILE pointer */#define _putc(c,fp) ((*(fp)->_pt)(c,fp)) /* putc() */#define _getc(fp) ((*(fp)->_gt)(fp)) /* getc() */



Besides these definitions, the header file stdio.h contains prototype declarations of the stdio functions listed in the table below.


void clearerr(FILE *stream); Clear error flag

int fclose(FILE *stream); Close a stream

int feof(FILE *stream); Test EOF

int ferror(FILE *stream); Test if an error occurred

int fflush(FILE *stream); Flush a stream

int fgetc(FILE *stream); Obtain one character from stream

int fgetpos(FILE *stream, fpos_t *pos);

Obtain current position in a stream

char *fgets(char *s, int n, FILE *stream);

Input a string from a stream

FILE *fopen(const char *filename, const char *mode);

Open a stream

int fprintf(FILE *stream, const char *format, ...);

Put formatted output to stream

int fputc(int c, FILE *stream); Put one character to stream

int fputs(const char *s, FILE *stream);

Put string to stream

size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);

Read a record from stream

FILE *freopen(const char *filename, const char *mode, FILE *stream);

Reopen a stream

int fscanf(FILE *stream, const char *format, ...);

Obtain formatted input from stream

int fseek(FILE *stream, long int offset, int whence);

Set position in a stream

int fsetpos(FILE *stream, const fpos_t *pos);

Set position in a stream

long ftell(FILE *stream); Obtain current file position

size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);

Write a record to stream

int getc(FILE *stream); Obtain a character from stream

int getchar(void); Obtain character from stdin

char *gets(char *s); Read characters from input string

void perror(const char *s); Write an error message

int printf(const char *format, ...); Put formatted output to stdout

int putc(int c, FILE *stream); Put a character to stream

int putchar(int c); Put a character to stdout



int puts(const char *s); Put a string

int remove(const char *filename); Remove a file

int rename(const char *oldname, const char *newname);

Rename a file

void rewind(FILE *stream); Rewind a stream

int scanf(const char *format, ...); Formatted input from stdin

void setbuf(FILE *stream, char *buf); Set stream I/O buffer

int setvbuf(FILE *stream, char *buf, int mode, size_t size);

Set stream I/O buffer and buffer size

int sprintf(char *s, const char *format, ...);

Formatted output to string

int sscanf(const char *s, const char *format, ...);

Formatted input from string

FILE *tmpfile(void); Create a temporary file

char *tmpnam(char *mode); Create a temporary filename

int ungetc(int c, FILE *stream);

Put a character back to stream

int vfprintf(FILE *stream, const char *format, va_list arg);

Write formatted output to file with argument pointer

int vprintf(const char *format, va_list arg);

Write formatted output to stdout with argument pointer

int vsprintf(char *s, const char *format, va_list arg);

Write formatted output to string with argument pointer




13.4.13 Header File stdlib.h

The header file stdlib.h defines types div_t, ldiv_t, size_t, wchar_t, macros, and functions of general utility.

The types are defined as follows:

typedef struct { int quot; int rem;} div_t;

typedef struct { long quot; long rem;} ldiv_t;


typedef unsigned short wchar_t; /* wide characters */

The header file contains the following macro definitions:



#define EXIT_FAILURE 1 /* program error exit code */#define EXIT_SUCCESS 0 /* successful program exit */#define MB_CUR_MAX 2 /* ==sizeof(wchar_t) */#define MB_LEN_MAX 2 /* == sizeof(wchar_t) */#define RAND_MAX 32767 /*range of rand() function*/

The table below lists all supplied functions:


int _sbrkblockfree (void); Set free sbrk_blocks.

void abort(void); Abort program.

int abs(int j); Calculate absolute value.

int atexit(void (*func) (void)); Register function.

double atof(const char *nptr); Convert ASCII to float.

int atoi(const char *nptr); Convert ASCII to integer.

long int atol(const char *nptr); Convert ASCII to long.

long long int atoll(const char *nptr); Convert ASCII to long.



void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

Search array.

void *calloc(size_t nmemb, size_t size);

Allocate dynamic memory.

div_t div(int numer, int denom); Divide.

void exit(int status); Exit program.

void free(void *ptr); Deallocate memory.

char *getenv(const char *name); Obtain environment value.

char *itoa(int value, char *nptr, int base);

Convert integer to string.

long int labs(long int j); Calculate long absolute value.

ldiv_t ldiv(long int numer, long int denom);

Divide long arguments.

char *lltoa (long long int value, char *nptr, int base);

Convert long long to string.

char *ltoa (long int value, char *nptr, int base);

Convert long to string.

long long int llabs(long long int); Calculate long long absolute value.

void *malloc(size_t size); Allocate dynamic memory.

void qsort(void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

Sort array.

int rand(void); Create pseudo random number.

void *realloc(void *ptr, size_t size);

Re-allocate dynamic memory.

void srand(unsigned int seed); Create pseudo random numbers.

double strtod(const char *nptr, char **endptr);

Convert string to double.

long int strtol(const char *nptr, char **endptr, int base);

Convert string to long.

long long int strtoll(const char *nptr, char **endptr, int base);

Convert string to long long.




unsignedlong int

strtoul(const char *nptr, char **endptr, int base);

Convert string to unsigned long.

unsigned long long int strtoull(const char *nptr, char **endptr, int base);

Convert string to unsigned long long.

int system(const char *str); Call a command interpreter with a program.




13.4.14 Header File string.h

The header file string.h defines the type size_t, the macro NULL, and functions used for string handling.

typedef unsigned int size_T;



The table below lists the supplied functions.


void *memchr(const void *s, int c, size_t n);

Search for c in the first n characters of s.

int memcmp(const void *s1, const void *s2, size_t n);

Compare the first n characters of s1 and s2.

void *memcpy(void *s1, const void *s2, size_t n);

Copy n characters from s2 to s1.

void *memmove(void *s1, const void *s2, size_t n);

Move n characters from s2 to s1.

void *memset(void *s, int c, size_t n); Set the first n characters of s to c.

char *strcat(char *s1, const char *s2); Copy s2 to the end of s1.

char *strchr(const char *s, int c); Search for position of c in s.

int strcmp(const char *s1, const char *s2); Compare strings.

int strcoll(const char *s1, const char *s2);

Compare strings.

char *strcpy(char *s1, const char *s2); Copy s2 to s1.

size_t strcspn(const char *s1, const char *s2);

Search for characters of s2 in s1.

char *strerror(int errnum); Map the error number in errnum to an error message string.

size_t strlen(const char *s); Calculate the length of s.

char *strncat(char *s1, const char *s2, size_t n);

Append n characters of s2 to the end of s1.

int strncmp(const char *s1, const char *s2, size_t n);

Compare the first n characters of s1 and s2.

char *strncpy(char *s1, const char *s2, size_t n);

Copy n characters of s2 to s1.

char *strpbrk(const char *s1, const char *s2);

Search for characters of s2 in s1.

char *strrchr(const char *s, int c); Search for the last occurrence of c in s.

size_t strspn(const char *s1, const char *s2); Search for all characters of s2 in s1.



char *strstr(const char *s1, const char *s2);

Search for the sequence of characters of s2 in s1.

char *strtok(char *s1, const char *s2); Search for tokens contained in s2 in s1 and break the string according to the location of tokens.

size _t strxfrm(char *s1, const char *s2, size_t n);

Compare s2 with s1 and transform n characters of s2 into s1.




13.4.15 Header File time.h

The header file time.h defines the macro CLOCKS_PER_SEC, the types size_t, clock_t, time_t, and struct tm. Besides these definitions, it contains prototype declarations used for date and time.

The definitions are as follows:

#define CLOCKS_PER_SEC 1000


typedef int clock_t; /* clock ticks 32-bit */typedef int time_t; /* time 32-bit */

typedef long clock_t; /* clock ticks */typedef long time_t; /* time */

struct tm { int tm_sec; /* seconds after the minute [0,59] */ int tm_min; /* minutes after the hour [0,59] */ int tm_hour; /* hours after midnight [0,23] */ int tm_mday; /* day of the month [1,31] */ int tm_mon; /* months since January [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday [0,6] */ int tm_yday; /* days since January 1 [0,365] */ int tm_isdst; /* Daylight SavingsTime flag */};

Note: The flag tm_isdst is set by the system function _isdaylight(). See Section 13.2.5, “System Interface Functions” on page 276.

The following function prototypes are supplied:


char *asctime(const struct tm *timeptr); Convert struct tm to a string.

clock_t clock(void); Obtain processor time.

char *ctime(const time_t *timer); Convert time_t to a string.

double difftime(time_t time1, time_t time2); Calculate difference between two calendar times.

struct tm *gmtime(const time_t *timer); Convert calendar time to UTC.

struct tm *localtime(const time_t *timer); Convert calendar time to local time.

time_t mktime(struct tm *timeptr); Obtain calendar time.

size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr);

Formats struct tm controlled by a format string.

time_t time(time_t *timer); Obtain current time.



13.4.16 Header File version.h

The header file version.h provides the library version. The variable libversion is defined as follows:

extern char libversion[];



13.5 Macros

This section describes the five macros which are supplied by the C Standard Library:

• assert

• va_arg

• va_copy

• va_end

• va_start

13.5.1 Macro assert

Syntax: #include <assert.h>voidassert(int expression);

Description: assert checks the validity of the specified expression at run time. If the expression is false (0), it prints an error message and calls abort. assert is mostly used to detect situations that should “never happen”. Calls to assert are inserted in programs to validate the consistency of control flow and, if a program uses assert expressions, errors can be detected earlier. When a program is well tested, all assert expressions may be removed if the program was compiled with the macro NDEBUG set to 1. This can be done with the compiler option -DNDEBUG or a #define preprocessor directive prior to the #include <assert.h> directive.

Further Information:For a definition of the macro, please refer to Section 13.4.1, “Header File assert.h” on page 280.



13.5.2 Macro va_arg

Syntax: #include <stdarg.h>typeva_arg(va_list param, type);

Description: va_arg is a macro that retrieves a value of type type in a variable list from the location given by param. param is then incremented to point to the next argument in the list. param uses the size of type to determine where the next argument starts.

va_arg can be used any number of times within a function to retrieve arguments from the list.

Diagnostics: va_arg returns the value of the next variable argument, according to type.

Note: va_arg must be used with the associated macros va_start and va_end. va_start must be executed first in order to properly initialize the function. va_end should be executed after all arguments have been obtained.

Further Information:Section 13.5.4, “Macro va_end” on page 303Section 13.5.5, “Macro va_start” on page 304Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.5.3 Macro va_copy

Syntax: #include <stdarg.h>void va_copy(va_list dest, va_list src);

Description: va_copy is a macro that initializes dest as a copy of src. This macro performs the same action as if the va_start macro had been applied to dest followed by the same sequence of uses of the va_arg macro as had previously been used to reach the present state of src. Note, that the va_copy and va_start macro shall not be issued to reinitialize dest without calling the va_end macro for the same dest.

Diagnostics: va_copy does not return a value.

Further Information:Section 13.4.1, “Header File assert.h” on page 280



13.5.4 Macro va_end

Syntax: #include <stdarg.h>voidva_end(va_list param);

Description: va_end is a macro used to complete the acquisition of arguments from a list of variable arguments. va_end resets the pointer param to NULL.

Diagnostics: va_end does not return a value.

Note: va_end must be used with the associated macros va_arg and va_start.

Further Information:Section 13.5.2, “Macro va_arg” on page 301Section 13.5.5, “Macro va_start” on page 304Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.5.5 Macro va_start

Syntax: #include <stdarg.h>voidva_start(va_list param, previous);

Description: va_start is a macro which sets param to the first optional argument in the list of arguments passed to the function. The argument previous is the name of the required parameter immediately preceding the first optional argument in the argument list. If previous is declared with the register storage class, the behavior of va_start is undefined.

Diagnostics: va_start does not have a value.

Note: va_start must be used before va_arg is used for the first time.

Further Information:Section 13.5.2, “Macro va_arg” on page 301Section 13.5.4, “Macro va_end” on page 303Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.6 Library Functions

The C Standard Library provided with the Intel® C++ Compiler is compliant with the ANSI C Standard. The Intel® C++ Compiler supports the following library functions, which are listed in alphabetical order.

13.6.1 _sbrkblockfree

Syntax: #include <stdlib.h>int_sbrkblockfree (void );

Description: The _sbrkblockfree function sets free all sbrk-blocks obtained from the operating system. This function calls the _freebrk system interface function which accepts the mentioned blocks.

Diagnostics: Returns 0 if there are no sbrk-blocks allocated for application, or setting of the _sblockcontrbrk function provides no fixed sbrk-blocks; otherwise it returns 1.

Further Information:For an example see Section 13.6.41, “free” on page 360Section 2.4.40, “Function free”Section 5.3.2, “Function _freebrk”



13.6.2 abort

Syntax: #include <stdlib.h>voidabort(void);

Description: The abort call terminates a process with a message unless the signal SIGABRT is caught and the signal handler does not return. abort is normally invoked in situations that “should not happen” in a program. Open output streams are not flushed, open streams are not closed and temporary files are not removed when abort is called.

Diagnostics: abort does not return to the caller.

Example 129. Function abort

#include <stdlib.h>#include <stdio.h>

int main(void){ FILE *stream; if((stream = fopen("NO.TMP", "r")) == NULL) { perror("Cannot open file"); abort(); printf("You will not get this far\n"); } else { fclose(stream); } return 0;}

If the file NO.TMP cannot be opened for reading, the program above produces the following output:

Cannot open file: Error 2

The text "You will not get this far" is not printed because the program is terminated before it can reach this statement.



13.6.3 abs

Syntax: #include <stdlib.h>intabs(int j );

Description: abs computes the absolute value of its integer argument j.

Diagnostics: abs returns the absolute value of its argument. There is no error return.

Example 130. Function abs


int main(void){ int ix = -2, iabs; iabs = abs(ix); printf("The absolute value of %d is %d\n", ix, iabs); return 0;}

The program above produces the following output:

The absolute value of -2 is 2



13.6.4 acos

Syntax: #include <math.h>doubleacos(double x);

Description: acos computes the arc cosine of x in the range of 0 to π radians. The value of x must be between –1 and 1.

Diagnostics: acos returns the arc cosine in the range of [0,π]. If x is less than –1 or greater than 1, the function sets errno to EDOM. In this case the return value is 0.

Example 131. Function acos

#include <stdio.h>#include <math.h>

int main(void){ double x = .5; printf("The arc cosine of %.2f is %lf.\n", x, acos(x)); return 0;}


The arc cosine of 0.50 is 1.047198.

Further Information:Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.8, “atan2” on page 312



13.6.5 asctime

Syntax: #include <time.h>char *asctime(const struct tm *timeptr);

Description: asctime returns an ASCII string, containing time and date, stored in the structure referenced by timeptr. The timeptr argument is usually obtained with a call to gmtime or localtime. struct tm is defined in time.h.

The result of asctime is a string of 26 bytes (including \n and \0). The format is as follows:

DDD MMM dd hh:mm:ss YYYY\n

where:

Example 132. Function asctime

#include <stdlib.h>#include <stdio.h>#include <time.h>struct tm *today;time_t aclock;

int main(void){ time(&aclock); /* get time in seconds */ today = localtime(&aclock); /* convert to *struct tm */ printf("Current date and time: %s\n", asctime(today)); return 0;}

The program above produces output like:

Current date and time: Mon Feb 4 07:35:03 2002

Further Information:Section 13.6.53, “gmtime” on page 382Section 13.6.72, “localtime” on page 412Section 13.6.137, “time” on page 508

DDD Sun, Mon, Tue, Wed, Thu, Fri, or Sat

MMM Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec

dd Day of the month (01..31)

hh Hour of the day (00..24)

mm Minute of the hour (00..59)

ss Second of the minute (00..59)

YYYY The year (0000..9999)



13.6.6 asin

Syntax: #include <math.h>doubleasin(double x);

Description: asin computes the arc sine of x in the range of -π/2 to π/2 radians. The value of x must be between –1 and 1.

Diagnostics: asin returns the arc sine in the range of [-π/2, π/2]. If x is less than –1 or greater than 1, the function sets errno to EDOM. In this case the return value is 0.

Example 133. Function asin


int main(void){ double x = .5;

printf("The arc sine of %.2lf is %lf\n", x, asin(x)); printf("arc cosine %lf\n", acos(x)); return 0;}


The arc sine of 0.50 is 0.523599 arc cosine 1.047198

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.7, “atan” on page 311Section 13.6.8, “atan2” on page 312



13.6.7 atan

Syntax: #include <math.h>doubleatan(double x);

Description: atan computes the arc tangent of x. x may be any valid double precision floating point argument.

Diagnostics: atan returns the arc tangent of x. The result is in the range of (-π/2, π/2).

Example 134. Function atan



printf( "The arcus tangent of %.2lf is %lf.\n", x, atan(x)); return 0;}


The arcus tangent of 0.50 is 0.463648.

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.8, “atan2” on page 312



13.6.8 atan2

Syntax: #include <math.h>doubleatan2(double y, double x);

Description: atan2 computes the arc tangent of y/x using the signs of both arguments to determine the quadrant of the return value. Both arguments must not be zero at the same time.

Diagnostics: atan2 returns the arc tangent of y/x, in the range of [-π, π]. If x and y are both zero, the function sets errno to EDOM. In this case the return value is zero.

Example 135. Function atan2


int main(void){ double x = .5, y = 2.;

printf("The arc tangent of %.2lf/%.2lf = %.2lf is %lf.\n", x, y, x/y, atan2(x,y)); return 0;}


The arc tangent of 0.50/2.00 = 0.25 is 0.244979.

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311



13.6.9 atexit

Syntax: #include <stdlib.h>intatexit(void (*func ) (void ) );

Description: atexit registers the function pointed to by func. The function will be executed without arguments at normal program termination.

Successive calls to atexit create a “last_in_first_out data structure.” This structure is interpreted as the exit function is called by the program or at normal termination. The registered functions are then executed in the reverse order of their registration.

These functions must not have parameters. If one of the functions supplies a result value, it is ignored.

Up to 32 functions can be registered.

Diagnostics: atexit returns non-zero if the registration fails, zero if it succeeds.

Note: Since atexit works on a static allocated data structure, it must not be used for reentrant tasks.

Example 136. Function atexit

#include <stdlib.h>#include <stdio.h>void func1(void) { printf("last!\n"); }void func2(void) { printf("done "); }void func3(void) { printf("is "); }void func4(void) { printf("This "); }

int main(void){ atexit(func1); atexit(func2); atexit(func3); atexit(func4); printf("This is done first!\n"); return 0;}

When the program exits, the functions func4 to func1 are called in this order. The following output is generated:

This is done first! This is done last!

Further Information:Section 13.6.24, “exit” on page 330



13.6.10 atof

Syntax: #include <stdlib.h>doubleatof(const char *nptr );

Description: atof reads a string representing a floating point value and returns a double precision floating point as its result. The string pointed to by nptr may contain an optional leading sign, any number of decimal digits, and can contain one decimal point. It may also be followed by an optional exponent given by an “e” or “E” (or “d” or “D”). Leading blanks and tabs are ignored. Scanning stops as soon as an inappropriate character is encountered and the resulting number is returned.

The leading sign may be plus (+) or minus (–). If no digits appear before the decimal point, at least one digit must follow.

Diagnostics: atof returns the converted value or 0.0 if the conversion fails.

Note: In case of an overflow the return value is undefined.

Example 137. Function atof


int main(void){ char *cptr; double val;

cptr = "125.0E+3"; val = atof(cptr); printf("String value %s converted to %e\n", cptr, val); return 0;}


String value 125.0E+3 converted to 1.250000e+05



Further Information:Section 13.6.11, “atoi” on page 316Section 13.6.12, “atol” on page 317Section 13.6.65, “itoa” on page 403Section 13.6.76, “ltoa” on page 417Section 13.6.70, “lltoa” on page 408Section 13.6.107, “sprintf” on page 464Section 13.6.127, “strtod” on page 491Section 13.6.129, “strtol” on page 495Section 13.6.131, “strtoul” on page 499



13.6.11 atoi

Syntax: #include <stdlib.h>intatoi (const char *nptr );

Description: atoi reads a string representing an integer value and returns an integer as its result. The string pointed to by nptr may contain a leading sign, plus (+) or minus (–), and any number of decimal digits. Leading blanks and tabs are ignored. Scanning stops when any inappropriate character is encountered and the value is then returned.

Diagnostics: atoi returns the converted value or 0 if no numeric value could be detected. If an overflow occurs, i.e. value exceeds INT_MAX (if negative INT_MIN), the function returns INT_MAX (INT_MIN) and sets errno to ERANGE.

Example 138. Function atoi


int main(void){ int i; char *cptr;

cptr ="100 men"; i = atoi(cptr); printf("String value %s converted by atoi to %d\n", cptr, i); return 0;}


String value 100 men converted by atoi to 100

Further Information:Section 13.6.10, “atof” on page 314Section 13.6.12, “atol” on page 317Section 13.6.65, “itoa” on page 403Section 13.6.76, “ltoa” on page 417Section 13.6.70, “lltoa” on page 408Section 13.6.107, “sprintf” on page 464Section 13.6.127, “strtod” on page 491Section 13.6.129, “strtol” on page 495Section 13.6.131, “strtoul” on page 499



13.6.12 atol

Syntax: #include <stdlib.h>longatol(const char *nptr );

Description: atol reads a string representing a long integer and returns a long value as its result. The string pointed to by nptr may contain an optional leading sign, plus (+) or minus (–), and any number of decimal digits. Leading blanks and tabs are ignored. Scanning stops if an inappropriate character is encountered; the result value is then returned.

Diagnostics: atol returns the converted value; otherwise 0 is returned if no numeric value could be detected. If an overflow occurs, i.e. value exceeds LONG_MAX (if negative: LONG_MIN), the function returns LONG_MAX (LONG_MIN) and sets errno to ERANGE.

Example 139. Function atol


int main(void){ long l; char *cptr;

cptr = "-12255"; l = atol(cptr); printf("string value %s converted by atol to %ld\n", cptr, l); return 0;}


string value -12255 converted by atol to -12255

Further Information:Section 13.6.10, “atof” on page 314Section 13.6.11, “atoi” on page 316Section 13.6.11, “atoi” on page 316Section 13.6.65, “itoa” on page 403Section 13.6.76, “ltoa” on page 417Section 13.6.70, “lltoa” on page 408Section 13.6.107, “sprintf” on page 464Section 13.6.127, “strtod” on page 491Section 13.6.129, “strtol” on page 495Section 13.6.131, “strtoul” on page 499



13.6.13 atoll

Syntax: #include <stdlib.h>long long intatoll(const char *ptr);

Description: The function atoll reads a string representing a numeric value and returns this value in long long integer format. The string pointed to by ptr may contain an optional leading sign, plus (+) or minus (–), and any number of decimal digits. Leading blanks and tabs are ignored. The scan stops if any inappropriate character is encountered. The result value is then returned.

Diagnostics: If no numeric value is detected, atoll returns 0. In case of an overflow, i.e. a value exceeds LLONG_MAX (if negative, LLONG_MIN), the function returns LLONG_MAX (LLONG_MIN) and sets errno to ERANGE.

Example 140. Function atoll


int main(void){ long long int l; char *cptr;

cptr = "-9223372036854775808"; l = atoll(cptr); printf("string value %s converted by atoll to %21d\n", cptr, l); return 0;}


string value -9223372036854775808 converted by atoll to -9223372036854775808

Further Information:Section 13.6.11, “atoi” on page 316Section 13.6.12, “atol” on page 317Section 13.6.65, “itoa” on page 403Section 13.6.76, “ltoa” on page 417Section 13.6.70, “lltoa” on page 408Section 13.6.107, “sprintf” on page 464



13.6.14 bsearch

Syntax: #include <stdlib.h>void *bsearch(const void *key,

const void *base, size_t nelem,

size_t width,int (*compare)(const void *pkey,

const void *pbase));

Description: bsearch performs a binary search on a sorted array of nelem elements for an object that matches key. The pointer base points to the sorted array. Every element in the array is of width bytes in size.

The comparison function pointed to by compare is called with two arguments pointing to the elements of the array. The first argument pkey points to the same object as key. The second argument points to an element in the array. The comparison function should return an integer value less than, equal to, or greater than zero if the object pointed to by key is less than, equal to or greater than the element of the array.

Diagnostics: bsearch returns a pointer to a matching element of the array, or NULL if none can be found.



Example 141. Function bsearch

#include <stdlib.h>#include <stdio.h>#include <string.h>

#define NELEM sizeof(keyarray) / sizeof (char *)

static char *keyarray[] ={ "auto", "bear", "cat", "deer", "ear", "find", "very", "wild"};

int compare(const char *pkey, const char **pbase){ return strcmp(pkey, *pbase);}

int look_for_key(char *name){ char **key;

key = bsearch(name, keyarray, NELEM, sizeof(char *), (int(*)(const void*, const void*))compare); return key == NULL ? -1 : key - keyarray;}

int main(void){ printf("Looking for key ’cat’: %2d\n", look_for_key("cat")); printf("Looking for key ’carry’: %2d\n", look_for_key("carry")); printf("Looking for key ’deer’: %2d\n", look_for_key("deer")); return 0;}


Looking for key ’cat’: 2 Looking for key ’carry’: -1 Looking for key ’deer’: 3



13.6.15 calloc

Syntax: #include <stdlib.h>void *calloc(size_t nelem, size_t width);

Description: calloc allocates memory to hold consecutive bytes for nelem elements of size width and returns the address of the origin of this memory area.

Diagnostics: calloc returns a pointer to the allocated space or NULL if insufficient memory is available.

Note: Frequent memory allocation and deallocation may lead to heap fragmentation and, as a result, memory allocation may fail.The function calloc always needs the interface function _sbrk.

Example 142. Function calloc

#include <stdio.h>#include <stdlib.h>

int main(void){ typedef char * PCHAR; PCHAR buf;

buf = (PCHAR)calloc(20, sizeof(char)); if(buf) { printf("Memory for 20 characters could be allocated!\n"); } else { printf("Not enough memory available to allocate characters!\n"); } free(buf); return 0;}

The program above produces the following output (if the space is available):

Memory for 20 characters could be allocated!

Further Information:Section 13.6.41, “free” on page 360Section 13.6.77, “malloc” on page 418Section 13.6.95, “realloc” on page 445Section 14.4.9, “_sbrk” on page 621



13.6.16 ceil

Syntax: #include <math.h>doubleceil(double x);

Description: ceil calculates the ceiling of a value.

Diagnostics: ceil returns a double value representing the smallest integer that is greater than or equal to x.

Example 143. Function ceil


int main(void){ double x1 = -3.2, x2 = 3.2, x3 = 0.0, x4 = 1.8;

printf("The ceiling of %+.2lf is %+.2lf\n", x1, ceil(x1)); printf(" floor is %+.2lf\n", floor(x1)); printf("The ceiling of %+.2lf is %+.2lf\n", x2, ceil(x2)); printf(" floor is %+.2lf\n", floor(x2)); printf("The ceiling of %+.2lf is %+.2lf\n", x3, ceil(x3)); printf(" floor is %+.2lf\n", floor(x3)); printf("The ceiling of %+.2lf is %+.2lf\n", x4, ceil(x4)); printf(" floor is %+.2lf\n", floor(x4)); return 0;}


The ceiling of -3.20 is -3.00 floor is -4.00 The ceiling of +3.20 is +4.00 floor is +3.00 The ceiling of +0.00 is +0.00 floor is +0.00 The ceiling of +1.80 is +2.00 floor is +1.00

Further Information:Section 13.6.34, “floor” on page 345Section 13.6.35, “fmod” on page 346



13.6.17 clearerr

Syntax: #include <stdio.h>voidclearerr(FILE *stream );

Description: A call to clearerr resets the EOF and error indicators for stream.

Diagnostics: clearerr has no return value.

Example 144. Function clearerr

#include <stdio.h>

int main(void){ FILE *f = NULL; printf("Creating an error by opening a non-existent read-only file.\n"); f = fopen("exist.non", "r"); if(f == NULL || ferror(f)) { perror("Error"); clearerr(stdin); } else { printf("No error!\n"); fclose(f); } return 0;}


Creating an error by opening a non-existent read-only file. Error: Error 2



13.6.18 clock

This function is also a system interface function and therefore described in Section 14.3.1, “clock” on page 606.



13.6.19 cos

Syntax: #include <math.h>doublecos(double x);

Description: cos calculates the cosine of x.

Diagnostics: cos returns the cosine value of x. If x is large, a partial loss of significance in the result may occur.

Example 145. Function cos


int main(void){ double x = .5; printf("The cosine of %.2lf is %lf\n", x, cos(x)); printf(" sine is %lf\n", sin(x)); return 0;}


The cosine of 0.50 is 0.877583 sine is 0.479426

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.8, “atan2” on page 312Section 13.6.20, “cosh” on page 326Section 13.6.105, “sin” on page 462Section 13.6.135, “tan” on page 506



13.6.20 cosh

Syntax: #include <math.h>doublecosh(double x);

Description: cosh calculates the hyperbolic cosine of x.

Diagnostics: cosh returns the hyperbolic cosine value of x. If x is too large, the function returns HUGE_VAL and sets errno to ERANGE.

Example 146. Function cosh



printf("The hyperbolic cosine of %.2lf is %lf\n", x, cosh(x)); printf("The hyperbolic sine is %lf\n", sinh(x)); printf("The cosine is %lf\n", cos(x)); return 0;}


The hyperbolic cosine of 0.50 is 1.127626 The hyperbolic sine is 0.521095 The cosine is 0.877583

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.8, “atan2” on page 312Section 13.6.19, “cos” on page 325Section 13.6.105, “sin” on page 462Section 13.6.135, “tan” on page 506



13.6.21 ctime

Syntax: #include <time.h>char*ctime(const time_t *timer);

Description: ctime converts the internal time stored as time_t, pointed to by timer, to a 26 character string of the following format:

"Wed Oct 13 16:30:45 1993\n\0"

Note: Calling ctime is the same as calling localtime and then calling asctime:

asctime( localtime( timer));

Diagnostics: ctime returns a pointer to the static buffer of the character string result. This buffer is re-used each time ctime is called. Every call destroys the result of the previous buffer, which is also used by gmtime and localtime.

ctime represents a date after midnight, December 31, 1899, Universal Coordinated Time (UCT). Out of this range, ctime returns NULL.

Note: UTC was formerly known as Greenwich Mean Time (GMT).

Example 147. Function ctime

#include <time.h>#include <stdio.h>

int main(void){ time_t local_time; time(&local_time); printf("Local date and time are:\n\t\t%s\n", ctime(&local_time)); return 0;}


Local date and time are: Mon Feb 4 08:12:52 2002

Further Information:Section 13.6.5, “asctime” on page 309Section 13.6.53, “gmtime” on page 382Section 13.6.72, “localtime” on page 412Section 13.6.137, “time” on page 508



13.6.22 difftime

Syntax: #include <time.h>doubledifftime(time_h time1, time_t time0 );

Description: difftime calculates the difference between the two calendar times time1 and time0 in seconds.

Diagnostics: difftime returns the calculated time in seconds. The result returned is a double value.

Example 148. Function difftime

#include <stdio.h>#include <time.h>

void making_time(void){ long loops = 60000L;

printf("Making %ld loops.\n", loops); while( loops--);}

int main(void){ time_t start_time, fin_time;

time(&start_time); /* or ’start_time = time(NULL); */ making_time(); time(&fin_time); printf("The process lasted %3.1f seconds!\n", difftime(fin_time, start_time)); return 0;}


Making 60000 loops. The process lasted 12.0 seconds!

Further Information:Section 13.6.137, “time” on page 508



13.6.23 div

Syntax: #include <stdlib.h>div_tdiv(int numer, int denom);

Description: div computes the quotient and remainder of the integer division of the numerator numer by the denominator denom.

Diagnostics: div returns a structure of type div_t containing the quotient quot and the remainder rem.If denom is 0, the function returns {0,0} and errno is set to ERANGE.If denom is -1 and numer is INT_MIN, the function returns {0,0} and errno is set to EDOM.

Example 149. Function div


int main(void){ int x,y; div_t res;

x = 12345; y = 300; printf("x = %d\n", x); printf("y = %d\n", y); res = div(x, y); printf("quotient = %d and remainder = %d\n", res.quot, res.rem); return 0;}


x = 12345 y = 300 quotient = 41 and remainder = 45

Further Information:Section 13.6.68, “ldiv” on page 406



13.6.24 exit

Syntax: #include <stdlib.h>voidexit(int status);

Description: exit causes normal program termination. Normal program termination happens as follows:

All functions registered by atexit are called in the reverse order of their registration. Each function is called as many times as it was registered. The execution environment is as if the main function, called at program startup, had returned. All open streams are closed and all open output streams are flushed. All files created by tmpfile are removed. Then the system interface function _exit is called with status as parameter. Finally, control is returned to the host environment.

Diagnostics: The status “successful termination” is returned if the value of status is zero or EXIT_SUCCESS. If the value of status is EXIT_FAILURE, the status “unsuccessful termination” is returned.

Example 150. Function exit


void copy(char *src_name, char *dst_name){ register int i; char buffer[1024]; FILE *src, *dst;

if((src = fopen(src_name, "r")) == NULL) { printf(" File ’%s’ not found!\n", src_name); exit(EXIT_FAILURE); }

if((dst = fopen(dst_name, "wt")) == NULL) { printf(" File ’%s’ could not be opened / created!\n", dst_name); exit(EXIT_FAILURE); }

printf("Copying... ’%s’ to ’%s’\n", src_name, dst_name); do { i = fread(buffer, 1, 1024, src); fwrite(buffer, 1, i, dst); } while (i == 1024); fclose(src); fclose(dst);}



int main(int argc, char *argv[]){ if (argc != 3) { printf("Missing argument or too many!\n"); exit(EXIT_FAILURE); } else { copy(argv[1], argv[2]); printf("Success!\n"); exit(EXIT_SUCCESS); } return 0;}

If the program above is called with the correct arguments (names of files that can be opened), it produces the following output and ends, returning the value EXIT_SUCCESS:

Copying... ’test.txt’ to ’test2.txt’ Success!

The program then ends, returning the value EXIT_SUCCESS.

Further Information:Section 13.2.5, “System Interface Functions” on page 276Section 13.6.9, “atexit” on page 313Section 13.6.138, “tmpfile” on page 509



13.6.25 exp

Syntax: #include <math.h>doubleexp(double x);

Description: exp computes the exponential function of its floating point argument x.

Diagnostics: The function returns ex. HUGE_VAL is returned on overflow and errno is set to ERANGE. On underflow, zero is returned but errno is not set.

Example 151. Function exp


int main(void){ double x = .5, y = 2.3025851;

printf("exp(%.2lf) = %lf\n", x, exp(x)); printf("exp(%lf) = %lf\n", y, exp(y)); return 0;}L


exp(0.50) = 1.648721 exp(2.302585) = 10.000000

Further Information:Section 13.6.73, “log” on page 413Section 13.6.74, “log10” on page 414



13.6.26 fabs

Syntax: #include <math.h>doublefabs(double x);

Description: fabs computes the absolute value of its floating point argument x.

Diagnostics: fabs returns the absolute value of its argument x. There is no error return.

Example 152. Function fabs


int main(void){ double x = 3.56, y = -3.56;

printf("The absolute value of %+.2lf is %+.2lf\n", x, fabs(x)); printf("The absolute value of %+.2lf is %+.2lf\n", y, fabs(y)); return 0;}


The absolute value of +3.56 is +3.56 The absolute value of -3.56 is +3.56

Further Information:Section 13.6.3, “abs” on page 307Section 13.6.66, “labs” on page 404



13.6.27 fclose

Syntax: #include <stdio.h>intfclose(FILE *stream );

Description: fclose closes the stream stream. It calls fflush on the given stream, closes the associated file and releases any allocated buffer.

Diagnostics: fclose returns zero if stream was successfully closed. It returns EOF on error.

Example 153. Function fclose

#include <stdio.h>

int main(void){ FILE *f; int first, sec; printf("Enter two integer values!\n"); scanf("%d%d", &first, &sec); f = fopen("TMP.TMP", "w"); fprintf(f, "first: %d\nsecond: %d\n", first, sec); fclose(f); return 0;}


Enter two integer values!

If the following lines are entered

1 2

then the file TMP.TMP contains the following text after the program has finished:

first: 1 second: 2

Further Information:Section 13.6.30, “fflush” on page 338Section 13.6.36, “fopen” on page 347



13.6.28 feof

Syntax: #include <stdio.h>intfeof(FILE *stream );

Description: feof tests the end-of-file indicator for stream.

Diagnostics: feof returns non-zero only if the EOF indicator is set for stream.

Example 154. Function feof


void copy(char *src_name){ register int i; char buffer[1024]; FILE *src; if((src = fopen(src_name, "r")) == NULL) { printf(" File ’%s’ not found!\n", src_name); exit( EXIT_FAILURE); } else { printf("Reading ’%s’ and printing contents to the sceen\n", src_name); } while (!feof(src)) { i = fread(buffer, 1, 1024, src); printf("%s", buffer); } fclose(src);}

int main(int argc, char *argv[]){ if(argc != 2) { printf("Wrong number of arguments!\n"); exit(EXIT_FAILURE); } else { copy(argv[1]); printf("Success!\n"); exit(EXIT_SUCCESS); } return 0;}



The program above is called as follows:

a.out tmp.tmp

with the file tmp.tmp containing the following text:

first: 1second: 2

The program produces the following output:

Reading ’tmp.tmp’ and printing contents to the sceen first: 1 second: 2 Success!

Further Information:Section 13.6.17, “clearerr” on page 323Section 13.6.36, “fopen” on page 347Section 13.6.29, “ferror” on page 337Section 13.6.85, “perror” on page 430



13.6.29 ferror

Syntax: #include <stdio.h>intferror(FILE *stream );

Description: ferror yields the error indicator for the file stream.

Diagnostics: ferror returns a non-zero value if an error occurs. A call to ferror does not reset the error indicator.

Example 155. Function ferror

#include <stdio.h>

int main(void){ FILE *f = NULL;

printf("Creating an error by opening a non-existent read-only file.\n"); f = fopen("exist.non", "r"); if(f == NULL || ferror(f)) { perror("Error"); clearerr(stdin); } else { printf("No error!\n"); fclose(f); } return 0;}

If the file exist.non does not exist, the program above produces the following output:

Creating an error by opening a non-existent read-only file. Error: Error 2

Further Information:Section 13.6.17, “clearerr” on page 323Section 13.6.28, “feof” on page 335Section 13.6.36, “fopen” on page 347Section 13.6.85, “perror” on page 430



13.6.30 fflush

Syntax: #include <stdio.h>intfflush(FILE *stream );

Description: fflush writes any data saved in internal buffers for the given file stream to this file. If stream is the NULL pointer, fflush is applied to all opened files.

It is not necessary that fllush is called directly within application programs since fclose calls fflush.

Diagnostics: fflush returns EOF if an error occurs; otherwise zero is returned. The variable errno is not modified by fflush unless the system interface function write sets errno. The low level I/O function write is called by fflush to omit output.

Example 156. Function fflush

#include <stdio.h>

int main(void){ printf("Output a string before an abort (y/n)?"); if(getchar() == ’y’) { printf("This line will be written to the screen!"); fflush(stdout); abort(); } else { printf("This line will not be written to the screen!"); abort(); } return 0;}


Output a string before an abort (y/n)?

If the input is ’y’, the program produces the following output:

This line will be written to the screen!

Otherwise, no further output is produced.

Further Information:Section 13.6.27, “fclose” on page 334



13.6.31 fgetc

Syntax: #include <stdio.h>intfgetc(FILE *stream );

Description: fgetc obtains a single character from the current position of the file stream as an unsigned character. Then it converts this character to an integer. The associated pointer is then incremented to point to the next character.

Diagnostics: fgetc returns EOF if end of file is reached or an error occurs.

The variable errno is not modified by fgetc unless the system interface function read sets errno. The low level I/O function read is called by fgetc to request input.

Note: The variable receiving the character from fgetc must be of type int to detect EOF.

Example 157. Function fgetc

#include <stdio.h>

int main(void){ int c; FILE * f;

printf("Read one character from a stream\n"); if((f = fopen("TMP.TMP", "r")) != NULL) { if ((c = fgetc(f)) == EOF) { printf("Read failed\n"); } else { printf("Read character...’%c’\n", c); fclose(f); } } return 0;}

The input file TMP.TMP contains the following text:

How much wood would a woodchuck chuckif a woodchuck could chuck wood?




Read one character from a stream Read character...’H’

Further Information:Section 13.6.38, “fputc” on page 354Section 13.6.49, “getc” on page 377Section 13.6.50, “getchar” on page 379



13.6.32 fgetpos

Syntax: #include <stdio.h>intfgetpos(FILE *stream, fpos_t *pos );

Description: fgetpos stores the current file position of file stream in the object pointed to by pos. The value stored contains unspecified information used by fgetpos for repositioning the stream to its position at the time of the last call to fgetpos.

Diagnostics: fgetpos returns zero if no error occurs; otherwise a non-zero value is returned. The variable errno is only set if the system interface function lseek sets it.

Example 158. Function fgetpos

#include <stdio.h>#define MAX 85

int main(void){ FILE *f; fpos_t pos; char data[MAX + 1];

if (f = fopen("poem.txt", "r")) { printf("Reading the contents of file ’poem.txt’.\n" "Writing it to the screen with the position of the beginning" " of every line.\n\n"); printf("POSITION TEXT\n\n"); fgetpos(f, &pos); while(fgets(data, MAX, f) != NULL) { printf("%7ld. %s", pos, data); fgetpos(f, &pos); } fclose(f); } return 0;}

The input file poem.txt contains the following:

Jack and Jill

Jack and Jill went up the hillTo fetch a pail of water;Jack fell down and broke his crown,And Jill came tumbling after.




Reading the contents of file ’poem.txt’. Writing it to the screen with the position of the beginning of every line.

POSITION TEXT

0. Jack and Jill 20. 21. Jack and Jill went up the hill 52. To fetch a pail of water; 78. Jack fell down and broke his crown, 114. And Jill came tumbling after.

Further Information:Section 13.6.46, “fsetpos” on page 371



13.6.33 fgets

Syntax: #include <stdio.h>char *fgets(char *s, int n, FILE *stream );

Description: fgets reads at most n–1 characters from the file stream in string s until the end of file has been reached or a newline character has been encountered. fgets retains a newline character and appends “\0” at the end of file.

Diagnostics: fgets returns the pointer s if no error occurs; otherwise the NULL pointer is returned. The variable errno is not modified by fgets unless the system interface function read sets errno. The low level I/O function read is called by fgets to request input.

Example 159. Function fgets

#include <stdio.h>#define MAXCHAR 85

int main(void){ FILE *f; int line_num; char data[MAXCHAR + 1];

if((f = fopen("poem.txt", "r")) != NULL) { printf("Reading from the file ’poem.txt’.\n" "Output to the screen the lines with their number.\n\n"); line_num = 0; while (fgets(data, MAXCHAR, f) != NULL) { line_num++; printf("%4d. %s", line_num, data); } fclose( f); } return 0;}

The input file poem.txt contains the following text:

Jack and Jill





Reading from the file ’poem.txt’. Output to the screen the lines with their number.


Further Information:Section 13.6.31, “fgetc” on page 339Section 13.6.49, “getc” on page 377Section 13.6.50, “getchar” on page 379Section 13.6.91, “puts” on page 439



13.6.34 floor

Syntax: #include <math.h>doublefloor(double x);

Description: floor computes the largest integral value not greater than x.

Diagnostics: floor returns a double value.

Example 160. Function floor


int main(void){ double x1 = -3.2, x2 = 3.2, x3 = 0.0, x4 = 1.8;

printf("The ceiling of %+.2lf is %+.2lf\n", x1, ceil(x1)); printf(" floor is %+.2lf\n", floor(x1)); printf("The ceiling of %+.2lf is %+.2lf\n", x2, ceil(x2)); printf(" floor is %+.2lf\n", floor(x2)); printf("The ceiling of %+.2lf is %+.2lf\n", x3, ceil(x3)); printf(" floor is %+.2lf\n", floor(x3)); printf("The ceiling of %+.2lf is %+.2lf\n", x4, ceil(x4)); printf(" floor is %+.2lf\n", floor(x4)); return 0;}


The ceiling of -3.20 is -3.00 floor is -4.00 The ceiling of +3.20 is +4.00 floor is +3.00 The ceiling of +0.00 is +0.00 floor is +0.00 The ceiling of +1.80 is +2.00 floor is +1.00

Further Information:Section 13.6.16, “ceil” on page 322Section 13.6.35, “fmod” on page 346



13.6.35 fmod

Syntax: #include <math.h>doublefmod(double x, double y);

Description: fmod calculates the floating point remainder of x/y even if the quotient x/y is not representable.

Diagnostics: fmod returns the value x–(i·y), where i is an integer value. The result has the same sign as x and magnitude of y if y is non-zero; otherwise zero is returned.

Example 161. Function fmod


int main(void){ double x = -20., y1 = 3., y2 = 7.;

printf("The floating-point remainder of %.1lf/%.1lf is %.1lf\n", x, y1, fmod(x,y1)); printf("The floating-point remainder of %.1lf/%.1lf is %.1lf\n", x, y2, fmod(x,y2)); return 0;}


The floating-point remainder of -20.0/3.0 is -2.0The floating-point remainder of -20.0/7.0 is -6.0

Further Information:Section 13.6.16, “ceil” on page 322Section 13.6.26, “fabs” on page 333Section 13.6.34, “floor” on page 345



13.6.36 fopen

Syntax: #include <stdio.h>FILE *fopen(const char *filename, const char *mode );

Description: fopen opens the file filename using the open mode mode. If filename does not exist, filename is created.

mode may have one of the following values:

Opening a file using the read mode (r as the first character) fails if the file cannot be read or does not exist.

Opening a file using the append mode (a as the first character) forces all following writes to the end of the file, regardless of previous calls to the fseek function.

Opening a file using the update mode (+ as second or third character), input and output may be performed on the associated stream. However, output must not followed directly by input without an intervening call to fflush, fseek, fsetpos, or rewind (the file positioning functions). If the reverse is also true, output must not be directly followed by input without an intervening call to a file positioning function unless the input encounters end-of-file.

Mode Meaning

"r" Opens a text file for reading. An error occurs if file is not found.

"w" Creates a text file for writing. The contents of an existing file is destroyed.

"a" Opens or creates a text file for writing at the end of the file.

"rb" Opens a binary file for reading. An error occurs if file is not found.

"wb" Creates a binary file for writing. The contents of an existing file is destroyed.

"ab" Opens or creates a binary file for writing at the end of the file.

"r+" Reads and/or writes a text file to update its contents. An error occurs if the file is not found.

"w+" Creates a new text file or removes the contents of an existing text file.

"a+" Creates a new text file or opens an existing text file to update its end.

"rb+" Reads and/or writes a binary file to update its contents. An error occurs if the file is not found.

"wb+" Creates a new binary file or removes the contents of an existing binary file.

"ab+" Creates a new binary file or opens an existing binary file to update its end.



Diagnostics: fopen returns a pointer to the structure of type FILE * if no error occurs.Otherwise fopen returns the pointer value 0 if an error occurs and errno contains a value indicating the type of error that has been detected.

Example 162. Function fopen

#include <stdio.h>#define MAXCHAR 85

int main(void){ FILE *f; int line_num; char data[MAXCHAR + 1];

if((f = fopen("poem.txt","r")) != NULL) { printf("Reading from the file ’poem.txt’.\n" "Output to the screen the lines with their line number.\n\n"); line_num = 0; while(fgets(data, MAXCHAR, f) != NULL) { line_num++; printf("%4d. %s", line_num, data); } fclose(f); } return 0;}


Jack and Jill


Value Meaning

ENOENT No such file or directory

EINVAL Invalid argument

ENOMEM Not enough space to allocate file management structures

ENFILE File table overflow because of too many open files




Reading from the file ’poem.txt’. Output to the screen the lines with their line number.


Further Information:Section 13.6.27, “fclose” on page 334Section 13.6.100, “setbuf” on page 454



13.6.37 fprintf

Syntax: #include <stdio.h>intfprintf(FILE *stream, const char *format, ... );

Description: fprintf directs output to the file stream using format conditions format. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but are otherwise ignored. fprintf returns if the end of the format string is encountered.

format is a multibyte character sequence. It is composed of zero or more directives:

• Ordinary multibyte characters (not %), which are copied to the output stream.

• Conversion specifiers, each of which results in fetching zero or more subsequent arguments.

A conversion specifier may have the following form:

% flag * field conversion-string

where the asterisk (*) and field are optional and preceded by zero or more flag (in any order) which modify the meaning of the conversion. flag may have one of the following values:

flag Description

– Adjustment flag. The result of the conversion will be left-justified within the field. If this flag is not specified, the result will be right-justified.

+ The result of the signed conversion will begin with a plus or minus sign. If this flag is not specified, only a negative value will begin with a sign.

space A space will be prefixed to the result if the first character of a signed conversion is not a sign or if a signed conversion results in no characters. If both space and + flags appear, the space flag will be ignored.

# The result is to be converted to an alternate form. For o, the first digit of the result will be a zero. For x (or X), a non-zero result will have a preceding 0x (or 0X). For e, E, f, g, and G, the result will have a decimal point.

0 For d, i, o, u, x, X, e, E, f, g, and G conversions: Leading zeroes are used to pad width. If 0 and the – flag appear, the 0 flag will be ignored. It will also be ignored for d, i, o, u, x and X conversions if a precision is specified. In all other cases, the behavior is undefined.



field may have one of the following values:

The following format conversion strings are recognized:

field Description

* width, precision or both may be indicated by an asterisk.

In this case, an integer argument supplies the width or precision. The indicated argument appears (in the given order) before the argument to be converted (if any). A negative width argument is taken as a – flag followed by a positive field width. A negative precision argument is taken as if the precision argument was omitted.

width An asterisk (*) or a decimal integer defines the minimum field width. If the converted value has fewer characters than width, it will be padded with spaces (by default) to the given field width. Also see the adjustment flag.

precision A period (.) followed by either an asterisk (*) or optional decimal integer.

Gives for d, i, o, u, x, and X the minimum number of digits to appear; for e, E, and f, the maximum number of digits are provided to appear after the decimal point character; for g and G, the maximum number of significant digits are provided.

h, l, L,ll, or L64

The character h before any conversion (d, i, o, x, X or u) indicates that the argument is a short int or an unsigned short int.

The character l before any conversion (d, i, o, x, X or u) indicates that the argument is a long int or an unsigned long int. An optional l specifies that a following n conversion specifier applies to a pointer to a long int argument.

The letter L before any conversion (e, E, f, g or G) indicates that the argument is long double.

The strings ll or L64 before any conversion (d, o, x, X) indicates that the argument is long long.

conversion-string

ArgumentType Description

% Output a % character. No arguments are processed.

The complete conversion specification to output a percent sign is %%.

c int The argument is converted to a character of type char or wchar.

d, i intlonglong long

Converts the argument to signed decimal of the format [-]dddd.

e, E double Converts the double argument to exponential form with the format d.ddddddesdd. There is always one digit before the decimal point and as many as precision specifiers after it (default is six). The exponent sign s may be either + or –. The exponent is introduced by e (or E).

If precision zero and – are not specified, no decimal point appears.

If the argument is a double value, e has to be proceeded by L or l.

f double Converts the double argument to a representation in the format [-]ddd.ddd. The number of digits after the decimal point is the precision (default is six). If precision zero and – are not specified, no decimal point appears. If a decimal point does appear, then at least one digit will appear before it.



Diagnostics: fprintf returns the number of characters written. If an output error occurs, a negative value is returned.

The variable errno is not modified by fprintf unless the system interface function write sets errno. The low level I/O function write is called by fprintf to omit output.

g, G double Converts the double argument to whichever of the styles d, e, E (in case of G) or f which causes the smallest loss of precision and which takes the least space. If the precision is set to zero, it is taken as one. Style e (or E) are used only if the exponent is less than –4 or greater than or equal to the precision. Trailing zeros are removed.

o int Converts the int argument to unsigned octal.

s char *wchar_t

The argument type char * is converted to a character string (sequence of non-whitespace characters).It must be large enough to contain the input field plus the NULL character /0, which will be added automatically.To convert a wchar_t argument type, the qualifier l is used. So %lc converts a wchar_t argument type.

u int Converts the int argument to unsigned decimal.

x int Converts the int argument to unsigned hexadecimal, using lower case letters.

X int Converts the int argument to unsigned hexadecimal, using upper case letters.

p, P int The argument type int * is converted to a signed hexadecimal integer.

n This argument is a pointer to an integer containing the number of characters so far successfully written to the output stream by the current call. No argument is converted.

Ld, Li long Converts the long argument to signed long decimal.

Lo long Converts the long argument to unsigned long octal.

Lu long Converts the long argument to unsigned long decimal.

Lx long Converts the long argument to unsigned long hexadecimal, using lower case letters.

LX long Converts the long argument to unsigned long hexadecimal, using upper case letters.

lld, lli,L64d, L64i

long Converts the long argument to signed long long decimal.

llo, L64o long Converts the long argument to unsigned long long octal.

llu, L64u long Converts the long argument to unsigned long long decimal.

llx, L64x long Converts the long argument to unsigned long long hexadecimal, using lower case letters.

llX, L64X long Converts the long argument to unsigned long long hexadecimal, using upper case letters.

conversion-string

ArgumentType Description



Example 163. Function fprintf

#include <stdio.h>

int main(void){ char c = ’Y’, *string = "sentence"; int cnt = -1234; double fl = 123.4567;

fprintf(stdout, "Strings:\n’%20s’\n’%20.5s’\n", string, string); fprintf(stdout, "Characters:\n’%3c’\n’%6c’\n", c, c); fprintf(stdout, "Integer formats:\nDecimal: ’%d’\nJustified:’%.4d’\n" "Unsigned: ’%u’\n", cnt, cnt, cnt); fprintf(stdout, "Int Decimals as \nHex: %Xh\nC hex: 0x%x\nOctal: %o\n", cnt, cnt, cnt); fprintf(stdout, "Real numbers:\n’%f’\n’%.3f’\n’%e’\n’%E’\n", fl, fl, fl, fl); return 0;}


Strings: ’ sentence’ ’ sente’ Characters: ’ Y’ ’ Y’ Integer formats: Decimal: ’-1234’ Justified:’-1234’ Unsigned: ’4294966062’ Int Decimals as Hex: FFFFFB2Eh C hex: 0xfffffb2e Octal: 37777775456 Real numbers: ’123.456700’ ’123.457’ ’1.234567e+02’ ’1.234567E+02’

Further Information:Section 13.6.44, “fscanf” on page 364Section 13.6.88, “printf” on page 433Section 13.6.107, “sprintf” on page 464Section 13.6.143, “vfprintf” on page 517



13.6.38 fputc

Syntax: #include <stdio.h>intfputc(int c, FILE *stream );

Description: fputc writes a single character c to the file stream.

Diagnostics: fputc returns the character itself if no error occurs; otherwise fputc returns EOF.

The variable errno is not modified by fputc unless the system interface function write sets errno. The low level I/O function write is called by fputc to omit output.

Example 164. Function fputc

#include <stdio.h>

void filecopy(FILE * fp){ int c; while((c = getc(fp)) != EOF) { fputc(c, stdout); }}

int main(int argc, char *argv[]) /* concatenate files to stdout */{ FILE *f, *fopen();

if (argc == 1) /* no arguments; copy from standard input */ { filecopy(stdin); } else { while(--argc > 0) { if((f = fopen(*++argv, "r")) == NULL) { fprintf(stderr, "File %s not found! \n", *argv); break; } else { filecopy(f); fclose(f); } } } return 0;}



Consider the following input files:

in_1.txt:

Humpty Dumpty sat on a wall

in_2.txt:

Humpty Dumpty had a great fall

If called as follows

a.out in_1.txt in_2.txt

the program above produces the following output:

Humpty Dumpty sat on a wall Humpty Dumpty had a great fall

Further Information:Section 13.6.31, “fgetc” on page 339Section 13.6.38, “fputc” on page 354Section 13.6.49, “getc” on page 377Section 13.6.89, “putc” on page 435



13.6.39 fputs

Syntax: #include <stdio.h>intfputs(const char *s, FILE *stream );

Description: fputs writes a character string s to the file stream. The terminating null character \0 is not written.

Diagnostics: fputs returns EOF if an error occurs; otherwise a non-negative value is returned. The variable errno is not modified by fputs unless the system interface function write sets errno. The low level I/O function write is called by fputs to emit output.

Example 165. Function fputs


int main(void){ FILE *f; int line_num; char data[MAX + 1];

if((f = fopen("poem.txt","r")) != NULL) { printf("Reading from the file ’poem.txt’.\n" "Output to the screen the lines with their number.\n\n"); line_num = 0; while(fgets(data, MAX, f) != NULL) { line_num++; printf("%4d. ", line_num); fputs(data, stdout); } fclose( f); } return 0;}


Jack and Jill





Reading from the file ’poem.txt’. Output to the screen the lines with their number. 1. Jack and Jill 2. 3. Jack and Jill went up the hill 4. To fetch a pail of water; 5. Jack fell down and broke his crown, 6. And Jill came tumbling after.

Further Information:Section 13.6.33, “fgets” on page 343Section 13.6.38, “fputc” on page 354Section 13.6.52, “gets” on page 381Section 13.6.89, “putc” on page 435Section 13.6.91, “puts” on page 439



13.6.40 fread

Syntax: #include <stdio.h>size_tfread(void *ptr, size_t size, size_t nmemb, FILE *stream);

Description: fread reads nmemb objects of size bytes each from the file stream into the memory location ptr. fread is often used to read files with a fixed structure.

Diagnostics: fread returns the actual number of successfully read objects if an error occurs or the end of file has been reached. The actual number may be less than size. To determine whether EOF has been encountered or an input/output error has occurred, the functions feof and ferror can be used. The variable errno is not modified by fread unless the system interface function read sets errno. The low level I/O function read is called by fread to request input.

Example 166. Function fread

#include <stdio.h>#include <stdlib.h>#include <time.h>

#define NAMELENGTH 50#define CODELENGTH 10#define ADR_SIZE sizeof(ADDRESS)

typedef struct { long sequence_no; char name[NAMELENGTH + 1]; char first_name[NAMELENGTH + 1]; time_t date_of_birth; char street[NAMELENGTH + 1]; int street_no; char postal_code[CODELENGTH + 1]; char town[NAMELENGTH + 1];} ADDRESS, *ADR_PTR;

int main(void){ FILE *f; ADDRESS buffer; printf("Reading a file of addresses!\n"); if((f = fopen("address.dat","w+")) == NULL) { exit( EXIT_FAILURE); } else { buffer.sequence_no = 42; strcpy(buffer.first_name, "Frank"); strcpy(buffer.name, "Miller");



fwrite((char *)&buffer, ADR_SIZE, 1, f); rewind(f); printf("The entry consists of following components:\n"); while(fread((char *) &buffer, ADR_SIZE, 1, f) == 1) { printf("\t%ld.\t: %s, %s\n", buffer.sequence_no, buffer.name, buffer.first_name); } fclose(f); } return 0;}


Reading a file of addresses! The entry consists of following components: 42.: Miller, Frank

Further Information:Section 13.6.36, “fopen” on page 347Section 13.6.28, “feof” on page 335Section 13.6.48, “fwrite” on page 375



13.6.41 free

Syntax: #include <stdlib.h>voidfree(void *ptr );

Description: free deallocates a memory block to which ptr points. The memory block was allocated by the function calls of calloc, malloc, or realloc. free does not update the value of ptr. This pointer is still pointing to the same memory area that has been deallocated. It is the programmer’s responsibility not to access that area.

free accepts the setting of the interface function _sblockcontrbrk. Since free calls the interface function _freebrk, it returns the last allocated sbrk-block to the operating system. If _sblockcontrbrk returns zero, free deallocates a memory block as described above. free concatenates neighboring freed areas only if these areas belong to the same allocated block. The value 0 is a valid input to free, but no action takes place.

Example 167. Function free


int main( void){ char * buf;

buf = (PCHAR) calloc(20, sizeof(char)); if(buf) { printf("Memory for 20 characters could be allocated!\n"); } else { printf("Not enough memory available to allocate characters!\n"); } free(buf); return 0;}

The program above produces the following output (provided the memory is available):

Memory for 20 characters could be allocated!

Further Information:Section 13.6.1, “_sbrkblockfree” on page 305Section 13.6.15, “calloc” on page 321Section 13.6.77, “malloc” on page 418Section 13.6.95, “realloc” on page 445Section 14.4.3, “_freebrk” on page 615



13.6.42 freopen

Syntax: #include <stdio.h>FILE *freopen(const char *filename, const char *mode, FILE*stream );

Description: freopen opens the file filename. The file previously associated with stream is closed as if fclose were called. freopen is usually used for redirection of stdin or stdout. For more information on the argument mode can be found in the description of the function fopen.

Diagnostics: freopen returns a pointer to the object controlling the stream whose name is the string pointed to by filename. This pointer must be passed as a parameter to subsequent functions which perform operations on the file.

freopen returns the pointer value 0 if an error occurs and errno contains a value indicating the type of error that has been detected.

Example 168. Function freopen

#include <stdio.h>

void filecopy1(void){ int c; while((c = getchar()) != EOF) { putchar(c); }}

int main(int argc, char *argv[]) /* concatenate files */{ if(argc == 1) /* no arguments; copy from standard input */ { filecopy1(); } else { while(--argc > 0) { if(freopen(*++argv, "r", stdin) == 0) { printf("Cannot open File %s!\n", *argv); break;

Value Description






} else { filecopy1(); } } } return 0;}

Consider the following input files:

in_1.txt:

Humpty Dumpty sat on a wall

in_2.txt:

Humpty Dumpty had a great fall

If called as follows

a.out in_1.txt in_2.txt

the program above produces the following output:

Humpty Dumpty sat on a wall Humpty Dumpty had a great fall

Further Information:Section 13.6.36, “fopen” on page 347



13.6.43 frexp

Syntax: #include <math.h>doublefrexp(double x, int *expptr);

Description: frexp breaks down the floating point value (x) into a mantissa (m) and an exponent (n), so that the absolute value of m is between [0.5, 1.0] and

x = m ·2n

The integer exponent n is stored at the location pointed to by expptr.

Diagnostics: frexp returns the mantissa m. If x is zero, zero is returned for the mantissa m and the exponent n.

Example 169. Function frexp


int main(void){ double x = 8.15, mant; int expptr;

mant = frexp(x, &expptr); printf("%.2lf is composed with mantissa %lf and exponent %d (base 2)\n", x, mant, expptr); printf("In other words %.2lf = %lf * 2^%d\n", x, mant, expptr); return 0;}


8.15 is composed with mantissa 0.509375 and exponent 4 (base 2) In other words 8.15 = 0.509375 * 2^4

Further Information:Section 13.6.67, “ldexp” on page 405Section 13.6.84, “modf” on page 429



13.6.44 fscanf

Syntax: #include <stdio.h>intfscanf(FILE *stream, const char *format, ...);

Description: fscanf reads input from the file stream using the format conditions format.

Input data is defined as a string of consecutive non-whitespace characters. Whitespace characters are skipped when an input function is searching for an input field which matches the specification it is searching for. If the specification includes a [, c, or n specifier, whitespaces are not skipped.

The format control string format determines the interpretation of input sequences as they are read. It may contain:

• conversion specifications starting with %

• whitespace characters

• ordinary characters

If there are insufficient arguments for the format control string, the behavior of the function is undefined. If the format control string is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. In addition, an argument’s type must match its corresponding conversion specification.

As all arguments will receive some values as a result of the call, they must be passed by reference. This means that all arguments must be pointers.

A conversion specification may have the following form:

% * width size conversion-character

where width and size are optional fields.

• The optional asterisk * is an assignment suppress character. This means that the input data is read but not assigned to the argument; the input data is discarded.

• width must be a positive decimal integer. It specifies the maximum input field width.

There are five possible size flags. These are the letters h, l, and L and the strings ll and L64.

• The flag h causes the argument involved to be treated as short. It can be used with any of the conversion characters for:

— signed decimal

— unsigned decimal

— unsigned octal



— unsigned hexadecimal

• The flag l causes the argument involved to be treated as long.

• The flag L causes the argument involved to be treated as long double.

• The flags L64 or ll cause the argument involved to be treated as long long.

The following format conversion characters are recognized:

Diagnostics: fscanf returns the number of successful assignments from input sequences to arguments. The number returned may be less than the given number of arguments in two cases:

Character Argument Type Description

c char *wchar_t

The argument type char * is converted to a sequence of the number of characters specified by width (default=1 if no directive is present).Note that whitespace characters are read. To read the next non-whitespace character, use %1s.c must be large enough to accept the sequence. Note that no NULL character \0 is added.To convert a wchar_t argument type, the qualifier l is used. So %lc converts a wchar_t argument type.

d int * The argument type int * is converted to a signed decimal integer.

e, E, f, g, G float * The argument type float * is converted to a floating point number of the form [–]ddd.ddd[E[sign]dd], where everything within square brackets is optional.A lowercase e may also be used to specify the exponent part of the expression. All these operations are identical.

i int * The argument type int * is converted to a signed integer, even as octal or hexadecimal value.

n,N int * No input is read.The number of already successfully read characters from the current call is stored to this pointer. Execution of a %n directive does not increment the assignment count.

o unsigned int * The argument type int * is converted to a signed octal integer.

p, P int * The argument type int * is converted to a signed hexadecimal integer.

s char *wchar_t

The argument type char * is converted to a character string (sequence of non-whitespace characters).It must be large enough to contain the input field plus the NULL character /0, which will be added automatically.To convert a wchar_t argument type, the qualifier l is used. So %lc converts a wchar_t argument type.

u unsigned int * The argument type unsigned int * is converted to a signed decimal integer.

x, X int * The argument type int * is converted to a signed hexadecimal integer.

[ ] char * The argument type char * is converted to a non-empty sequence of characters from a set of expected characters (scanset). The conversion character includes all subsequent characters in the format string up to and including the matching right bracket ]. Whitespace characters are read. It must be large enough to contain the input field plus the NULL character /0, which will be added automatically.



1. EOF is reached before the arguments are read in which case EOF is returned.

2. Input data does not match specifications given in the control string. In this case, the number of successful assignments is returned.

If a conversion terminates due to a conflicting input character, the offending character is not read in the input stream.

The success of literal matches can only be determined and suppressed assignments can only be revealed with the %n directive.



Example 170. Function fscanf

#include <stdio.h>

int main(void){ char c; unsigned int ui; int i; float fl; char x[5], y[5]; FILE *f;

if((f = fopen("TMP.TMP","w+")) == NULL) { printf("File cannot be opened\n"); } else { fprintf(f, "21 3456\n1.2 abcd367Z\n"); printf("Input stream:\n21 3456\n1.2abcd367Z\n\n"); fseek(f, 0L, SEEK_SET); /* Set pointer to the beginning of the file */ fscanf(f, "%c%u%2o%*d%f%4s%4[0-9]", &c, &ui, &i, &fl, x, y); printf("c = %c\nui = %u\ni = %o\nfl = %f\nx = %s\ny = %s\n", c, ui, i, fl, x, y); fclose(f); } return 0;}

The following text is written to the file TMP.TMP:

21 34561.2 abcd367Z


Input stream: 21 3456 1.2abcd367Z

c = 2 ui = 1 i = 34 fl = 1.200000 x = abcd y = 367

Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.99, “scanf” on page 451Section 13.6.110, “sscanf” on page 468



13.6.45 fseek

Syntax: #include <stdio.h>intfseek(FILE *stream, long offset, int mode);

Description: fseek changes the current position of the data pointer of a binary file. The new position is offset+mode. The position in a binary file is measured in characters from the beginning of the file.

mode may have one of the following values:

When using files opened in text mode, it is best to use either an offset of zero relative to the mode value or an offset value returned by an earlier call to ftell on the same stream. Line feeds and carriage-returns can produce unexpected results.

Whether fseek produces a valid result for a binary stream in mode SEEK_END depends on how lseek has been implemented for the specific target system.

Diagnostics: fseek clears the EOF indicator for file stream and deletes any effects of ungetc on the same file. After calling fseek, the next operation on an update file may be either input or output.

fseek returns non-zero if an error occurs. The variable errno is only set if the system interface function lseek sets it.

Mode Description

SEEK_SET Beginning of file

SEEK_CUR Current file position

SEEK_END End of file



Example 171. Function fseek

#include <stdio.h>#define MAX 85#define READ_LINE 3

int main(void){ FILE *f; int i; char data[MAX + 1];

if(f = fopen("poem.txt", "r")) { printf("Reading %d lines of file poem.txt’.\n\n", READ_LINE); i = 1; while((fgets(data, MAX, f) != NULL) && (i++ <= READ_LINE)) { printf(" %s", data); } printf("\nReposition file pointer to the beginning and read all:\n\n"); fseek(f, 0L, SEEK_SET); while(fgets(data, MAX, f) != NULL) { printf(" %s", data); } fclose( f); } return 0;}


There was an old womanWho lived in a shoe,She had so many childrenShe didn’t know what to do.She gave them some brothWithout any bread.She whipped them all soundlyAnd put them to bed.


Reading 3 lines of file poem.txt’.

There was an old woman Who lived in a shoe, She had so many children

Reposition file pointer to the beginning and read all:

There was an old woman Who lived in a shoe, She had so many children



She didn’t know what to do. She gave them some broth Without any bread. She whipped them all soundly And put them to bed.

Further Information:Section 13.6.47, “ftell” on page 373Section 13.6.46, “fsetpos” on page 371Section 13.6.98, “rewind” on page 449



13.6.46 fsetpos

Syntax: #include <stdio.h>intfsetpos(FILE *stream, const fpos_t *pos);

Description: fsetpos sets the file position indicator for file stream according to the value of pos, which shall be a value returned by an earlier call to fgetpos on the same stream.

Diagnostics: fsetpos returns zero, clears the EOF indicator for the file and deletes any effects of ungetc on the same file if no error occurs; otherwise fsetpos returns a non-zero value. Note that the variable errno is only set if the system interface function lseek sets it. After calling fsetpos the next operation on an update file may be either input or output.

Example 172. Function fsetpos

#include <stdio.h>#define MAX 85#define MAX_LINE 20

int main(void){ int i, line; FILE *f; fpos_t pos; char data[MAX + 1]; fpos_t pos_array[MAX_LINE];

if(f = fopen("poem.txt", "rb")) { printf("Reading the contents of file ’poem.txt’.\n" "Writing it to the screen with the line " "number at the beginning of every line.\n\n"); printf("LINE TEXT\n\n"); pos_array[0] = 0; i = 0; fgetpos(f, &pos); while(fgets(data, MAX, f) != NULL) { pos_array[++i] = pos; printf("%3d. %s", i, data); fgetpos(f, &pos); } printf("\nReposition to line: "); scanf("%d", &line); if(line < 1) { line = 1; } if(line > i) { line = i; } fsetpos(f, &pos_array[line]);



fgets(data, MAX, f); printf("\n%s\n", data); fclose(f); } return 0;}


Jack and Jill



Reading the contents of file ’poem.txt’. Writing it to the screen with the line number at the beginning of every line.

LINE TEXT

1. Jack and Jill 2. 3. Jack and Jill went up the hill 4. To fetch a pail of water; 5. Jack fell down and broke his crown, 6. And Jill came tumbling after. Reposition to line:

The following line is typed in:

3

The program continues to write:

Jack and Jill went up the hill

Further Information:Section 13.6.32, “fgetpos” on page 341Section 13.6.142, “ungetc” on page 515



13.6.47 ftell

Syntax: #include <stdio.h>longftell(FILE *stream);

Description: ftell yields the current offset of the file pointer relatively to the beginning of the file stream. For a binary file, the offset is the number of character bytes from the beginning of the file to the current position of the pointer. For a file opened in text mode, the value of the pointer contains unspecified information which is only usable in conjunction with fseek. fseek uses this information to return the file pointer of the file to its position before the last ftell call.

Diagnostics: ftell returns the current position of the file pointer; otherwise –1L is returned.The variable errno is only set if the system interface function lseek sets it.

Example 173. Function ftell


int main(void){ FILE *f; long pos; char data[MAX + 1];

if(f = fopen("poem.txt", "rb")) { printf("Reading the contents of file ’poem.txt’.\n" "Writing to the screen with the position " "at the beginning of every line.\n\n"); printf("POSITION TEXT\n\n"); pos = ftell(f); while(fgets(data, MAX, f) != NULL) { printf("%7ld. %s", pos, data); pos = ftell(f); fseek(f, pos); } fclose(f); } return 0;}




Jack and Jill



Reading the contents of file ’poem.txt’. Writing to the screen with the position at the beginning of every line.

POSITION TEXT


Further Information:Section 13.6.45, “fseek” on page 368



13.6.48 fwrite

Syntax: #include <stdio.h>size_tfwrite(const void *ptr, size_t size, size_t nmemb,

FILE *stream);

Description: fwrite writes nmemb objects of size size bytes from ptr to file stream.

Diagnostics: fwrite returns the number of actually written objects if a write error occurs; the number of actually written objects might be less than nmemb. The variable errno is not modified by fwrite unless the system interface function write sets errno. The low level I/O function write is called by fwrite to omit output.

Example 174. Function fwrite

#include <stdio.h>#include <stdlib.h>#include <time.h>

#define NAMELENGTH 50#define CODELENGTH 10#define ADR_SIZE sizeof(ADDRESS)

typedef struct{ long sequence_no; char name[NAMELENGTH + 1]; char first_name[NAMELENGTH + 1]; time_t date_of_birth; char street[NAMELENGTH + 1]; int street_no; char postal_code[CODELENGTH + 1]; char town[NAMELENGTH + 1];} ADDRESS, *ADR_PTR;

int main(void){ FILE *f; ADDRESS buffer; printf("Writing a file of addresses!\n"); if((f = fopen("address.dat", "w+")) == NULL) { exit( EXIT_FAILURE); } else { buffer.sequence_no = 471; strcpy(buffer.first_name, "Frank"); strcpy(buffer.name, "Zappa"); fwrite((char *) &buffer, ADR_SIZE, 1, f); rewind(f); printf("The entry consists of following components:\n"); while(fread((char *) &buffer, ADR_SIZE, 1, f) == 1)



{ printf("\t%ld: %s, %s\n", buffer.sequence_no, buffer.name, buffer.first_name); } fclose(f); } return 0;}

The program above writes the following output:

Writing a file of addresses! The entry consists of following components: 471: Zappa, Frank

Further Information:Section 13.6.40, “fread” on page 358



13.6.49 getc

Syntax: #include <stdio.h>intgetc(FILE *stream);

Description: getc obtains a single character from the current position of the file stream as an unsigned character and converts this character to an integer. The associated pointer is then incremented to point to the next character.

Diagnostics: getc returns EOF if end of file is reached or an error occurs.

The variable errno is not modified by getc unless the system interface function read sets errno. The low level I/O function read is called by getc to request input.

Note: The variable receiving the character from getc must be of type int to test EOF.

Example 175. Function getc

#include <stdio.h>#define BUFF_SIZ 15

int main(void){ char data[BUFF_SIZ + 1]; int i, c; printf("Type up to %d characters:\n", BUFF_SIZ); for(i = 0; (i < BUFF_SIZ) && ((c = getc(stdin)) != ’\n’); i++) { data[i] = c; } data[i] = ’\0’; /* Terminate string */ printf("Contents of data: %s\n", data); return 0;}

The program above produces the following output line:

Type up to 15 characters:


123456789 12345


Contents of data: 123456789 12345



Further Information:Section 13.6.31, “fgetc” on page 339Section 13.6.50, “getchar” on page 379Section 13.6.89, “putc” on page 435Section 13.6.90, “putchar” on page 437Section 13.6.142, “ungetc” on page 515



13.6.50 getchar

Syntax: #include <stdio.h>intgetchar(void);

Description: getchar is equivalent to getc(stdin).

Diagnostics: getchar returns EOF if end of file is reached or an error occurs.

The variable errno is not modified by getchar unless the system interface function read sets errno. The low level I/O function read is called by getchar to request input.

Example 176. Function getchar


int main(void){ char data[BUFF_SIZ + 1]; int i, c; printf("Type up to %d characters:\n", BUFF_SIZ); for(i = 0; (i < BUFF_SIZ) && ((c = getchar()) != ’\n’); i++) { data[i] = c; } data[i] = ’\0’; /* Terminate string */ printf("\nContents of data: %s\n", data); return 0;}




123456789 12345


Contents of data: 123456789 12345

Further Information:Section 13.6.31, “fgetc” on page 339Section 13.6.49, “getc” on page 377Section 13.6.89, “putc” on page 435Section 13.6.90, “putchar” on page 437Section 13.6.142, “ungetc” on page 515



13.6.51 getenv

Syntax: #include <stdlib.h>char *getenv(const char *name);

Description: getenv searches for the name set by name in the operating system. name is set using the SET command (e.g. SET name=value).

Diagnostics: getenv returns a pointer to the string associated with name if name was found within the operating system; otherwise getenv returns NULL.

Note: getenv is target-dependent. If the target system is an embedded system, getenv returns NULL regardless of the argument used.

Example 177. Function getenv


int main(void){ char *path_var; printf("Reading the environment variable of PATH!\n"); path_var = getenv("PATH"); if(path_var) { printf("The variable is:\n\t%s\n", path_var); } else { printf("Variable not found!\n"); } return 0;}

If the environment variable PATH is undefined in the environment, the program above produces the following output:

Reading the environment variable of PATH! Variable not found!

Further Information:Chapter 14, “Library-Target System Interface”



13.6.52 gets

Syntax: #include <stdio.h>char *gets(char *s);

Description: gets reads characters from standard input and stores them in string s until the newline character or the end-of-file character is encountered. It discards the newline character and appends a NULL character \0 at the end of the string which was read.

It is advantageous to use fgets instead of gets because any data beyond the array s will be destroyed if no newline character is read from standard input before the end of the array is reached.

Diagnostics: gets returns s if no read error occurs; otherwise NULL is returned.

The variable errno is not modified by gets unless the system interface function read sets errno. The low level I/O function read is called by gets to request input.

Example 178. Function gets

#include <stdio.h>

int main(void){ char data[21]; printf("Input a string of max. 20 characters: "); gets(data); printf("\nNow from data: %s\n", data); return 0;}


Input a string of max. 20 characters:


123456789ABCDEF 1234


Now from data: 123456789ABCDEF 1234

Further Information:Section 13.6.33, “fgets” on page 343Section 13.6.39, “fputs” on page 356Section 13.6.91, “puts” on page 439



13.6.53 gmtime

Syntax: #include <time.h>struct tm *gmtime(const time_t *timer);

Description: gmtime breaks down the calendar time timer and stores it in a structure of type tm, which is defined in the file time.h.

The time is expressed as Coordinated Universal Time (UTC). UTC was known as Greenwich Mean Time in former times.

Diagnostics: gmtime returns a pointer to that object if no error occurs; otherwise NULL is returned.

Note: The returned pointer refers to a pre-allocated static memory area. Therefore, do not use gmtime if the application needs to be reentrant.

Example 179. Function gmtime


int main(void){ time_t time_l; struct tm now_time; time(&time_l); printf("Now it is : %s\n", asctime(gmtime(&time_l))); return 0;}

The program above might produce the following output:

Now it is : Tue Feb 5 08:12:19 2002

Further Information:Section 13.4.15, “Header File time.h” on page 298Section 13.6.5, “asctime” on page 309Section 13.6.72, “localtime” on page 412Section 13.6.137, “time” on page 508



13.6.54 isalnum

Syntax: #include <ctype.h>intisalnum(int c);

Description: isalnum tests if the argument c is a letter or a number (a to z, A to Z or 0 to 9).

Diagnostics: isalnum returns zero if the argument is neither a letter nor a number; otherwise a non-zero value is returned.

Example 180. Function isalnum

#include <stdio.h>#include <ctype.h>

int main(void){ int ch; printf("Of the first 7Fh characters are the " "following ones letters or numbers:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isalnum(ch)) { printf("%.2Xh=%c \t", ch, ch); } } printf("\n"); return 0;}


Of the first 7Fh characters are the following ones letters or numbers: 30h=0 31h=1 32h=2 33h=3 34h=4 35h=5 36h=6 37h=7 38h=8 39h=9 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 47h=G 48h=H 49h=I 4Ah=J 4Bh=K 4Ch=L 4Dh=M 4Eh=N 4Fh=O 50h=P 51h=Q 52h=R 53h=S 54h=T 55h=U 56h=V 57h=W 58h=X 59h=Y 5Ah=Z 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f 67h=g 68h=h 69h=i 6Ah=j 6Bh=k 6Ch=l 6Dh=m 6Eh=n 6Fh=o 70h=p 71h=q 72h=r 73h=s 74h=t 75h=u 76h=v 77h=w 78h=x 79h=y 7Ah=z

Further Information:Section 13.6.55, “isalpha” on page 384Section 13.6.57, “isdigit” on page 387Section 13.6.59, “islower” on page 391Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401



13.6.55 isalpha

Syntax: #include <ctype.h>intisalpha(int c);

Description: isalpha tests if the argument c is a letter (a to z, or A to Z). A letter is any character for which isupper or islower is true.

Diagnostics: isalpha returns a non-zero value if c is a letter; otherwise zero is returned.

Example 181. Function isalpha


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones are letters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if (isalpha(ch)) { printf("%.2Xh=%c \t", ch, ch); } } printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are letters: 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 47h=G 48h=H 49h=I 4Ah=J 4Bh=K 4Ch=L 4Dh=M 4Eh=N 4Fh=O 50h=P 51h=Q 52h=R 53h=S 54h=T 55h=U 56h=V 57h=W 58h=X 59h=Y 5Ah=Z 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f 67h=g 68h=h 69h=i 6Ah=j 6Bh=k 6Ch=l 6Dh=m 6Eh=n 6Fh=o 70h=p 71h=q 72h=r 73h=s 74h=t 75h=u 76h=v 77h=w 78h=x 79h=y 7Ah=z

Further Information:Section 13.6.59, “islower” on page 391Section 13.6.63, “isupper” on page 399



13.6.56 iscntrl

Syntax: #include <ctype.h>intiscntrl(int c);

Description: iscntrl tests if the argument c is a control character (0x00 to 0x1F, or 0x7F).

Diagnostics: iscntrl returns a non-zero value if the argument is a control character; otherwise zero is returned.

Example 182. Function iscntrl


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones " "are control characters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(iscntrl(ch)) { printf("%.2Xh = #%d \t", ch, ch); } } printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are control characters: 00h = #0 01h = #1 02h = #2 03h = #3 04h = #4 05h = #5 06h = #6 07h = #7 08h = #8 09h = #9 0Ah = #10 0Bh = #11 0Ch = #12 0Dh = #13 0Eh = #14 0Fh = #15 10h = #16 11h = #17 12h = #18 13h = #19 14h = #20 15h = #21 16h = #22 17h = #23 18h = #24 19h = #25 1Ah = #26 1Bh = #27 1Ch = #28 1Dh = #29 1Eh = #30 1Fh = #31 7Fh = #127

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397



Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.57 isdigit

Syntax: #include <ctype.h>intisdigit(int c);

Description: isdigit tests if the argument c is a number (0 to 9).

Diagnostics: isdigit returns a non-zero value if the argument is a number; otherwise zero is returned.

Example 183. Function isdigit


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones are numbers:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isdigit(ch)) { printf("%.2Xh=%c \n", ch, ch); } } printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are numbers: 30h=0 31h=1 32h=2 33h=3 34h=4 35h=5 36h=6 37h=7 38h=8 39h=9

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393



Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.58 isgraph

Syntax: #include <ctype.h>intisgraph(int c);

Description: isgraph tests if the argument c is a printable character.

Diagnostics: isgraph returns a non-zero value if the argument is a printable character, otherwise zero is returned.

Example 184. Function isgraph

#include <stdio.h>#include <ctype.h>int main(void){ int ch; printf("For the first 7Fh characters, the " "following are printable characters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isgraph(ch)) { printf("%.2Xh=%c \t", ch, ch); } }printf("\n"); return 0;}


For the first 7Fh characters, the following are printable characters: 21h=! 22h=" 23h=# 24h=$ 25h=% 26h=& 27h=’ 28h=( 29h=) 2Ah=* 2Bh=+ 2Ch=, 2Dh=- 2Eh=. 2Fh=/ 30h=0 31h=1 32h=2 33h=3 34h=4 35h=5 36h=6 37h=7 38h=8 39h=9 3Ah=: 3Bh=; 3Ch=< 3Dh== 3Eh=> 3Fh=? 40h=@ 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 47h=G 48h=H 49h=I 4Ah=J 4Bh=K 4Ch=L 4Dh=M 4Eh=N 4Fh=O 50h=P 51h=Q 52h=R 53h=S 54h=T 55h=U 56h=V 57h=W 58h=X 59h=Y 5Ah=Z 5Bh=[ 5Ch=\ 5Dh=] 5Eh=^ 5Fh=_ 60h=‘ 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f 67h=g 68h=h 69h=i 6Ah=j 6Bh=k 6Ch=l 6Dh=m 6Eh=n 6Fh=o 70h=p 71h=q 72h=r 73h=s 74h=t 75h=u 76h=v 77h=w 78h=x 79h=y 7Ah=z 7Bh={ 7Ch=| 7Dh=} 7Eh=~

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.59, “islower” on page 391



Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.59 islower

Syntax: #include <ctype.h>intislower(int c);

Description: islower tests if the argument c is a lower case letter (a to z).

Diagnostics: islower returns a non-zero value if the argument is a lower case letter; otherwise zero is returned.

Example 185. Function islower


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones " "are lower case letters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(islower(ch)) { printf("%.2Xh => %c \t", ch, ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are lower case letters: 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f 67h=g 68h=h 69h=i 6Ah=j 6Bh=k 6Ch=l 6Dh=m 6Eh=n 6Fh=o 70h=p 71h=q 72h=r 73h=s 74h=t 75h=u 76h=v 77h=w 78h=x 79h=y 7Ah=z

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397



13.6.60 isprint

Syntax: #include <ctype.h>intisprint(int c);

Description: isprint tests if the argument c is a printable character.

Diagnostics: isprint returns a non-zero value if the argument is a printable character; otherwise zero is returned.

Example 186. Function isprint


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones " " are printable characters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isprint(ch)) { printf("%.2Xh=%c \t", ch, ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are printable characters: 20h= 21h=! 22h=" 23h=# 24h=$ 25h=% 26h=& 27h=’ 28h=( 29h=) 2Ah=* 2Bh=+ 2Ch=, 2Dh=- 2Eh=. 2Fh=/ 30h=0 31h=1 32h=2 33h=3 34h=4 35h=5 36h=6 37h=7 38h=8 39h=9 3Ah=: 3Bh=; 3Ch=< 3Dh== 3Eh=> 3Fh=? 40h=@ 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 47h=G 48h=H 49h=I 4Ah=J 4Bh=K 4Ch=L 4Dh=M 4Eh=N 4Fh=O 50h=P 51h=Q 52h=R 53h=S 54h=T 55h=U 56h=V 57h=W 58h=X 59h=Y 5Ah=Z 5Bh=[ 5Ch=\ 5Dh=] 5Eh=^ 5Fh=_ 60h=‘ 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f 67h=g 68h=h 69h=i 6Ah=j 6Bh=k 6Ch=l 6Dh=m 6Eh=n 6Fh=o 70h=p 71h=q 72h=r 73h=s 74h=t 75h=u 76h=v 77h=w 78h=x 79h=y 7Ah=z 7Bh={ 7Ch=| 7Dh=} 7Eh=~

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387



Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.61 ispunct

Syntax: #include <ctype.h>intispunct(int c);

Description: ispunct tests if the argument c is a printable punctuation character, that is a printable character that is neither a space character, an alphabet letter, nor a number.

Diagnostics: ispunct returns returns a non-zero value if the argument is a printable punctuation character; otherwise zero is returned.

Example 187. Function ispunct


int main(void){ int ch; printf("Of the first 7Fh characters, the following ones " " are punctuation characters:\n"); for(ch = 0; ch <= 0x7F ; ch++) { if (ispunct(ch)) { printf("%.2Xh=%c \t", ch, ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are punctuation characters: 21h=! 22h=" 23h=# 24h=$ 25h=% 26h=& 27h=’ 28h=( 29h=) 2Ah=* 2Bh=+ 2Ch=, 2Dh=- 2Eh=. 2Fh=/ 3Ah=: 3Bh=; 3Ch=< 3Dh== 3Eh=> 3Fh=? 40h=@ 5Bh=[ 5Ch=\ 5Dh=] 5Eh=^ 5Fh=_ 60h=‘ 7Bh={ 7Ch=| 7Dh=} 7Eh=~

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.62, “isspace” on page 397



13.6.62 isspace

Syntax: #include <ctype.h>intisspace(int c);

Description: isspace tests if the argument c is a whitespace character such as listed in the following table:

Diagnostics: isspace returns a non-zero value if the argument is a whitespace character; otherwise zero is returned.

Example 188. Function isspace


int main(void){ int ch;

printf("Of the first 7Fh characters, the following ones " " are whitespace characters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isspace(ch)) { printf("%.2Xh \t", ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are whitespace characters: 09h 0Ah 0Bh 0Ch 0Dh 20h

’ ’ Space

’\t’ Horizontal tab

’\n’ Newline or line-feed

’\r’ Carriage return

’\f’ Form feed

’\v’ Vertical tab



Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.63 isupper

Syntax: #include <ctype.h>intisupper(int c);

Description: isupper tests if the argument c is an upper case letter (A to Z).

Diagnostics: isupper returns a non-zero value if the argument is an upper case letter; otherwise zero is returned.

Example 189. Function isupper



printf("Of the first 7Fh characters, the following ones " " are upper case letters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isupper(ch)) { printf("%.2Xh=%c \t", ch, ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are upper case letters: 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 47h=G 48h=H 49h=I 4Ah=J 4Bh=K 4Ch=L 4Dh=M 4Eh=N 4Fh=O 50h=P 51h=Q 52h=R 53h=S 54h=T 55h=U 56h=V 57h=W 58h=X 59h=Y 5Ah=Z

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395



Section 13.6.62, “isspace” on page 397Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.64 isxdigit

Syntax: #include <ctype.h>intisxdigit(int c);

Description: isxdigit tests if the argument c is a hexadecimal character. These characters are the numbers ‘0’ to ‘9’ and the letters ‘a’ to ‘f’ as well as ‘A’ to ‘F’.

Diagnostics: isxdigit returns a non-zero value if the argument is a hexadecimal character; otherwise zero is returned.

Example 190. Function isxdigit



printf("Of the first 7Fh characters, the following ones " " are hexadecimal characters:\n"); for(ch = 0; ch <= 0x7F; ch++) { if(isxdigit(ch)) { printf("%.2Xh=%c \t", ch, ch); } }printf("\n"); return 0;}


Of the first 7Fh characters, the following ones are hexadecimal characters: 30h=0 31h=1 32h=2 33h=3 34h=4 35h=5 36h=6 37h=7 38h=8 39h=9 41h=A 42h=B 43h=C 44h=D 45h=E 46h=F 61h=a 62h=b 63h=c 64h=d 65h=e 66h=f

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395



Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.140, “tolower” on page 511Section 13.6.141, “toupper” on page 513



13.6.65 itoa

Syntax: #include <stdlib.h>char *itoa(int value, char *string, int base);

Description: The function itoa converts its integer argument value into a string. The parameter base determines the numeric base of the conversion, e.g. 2 for binary numbers or 16 for hexadecimal numbers. Valid bases are 2 to 36. The result is stored in the argument string as well as in the return value of the function.

Diagnostics: If the argument string is NULL, the resulting string is NULL. If base is smaller than 2 or greater than 36, the result is an empty string. Otherwise the integer value is converted into a string and placed in the string argument.

Example 191. Function itoa


int main(void){ char *l; int value, base; char string[64]; value = 60; base = 16; l = itoa(value, string, base); printf("Integer value %d converted by itoa to %s\n" "Numeric base of conversion: %d (decimal)\n", value, string, base); return 0;}


Integer value 60 converted by itoa to 3c Numeric base of conversion: 16 (decimal)

Further Information:Section 13.6.11, “atoi” on page 316Section 13.6.76, “ltoa” on page 417Section 13.6.70, “lltoa” on page 408



13.6.66 labs

Syntax: #include <stdlib.h>long intlabs(long int j);

Description: labs computes the absolute value of its long integer argument j.

Diagnostics: labs returns the absolute value of its long integer argument. There are no error returns.

Example 192. Function labs


int main(void){ long x = 367489L, y = -398654L;

printf("The absolute value of %+ld is %+ld\n", x, labs(x)); printf("The absolute value of %+ld is %+ld\n", y, labs(y)); return 0;}


The absolute value of +367489 is +367489 The absolute value of -398654 is +398654

Further Information:Section 13.6.3, “abs” on page 307Section 13.6.26, “fabs” on page 333



13.6.67 ldexp

Syntax: #include<math.h>doubleldexp(double x, int exp);

Description: ldexp calculates the value of x·2exp.

Diagnostics: ldexp returns the value of x·2exp. If an overflow results, HUGE_VAL is returned and errno is set to ERANGE.

Example 193. Function ldexp


int main(void){ double x1 = .5, x2 = 2.3025851; int exp1 = 2, exp2 = 3; printf("%.2lf * 2^%d = %lf\n", x1, exp1, ldexp(x1, exp1)); printf("%.2lf * 2^%d = %lf\n", x1, exp2, ldexp(x1, exp2)); printf("%.2lf * 2^%d = %lf\n", x2, exp1, ldexp(x2, exp1)); printf("%.2lf * 2^%d = %lf\n", x2, exp2, ldexp(x2, exp2)); return 0;}


0.50 * 2^2 = 2.000000 0.50 * 2^3 = 4.000000 2.30 * 2^2 = 9.210340 2.30 * 2^3 = 18.420681

Further Information:Section 13.6.43, “frexp” on page 363Section 13.6.84, “modf” on page 429



13.6.68 ldiv

Syntax: #include <stdlib.h>ldiv_tldiv(long int numer, long int denom);

Description: ldiv calculates the quotient and remainder for the division of the numerator numer by the denominator denom. The sign of the quotient is the same as that of the mathematical quotient. Its absolute value is the largest integer that is less than the absolute value of the mathematical quotient.

ldiv is similar to the div function except that the arguments and the members of the returned structure ldiv_t are all of type long int.

Diagnostics: ldiv returns a structure of type ldiv_t containing the quotient quot and the remainder rem.If denom is 0, the function returns {0,0} and errno is set to ERANGE.If denom is -1 and numer is INT_MIN, the function returns {0,0} and errno is set to EDOM.

Example 194. Function ldiv


int main(void){ long x = 354650, y = 200; ldiv_t lres;

lres = ldiv(x, y); printf("x/y = %ld/%ld = %ld\n", x, y, lres.quot); printf("quotient = %ld and remainder = %ld\n", lres.quot, lres.rem); return 0;}


x/y = 354650/200 = 1773 quotient = 1773 and remainder = 50

Further Information:Section 13.6.23, “div” on page 329



13.6.69 llabs

Syntax: #include <stdlib.h>long long intllabs(long long int val);

Description: The function llabs returns the absolute value of its long long argument.

Diagnostics: llabs returns the absolute value of its long long integer argument. There are no error returns.

Example 195. Function llabs


int main(void){ long long int l; long long int value;

value = -9223372036854775ll; l = llabs(value); printf("Absolute value of %lld is %2ld\n", value, l); return 0;}


Absolute value of -9223372036854775 is 9223372036854775

Further Information:Section 13.6.3, “abs” on page 307Section 13.6.26, “fabs” on page 333Section 13.6.66, “labs” on page 404



13.6.70 lltoa

Syntax: #include <stdlib.h>char *lltoa(long long int value, char * nptr, int base);

Description: The function lltoa converts its long long argument value into a string. The parameter base determines the numeric base of the conversion, e.g. 2 for binary numbers or 16 for hexadecimal numbers. Valid bases are 2 to 36. The result is stored in the argument nptr as well as in the return value of the function.

Diagnostics: If the argument string is NULL, the resulting string is NULL. If base is smaller than 2 or greater than 36, the result is the empty string.

Example 196. Function lltoa


int main(void){ char *l; long long int value; int base; char string[64];

value = 92147483647LL; base = 16; l = lltoa(value, string, base); printf("Long Long integer value %lld converted by lltoa to %s\n" "Numeric base of conversion: %d (decimal)\n", value, string, base); return 0;}


Long Long integer value 92147483647 converted by lltoa to 15746b03ff Numeric base of conversion: 16 (decimal)

Further Information:Section 13.6.12, “atol” on page 317Section 13.6.65, “itoa” on page 403Section 13.6.76, “ltoa” on page 417



13.6.71 localeconv

Syntax: #include <locale.h>struct lconv *localeconv(void);

Description: localeconv obtains detailed information on specific local settings regarding numeric and currency formatting.

The components of the struct lconv and their descriptions are as follows:

Component Description

char *decimal_point Decimal point for non-monetary quantities.

char *thousands_sep Character used to separate groups of digits to the left of the decimal point character in formatted non-monetary quantities.

char *grouping String whose elements indicate the size of each group of digits in formatted non-monetary quantities. See following page for details.

char *int_curr_symbol International currency symbol for the current locale. The first three characters specify the alphabetic international currency symbol as defined in the “ISO 4217 Codes for the Representation of Currency and Funds”. The fourth character (immediately after the null character) is used to separate the international currency symbol from the monetary quantity.

char *currency_symbol Local currency symbol for the current locale.

char *mon_decimal_point Decimal point character for monetary quantities.

char *mon_thousands_sep Separator for groups of digits to the left of the decimal place in monetary quantities.

char *mon_grouping String that indicates the size of each group of digits in formatted monetary quantities. See following page for details.

char *positive_sign String used to indicate a non-negative value monetary quantity.

char *negative_sign String used to indicate a negative value monetary quantity.

char int_frac_digits Number of digits to the right of the decimal point in internationally formatted monetary quantities.

char frac_digits Number of digits to the right of the decimal point in locally formatted monetary quantities.

char p_cs_precedes Set to 1 if the currency symbol precedes the value for a non-negative formatted monetary quantity. Set to 0 if the symbol follows the value.

char p_sep_by_space Set to 1 if the currency symbol is separated by a space from the value of a non-negative formatted monetary quantity. Set to 0 if there is no space separation.

char n_cs_precedes Set to 1 if the currency symbol precedes the value for a negative formatted monetary quantity. Set to 0 if the symbol succeeds the value.

char n_sep_by_space Set to 1 if the currency symbol is separated by a space from the value of a negative formatted monetary quantity. Set to 0 if there is no space separation.

char p_sign_posn Position of the positive sign in non-negative formatted monetary quantities. See following page for details.

char n_sign_posn Position of the positive sign in negative formatted monetary quantities.See following page for details.



The char * members of the struct are pointers to strings. Any of these (other than char *decimal_point) can point to “” which means that the value is of zero length or not available.

The char members of struct are non-negative numbers. If any of these numbers equals CHAR_MAX, the corresponding value is not available in the current locale.

The elements of grouping and mon_grouping are interpreted according to the following table:

The values of p_sign_posn and n_sign_posn are interpreted according to the following rules:

Diagnostics: localeconv returns a pointer to the filled-in object of type struct lconv.

Note: The returned pointer refers to a structure which has been statically allocated. Therefore, a reentrant program must not use localeconv if it uses setlocale.

Example 197. Function localeconv

#include <locale.h>#include <stdlib.h>#include <stdio.h>

int main(void){ struct lconv *locale; locale = localeconv();

printf("Decimal point: %s\n",locale->decimal_point); return 0;}

Elements Description

CHAR_MAX No further grouping is performed.

0 The previous element is to be repeated and used for the remaining digits.

n The integer value n is the number of digits that comprises the current group. The next element is examined to determine the size of the next group of digits to the left of the current group.

Value Description

0 Parentheses surround the quantity and currency symbol.

1 Sign string immediately precedes the quantity and currency symbol.

2 Sign string immediately follows the quantity and currency symbol.

3 Sign string immediately precedes the currency symbol only.

4 Sign string immediately follows the currency symbol only.




Decimal point: .

Further Information:Section 13.6.102, “setlocale” on page 457Section 13.6.114, “strcoll” on page 474Section 13.6.118, “strftime” on page 479Section 13.6.133, “strxfrm” on page 503



13.6.72 localtime

Syntax: #include <time.h>struct tm *localtime(const time_t *timer);

Description: localtime converts the calendar time timer, stored as time_t, into a structure of type tm. The time information stored in the structure is expressed as local time. The long value timer represents the seconds elapsed since midnight (00:00:00), Jan 1st 1970, Universal Coordinated Time (UTC). Note that UTC was formerly known as Greenwich Mean Time (GMT). This value is obtained from the time function.

Diagnostics: localtime returns a pointer to a tm structure containing the time information. If the value in timer is a date before midnight, December 31, 1899, the function returns NULL.

Note: localtime uses a single statically allocated tm structure for the conversion. Thus, each call to the routine destroys the result of the previous call. A reentrant program must not use localtime.

Example 198. Function localtime

#include <stdlib.h>#include <stdio.h>#include <time.h>

struct tm *today;time_t aclock;

int main(void){ time(&aclock); /* get time in seconds */ today = localtime(&aclock); /* convert to *struct tm */ printf("Current date and time: %s\n", asctime(today)); return 0;}


Current date and time: Tue Feb 5 13:10:31 2002

Further Information:Section 13.4.15, “Header File time.h” on page 298Section 13.6.5, “asctime” on page 309Section 13.6.21, “ctime” on page 327Section 13.6.53, “gmtime” on page 382Section 13.6.137, “time” on page 508



13.6.73 log

Syntax: #include <math.h>doublelog(double x);

Description: log computes the logarithm of x to base e.

Diagnostics: log returns a domain error (0.0) and sets errno to EDOM if the argument is negative; log returns a range error (0.0) and sets errno to ERANGE if the argument is zero.

Example 199. Function log


int main(void){ double x = .5, y = 10;

printf("The natural logarithm of %.2lf is %lf\n", x, log(x)); printf("log(%.0lf) = %.8lf\n", y, log(y)); return 0;}


The natural logarithm of 0.50 is -0.693147 log(10) = 2.30258509

Further Information:Section 13.6.25, “exp” on page 332Section 13.6.74, “log10” on page 414Section 13.6.86, “pow” on page 431



13.6.74 log10

Syntax: #include <math.h>doublelog10(double x);

Description: log10 computes the logarithm of x to base 10.

Diagnostics: log10 returns a domain error (0.0) and sets errno to EDOM if the argument is negative; log10 returns a range error (0.0) and sets errno to ERANGE if the argument is zero.

Example 200. Function log10



printf("The logarithm (base 10) of %.2lf is %lf\n", x, log10(x)); printf("log10(%.0lf) = %lf\n", y, log10(y)); return 0;}


The logarithm (base 10) of 0.50 is -0.301030 log10(10) = 1.000000

Further Information:Section 13.6.25, “exp” on page 332Section 13.6.73, “log” on page 413Section 13.6.86, “pow” on page 431



13.6.75 longjmp

Syntax: #include <setjmp.h>voidlongjmp(jmp_buf env, int value );

Description: longjmp restores the stack environment and execution locale saved by the most recent call to the setjmp function in env. The setjmp and longjmp functions provide a way to execute a non-local goto and are typically used to pass execution control to error handling or recovery code in a previously called routine without using the normal call and return conventions.

A call to setjmp saves the current register environment in env. A subsequent call to longjmp restores the saved environment and returns control to the point immediately following the corresponding setjmp call. Execution resumes as if value had just been returned by the setjmp call. The values (except register variables), which are accessible to the routine receiving control, contain the values they had when longjmp was called. The values of the register variables are the same as they were at the moment of the call to setjmp.

Diagnostics: longjmp restores the environment. Program execution continues as if the corresponding call to setjmp had just returned the value specified by value. If the value value is zero, 1 is returned.

Note: longjmp must be called before the function which calls setjmp returns. Unpredictable program behavior results if this is not performed.

Example 201. Function longjmp

#include <stdio.h>#include <setjmp.h>

jmp_buf env;

void make_jump(void){ printf("About to make a long jump\n"); longjmp(env, 24);}

int main(void){ int return_val = 293; if((return_val = setjmp(env)) == 0) { printf("After the environment was stored: %d\n", return_val); make_jump(); printf("After the sub-routine: %d\n", return_val); } else { printf("After the long jump: %d\n", return_val); } return 0;



}


After the environment was stored: 0 About to make a long jump After the long jump: 24

Further Information:Section 13.6.101, “setjmp” on page 455



13.6.76 ltoa

Syntax: #include <stdlib.h>char *ltoa(long int value, char * nptr, int base);

Description: The function ltoa converts its long argument value into a string. The parameter base determines the numeric base of the conversion, e.g. 2 for binary numbers or 16 for hexadecimal numbers. Valid bases are 2 to 36. The result is stored in the argument nptr as well as in the return value of the function.

Diagnostics: If the argument string is NULL, the resulting string is NULL. If base is smaller than 2 or greater than 36, the result is the empty string.

Example 202. Function ltoa

#include <stdlib.h>#include <stdio.h> int main(void){ char *l; long int value; int base; char string[64];

value = 2147483647; base = 16; l = ltoa(value, string, base); printf("Integer value %ld converted by ltoa to %s\n" "Numeric base of conversion: %d (decimal)\n", value, string, base); return 0;}


Integer value 2147483647 converted by ltoa to 7fffffff Numeric base of conversion: 16 (decimal)

Further Information:Section 13.6.12, “atol” on page 317Section 13.6.65, “itoa” on page 403Section 13.6.70, “lltoa” on page 408



13.6.77 malloc

Syntax: #include <stdlib.h>void *malloc(size_t size);

Description: malloc allocates memory of size size bytes. The block may be larger because of memory required for alignment and maintenance information. If size is 0, malloc allocates a zero-length item in the heap and returns a valid pointer to that item.

malloc accepts settings of the interface functions _sblockcontrbrk and _blocksizebrk.If the return value of _sblockcontrbrk is zero, _sbrk-blocks can be concatenated and will never be returned to the system during run-time.If the return value of _sblockcontrbrk is not zero, the memory block can be returned to the system memory.

_blocksizebrk is used to round the block size for _sbrk.

Diagnostics: malloc returns a void pointer to the start of the allocated memory if enough memory is available; otherwise NULL is returned.

Note: malloc does not initialize allocated memory. malloc needs the interface function _sbrk.

Check always the value returned by malloc even if the amount of memory requested is small. If malloc returns NULL, check if the interface function _sbrk returns enough memory.

Example 203. Function malloc


#define MAX_PATH_LENGTH 60

int main(void){ char *path_str; path_str = malloc(MAX_PATH_LENGTH); if(path_str == NULL) { printf("Not enough memory\n"); } else { printf("Memory successfully allocated\n"); free(path_str); } return 0;}



If the requested memory is available, the program above produces the following output:

Memory successfully allocated

Further Information:Section 13.6.15, “calloc” on page 321Section 13.6.41, “free” on page 360Section 13.6.95, “realloc” on page 445Section 14.4.9, “_sbrk” on page 621Section 14.4.1, “_blocksizebrk” on page 613Section 14.4.8, “_sblockcontrbrk” on page 620



13.6.78 memchr

Syntax: #include <string.h>void *memchr(const void *s, int c, size_t n);

Description: memchr searches for the first occurrence of c within the first n bytes of s. The function returns when c is found or the first n bytes have been checked.

Diagnostics: If c is found, then memchr returns a pointer to the first location of c in s, otherwise NULL is returned.

Example 204. Function memchr

#include <string.h>#include <stdio.h>

int main(void){ int ch = ’w’; char string[] = "Humpty Dumpty sat on a wall"; char *ptr_str;

printf("Given string: \t%s\n", string); printf("Looking for: %c\n", ch); ptr_str = (char*) memchr(string, ch, sizeof(string)); if(ptr_str != NULL) { printf("The character %c was found at position %d\n", ch, ptr_str-string+1); } else { printf("The character %c could not be found in the given string\n", ch); } return 0;}


Given string: Humpty Dumpty sat on a wall Looking for: w The character w was found at position 24

Further Information:Section 13.6.79, “memcmp” on page 421Section 13.6.80, “memcpy” on page 423Section 13.6.82, “memset” on page 425Section 13.6.112, “strchr” on page 471



13.6.79 memcmp

Syntax: #include <string.h>intmemcmp(const void *s1, const void *s2, size_t n);

Description: memcmp compares the first n bytes of s1 with the first n bytes of s2 and returns a value indicating their relationship.

Diagnostics: memcmp returns a value indicating the relationship of s1 and s2. The return value may have one of the following values:

Example 205. Function memcmp


int main(void){ char string1[] = "Humpty Dumpty sat on a wall"; char string2[] = "Humpty Dumpty sat on a wall"; int result, count = 25;

printf("Comparing the first %d characters of two strings\n", count); printf("\t%s\n", string1); printf("\t%s\n\n", string2); result = memcmp(string1, string2, (size_t)count); if (result < 0) { printf("The first %d characters of the first string are less " "than of the second\n", count); } else { if (result == 0) { printf("The strings are equal\n"); } else { printf("The first %d characters of the first string are " "greater than of the second\n", count); } } return 0;}

Value Description

< 0 s1 is less than s2

= 0 s1 is identical to s2

> 0 s1 is greater than s2




Comparing the first 25 characters of two strings Humpty Dumpty sat on a wall Humpty Dumpty sat on a wall

The strings are equal

Further Information:Section 13.6.78, “memchr” on page 420Section 13.6.80, “memcpy” on page 423Section 13.6.82, “memset” on page 425Section 13.6.112, “strchr” on page 471Section 13.6.113, “strcmp” on page 472



13.6.80 memcpy

Syntax: #include <string.h>void *memcpy(void *s1, const void *s2, size_t n);

Description: memcpy copies n bytes from the buffer pointed to by s2 to the buffer pointed to by s1.

Diagnostics: memcpy returns the value of s1.

Note: If the source buffer s2 and the destination buffer s1 overlap, the function does not ensure that the original source bytes in the overlapping region are copied before being overwritten. memmove should be used to handle overlapping regions.

Example 206. Function memcpy


int main(void){ char string1[40] = "Humpty Dumpty sat on a wall"; char string2[15] = "was a big egg";

printf("Copying a string into another string\n"); printf("Source: %s\n", string1); printf("string to be copied: %s\n", string2); memcpy(string1 + 14, string2, 13); printf("Result: %s\n", string1); return 0;}


Copying a string into another string Source: Humpty Dumpty sat on a wall string to be copied: was a big egg Result: Humpty Dumpty was a big egg

Further Information:Section 13.6.78, “memchr” on page 420Section 13.6.80, “memcpy” on page 423Section 13.6.82, “memset” on page 425Section 13.6.115, “strcpy” on page 475Section 13.6.122, “strncpy” on page 485



13.6.81 memmove

Syntax: #include <string.h>void *memmove(void *s1, const void *s2, size_t n);

Description: memmove moves n characters from the source buffer s2 to the destination buffer s1. If some regions of the two object areas overlap, memmove ensures that the original source bytes in the overlapping area are copied before being overwritten.

Diagnostics: memmove returns the value of the destination object s1.

Example 207. Function memmove


int main(void){ char string1[40] = "Humpty Dumpty sat on a wall"; printf("Copying a string into another string\n"); printf("Source: %s\n", string1); memmove(string1 + 14, string1, 30); printf("Result: %s\n", string1); return 0;}


Copying a string into another string Source: Humpty Dumpty sat on a wall Result: Humpty Dumpty Humpty Dumpty sat on a wall

Further Information:Section 13.6.80, “memcpy” on page 423Section 13.6.82, “memset” on page 425Section 13.6.115, “strcpy” on page 475Section 13.6.122, “strncpy” on page 485



13.6.82 memset

Syntax: #include <string.h>void *memset(void *s, int c, size_t n);

Description: memset sets the first n bytes of the destination pointed to by s to the character c.

Diagnostics: memset returns the value of s.

Example 208. Function memset


int main(void){ char string1[40] = "Humpty Dumpty sat on a wall"; int count = 6; int ch = ’#’; printf("Setting the first %d characters to %c\n", count, ch); printf("Source: \t%s\n", string1); memset(string1, ch, (size_t)count); printf("Result: \t%s\n", string1); return 0;}


Setting the first 6 characters to # Source: Humpty Dumpty sat on a wall Result: ###### Dumpty sat on a wall

Further Information:Section 13.6.78, “memchr” on page 420Section 13.6.79, “memcmp” on page 421Section 13.6.80, “memcpy” on page 423Section 13.6.81, “memmove” on page 424



13.6.83 mktime

Syntax: #include <string.h>time_tmktime(struct tm *timeptr);

Description: mktime converts the supplied time structure tm pointed to by timeptr into a fully defined structure with normalized values. Then it converts this structure to a time_t calendar time value. The same encoding is used in this function and in the time function. The structure tm is defined in time.h as follows:

struct tm { int tm_sec; /* seconds after the minute [0,59] */ int tm_min; /* minutes after the hour [0,59] */ int tm_hour; /* hours after midnight [0,23] */ int tm_mday; /* day of the month [1,31] */ int tm_mon; /* months since January [0,11] */ int tm_year; /* years since 1900 [0,11] */ int tm_wday; /* days since Sunday [0,6] */ int tm_yday; /* days since January 1 [0,365] */ int tm_isdst;/* Daylight Savings Time flag */};

The original values of the fields tm_sec, tm_min, tm_hour, tm_mday, and tm_mon are not restricted to the ranges described in struct tm.The original values of the components tm_wday and tm_yday are ignored. If the original value of tm_isdst is negative, this field is computed by the system interface function _isdaylight. If the original value is 0, then Daylight Savings Time is considered not to be in effect. If the value is positive then Daylight Savings Time is considered to be in effect.

Note: gmtime and localtime use a single statically allocated buffer for their conversions. If this buffer is supplied to mktime, the previous contents will be destroyed.

Diagnostics: mktime returns the converted calendar time, encoded as a value of type time_t. If the calendar time cannot be represented, mktime returns the value –1 cast to type time_t. I.e., if the value of tm_year is outside the range of 70...137, a year before 1970 or after 2037, mktime returns the value –1.

Example 209. Function mktime


static char *week_day[] ={ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday",



"Saturday"};

int main(void){ struct tm birth; int c; time_t result; printf("What day of the week were you born?\n" "Enter your birth day (dd.mm.yyyy): "); scanf("%2d.%2d.%4d", &birth.tm_mday, &birth.tm_mon, &birth.tm_year); if (birth.tm_year < 1970 || birth.tm_year > 2038) { printf("Specified year out of range,c 1970 <= %d <= 2038\n", birth.tm_year); } else { birth.tm_year -= 1900; birth.tm_mon -= 1; birth.tm_hour = 12; birth.tm_min = 0; birth.tm_sec = 0; birth.tm_isdst = 0; if((result = mktime(&birth)) != (time_t) - 1) { printf("\n\tYou were born on a %s\n", week_day[birth.tm_wday]); } else { printf("\n\tmktime failed\n"); } }}


What day of the week were you born? Enter your birth day (dd.mm.yyyy):


01.01.2002


You were born on a Tuesday

Further Information:Section 13.2.5, “System Interface Functions” on page 276Section 13.4.15, “Header File time.h” on page 298Section 13.6.5, “asctime” on page 309Section 13.6.18, “clock” on page 324Section 13.6.22, “difftime” on page 328



Section 13.6.53, “gmtime” on page 382Section 13.6.72, “localtime” on page 412Section 13.6.118, “strftime” on page 479Section 13.6.137, “time” on page 508



13.6.84 modf

Syntax: #include <math.h>doublemodf(double x, double *iptr);

Description: modf breaks the argument x into integral and fractional parts, each of which has the same sign as x. The integral part is stored as a double in the object pointed to by iptr. The signed fractional part is returned.

Diagnostics: modf returns the signed fractional part of x.

Example 210. Function modf


int main(void){ double x1 = -20.3, x2 = 20.3, integral; printf("The fraction of %+.1lf is %+.1lf\n", x1, modf(x1, &integral)); printf("The integral value is %+.1lf\n", integral); printf("The fraction of %+.1lf is %+.1lf\n", x2, modf(x2, &integral)); printf("The integral value is %+.1lf\n", integral); return 0;}


The fraction of -20.3 is -0.3 The integral value is -20.0 The fraction of +20.3 is +0.3 The integral value is +20.0

Further Information:Section 13.6.43, “frexp” on page 363 Section 13.6.67, “ldexp” on page 405



13.6.85 perror

Syntax: #include <stdio.h>voidperror(const char *s);

Description: perror prints an error message corresponding to the error number stored in errno to stderr.

The s argument is printed first followed by a colon; then the system error message for the last library call that produced the error is printed and finally a newline character is issued.

Note: To produce accurate results, perror should be called immediately after a library routine returns with an error. If this is not done, the value of errno may be overwritten by subsequent calls.

Diagnostics: perror returns no value.

Example 211. Function perror

#include <stdio.h>

int main(void){ FILE *f = NULL;

printf("Creating an error by opening a non-existent read-only file.\n"); f = fopen("exist.non", "r"); if(f == NULL || ferror(f)) { perror("ERROR"); clearerr(stdin); } else { printf("No error!\n"); fclose(f); } return 0;}

If the file exist.non does not exist, the program above produces the following output:

Creating an error by opening a non-existent read-only file. ERROR: Error 2

Further Information:Section 13.6.17, “clearerr” on page 323Section 13.6.29, “ferror” on page 337Section 13.6.117, “strerror” on page 478



13.6.86 pow

Syntax: #include <math.h>doublepow(double x, double y);

Description: pow computes x raised to the power of y.

Diagnostics: pow returns the value of xy if no error occurs; otherwise NAN is returned and errno is set to EDOM if both values are 0.0, x is negative and y is not an integer, or x is 0.0 and y is negative. If an overflow results, errno is set to ERANGE and HUGE_VAL is returned.

Note: pow does not recognize integral floating point values greater than 264 such as 1.0E100.

Example 212. Function pow


int main(void){ double x = 2, y = 5;

printf("%.1lf to the power of %.1lf is %.1lf\n", x, y, pow(x, y)); return 0;}


2.0 to the power of 5.0 is 32.0

Further Information:Section 13.6.25, “exp” on page 332Section 13.6.73, “log” on page 413Section 13.6.74, “log10” on page 414Section 13.6.108, “sqrt” on page 466



13.6.87 pow10

Syntax: #include <math.h>doublepow10(int i);

Description: pow10 computes 10 raised to the power of i.

Diagnostics: pow10 returns the value of 10i. 0.0 is returned if i is less than -308.If an overflow results, errno is set to ERANGE and HUGE_VAL is returned.

Note: pow10 does not recognize integral floating point values greater than 10308.

Example 213. Function pow10


int main(void){ double x = 10, y = 12; printf("%.1lf to the power of %.1lf is %.1lf\n", x, y, pow10(x, y)); return 0;}


10.0 to the power of 12.0 is 1000000000000.0

Further Information:Section 13.6.25, “exp” on page 332Section 13.6.73, “log” on page 413Section 13.6.74, “log10” on page 414Section 13.6.108, “sqrt” on page 466



13.6.88 printf

Syntax: #include <stdio.h>intprintf(const char *format, ... );

Description: printf prints a series of characters and values to the standard output stdout. The argument format specifies which format is used to print characters and values. format consists of ordinary characters, escape sequences, and format specifications. printf accepts normalized format as well as denormalized format and the values infinity and nan.

For more detailed information on format refer to “fprintf” on page 350.

Diagnostics: printf returns the number of characters written. If an output error occurs, a negative value is returned.

The variable errno is not modified by printf unless the system interface function write sets errno. The low level I/O function write is called by printf to omit output.

Example 214. Function printf


int main(void){ FILE *f; int line_num; char data[MAX + 1];

if((f = fopen("poem.txt", "r")) != NULL) { printf("Reading from the file ’poem.txt’\n" "Output to the screen the lines with their numbers.\n\n"); line_num = 0; while(fgets(data, MAX, f) != NULL) { line_num++; printf("%4d. %s", line_num, data); } fclose(f); } return 0;}


Jack and Jill

Jack and Jill went up the hill To fetch a pail of water; Jack fell down and broke his crown,



And Jill came tumbling after.


Reading from the file ’poem.txt’ Output to the screen the lines with their numbers.


Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.99, “scanf” on page 451Section 13.6.107, “sprintf” on page 464Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.6.89 putc

Syntax: #include <stdio.h>intputc(int c, FILE * stream);

Description: putc writes a single character c to the file stream. Any integer can be passed to putc, but only the lower 8 bits are written.

Diagnostics: putc returns the character itself if no error occurs; otherwise putc returns EOF.

The variable errno is not modified by putc unless the system interface function write sets errno. The low level I/O function write is called by putc to emit output.

Example 215. Function putc


int main(void){ int i, c;

printf("Type up to %d characters:\n", BUFF_SIZ); for(i = 0; (i < BUFF_SIZ) && (( c = getc( stdin)) !=’\n’); i++) { putc(c, stdout); } putc( ’\n’, stdout); return 0;}




123456789ABCDEF 1234


123456789ABCDEF 1234



Further Information:Section 13.6.38, “fputc” on page 354Section 13.6.39, “fputs” on page 356Section 13.6.49, “getc” on page 377Section 13.6.50, “getchar” on page 379Section 13.6.90, “putchar” on page 437Section 13.6.91, “puts” on page 439



13.6.90 putchar

Syntax: #include <stdio.h>intputchar(int c);

Description: putchar prints the character specified by c to the standard output stdout. putchar is equivalent to putc(c,stdout).

Diagnostics: putchar returns the character itself if no error occurs; otherwise putchar returns EOF.

The variable errno is not modified by putchar unless the system interface function write sets errno. The low level I/O function write is called by putchar to omit output.

Example 216. Function putchar


int main(void){ int i, c; printf("Type up to %d characters:\n", BUFF_SIZ); for(i = 0; (i < BUFF_SIZ) && ((c = getchar()) !=’\n’); i++) { putchar(c); } putchar(’\n’); return 0;}




123456789ABCDEF 1234


123456789ABCDEF 1234



Further Information:Section 13.6.38, “fputc” on page 354Section 13.6.39, “fputs” on page 356Section 13.6.49, “getc” on page 377Section 13.6.50, “getchar” on page 379Section 13.6.89, “putc” on page 435Section 13.6.91, “puts” on page 439



13.6.91 puts

Syntax: #include <stdio.h>intputs(const char *s);

Description: puts writes the character string s to the standard output stream stdout without the ‘\0’ character. puts appends a newline character \n character at the end of the output stream.

Diagnostics: puts returns zero if no error occurs; otherwise a non-zero value is returned. The variable errno is not modified by puts unless the system interface function write sets errno. The low level I/O function write is called by puts to omit output.

Example 217. Function puts

#include <stdio.h>#define BUFFER 20

int main(void){ char data[BUFFER + 1];

printf("Input a string of max. %d characters:\n", BUFFER); fgets(data, BUFFER + 1, stdin); puts("\nNow from data: "); puts(data); return 0;}


Input a string of max. 20 characters:


123456789ABCDEF 1234


123456789ABCDEF 1234

Further Information:Section 13.6.39, “fputs” on page 356Section 13.6.33, “fgets” on page 343Section 13.6.52, “gets” on page 381Section 13.6.89, “putc” on page 435



13.6.92 qsort

Syntax: #include <stdlib.h>voidqsort(void *base,

size_t nmemb,size_t size,int (*compar)(const void *elem1,

const void *elem2));

Description: qsort sorts an array of nmemb elements and of size size bytes. The argument base is a pointer to the base of the array to be sorted. This array will be overwritten with the sorted elements by qsort.

The argument compar is a pointer to the user-supplied routine that compares two array elements and returns one of the following values specifying their relationship:

qsort calls the compar routine one or more times during the sort, passing pointers to two array elements on each call. The array is sorted in increasing order, as defined by the comparison function.

Diagnostics: qsort returns no value.

Example 218. Function qsort


char *to_sort[] ={ "there", "was", "an", "old", "woman", "who", "lived", "in", "a", "shoe"};

int compare(char **first, char **second){

Value Meaning

< 0 elem1 is less than elem2

= 0 elem1 is equivalent to elem2

> 0 elem1 is greater than elem2



return(strcmp(*first, *second));}

int main(void){ printf("Before the sort:\n\t%s %s %s %s %s\n", to_sort[0], to_sort[1], to_sort[2], to_sort[3], to_sort[4]); printf("\t%s %s %s %s %s\n", to_sort[5], to_sort[6], to_sort[7], to_sort[8], to_sort[9]); qsort(to_sort, sizeof(to_sort) / sizeof(char *), sizeof(char *), compare); printf("After the sort:\n\t%s %s %s %s %s\n", to_sort[0], to_sort[1], to_sort[2], to_sort[3], to_sort[4]); printf("\t%s %s %s %s %s\n", to_sort[5], to_sort[6], to_sort[7], to_sort[8], to_sort[9]); return 0;}


Before the sort: there was an old woman who lived in a shoe After the sort: a an in lived old shoe there was who woman

Further Information:Section 13.6.14, “bsearch” on page 319



13.6.93 raise

Syntax: #include <signal.h>intraise(int sig);

Description: raise sends the signal sig to the executing program. If a signal-handling routine for sig has been installed by a previous call to signal, raise causes that routine to be executed. If no handler routine has been installed, the default action, which is listed below, is taken.

The signal value sig may have one of the following values:

Note: There may be no control following the function call if the action for that condition is to terminate the program or to transfer control using the longjmp function.

Diagnostics: raise returns zero if raise is successful; otherwise a non-zero value is returned.

Value Meaning

SIGABRT Abnormal termination, such as caused by abort.

SIGFPE Erroneous arithmetic operation, such as zero division, or an operation resulting in overflow.

SIGILL Detection of an invalid function image such as an illegal instruction.

SIGINT Receipt of an interactive attention signal.

SIGSEGV Invalid access or storage access.

SIGTERM Termination request sent to the program.



Example 219. Function raise

#include <stdio.h>#include <signal.h>

void sigfunc(int sig){ printf("Error: Division by 0\n");}

int main(void){ int a, b;

signal(SIGFPE, sigfunc); printf("Number : "); scanf("%d", &a); printf("divide by : "); scanf("%d", &b);

if(b == 0) { raise(SIGFPE); } else { printf("Result: %d\n",a/b); }

return 0;}

The program above produces the following output (the boldfaced text being typed in by the user):

Number : 100 divide by : 0 Error: Division by 0

Further Information:Section 13.6.104, “signal” on page 460



13.6.94 rand

Syntax: #include <stdlib.h>intrand(void);

Description: rand yields a pseudo-random integer number in the range 0 to RAND_MAX (32767).

Diagnostics: rand returns a pseudo-random integer. There is no error return.

Note: rand uses a statically allocated object to calculate the random value and to keep the last random value. Therefore, if an application program is reentrant, it must not use rand.

Example 220. Function rand


int main(void){ int i; srand(NULL); for(i = 0; i < 5; i++) { printf(" %d\t", rand()); } return 0;}


6924 24032 10555 21390 7145

Further Information:Section 13.6.109, “srand” on page 467



13.6.95 realloc

Syntax: #include <stdlib.h>void *realloc(void *ptr, size_t size);

Description: realloc changes the size of a previously allocated memory block. The ptr argument points to the beginning of the memory block. If ptr is NULL, realloc allocates a new block of size bytes in the same way that malloc does.

If size is zero, the free function is called to release the memory pointed to by prt. Otherwise realloc re-allocates memory by:

• shrinking the allocated size of the allocated memory block ptr when size is sufficiently smaller than the size of ptr

• extending the allocated size of the allocated memory block ptr if there is a large enough block of un-allocated memory immediately following ptr

• allocating a new block and copying the contents of ptr to the new block.

Note: Because a new block can be allocated, no other pointers should point into the memory of ptr. These pointers would point to free memory, with potentially disastrous results, when a new block is allocated.

realloc needs the interface function _sbrk.

Diagnostics: realloc returns a void pointer to the re-allocated and possibly moved memory block.



Example 221. Function realloc

#include <stdlib.h>#include <stdio.h>#define MAX_PATH_LENGTH 60

int main(void){ char *path_str; path_str = malloc(MAX_PATH_LENGTH); if(path_str == NULL) { printf("Not enough memory\n"); } else { printf("Memory successfully allocated.\n"); } path_str = realloc(path_str, 85); if(path_str == NULL) { printf("Not enough memory to re-allocate\n"); } else { printf("Memory successfully re-allocated.\n"); } free( path_str); return 0;}

If the memory operations can be performed, the program above produces the following output:

Memory successfully allocated. Memory successfully re-allocated.

Further Information:Section 13.6.15, “calloc” on page 321Section 13.6.41, “free” on page 360Section 13.6.77, “malloc” on page 418Section 14.4.9, “_sbrk” on page 621



13.6.96 remove

This function is also a system interface function and therefore described in Section 14.3.3, “remove” on page 608.



13.6.97 Function rename

This function is also a system interface function and therefore described in Section 14.3.4, “rename” on page 609.



13.6.98 rewind

Syntax: #include <stdio.h>voidrewind(FILE *stream);

Description: rewind repositions the file pointer to the beginning of the file stream. A call to rewind is equivalent to

fseek( stream, 0L, SEEK_SET);

except that rewind clears the error indicator for the stream which fseek does not. fseek returns a value that indicates whether the pointer was successfully moved. rewind does not return this value.

Diagnostics: rewind has no return value.

Example 222. Function rewind

#include <stdio.h>#define MAX 85#define READ_LINE 3

int main(void){ FILE *f; int i; char data[MAX + 1];

if(f = fopen("poem.txt", "r")) { printf("Reading %d lines of file ’poem.txt’.\n\n", READ_LINE); i = 1; while((fgets(data, MAX, f) != NULL) && (i++ <=READ_LINE)) { printf("\t %s", data); } printf("\nReposition file pointer to " "the beginning and read all:\n\n"); rewind(f); while(fgets(data, MAX, f) != NULL) { printf("\t %s", data); } fclose( f); } return 0;}




Jack and Jill



Reading 3 lines of file poem.txt.

Jack and Jill Jack and Jill went up the hill

Reposition file pointer to the beginning and read all:

Jack and Jill Jack and Jill went up the hill To fetch a pail of water; Jack fell down and broke his crown, And Jill came tumbling after.

Further Information:Section 13.6.36, “fopen” on page 347Section 13.6.17, “clearerr” on page 323



13.6.99 scanf

Syntax: #include <stdio.h>intscanf(const char *format,...);

Description: scanf reads input from stdin using the format conditions format. scanf is equivalent to fscanf(stdin). Input data is defined as a string of consecutive non-whitespace characters. Whitespace characters are skipped when an input function is searching for an input field which matches the specification it is searching for. If the specification includes a [, c, or n specifier, whitespaces are not skipped.

The format control string format, a multibyte sequence, determines the interpretation of input sequences as they are read. It may contain:




If there are insufficient arguments for the format control string, the behavior of the function is undefined. If the format control string is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. Therefore, the number of conversion specifications and the number of arguments must be equal. In addition, an argument’s type must match its corresponding conversion specification.

Details about the contents of the format string are described in Section 13.6.44, “fscanf” on page 364.

Diagnostics: scanf returns the number of successful assignments from input sequences to arguments. The number returned may be less than the given number of arguments in two cases:







Example 223. Function scanf

#include <stdio.h>

int main(void){ char c; unsigned ui; int i; float fl; char x[5], y[5];

int vars_read, ret_read; printf("Write the following string as input to be scanned:\n"); printf("\t21 34561.2 abcd367Z\n"); printf("Write the string now: "); ret_read = scanf("%c%u%2o%*2d%f%4s%4[0-9]%n", &c, &ui, &i, &fl, x, y, &vars_read); printf("\n%d characters were read by scanf.\n", vars_read); printf("The following %d values were assigned:\n", ret_read); printf("c = %c\nui = %u\ni = %o\nfl = %f\nx = %s\ny = %s\n", c, ui, i, fl, x, y); return 0;}


Write the following string as input to be scanned: 21 34561.2 abcd367Z Write the string now:

18 characters were read by scanf. The following 6 value were assigned: c = 2 ui = 1 i = 34 fl = 1.200000 x = abcd y = 367


Write the following string as input to be scanned: 21 34561.2 abcd367Z Write the string now:


21 34561.2 abcd367Z


18 characters were read by scanf. The following 6 values were assigned: c = 2 ui = 1 i = 34



fl = 1.200000 x = abcd y = 367

Further Information:Section 13.6.44, “fscanf” on page 364Section 13.6.88, “printf” on page 433Section 13.6.37, “fprintf” on page 350Section 13.6.110, “sscanf” on page 468Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.6.100 setbuf

Syntax: #include <stdio.h>voidsetbuf(FILE *stream, char *buf);

Description: setbuf controls buffering for stream. The stream argument must refer to a newly opened file, before it has been read from or written to. If the buf argument is NULL, the stream is completely unbuffered. If the buf argument is not NULL, the buffer must point to a character array of length BUFSIZ, where BUFSIZ is the buffer size as defined in stdio.h. Hence, all I/O will be fully buffered.

Diagnostics: setbuf has no return value.

Example 224. Function setbuf

#include <stdio.h>

int main(void){ char buffer[BUFSIZ]; FILE *f;

printf("Create a file to buffer it.\n"); if((f = fopen("EMPTY.TMP", "w+")) == NULL) { printf("The file EMPTY.TMP could not be created\n"); } else { printf("The file EMPTY.TMP was successfully created\n"); } setbuf(f, buffer); fclose(f); return 0;}


Create a file to buffer it. The file EMPTY.TMP was successfully created

Further Information:Section 13.6.27, “fclose” on page 334Section 13.6.30, “fflush” on page 338Section 13.6.36, “fopen” on page 347Section 13.6.103, “setvbuf” on page 458



13.6.101 setjmp

Syntax: #include <setjmp.h>intsetjmp(jmp_buf env);

Description: setjmp saves a register environment in its jmp_buf argument that can subsequently be restored using the longjmp function. Control is then returned from the longjmp call to the point just after the corresponding setjmp call. All variables, except register variables, accessible to the routine receiving control contain the values they had when longjmp was called. All registers except floating point registers contain the values they had when setjmp was called.

Note: Side effects that are left undone (allocated memory, opened files, etc.) must be satisfactorily handled by the user.

Diagnostics: setjmp returns 0 after saving the stack environment. If setjmp returns as a result of a longjmp call, it returns the value argument of longjmp. If the value argument of longjmp is 0, setjmp returns 1. There is no error return.

Example 225. Function setjmp

#include <stdio.h>#include <setjmp.h>

jmp_buf env;

make_jump(void){ printf("About to make a long jump\n"); longjmp( env, 24);}

int main( void){ int return_val = 293; if((return_val = setjmp(env)) == 0) { printf("After the environment was stored: %d\n", return_val); make_jump(); printf("After the sub-routine: %d\n", return_val); } else { printf("After the long jump: %d\n", return_val); } return 0;}


After the environment was stored: 0 About to make a long jump



After the long jump: 24

Further Information:Section 13.6.75, “longjmp” on page 415



13.6.102 setlocale

Syntax: #include <locale.h>char *setlocale(int category, const char *locale);

Description: setlocale selects a portion or the entirety of a program’s locale according to the category given by category and the locale specified by locale.

The argument locale refers to the locality (country and language) for which certain aspects of a program can be customized. locale is a string that specifies the name of the locale. If locale points to an empty string, the locale is an implementation defined native environment.

category uses the following macros:

Diagnostics: If the locale and category values given are valid, setlocale returns a pointer to the string associated with the specified category for the previous locale. If locale or category is invalid, setlocale returns a NULL pointer and the program’s current locale settings are not changed.

Further Information:Section 13.6.55, “isalpha” on page 384Section 13.6.71, “localeconv” on page 409Section 13.6.114, “strcoll” on page 474Section 13.6.118, “strftime” on page 479

Category Description

LC_ALL All categories listed below.

LC_COLLATE The strcoll and strxfrm functions.

LC_CTYPE Character-handling functions (except for isdigit and isxdigit, which are unaffected).

LC_MONETARY Monetary formatting information returned by the localeconv function.

LC_NUMERIC Decimal point character for the formatted output routines such as printf for the data conversion routines and for the non-monetary formatting information returned by the localeconv function.

LC_TIME strftime function.



13.6.103 setvbuf

Syntax: #include <stdio.h>intsetvbuf(FILE *stream, char *buf, int mode, size_t size);

Description: setvbuf controls stream buffering and buffer size for a stream pointed to by stream. stream must refer to a newly opened file that has not been read from or written to since it was opened.

A buffer of size size bytes is automatically allocated if the array pointed to by buf is NULL; otherwise the array to which buf points is used. The legal values for size are greater than 0 and less than 32,768.

The argument mode determines how the file stream will be buffered as follows:

Diagnostics: setvbuf returns zero if no error occurs; otherwise a non-zero value is returned if an illegal type or buffer size is specified.

Mode Meaning

_IOFBF Full buffering; buf is used as the buffer and size as its size. If buffer is NULL, an automatically allocated buffer size bytes long is used.

_IOLBF Output is line buffered; the buffer will be flushed when a newline character is written, when the buffer is full, or when input is requested.

_IONBF No buffering regardless of buf or size.



Example 226. Function setvbuf

#include <stdio.h>#define SIZE 1024

int main(void){ char buf[ SIZE]; FILE *file1, *file2; file1 = fopen("App.tmp", "a"); file2 = fopen("Write.tmp", "w"); if(setvbuf(file1, buf, _IOFBF, sizeof(buf)) != 0) { printf("setvbuf failed\n"); } else { printf("’file1’ is now buffered with %d bytes\n", SIZE); } if(setvbuf(file2, NULL, _IONBF, 0) != 0) { printf("setvbuf failed\n"); } else { printf("I/O to ’file2’ is unbuffered \n"); } fclose(file1); fclose(file2); return 0;}


’file1’ is now buffered with 1024 bytes I/O to ’file2’ is unbuffered

Further Information:Section 13.6.27, “fclose” on page 334Section 13.6.30, “fflush” on page 338Section 13.6.36, “fopen” on page 347Section 13.6.100, “setbuf” on page 454



13.6.104 signal

Syntax: #include <signal.h>void(*signal(int sig,void (*func) (int sig))) (int sig);

Description: signal enables a process to choose one of several ways to handle an interrupt signal from the operating system. The argument sig must be one of the following values:

An implementation needs not generate any of these signals, except as a result of explicit calls to the raise function. Additional signals and pointers to undeclarable functions, with macro definitions beginning with the letters SIG and an upper case letter or with SIG_ and an upper case letter, may also be specified by the implementation. Note that the complete set of signals, their semantics, and their default handling is implementation-defined and that all signal numbers need be positive.

The action, that is carried out when an interrupt signal is received, depends on the value of func. func must be a function address or one of the manifest constants defined in signal.h and listed below:

Note: Signal settings are not preserved in created child processes. The child processes instead have their signal settings set to the default values.

Diagnostics: signal returns the previous value of func in order to indicate the signal. If the return value is SIG_ERR, the request could not be handled and errno is set to EINVAL.

Value Description

SIGABRT Abnormal termination such as caused by abort

SIGFPE Erroneous arithmetic operation such as zero division, or an operation resulting in overflow.

SIGILL Detection of an invalid function image such as an illegal instruction.

SIGINT Receipt of an interactive attention signal.

SIGSEGV Invalid access or storage access.

SIGTERM Termination request sent to the program.

Constant Description

SIG_DFL Causes the default action for the condition mode to occur. The system-default-response for all signals is to abort the calling process and terminate with exit code 3. Control then returns to the calling system. If the calling process used stream I/O, buffers created by the run-time library are not flushed though buffers created by the operating system are flushed.

SIG_IGN Causes the indicated signal to be ignored. This value should never be used with SIGFPE, since the floating point state would be left undefined.

function address The specified function is installed as the handler for the given signal. For all signals except SIGFPE, the function is passed the sig argument SIGINT and executed. For SIGFPE signals, the function is passed two arguments, SIGFPE and the floating point error code, which identify the type of exception that occurred.



Example 227. Function signal

#include <stdio.h>#include <signal.h>

sig_atomic_t signal_count;

void MyHandler(int sig_number){ ++signal_count; printf("Value of signal_count: %d\n", signal_count);}

int main(void){ if(signal(SIGFPE, MyHandler) == SIG_ERR) { printf("Could not set MyHandler"); abort(); } else { printf("MyHandler set!\n"); MyHandler((int)SIG_DFL); signal(SIGABRT, SIG_DFL); signal(SIGFPE, SIG_IGN); } return 0;}


MyHandler set! Value of signal_count: 1

Further Information:Section 13.6.2, “abort” on page 306Section 13.6.24, “exit” on page 330Section 13.6.93, “raise” on page 442



13.6.105 sin

Syntax: #include <math.h>doublesin(double x);

Description: sin computes the sine of x.

Diagnostics: sin returns the sine of x. If x is large, a partial loss of significance in the result may occur.

Example 228. Function sin


int main(void){ double x = 0.5;

printf("The sine of %.2lf is %lf.\n", x, sin(x)); return 0;}


The sine of 0.50 is 0.479426.

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.8, “atan2” on page 312Section 13.6.19, “cos” on page 325Section 13.6.20, “cosh” on page 326Section 13.6.106, “sinh” on page 463Section 13.6.135, “tan” on page 506Section 13.6.136, “tanh” on page 507



13.6.106 sinh

Syntax: #include <math.h>doublesinh(double x);

Description: sinh computes the hyperbolic sine of x.

Diagnostics: sinh returns the hyperbolic sine of x. If x is large, HUGE_VAL is returned, and errno is set to ERANGE.

Example 229. Function sinh


int main (void){ double x = .5; printf("The hyperbolic sine of %.2lf is %lf\n", x, sinh(x)); printf("The sine is %lf\n", sin(x)); printf("The hyperbolic cosine is %lf\n", cosh(x)); return 0;}


The hyperbolic sine of 0.50 is 0.521095 The sine is 0.479426 The hyperbolic cosine is 1.127626

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.19, “cos” on page 325Section 13.6.20, “cosh” on page 326Section 13.6.105, “sin” on page 462Section 13.6.135, “tan” on page 506Section 13.6.136, “tanh” on page 507



13.6.107 sprintf

Syntax: #include <stdio.h>intsprintf(char *s, const char *format,...);

Description: sprintf directs output to the character array s using format conditions format. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but are otherwise ignored. sprintf returns if the end of the format string is encountered. For more information on the argument format, refer to Section 13.6.37, “fprintf” on page 350.

Diagnostics: sprintf returns the number of characters written. If an output error occurs, a negative value is returned.

The variable errno is not modified by sprintf unless the system interface function write sets errno. The low level I/O function write is called by sprintf to omit output.

Example 230. Function sprintf


int main(void){ char c = 50; unsigned ui = 34; int i = 56; float fl = 1.2; char x[5] = "abcd", y[5] = "367Z"; char buf[SIZE + 1];

printf("The following variables will be written to a buffer:\n"); printf("c = %c \tui = %u \ti = %o \tfl = %f \tx = %s \ty = %s\n\n", c, ui, i, fl, x, y); sprintf(buf, "c = %c \tui = %u \ti = %o \tfl = %f \tx = %s \ty = %s", c, ui, i, fl, x, y); printf("The contents of the buffer is the following: \n%s\n", buf); return 0;}


The following variables will be written to a buffer: c = 2 ui = 34 i = 70 fl = 1.200000 x = abcd y = 367Z

The contents of the buffer is the following: c = 2 ui = 34 i = 70 fl = 1.200000 x = abcd y = 367Z



Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.88, “printf” on page 433Section 13.6.110, “sscanf” on page 468Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519Section 13.6.145, “vsprintf” on page 521



13.6.108 sqrt

Syntax: #include <math.h>doublesqrt(double x);

Description: sqrt computes the non-negative square root of the argument x.

Diagnostics: If x is negative, zero is returned and errno is set to EDOM.

Example 231. Function sqrt


int main(void){ double x = 361; printf("The square root of %.2lf is %lf \n", x, sqrt(x)); return 0;}


The square root of 361.00 is 19.000000

Further Information:Section 13.6.25, “exp” on page 332Section 13.6.73, “log” on page 413Section 13.6.74, “log10” on page 414Section 13.6.86, “pow” on page 431



13.6.109 srand

Syntax: #include <stdlib.h>voidsrand(unsigned int seed);

Description: srand generates a series of pseudo-random integers. The argument seed is used as the starting point for the new series. The sequence is returned by subsequent calls to rand.

To reinitialize the generator, use 1 as the seed argument. If srand is called with the same seed value, a particular sequence of pseudo-random integers can be repeated.

Diagnostics: srand returns no value.

Note: srand uses a statically allocated object to calculate the random value and to keep the last random value. Therefore, if an application program is reentrant, it must not use srand.

Example 232. Function srand


int main(void){ int i; srand(NULL); for(i = 0; i < 5; i++) { printf(" %d\t", rand()); } printf("\n"); return 0;}


6924 24032 10555 21390 7145

Further Information:Section 13.6.94, “rand” on page 444



13.6.110 sscanf

Syntax: #include <stdio.h>intsscanf(const char *s, const char *format,...);

Description: sscanf reads input from the string s using the format conditions format.

Input data is defined as a string of consecutive non-whitespace characters. Whitespace characters are skipped when an input function is searching for an input field which matches the specification it is searching for. If the specification includes a [, c, or n specifier, whitespaces are not skipped.

The format control string format, a multibyte sequence, determines the interpretation of input sequences as they are read. It may contain:




If there are insufficient arguments for the format control string, the behavior of the function is undefined. If the format control string is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. Therefore, the number of conversion specifications and the number of arguments must be equal. In addition, an argument’s type must match its corresponding conversion specification.

As all arguments will receive some values as a result of the call, they must be passed by reference. This means that all arguments must be pointers. For more information on format, refer to Section 13.6.44, “fscanf” on page 364.

Diagnostics: sscanf returns the number of successful assignments from input sequences to arguments. The number returned may be less than the given number of arguments in two cases:







Example 233. Function sscanf


int main(void){ char c; unsigned ui; int i; float fl; char x[5], y[5]; char buf[SIZE + 1]= "21 3456 1.2 abcd 367Z"; int ret_val;

printf("The buffer buf: %s\n", buf); ret_val = sscanf(buf, "%c%u%o%f%s%s", &c, &ui, &i, &fl, x, y); printf("The %d assigned variables have the following values:\n", ret_val); printf("c = %c\nui = %u\ni = %o\nfl = %f\nx = %s\ny = %s\n\n", c, ui, i, fl, x, y); return 0;}


The buffer buf: 21 3456 1.2 abcd 367Z The 6 assigned variables have the following values: c = 2 ui = 1 i = 3456 fl = 1.200000 x = abcd y = 367Z

Further Information:Section 13.6.44, “fscanf” on page 364Section 13.6.99, “scanf” on page 451Section 13.6.107, “sprintf” on page 464



13.6.111 strcat

Syntax: #include <string.h>char *strcat(char *s1, char *s2);

Note: We recommend to use strncat instead of strcat to avoid buffer overflow problems.

Description: strcat appends a copy of s2 to the end of s1. The first character of *s2 overwrites the terminating null character \0 of *s1. No overflow checking is performed. Thus, all used strings must be null-terminated.

Note: The user must ensure that s1 points to a memory area which is at least of the size:

strlen(s1) + strlen(s2) + 1

Diagnostics: strcat returns a pointer to the concatenated string s1.

Example 234. Function strcat

#include <stdio.h>#include <string.h>#define MAX 85

int main(void){ char string[MAX + 1]; strcpy(string, "Bah, bah, black sheep\n"); strcat(string, "Have you any wool?\n"); strcat(string, "Yes, Sir! Yes, Sir!\n"); strcat(string, "Three bags full."); printf("%s\n", string); return 0;}


Bah, bah, black sheep Have you any wool? Yes, Sir! Yes, Sir! Three bags full.

Further Information:Section 13.6.120, “strncat” on page 482Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.112 strchr

Syntax: #include <string.h>char *strchr(const char *s, int c);

Description: strchr searches for the first occurrence of c in s. The search can also include the terminating null character \0.

Diagnostics: strchr returns a pointer to the first occurrence of c if strchr is successful; otherwise the NULL pointer is returned.

Example 235. Function strchr


int main(void){ char string[MAX + 1]; char ch = ’w’; char *first; int pos;

strcpy(string, "Bah, bah, black sheep Have you any wool? "); strcat(string, "Yes, Sir! Yes, Sir! Three bags full."); first = strchr(string, ch); pos = first - string + 1; printf("\nIn the string \n\n%s\n\nthe character %c " "was first found at position %d\n", string, ch, pos); return 0;}


In the string

Bah, bah, black sheep Have you any wool? Yes, Sir! Yes, Sir! Three bags full.

the character w was first found at position 36

Further Information:Section 13.6.116, “strcspn” on page 477Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.123, “strpbrk” on page 487Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489Section 13.6.126, “strstr” on page 490



13.6.113 strcmp

Syntax: #include <string.h>intstrcmp(const char *s1, const char *s2);

Description: strcmp compares s1 with s2. A value is returned indicating the relationship. Possible values are as follows:

Diagnostics: strcmp returns a value indicating the relationship between s1 and s2.

Example 236. Function strcmp


int main(void){ char string1[MAX + 1]; char string2[MAX + 1]; int relation; strcpy(string1, "Bah, bah, black sheep Have you any wool? "); strcpy(string2, "Bah, bah, black sheep Have you any wool? "); printf("Comparing string\n\n\t’%s’\nwith\n\t’%s’\n\n", string1, string2); relation = strcmp(string1, string2); if(relation < 0) { printf("The first string is less than the second\n"); } else { if (relation == 0) { printf("The strings are identical\n"); } else { printf("The second string is greater than the first\n"); } } return 0;}

Value Meaning

< 0 s1 is less than s2.

= 0 s1 is equal to s2.

> 0 s1 is greater than s2.




Comparing string

’Bah, bah, black sheep Have you any wool? ’ with ’Bah, bah, black sheep Have you any wool? ’

The strings are identical

Further Information:Section 13.6.79, “memcmp” on page 421Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.114 strcoll

Syntax: #include <string.h>intstrcoll(const char * s1, const char *s2);

Description: strrcoll compares the string s1 with the string s2. Both are appropriately interpreted according to the LC_COLLATE category of the current locale which is selected by setlocale. strcoll operates on null-terminated strings as well.

strcoll returns a value indicating the relationship between s1 and s2, as follows:

For more information on the LC_COLLATE macro, see Section 13.6.102, “setlocale” on page 457.

Diagnostics: strcoll returns an integer (see table above) indicating the relationship between s1 and s2 according to the collating sequence selected.

Further Information:Section 13.6.71, “localeconv” on page 409Section 13.6.102, “setlocale” on page 457Section 13.6.113, “strcmp” on page 472Section 13.6.121, “strncmp” on page 483Section 13.6.133, “strxfrm” on page 503

Value Meaning


= 0 s1 is identical to s2.




13.6.115 strcpy

Syntax: #include <string.h>char *strcpy(char *s1, const char *s2);

Note: We recommend to use strncpy instead of strcpy to avoid buffer overflow problems.

Description: strcpy copies the string s2 to string s2. The terminating null character \0 is also copied.

Diagnostics: strcpy returns the value of s1.

Example 237. Function strcpy


int main(void){ char string1[MAX + 1] = "Bah, bah, black sheep Have you any wool?"; char string2[MAX + 1] = "Hello";

printf("The first string points to \n\t’%s’\nthe second one to \n\t’%s’\n\n", string1, string2); printf("Now we copy the first string to the location of the second one!\n"); strcpy(string2, string1); printf("The first string points to \n\t’%s’\nand the second one to \n\t’%s’\n", string1, string2); return 0;}


The first string points to ’Bah, bah, black sheep Have you any wool?’ the second one to ’Hello’

Now we copy the first string to the location of the second one! The first string points to ’Bah, bah, black sheep Have you any wool?’ and the second one to ’Bah, bah, black sheep Have you any wool?’



Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.113, “strcmp” on page 472Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.116 strcspn

Syntax: #include <string.h>size_tstrcspn(const char *s1, const char *s2);

Description: strcspn calculates the length of the maximum initial segment of s1 which consists of characters not included in s2. The terminating null character \0 is not included.

Diagnostics: strcspn returns the length of the initial segment.

Example 238. Function strcspn


int main(void){ char string[MAX + 1]; char charset1[] = "xyzXYZ"; char charset2[] = ""; int pos;

strcpy(string, "Bah, bah, black sheep Have you any wool?"); pos = strcspn(string, charset1); printf("\nIn the string \n\t’%s’\nthe first character " "of the set ’%s’ was first found at position %d,\n", string, charset1, pos); pos = strcspn(string, charset2); printf("the first character of the set ’%s’ was first found " "at position %d.\n", charset2, pos); printf("The string has %d characters.\n", strlen(string)); return 0;}


In the string ’Bah, bah, black sheep Have you any wool?’ the first character of the set ’xyzXYZ’ was first found at position 27, the first character of the set ’’ was first found at position 40. The string has 40 characters.

Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.113, “strcmp” on page 472Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.117 strerror

Syntax: #include <string.h>char *strerror(int errnum);

Description: strerror yields an error message string. The argument errnum is the error message number. The array containing the error message may be overwritten by a subsequent call to strerror, but should not be modified by the program.

The message is not actually printed by strerror; a call to an output function such as fprintf is needed to print the message.

Diagnostics: strerror returns a pointer to the error message string.

Example 239. Function strerror

#include <stdio.h>#include <errno.h>#include <string.h>

int main(void){ FILE *f; if((f = fopen("NO.FILE", "rt")) == NULL) { printf("File could not be opened: %s\n", strerror(errno)); } else { fclose(f); } return 0;}

If the file NO.FILE does not exist, the program above produces the following output:

File could not be opened: Error 2

Further Information:Section 13.6.17, “clearerr” on page 323Section 13.6.29, “ferror” on page 337Section 13.6.85, “perror” on page 430



13.6.118 strftime

Syntax: #include <time.h>size_tstrftime(char *s,

size_t maxsize,const char *format,

const struct tm *timeptr));

Description: strftime formats the tm time value in timeptr according to the supplied format argument and stores the result in the buffer s. The format string consists of zero or more directives and ordinary characters. A directive consists of a % character followed by a character that determines the substitution to take place. All ordinary characters are copied unchanged into the array. No more than maxsize characters are placed in the array.

The LC_TIME category of current locale affects the output formatting of strftime. The formatting codes are:

When the %Z directive is specified, the tzset function is called.

Format Description

%a Abbreviated weekday name

%A Full weekday name

%b Abbreviated month name

%B Full month name

%c Date and time representation appropriate for the locale

%d Day of the month as a decimal number (01-31)

%H Hour in 24-hour format (00-23)

%I Hour in 12-hour format (00-12)

%j Day of the year as a decimal number (001-366)

%m Month as a decimal number (01-12)

%M Minute as a decimal number (00-59)

%p Current locale’s AM/PM indicator for a 12-hour clock

%S Second as a decimal number (00-59)

%U Week of the year as a decimal number, with Sunday as the first day of the week (00-51)

%w Weekday as a decimal number (0-6; Sunday is 0)

%W Week of the year as a decimal number; with Monday as the first day of the week (00-51)

%x Date representation for current locale

%X Time representation for current locale

%y Year without the century as a decimal number (00-99)

%Y Year with the century as a decimal number

%Z Time zone name or abbreviation; no characters if time zone is unknown

%% Percentage sign



Diagnostics: strftime returns the number of characters placed in s (not including the terminating null character) if the total is not more than maxsize, otherwise zero is returned and the contents of the string are indeterminate.

Example 240. Function strftime

#include <stdio.h>#include <time.h>#define MAX 120

int main(void){ char string[MAX + 1]; time_t today; int c;

today = time(NULL); strftime(string, MAX, "Today is the %jth day of the year %Y,\n" "in other words: %A %B %d, %y, in the time zone %Z", localtime( &today)); printf("%s\n", string); return 0;}

The program above produces an output like:

Today is the 037th day of the year 2002, in other words: Wednesday February 06, 02, in the time zone GMT

Further Information:Section 13.6.5, “asctime” on page 309Section 13.6.18, “clock” on page 324Section 13.6.21, “ctime” on page 327Section 13.6.22, “difftime” on page 328Section 13.6.53, “gmtime” on page 382Section 13.6.71, “localeconv” on page 409Section 13.6.72, “localtime” on page 412Section 13.6.83, “mktime” on page 426Section 13.6.102, “setlocale” on page 457Section 13.6.114, “strcoll” on page 474Section 13.6.133, “strxfrm” on page 503Section 13.6.137, “time” on page 508



13.6.119 strlen

Syntax: #include <string.h>size_tstrlen(const char *s);

Description: strlen yields the length in bytes of s, not including the terminating null character \0.

Diagnostics: strlen returns the number of characters that precede the terminating null character.

Example 241. Function strlen

#include <stdio.h>#include <string.h>

int main(void){ char string1[] = "Bah, bah, black sheep Have you any wool?"; char string2[] = "Hello"; printf("The first string \n\t’%s’ has %d characters\n", string1, strlen(string1)); printf("the second one\n\t’%s’ has %d.\n\n", string2, strlen(string2)); return 0;}


The first string ’Bah, bah, black sheep Have you any wool?’ has 40 characters the second one ’Hello’ has 5.

Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.113, “strcmp” on page 472Section 13.6.115, “strcpy” on page 475



13.6.120 strncat

Syntax: #include <string.h>char *strncat(char s1, const char *s2, size_t n);

Description: strncat appends a copy of at most n characters of s2 to the end of s1. The first character of *s2 overwrites the terminating null character \0 of *s1. The resulting string is terminated with the null character \0. No overflow checking is performed. Thus, all used strings must be null-terminated.

Diagnostics: strncat returns a pointer to the concatenated string s1.

Example 242. Function strncat


int main(void){ char string1[MAX + 1] = "Bah, bah, black sheep Have you any wool?"; char string2[] = "Yes Sir, yes Sir"; size_t count = 10; printf("Append %d chars of the second string\n", count); printf("\t%s\n to the first one\n\t%s\n", string2, string1); strncat(string1, string2, count); printf("The concatenated string is now the following:\n\t%s\n", string1); return 0;}


Append 10 chars of the second string Yes Sir, yes Sir to the first one Bah, bah, black sheep Have you any wool? The concatenated string is now the following: Bah, bah, black sheep Have you any wool?Yes Sir, y

Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.114, “strcoll” on page 474Section 13.6.133, “strxfrm” on page 503



13.6.121 strncmp

Syntax: #include <string.h>intstrncmp(const char *s1, const char *s2, size_t n);

Description: strncmp compares of s1 with s2. n characters are compared at most. Possible values are as follows:

Diagnostics: strncmp returns a value indicating the relationship between s1 and s2.

Example 243. Function strncmp


int main(void){ char string1[MAX + 1]; char string2[MAX + 1]; size_t count = 10; int relation;

strcpy(string1, "Bah, bah, black sheep Have you any wool? "); strcpy(string2, "Bah, bah, white sheep Have you any wool? "); printf("Comparing string\n\t’%s’\nwith \n\t’%s’\n\n", string1, string2); relation = strncmp(string1, string2, count); if(relation < 0) { printf("The first string is lexically smaller than the second!\n"); } else { if(relation == 0) { printf("The first %d characters of the strings are equal!\n", count); } else { printf("The first string is lexically greater " "than the second!\n"); } } return 0;}

Value Meaning


= 0 s1 is identical to s2.





Comparing string ’Bah, bah, black sheep Have you any wool? ’ with ’Bah, bah, white sheep Have you any wool? ’

The first 10 characters of the strings are equal!

Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.113, “strcmp” on page 472Section 13.6.115, “strcpy” on page 475Section 13.6.120, “strncat” on page 482Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.122 strncpy

Syntax: #include <string.h>char *strncpy(char *dest,

const char *source,size_t n);

Description: strncpy copies at most n characters of the string source to string dest. The terminating null character \0 is also copied. If the string source has fewer than n characters, null characters are automatically appended to the copy in the array pointed to by dest. n number of characters are always written. If source longer than n characters, the resulting string dest will have no terminating null character appended at the end.

Diagnostics: strncpy returns the address of dest.

Example 244. Function strncpy


int main(void){ char string1[MAX + 1] = "Hello"; char string2[MAX + 1] = "Bah, bah, black sheep Have you any wool?"; size_t count = 20;

printf("The first %d characters of string2\n\t’%s\n’" "will be copied to string1\n\t’%s’\n", count, string2, string1); strncpy(string1, string2, count); string1[20]=’\0’; /*replace null terminator*/ printf("String1 points now to\n\t’%s’\n", string1); return 0;}


The first 20 characters of string2 ’Bah, bah, black sheep Have you any wool?’ will be copied to string1 ’Hello’ String1 points now to ’Bah, bah, black shee’



Further Information:Section 13.6.111, “strcat” on page 470Section 13.6.113, “strcmp” on page 472Section 13.6.115, “strcpy” on page 475Section 13.6.120, “strncat” on page 482Section 13.6.121, “strncmp” on page 483Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.123 strpbrk

Syntax: #include <string.h>char *strpbrk(const char *s1, const char *s2);

Description: strpbrk searches for the first occurrence of any character from s2 in s1. The terminating null character \0 is not included in the search.

Diagnostics: strpbrk returns a pointer to the first located character from s2 in s1; otherwise NULL is returned if no character was found.

Example 245. Function strpbrk


int main(void){ char string1[MAX + 1]; char string2[MAX + 1]; char *ptr; strcpy(string1, "10 little bears bouncing on a bed"); strcpy(string2, "One fell down and bumped his head"); ptr = strpbrk(string1, string2); printf("Pointer to the first occurrence of any character of string2\n" "\t’%s’\nin string1\n\t’%s’\npoints to\t’%s’.\n", string2, string1, ptr); return 0;}


Pointer to the first occurrence of any character of string2 ’One fell down and bumped his head’ in string1 ’10 little bears bouncing on a bed’ points to ’ little bears bouncing on a bed’.

Further Information:Section 13.6.112, “strchr” on page 471Section 13.6.124, “strrchr” on page 488Section 13.6.128, “strtok” on page 493



13.6.124 strrchr

Syntax: #include <string.h>char *strrchr(const char *s, int c);

Description: strrchr searches for the last occurrence of c in s. The terminating null character \0 is included in the search.

Diagnostics: strrchr returns a pointer to the last occurrence of the character c in s. If c does not occur in s, the NULL pointer is returned.

Example 246. Function strrchr


int main(void){ char string[MAX + 1]; char ch = ’a’; char *last; int pos;

strcpy(string, "Bah, bah, black sheep Have you any wool? "); last = strrchr(string, ch); pos = last - string + 1; printf("\nIn the string\n\t’%s’\nthe character ’%c’ was last found at " "position %d\n", string, ch, pos); return 0;}


In the string ’Bah, bah, black sheep Have you any wool? ’ the character ’a’ was last found at position 32

Further Information:Section 13.6.112, “strchr” on page 471Section 13.6.116, “strcspn” on page 477Section 13.6.120, “strncat” on page 482Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.123, “strpbrk” on page 487Section 13.6.125, “strspn” on page 489



13.6.125 strspn

Syntax: #include <string.h>size_tstrspn(const char *string, const char *charset);

Description: strspn yields the length of the initial segment of string that consists entirely of characters from charset. The null character \0 terminating string is not included in the search.

Diagnostics: strspn returns an integer value specifying the length of the segment that consists entirely of characters from string. The NULL pointer is returned if string starts with a character which is not part of charset.

Example 247. Function strspn


int main(void){ char string[MAX + 1]; char charset[] = " ,abh"; int count;

strcpy(string, "bah, bah, black sheep Have you any wool?"); count = strspn(string, charset); printf("The initial substring in string\n\t%s\n" "that consists entirely of characters of set\n\t’%s’\n", string, charset); printf("has %d characters.\n", count); return 0;}


The initial substring in string bah, bah, black sheep Have you any wool? that consists entirely of characters of set ’ ,abh’ has 11 characters.

Further Information:Section 13.6.116, “strcspn” on page 477Section 13.6.120, “strncat” on page 482Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.124, “strrchr” on page 488



13.6.126 strstr

Syntax: #include <string.h>char *strstr(const char * string, const char *substring);

Description: strstr searches for the first occurrence of substring in string. strstr does not search for the terminating null character \0.

Diagnostics: strstr returns a pointer to the first occurrence of substring in string; the NULL pointer is returned if the string is not found. If the length of substring is zero, strstr returns the pointer to string.

Example 248. Function strstr


int main(void){ char string[MAX + 1]; char charset[] = "sheep"; char *ptr; strcpy(string, "bah, bah, black sheep Have you any wool?"); ptr = strstr(string, charset); printf("The string ’%s’ was first located in " "the string\n\t%s\nat\n\t%s\n", charset, string,ptr); return 0;}


The string ’sheep’ was first located in the string bah, bah, black sheep Have you any wool? at sheep Have you any wool?

Further Information:Section 13.6.116, “strcspn” on page 477Section 13.6.120, “strncat” on page 482Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485Section 13.6.123, “strpbrk” on page 487Section 13.6.124, “strrchr” on page 488Section 13.6.125, “strspn” on page 489



13.6.127 strtod

Syntax: #include <stdlib.h>doublestrtod(const char *nptr, char **endptr);

Description: strtod reads a string representing a floating point value and returns a double precision floating point as its result. The string pointed to by nptr may contain an optional leading sign, any number of decimal digits, and can contain one decimal point. It may also be followed by an optional exponent given by an “e” or “E” (or “d” or “D”). Leading blanks and tabs are ignored. Scanning stops as soon as an inappropriate character is encountered and the resulting number is returned.

The leading sign may be plus (+) or minus (–). If no digits appear before the decimal point, at least one digit must follow.

The conversion ends at the first unrecognized character. A pointer is stored in endptr to that character if endptr is not NULL.

Diagnostics: strtod returns the value of the floating point value if no error occurs; otherwise HUGE_VAL is returned if the conversions results in an overflow. If no conversion can be performed or an underflow occurs, 0 is returned. errno is set to ERANGE if an overflow or underflow occurs.

Example 249. Function strtod


int main(void){ char *string, *breakstring; double pi;

string = "3.1415926is the value of PI"; pi = strtod(string, &breakstring); printf(" The string is \n\t’%s’\n", string); printf(" As a double value PI = %lf\n", pi); printf(" The scan was stopped at:\n\t’%s’\n", breakstring); return 0;}


The string is ’3.1415926is the value of PI’ As a double value PI = 3.141593 The scan was stopped at: ’is the value of PI’



Further Information:Section 13.6.10, “atof” on page 314Section 13.6.12, “atol” on page 317Section 13.6.129, “strtol” on page 495



13.6.128 strtok

Syntax: #include<string.h>char *strtok(char *s1, const char *s2);

Description: strtok is used to break the string s1 into a sequence of tokens, each of which is delimited by a character from s2. The tokens in s1 may be separated by one or more delimiters from s2.

The first call to strtok searches for the first character that is not contained in the current delimiter string, skipping leading delimiters. If such a token is found, strtok saves a pointer to the following character from which the next search will start. The first character found is overwritten by a null character \0 to terminate the token. To read the next token from s1, strtok must be called with a NULL value for the s1 argument. The NULL s1 argument causes strtok to search for the next token in the previous token string.

If no character is found, the current token extends to the end of s1.The set of delimiters may vary from call to call, so that s2 can have any value.

Note: Because strtok will modify the original string by inserting a null character ('\0') after the token in s1, the string should be duplicated if it is to be re-used.

Diagnostics: The first time strtok is called, it returns a pointer to the first token in s1. Further calls with the same token string cause strtok to return a pointer to the next token in the string. A NULL pointer is returned when there are no more tokens. All tokens are null-terminated.

Example 250. Function strtok

#include <stdio.h>#include <string.h>

int main(void){ char string[] = "Looking for\nall\t tokens in this string!"; char *delimiter; char *tokenptr; int i;

delimiter = " .,?!\n\t"; printf("%s\n", string); tokenptr = strtok(string, delimiter); i = 0; while(tokenptr != NULL) { printf("%d. token: %s\n", ++i, tokenptr); tokenptr = strtok(NULL, delimiter); } printf("%s\n", string); return 0;}




Looking for all tokens in this string! 1. token: Looking 2. token: for 3. token: all 4. token: tokens 5. token: in 6. token: this 7. token: string Looking

Further Information:Section 13.6.116, “strcspn” on page 477Section 13.6.123, “strpbrk” on page 487Section 13.6.125, “strspn” on page 489



13.6.129 strtol

Syntax: #include <stdlib.h>long intstrtol( const char *nptr, char **endptr, int base);

Description: strtol converts the string nptr to a long integer value. The function recognizes strings which contain:

• leading white space (optional)

• plus or minus (optional)

• a sequence of digits

The conversion ends at the first unrecognized character or at the end of the string. The parameter *endptr points to this byte (i.e. **endptr is the first character not being converted) unless the function was called with endptr being the NULL pointer; in this case, endptr remains NULL. The parameter base determines the numeric base for the conversion. If base is not zero, it must have a value between 2 and 36. This value determines which characters are recognized as digits. The letters a-z and A-Z represent the digits 10 through 36, up to (and excluding) the value of base. The character pairs “0x” or “0X” may optionally precede the digits if the value of base is 16. If the parameter base is zero, the base is determined by the first characters of the string following the optional leading white space and plus sign.

• If the digit part of the string starts with “0x” or “0X”, the base 16 is assumed.

• If the first character of the digit part is a zero and the second one is neither “x” nor “X”, base 8 is assumed.

• Otherwise, base 10 is assumed.

Diagnostics: strtol returns a long integer value. If no conversion can be performed, zero is returned. If the correct value is outside the range of representable values, LONG_MAX is returned for a value that too big and LONG_MIN returned for a value that is too small. In these cases the value of errno is set to ERANGE.



Example 251. Function strtol


int main(void){ char *string, *breakstring; long i; int base;

string = "31415.926is a value"; base = 0; i = strtol(string, &breakstring, base); printf(" The string is \n\t%s\n", string); printf(" As a long value: %ld\n", i); printf(" The scan was stopped at: ’%s’\n", breakstring); return 0;}


The string is 31415.926is a value As a long value: 31415 The scan was stopped at: ’.926is a value’

Further Information:Section 13.6.12, “atol” on page 317Section 13.6.127, “strtod” on page 491Section 13.6.130, “strtoll” on page 497Section 13.6.131, “strtoul” on page 499



13.6.130 strtoll

Syntax: #include <stdlib.h>long long intstrtoll(const char *ptr, char **endptr, int base);

Description: The function strtoll converts the string pointed to by ptr into a long long integer value. The function recognizes strings which contain:


• a leading plus or minus sign (optional)






Diagnostics: strtoll returns a long long integer value. If no conversion can be performed, zero is returned. If the correct value is outside the range of representable values, LLONG_MAX is returned for a value that too big and LLONG_MIN returned for a value that is too small. In these cases the value of errno is set to ERANGE.



Example 252. Function strtoll


int main( void){ char *string, *breakstring; long long int i; int base;

string = "9223372036.926is a value"; base = 0; i = strtoll(string, &breakstring, base); printf(" The string is \n\t’%s’\n", string); printf(" As a long long value: %lld\n", i); printf(" The scan was stopped at: ’%s’\n", breakstring); return 0;}


The string is ’9223372036.926is a value’ As a long long value: 9223372036854775807 The scan was stopped at: ’223372036.926is a value’

Further Information:Section 13.6.70, “lltoa” on page 408Section 13.6.129, “strtol” on page 495Section 13.6.131, “strtoul” on page 499Section 13.6.132, “strtoull” on page 501



13.6.131 strtoul

Syntax: #include <stdlib.h>unsigned long intstrtoul( const char *nptr, char **endptr, int base);

Description: strtoul converts the string nptr to an unsigned long integer value. The function recognizes strings containing:


• plus or minus (optional)






Diagnostics: strtoul returns an unsigned long int value. If no conversion can be performed, zero is returned. If the correct value is outside the range of representable values, ULONG_MAX is returned for a value that too big and ULONG_MIN returned for a value that is too small. In these cases the value of errno is set to ERANGE.



Example 253. Function strtoul


int main(void){ char *string, *breakstring; unsigned long i; int base; string = "10013726is a value"; printf(" The string is \n\t’%s’\n\n", string); for(base = 2; base <= 8; base *= 2) { i = strtoul(string, &breakstring, base); printf(" As a value base %d: %ld\n", base, i); printf(" The scan was stopped at: ’%s’\n\n", breakstring); } return 0;}


The string is ’10013726is a value’

As a value base 2: 9 The scan was stopped at: ’3726is a value’

As a value base 4: 263 The scan was stopped at: ’726is a value’

As a value base 8: 2103254 The scan was stopped at: ’is a value’

Further Information:Section 13.6.127, “strtod” on page 491Section 13.6.129, “strtol” on page 495



13.6.132 strtoull

Syntax: #include <stdlib.h>unsigned long long intstrtoull(const char * nptr, char **endptr, int base);

Description: strtoull converts the string nptr into an unsigned long long value. The function recognizes strings which contain:


• a leading plus sign (optional)








Example 254. Function strtoull


int main(void){ char *string, *breakstring; unsigned long long i; int base; string = "0123456789abcdefis a value"; printf(" The string is \n\t’%s’\n\n", string); for(base = 2; base <= 16; base += 2) { i = strtoull(string, &breakstring, base); printf(" As a value base %d: %lld\n", base, i); printf(" The scan was stopped at: ’%s’\n\n",breakstring); } return 0;}


The string is ’0123456789abcdefis a value’

As a value base 2: 1 The scan was stopped at: ’23456789abcdefis a value’




As a value base 10: 123456789 The scan was stopped at: ’abcdefis a value’

As a value base 12: 73686780563 The scan was stopped at: ’cdefis a value’

As a value base 14: 65751519677857 The scan was stopped at: ’efis a value’

As a value base 16: 81985529216486895 The scan was stopped at: ’is a value’

Further Information:Section 13.6.130, “strtoll” on page 497Section 13.6.131, “strtoul” on page 499Section 13.6.70, “lltoa” on page 408



13.6.133 strxfrm

Syntax: #include <string.h>size_tstrxfrm(char *dest, const char *source, size_t n);

Description: strxfrm transforms for at most n characters, including the null character \0, of the string source into a new collated form that is stored in dest. The size of array needed to hold the transformation of the source string is the value of the following expression:

1 + strxfrm( NULL, string, 0)

The transformation uses the collating sequence set by the setlocale function. If the collating sequence is selected from the 'C' locale, strxfrm is equivalent to:

strncpy( dest, source, count);return( strlen( source) );

A call to strcmp with the two transformed strings yields identical results to a call to srcoll applied to the two original strings.

Diagnostics: strxfrm returns the length of the transformed string, not counting the terminating null character. If the return value is equal to n then the contents of dest are indeterminate.

Example 255. Function strxfrm

#include <stdlib.h>#include <stdio.h>#include <string.h>

int main(void){ char Buf[10]; if(strxfrm(Buf, "Hello", sizeof(Buf)) < sizeof(Buf)) { printf("String completely copied\n"); } else { printf("Missing some Bytes\n"); } if(strxfrm(Buf, "Hello World", sizeof(Buf)) < sizeof(Buf)) { printf("String completely copied\n"); } else { printf("Missing some Bytes\n"); } return 0;}




String completely copied Missing some Bytes

Further Information:Section 13.6.71, “localeconv” on page 409Section 13.6.102, “setlocale” on page 457Section 13.6.113, “strcmp” on page 472Section 13.6.114, “strcoll” on page 474Section 13.6.119, “strlen” on page 481Section 13.6.121, “strncmp” on page 483Section 13.6.122, “strncpy” on page 485



13.6.134 system

This function is also a system interface function and therefore described in Section 14.3.5, “system” on page 610.



13.6.135 tan

Syntax: #include <math.h>doubletan(double x);

Description: tan computes the tangent of the argument x.

Diagnostics: tan returns the tangent of x. If x is too large, zero is returned and errno is set to ERANGE.

Example 256. Function tan


int main(void){ double x = .5; printf("The tangent of %.2lf is %lf\n", x, tan(x)); return 0;}


The tangent of 0.50 is 0.546302

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.19, “cos” on page 325Section 13.6.20, “cosh” on page 326Section 13.6.105, “sin” on page 462Section 13.6.106, “sinh” on page 463Section 13.6.136, “tanh” on page 507



13.6.136 tanh

Syntax: #include <math.h>doubletanh(double x);

Description: tanh computes the hyperbolic tangent of the argument x.

Diagnostics: tanh returns the hyperbolic tangent of x. If x is too large, the function returns HUGE_VAL and sets errno to ERANGE.

Example 257. Function tanh


int main(void){ double x = .5; printf("The hyperbolic tangent of %.2lf is %lf\n", x, tanh(x)); return 0;}


The hyperbolic tangent of 0.50 is 0.462117

Further Information:Section 13.6.4, “acos” on page 308Section 13.6.6, “asin” on page 310Section 13.6.7, “atan” on page 311Section 13.6.19, “cos” on page 325Section 13.6.20, “cosh” on page 326Section 13.6.105, “sin” on page 462Section 13.6.106, “sinh” on page 463Section 13.6.135, “tan” on page 506



13.6.137 time

This function is also a system interface function and therefore described in Section 14.3.6, “time” on page 611.



13.6.138 tmpfile

Syntax: #include <stdio.h>FILE *tmpfile(void);

Description: tmpfile creates a temporary binary file. This file is automatically deleted when closed or at program termination (if the current working directory is not changed). The temporary file is opened in binary read/write mode. The function will generate files with unique names up to TMP_MAX calls.

Diagnostics: If the temporary file can be successfully opened, a pointer to the stream of the file is returned; otherwise NULL is returned. If an error occurs, errno contains a value indicating the type of error detected:

Example 258. Function tmpfile

#include <stdio.h>

int main(void){ FILE *tmp; if((tmp = tmpfile()) != NULL) { printf("Temporary file was created!\n"); } else { printf("No temporary file could be opened!"); } return 0;}

If a temporary file can be created, the program above produces the following output:

Temporary file was created!

Further Information:Section 13.6.139, “tmpnam” on page 510

Value Meaning




ENFILE File table overflow (too many open files)



13.6.139 tmpnam

Syntax: #include <stdio.h>char *tmpnam(char *string);

Description: tmpnam creates a unique temporary file name that can be used to open a temporary file without overwriting an existing file. This file name is stored in string. The function will generate unique names up to TMP_MAX calls.

If string is NULL, tmpnam leaves the result in an internal static buffer and any subsequent call destroy this value. If string is not NULL, it is assumed to point to an array of at least L_TMPNAM bytes (defined in stdio.h).

Diagnostics: tmpnam returns a pointer to the name generated unless it is impossible to create this name or the name is not unique; otherwise NULL is returned.

Note: Since tmpnam works on a static allocated data structure, it must not be used for reentrant tasks.

Example 259. Function tmpnam

#include <stdio.h>

int main(void){ char tmp_name[L_tmpnam]; FILE *tmp; tmpnam(tmp_name); if((tmp = fopen(tmp_name, "w")) != NULL) { printf("Temporary file ’%s’ was created!\n", tmp_name); } else { printf("Temporary file cannot be opened!"); } return 0;}


Temporary file ’u0000000’ was created!

Further Information:Section 13.6.138, “tmpfile” on page 509



13.6.140 tolower

Syntax: #include <ctype.h>inttolower(int c);

Description: tolower converts an upper case letter to the corresponding lower case letter.

Diagnostics: tolower returns the corresponding lower case letter if the argument is an upper case letter; otherwise the original character is returned. There is no error return.

Example 260. Function tolower



printf("Of the first 7Fh characters are the following ones upper case:\n"); for(ch = 0; ch <= 0x7F ; ch++) { if(isupper(ch)) { printf("%.2Xh=%c \t", ch, ch); printf("lower case %c\n", tolower(ch)); } } return 0;}


Of the first 7Fh characters are the following ones upper case: 41h=A lower case a 42h=B lower case b 43h=C lower case c 44h=D lower case d 45h=E lower case e 46h=F lower case f 47h=G lower case g 48h=H lower case h 49h=I lower case i 4Ah=J lower case j 4Bh=K lower case k 4Ch=L lower case l 4Dh=M lower case m 4Eh=N lower case n 4Fh=O lower case o 50h=P lower case p 51h=Q lower case q 52h=R lower case r 53h=S lower case s



54h=T lower case t 55h=U lower case u 56h=V lower case v 57h=W lower case w 58h=X lower case x 59h=Y lower case y 5Ah=Z lower case z

Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.141, “toupper” on page 513



13.6.141 toupper

Syntax: #include <ctype.h>inttoupper(int c);

Description: toupper converts a lower case letter to the corresponding upper case letter.

Diagnostics: toupper returns the corresponding upper case letter if the argument is a lower case letter; otherwise the original character is returned. There is no error return.

Example 261. Function toupper


int main(void){ int ch; FILE *f;

if((f = fopen("poem.txt", "r")) == NULL) { printf("unable to open file\n"); abort(); } while((ch = fgetc(f)) != EOF) { putc(toupper(ch), stdout); } fclose(f); return 0;}




JACK AND JILL WENT UP THE HILL TO FETCH A PAIL OF WATER; JACK FELL DOWN AND BROKE HIS CROWN, AND JILL CAME TUMBLING AFTER.



Further Information:Section 13.6.54, “isalnum” on page 383Section 13.6.55, “isalpha” on page 384Section 13.6.56, “iscntrl” on page 385Section 13.6.57, “isdigit” on page 387Section 13.6.58, “isgraph” on page 389Section 13.6.59, “islower” on page 391Section 13.6.60, “isprint” on page 393Section 13.6.61, “ispunct” on page 395Section 13.6.62, “isspace” on page 397Section 13.6.63, “isupper” on page 399Section 13.6.64, “isxdigit” on page 401Section 13.6.140, “tolower” on page 511



13.6.142 ungetc

Syntax: #include <stdio.h>intungetc(int c, FILE *stream);

Description: ungetc pushes the character c back onto the input file stream and clears the end-of-file indicator. The stream must be opened for reading. A subsequent read operation on the file stream starts with c. The pushed-back character c will be discarded if a call to fflush or to a file position function (such as fseek, fsetpos, or rewind) is made before the next read operation is performed. The file-position indicator will have the same value it had before the characters were pushed back. Any attempt to push EOF onto the stream is ignored.

The file-position indicator is unspecified for a successful ungetc against a text stream of more than 3 characters until all the pushed back characters are read or discarded. The file-position indicator is decremented on a successful ungetc against a binary stream. For example, if its value was zero before the call, the value is undefined after the call.

Only one character (the most recent one) of push-back is remembered.

Note: Results are unpredictable if ungetc is called three times without a read operation between the calls.

ungetc may fail after a call to fscanf, unless another read operation (e.g. getc) has been performed. This is because fscanf itself calls ungetc.

Diagnostics: ungetc returns the character pushed back. EOF as a return value indicates a failure to push back the specified character.



Example 262. Function ungetc


int main(void){ int chr; int value = 0;

printf("Enter an integer: ");

while(((chr = getchar()) != EOF) && isdigit(chr)) { value = value * 10 + chr - ’0’; }

if(chr != EOF) { ungetc(chr, stdin); }

printf("Integer value: %d\n", value); printf("Next character in stdin: ’%c’\n", getchar());

return 0;}

The program above produces the following output (boldfaced text being typed by the user):

Enter an integer: 100abc Integer value: 100 Next character in stdin: ’a’

Further Information:Section 13.6.36, “fopen” on page 347Section 13.6.49, “getc” on page 377Section 13.6.50, “getchar” on page 379Section 13.6.89, “putc” on page 435Section 13.6.90, “putchar” on page 437



13.6.143 vfprintf

Syntax: #include <stdio.h>#include <stdarg.h>intvfprintf(FILE, *stream, const char *format, va_list arg);

Description: vfprintf writes output to file stream using format specifications format. vfprintf is similar to its counterparts fprintf, printf, and sprintf but accepts a pointer to a list of arguments instead of an argument list. This list of arguments has been initialized by va_start.

The format argument has the same form and function as the format argument for fprintf. See also Section 13.6.37, “fprintf” on page 350.

Diagnostics: vfprintf returns the number of characters written or a negative value if an output error occurs. The variable errno is not modified by vfprintf unless the system interface function write sets errno. The low level I/O function write is called by vfprintf to emit output.

Example 263. Function vfprintf

#include <stdio.h>#include <stdarg.h>

int _myvfprintf( const char *fmt, ...){ va_list arg_list; int ret_val; va_start(arg_list, fmt); ret_val = vfprintf(stdout, fmt, arg_list); va_end(arg_list); return ret_val;}

int main(void){ _myvfprintf("Hello World %d, %f\n", 1, 2.34); return 0;}


Hello World 1, 2.340000



Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.88, “printf” on page 433Section 13.6.107, “sprintf” on page 464Section 13.5.2, “Macro va_arg” on page 301Section 13.5.4, “Macro va_end” on page 303Section 13.5.5, “Macro va_start” on page 304Section 13.6.144, “vprintf” on page 519



13.6.144 vprintf

Syntax: #include <stdio.h>#include <stdarg.h>intvprintf(const char *format, va_list arg);

Description: vprintf writes output to the standard output using format specifications format. vprintf is similar to its counterparts fprintf, printf, and sprintf but accepts a pointer to a list of arguments instead of an argument list. This list of arguments has been initialized by va_start.

The format argument has the same form and function as the format argument for fprintf. See also Section 13.6.37, “fprintf” on page 350.

Diagnostics: vprintf returns the number of characters written. The variable errno is not modified by vprintf unless the system interface function write sets errno. The low level I/O function write is called by vprintf to omit output.

Example 264. Function vprintf


int _myvprintf( const char *fmt, ...){ va_list arg_list; register int ret_val; va_start(arg_list, fmt); ret_val = vprintf(fmt, arg_list); va_end(arg_list); return ret_val;}

int main(void){ _myvprintf("Hello World %d, %f\n", 1, 2.34); return 0;}





Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.88, “printf” on page 433Section 13.6.107, “sprintf” on page 464Section 13.5.2, “Macro va_arg” on page 301Section 13.5.4, “Macro va_end” on page 303Section 13.5.5, “Macro va_start” on page 304Section 13.6.143, “vfprintf” on page 517Section 13.6.145, “vsprintf” on page 521



13.6.145 vsprintf

Syntax: #include <stdio.h>#include <stdarg.h>intvsprintf(char *s,

const char *format,va_list arg);

Description: vsprintf writes output to the memory area pointed to by s using format specifications format. vsprintf is similar to its counterparts fprintf, printf, and sprintf but accepts a pointer to a list of arguments instead of an argument list. This list of arguments has been initialized by va_start.

The format argument has the same form and function as the format argument for fprint. See also Section 13.6.37, “fprintf” on page 350.

Diagnostics: vsprintf returns the number of characters written (not counting the terminating null character) or a negative value if an output error occurs.

Example 265. Function vsprintf


int _mysprintf(char *string, const char *fmt, ...){ va_list arg_list; register int ret_val; va_start(arg_list, fmt); ret_val = vsprintf(string, fmt, arg_list); va_end(arg_list); return ret_val;}

int main(void){ char str[21]; _mysprintf(str, "Hello World %d, %f\n", 1, 2.34); puts(str); return 0;}






Further Information:Section 13.6.37, “fprintf” on page 350Section 13.6.88, “printf” on page 433Section 13.6.107, “sprintf” on page 464Section 13.5.2, “Macro va_arg” on page 301Section 13.5.4, “Macro va_end” on page 303Section 13.5.5, “Macro va_start” on page 304Section 13.6.143, “vfprintf” on page 517Section 13.6.144, “vprintf” on page 519



13.7 The Intel® Run-time Library

This section describes functions of the Intel® Run-time Library supported by the Intel® C++ Compiler. The name of this library is x0__ar00.a. Most of these are functions relating to floating point operations between variables of differing types.The Run-time Library is part of the C Standard Library.

These functions are assembly language functions and are implicitly called by the Intel® C++ Compiler when required. For example in the following piece of code:

double a,b,c; // declare three double variables

a=1.2345e7; // load variable a with data b=1.67; // load variable b with data c=a+b; // add variable a to variable b, // save result to variable c

The compiler automatically calls the correct floating point function to carry out the addition of the two variables a and b.

Although it is not recommended, it is also possible to call these functions explicitly from the C/C++ source code. In order to do so the functions prototypes are required before a call is made to it in the correct manner. An example of this is provided for each of the functions described.

The chapter covers the following topics:

• Section 13.7.1, “General Remarks” on page 524 provides general remarks applying to the Floating Point Library.

• Section 13.7.2, “Summary of the Functions” on page 525 gives a summary of all supported floating point functions.

• Section 13.7.3 - Section 13.7.56 describe every available function in detail. They are given in alphabetical order and have examples where appropriate.



13.7.1 General Remarks

The following remarks apply to the Floating Point Library of the Intel® C++ Compiler:

• All numerical values conform to IEEE floating point format standards 754.

• 64-bit double precision floating point numbers are stored in register pairs such as R0:R1, where the most significant 32 bits are held in the lower numbered register of R0.

• Values stored in memory do so with their least significant bytes at the lowest address – This method of keeping floating point data is known as "Little endian".

• Upon return from these functions the state of the Condition Code Flags are undefined, except in the case of the comparison and test functions.

• All functions in this library use 32-bit code.

• In accordance with the IEEE standards it is possible for floating point numbers to be in an invalid state called a NaN, which stands for "Not a Number". This condition is frequently checked for within these functions and dealt with

• The global symbol errno is not changed within these functions.

• Scalar *mod* and *div* calls the various functions lmod0 and ldiv0 in the event of a divide by zero being attempted. These symbols are undefined if the default startup is not used.



13.7.2 Summary of the Functions

Functions are detailed in the following sections in alphabetical order. The tables below summarize which functions are available for each data type.

Note: Some functions occur in more than one table where, for example, a conversion is being made from one data type to another.

Table 41. Functions for 32-bit Floating Point Numbers (float)

Function Group Function Description

Arithmetic

__addsf3 Add.

__divsf3 Divide.

__mulsf3 Multiply.

__subsf3 Subtract.

__negsf2 Negate.

Comparisons

__eqsf2 Compare for equality.

__gesf2 Compare for greater than or equal to.

__gtsf2 Compare for greater than.

__lesf2 Compare for less than or equal to.

__ltsf2 Compare for less than.

__nesf2 Compare for not equal to.

Conversions

__extendsfdf2 Converts from 32-bit single precision floating point value

to 64-bit double precision floating point value.

__fixsfsi Converts from 32-bit single precision floating point value

to 32-bit signed integer..

__fixunssfsi Converts from 32-bit single precision floating point value

to 32-bit unsigned integer.

__fixsfdi Converts from 32-bit single precision floating point value

to 64-bit signed integer.

__fixunssfdi Converts from 32-bit single precision floating point value

to 64-bit unsigned integer.

__truncdfsf2 Converts from 64-bit double precision floating point value

to 32-bit single precision floating point value.

__floatsisf Converts from 32-bit signed integer to 32-bit single precision floating point value.

__floatunssisf Converts from 32-bit unsigned integer to 32-bit single precision floating point value.

__floatdisf Converts from 64-bit signed integer to 32-bit single precision floating point value.

__floatunsdisf Converts from 64-bit unsigned integer to 32-bit single precision floating point value.



Table 42. Functions for 64-bit Floating Point Numbers (double)


Arithmetic

__adddf3 Add.

__divdf3 Divide.

__muldf3 Multiply.

__subdf3 Subtract.

__negdf2 Negate.

Comparisons

ftp8 Analyze.

__eqdf2 Compare for equality.

__gedf2 Compare for greater than or equal to.

__gtdf2 Compare for greater than.

__ledf2 Compare for less than or equal to.

__ltdf2 Compare for less than.

Conversions

__nedf2 Compare for not equal to.

__truncdfsf2 Converts from 64-bit double precision floating point value to 32-bit single precision floating point value.

__fixdfsi Converts from 64-bit double precision floating point value to 32-bit signed integer.

__fixunsdfsi Converts from 64-bit double precision floating point value to 32-bit unsigned integer.

__fixdfdi Converts from 64-bit double precision floating point value to 64-bit signed Integer.

__fixunsdfdi Converts from 64-bit double precision floating point value to 64-bit unsigned integer.

__extendsfdf2 Converts from 32-bit floating point value to 64-bit double precision floating point value.

__floatsidf Converts from 32-bit signed integer to 64-bit double precision floating point value.

__floatunssidf Converts from 32-bit unsigned integer to 64-bit double precision floating point value.

__floatdidf Converts from 64-bit signed integer to 64-bit double precision floating point value.

__floatunsdidf Converts from 64-bit unsigned integer to 64-bit double precision floating point value.



Table 43. Functions for Integer Arithmetic


Arithmetic

__divdi3 64-bit signed integer division.

__divsi3 32-bit signed integer division.

__udivdi3 64-bit unsigned integer division.

__udivsi3 32-bit unsigned integer division.

__moddi3 64-bit signed modulo division.

__modsi3 32-bit signed modulo division.

__umoddi3 64-bit unsigned modulo division.

__umodsi3 32-bit unsigned modulo division.

_lmul 64-bit multiply.

Shifts

__ashldi3 Arithmetic and Logical shift left.

__ashrdi3 Arithmetic shift right.

__lshrdi3 Logical shift right.

Memory _memcopy implicit memcopy call.

Conversions

__fixdfdi Converts double to 64-bit Signed Integer.

__fixdfsi Converts double to 32-bit Signed Integer.

__fixsfdi Converts float to 64-bit Signed Integer.

__fixsfsi Converts float to 32-bit Signed Integer.

__fixunsdfdi Converts double to 64-bit Unsigned Integer.

__fixunsdfsi Converts double to 32-bit Unsigned Integer.

__fixunssfdi Converts float to 64-bit Unsigned Integer.

__fixunssfsi Converts float to 32-bit Unsigned Integer.

__floatdidf Converts from 64-bit Signed Integer to double..

__floatsidf Converts from 32-bit Signed Integer to double.

__floatdisf Converts from 64-bit Signed Integer to float.

__floatsisf Converts from 32-bit Signed Integer to float.

__floatunsdidf Converts from 64-bit Unsigned Integer to double.

__floatunssidf Converts from 32-bit Unsigned Integer to double.

__floatunsdisf Converts from 64-bit Unsigned Integer to float.

__floatunssisf Converts from 32-bit Unsigned Integer to float.



13.7.3 __adddf3

Syntax: double__adddf3(double x, double y);

Description: The function __adddf3 adds two 64-bit double precision floating point values to form a 64-bit double precision floating point result. The result is x+y. Both x and y may be any valid double precision values.

Example 266. Function __adddf3

#include <stdio.h>int main(void){ double x = .5, y = 10.;

printf("The value of %.2lf + %.2lf is %.2lf\n", x, y, __adddf3(x, y));

return 0;}


The value of 0.50 + 10.00 is 10.50

Further Information:Section 13.7.7, “__divdf3” on page 532Section 13.7.41, “__muldf3” on page 579Section 13.7.47, “__subdf3” on page 587Section 13.7.44, “__negdf2” on page 583Section 13.7.56, “ftp8” on page 597

Diagnostics:

Underflow The result becomes zero if it is too small to be held as a double precision floating point value. +0 for positive, and –0 for negative values.

Overflow The result becomes infinity if it is too large to be held as a double precision floating point value. +• for positive, and -• for negative values.

InfinityIf one or both inputs are +infinity the result is +infinity. If one or both inputs are –infinity the result is –infinity. If one input is +infinity and the other –infinity, a NaN is produced.

NaNs If either or both inputs are NaNs, this produces a NaN. If one input is +infinity and the other –infinity, a NaN is produced.



13.7.4 __addsf3

Syntax: float__addsf3(float x, float y);

Description: The function __addsf3 adds two 32-bit single precision floating point values together to form a 32-bit single precision floating point result. The result is x+y. Both x and y may be any valid single precision values.

Example 267. Function __addsf3

#include <stdio.h>

int main(void){ float x = .5, y = 10;

printf("The value of %.2f + %.2f is %.2f\n", x, y, __addsf3(x, y));

return 0;}


The value of 0.50 + 10.00 is 10.50

Further Information:Section 13.7.9, “__divsf3” on page 534Section 13.7.42, “__mulsf3” on page 580Section 13.7.45, “__negsf2” on page 584Section 13.7.48, “__subsf3” on page 588

Diagnostics:

Underflow The result becomes zero if it is too small to be held as a single precision floating point value. +0 for positive, and –0 for negative values.

Overflow The result becomes infinity if it is too large to be held as a single precision floating point value. +• for positive, and -• for negative values.

InfinityIf one or both inputs are +infinity the result is +infinity. If one or both inputs are –infinity the result is –infinity. If one input is +infinity and the other –infinity, a NaN is produced.

NaNs If either or both inputs are NaNs, this produces a NaN. If one input is +infinity and the other –infinity, a NaN is produced.



13.7.5 __ashldi3

Syntax: long long__ashldi3(long long x, unsigned long long y);

Description: The function __ashldi3 carries out an Arithmetic/Logical shift left. The argument xis shifted left y value of times, and the result returned. Shifting by more than 64 places will result in a zero result. The x value to be shifted is any valid 64-bit signed integer, while the value of times to be shifted y may be any valid 64-bit unsigned integers.

Example 268. Function __ashldi3

#include <stdio.h>

int main(void){ long long x = 0x800; unsigned long long y = 3;

printf("The value of %lx shifted %lu times is %lx\n", x, y, __ashldi3(x, y));

return 0;}


The value of 0x800 shifted 3 times is 0x100

Further Information:Section 13.7.6, “__ashrdi3” on page 531Section 13.7.36, “__lshrdi3” on page 572



13.7.6 __ashrdi3

Syntax: long long__ashrdi3(long long x, unsigned long long y);

Description: The function __ashrdi3 carries out an arithmetic shift right, that is the most significant bit remains the same as the shift is carried out. Hence a negative value (most significant bit set) remains a negative value after the shift. The argument x is shifted right y value of times, and the result returned. Shifting by more than 64 places will result in a zero result. The x value to be shifted is any valid 64-bit signed integer, while the value of times to be shifted y may be any valid 64-bit unsigned integer.

Example 269. Function __ashrdi3

#include <stdio.h>

int main(void){ long long x = -0x800; unsigned long long y = 3;

printf("The value of %lx shifted %lu times is %ld\n", x, y, __ashrdi3(x, y));

return 0;}


The value of -0x800 shifted 3 times is -256

Further Information:Section 13.7.5, “__ashldi3” on page 530Section 13.7.36, “__lshrdi3” on page 572



13.7.7 __divdf3

Syntax: double__divdf3(double x, double y);

Description: The function __divdf3 divides one 64-bit double precision floating point value with another to form a 64-bit double precision floating point result. The result is x/y. Both x and y may be any valid double precision values.

Example 270. Function __divdf3

#include <stdio.h>


printf("The value of %.2lf / %.2lf is %.2lf\n", x, y, __divdf3(x, y));

return 0;}


The value of 0.50 / 10.00 is 0.05

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.41, “__muldf3” on page 579Section 13.7.44, “__negdf2” on page 583Section 13.7.47, “__subdf3” on page 587Section 13.7.56, “ftp8” on page 597

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a double precision floating point value. +• for positive, and -• for negative values.

Infinity A numerator of ±infinity produces ±infinity. Dividing by zero will produce infinity. Dividing by infinity produces zero. Dividing infinity by infinity produces a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. Dividing zero by zero produces a NaN. Dividing infinity by infinity produces a NaN.



13.7.8 __divdi3

Syntax: long long__divdi3(long long x, long long y);

Description: The function __divdi3 carries out an integer division of one 64-bit signed integer value by another to form a 64-bit signed integer result. The result is integer x/y. Both x and y may be any valid 64-bit signed integers.

Example 271. Function __divdi3

#include <stdio.h>

int main(void){ long long x = -7, y = -2;

printf("The value of integer %ld / %ld is %ld\n", x, y, __divdi3(x, y));

return 0;}


The value of integer -7 / -2 is 3

Further Information:Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0x7FFFFFFFFFFFFFFF.



13.7.9 __divsf3

Syntax: float__divsf3(float x, float y);

Description: The function __divsf3 divides one 32-bit single precision floating point value with another to form a 32-bit single precision floating point result. The result is x/y. Both x and y may be any valid single precision values.

Example 272. Function __divsf3

#include <stdio.h>

int main(void){ float x = .5, y = 10;

printf("The value of %.2f / %.2f is %.2f\n", x, y, __divsf3(x, y));

return 0;}


The value of 0.50 / 10.00 is 0.05

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.42, “__mulsf3” on page 580Section 13.7.45, “__negsf2” on page 584Section 13.7.48, “__subsf3” on page 588

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a single precision floating point value. +• for positive, and -• for negative values.

Infinity A numerator of ±infinity produces ±infinity. Dividing by zero will produce infinity. Dividing by infinity produces zero. Dividing infinity by infinity produces a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. Dividing zero by zero produces a NaN. Dividing infinity by infinity produces a NaN.



13.7.10 __divsi3

Syntax: long__divsi3(long x, long y);

Description: The function __divsi3 carries out an integer division of one 32-bit signed integer with another to form a 32-bit signed integer result. The result is integer x/y. Both x and y may be any valid 32-bit signed integers.

Example 273. Function __divsi3

#include <stdio.h>

int main(void){ long x = -7, y = 2;

printf("The value of integer %d / %d is %d\n", x, y, __divsi3(x, y));

return 0;}


The value of integer -7 / 2 is -3

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0x7FFFFFFF.



13.7.11 __eqdf2

Syntax: long__eqdf2(double x, double y);

Description: The function __eqdf2 compares two 64-bit double precision floating point values for equality, returning the result as a 32-bit signed integer. The function calculate x-y, setting the return value according to the result, the result itself being thrown away. Both x and y may be any valid double precision values.

The return from this function is:

Value Description

0 If equal.

1 If not equal, or an operand is a NaN.

Diagnostics:

Zero Comparison of two zeros, one positive and the other negative are deemed to be equal.

Infinity Comparison of two positive infinities, or two negative infinities will result in them being equal. But a positive infinity is not equal to a negative infinity.

NaNs If either or both inputs are NaNs, the result is considered to be unordered which results in the N,Z and Q flags being cleared and the C and V flags being set.



Example 274. Function __eqdf2

#include <stdio.h>

int main(void){ double x = 1.2345, y = 6.7;

if( __eqdf2(x, y) == 0) printf("%.2lf is equal to %.2lf\n", x, y); else printf("%.2lf is not equal to %.2lf\n", x, y); return 0;}


1.23 is not equal to 6.70

Further Information:Section 13.7.30, “__gedf2” on page 560Section 13.7.32, “__gtdf2” on page 564Section 13.7.34, “__ledf2” on page 568Section 13.7.37, “__ltdf2” on page 573Section 13.7.43, “__nedf2” on page 581



13.7.12 __eqsf2

Syntax: long__eqsf2(float x, float y);

Description: The function __eqsf2 compares two 32-bit single precision floating point values for equality,returning the result as a 32-bit signed integer. The function calculates x-y, and sets the return values according to the result, the result itself being thrown away. Both x and y may be any valid single precision values.


Value Description

0 if equal.

1 if not equal, or an operand is a NaN.

Diagnostics:






Example 275. Function __eqsf2

#include <stdio.h>

int main(void){ float x = 1.234, y = 2.468;

if( __eqsf2(x, y) == 0) printf("%.2lf is equal to %.2f\n", x, y); else printf("%.2lf is not equal to %.2f\n", x, y); return 0;}



Further Information:Section 13.7.31, “__gesf2” on page 562Section 13.7.33, “__gtsf2” on page 566Section 13.7.35, “__lesf2” on page 570Section 13.7.38, “__ltsf2” on page 575Section 13.7.46, “__nesf2” on page 585



13.7.13 __extendsfdf2

Syntax: double__extendsfdf2(float x);

Description: The function __extendsfdf2 converts a 32-bit single precision floating point value into a 64-bit double precision floating point value. The argument x may be any valid single precision floating point value, and the function returns a double precision floating point value.

Example 276. Function __extendsfdf2

#include <stdio.h>

int main(void){ float x = -1.5234;

printf("The double precision value of %.4f is %.9lf\n", x, __extendsfdf2(x));

return 0;}


The double precision value of -1.5234 is -1.523400000

Diagnostics:

Infinity If the given operand is ±infinity, the result will be ±infinity.

NaNs If the given operand is a NaN, the result will be a NaN.



Further Information:Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.22, “__floatdidf” on page 552Section 13.7.23, “__floatdisf” on page 553Section 13.7.24, “__floatsidf” on page 554Section 13.7.25, “__floatsisf” on page 555Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.28, “__floatunssidf” on page 558Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589



13.7.14 __fixdfdi

Syntax: long long__fixdfdi(double x);

Description: The function __fixdfdi converts a 64-bit double precision floating point value into a 64-bit signed integer. The argument x may be any valid double precision value.

Example 277. Function __fixdfdi

#include <stdio.h>

int main(void){ double x = -0.54321e12;

printf("The value %lf expressed as an integer is %ld\n", x, __fixdfdi(x)); return 0;}


The value -0.54321e12 expressed as an integer is -543210000000

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than –263, the result is forced to the hexadecimal value 0x8000000000000000. If the result after rounding is greater than 263 – 1, the result is forced to the hexadecimal value 0x7FFFFFFFFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x8000000000000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0x7FFFFFFFFFFFFFFF.

NaNs If the given operand is a NaN, the result is forced to the hexadecimal value 0x0000000000000000.

In Range Accuracy of the result may suffer if an exact conversion cannot be made.



13.7.15 __fixdfsi

Syntax: long__fixdfsi(double x);

Description: The function __fixdfsi converts a 64-bit double precision floating point value into a 32-bit signed integer. The argument x may be any valid double precision value.

Example 278. Function __fixdfsi

#include <stdio.h>

int main(void){ double x = -0.54321e6;

printf("The value %lf expressed as an integer is %d\n", x, __fixdfsi(x)); return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than –231, the result is forced to the hexadecimal value 0x80000000. If the result after rounding is greater than 231 – 1, the result is forced to the hexadecimal value 0x7FFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x80000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0x7FFFFFFF.





13.7.16 __fixsfdi

Syntax: long long__fixsfdi(float x);

Description: The function __fixsfdi converts a 32-bit single precision floating point value into a 64-bit signed integer. The argument x may be any valid single precision value.

Example 279. Function __fixsfdi

#include <stdio.h>

int main(void){ float x = -0.54321e12;

printf("The value %f expressed as an integer is %ld\n", x, __fixsfdi(x));

return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553

Diagnostics:

Out of RangeIf the result after rounding is less than –263, the result is forced to the hexadecimal value 0x8000000000000000. If the result after rounding is greater than 263 – 1, the result is forced to the hexadecimal value 0x7FFFFFFFFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x8000000000000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0x7FFFFFFFFFFFFFFF.





Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589



13.7.17 __fixsfsi

Syntax: long__fixsfsi(float x);

Description: The __fixsfsi function converts a 32-bit single precision floating point value into a 32-bit signed integer. The argument x may be any valid single precision value.

Example 280. Function __fixsfsi

#include <stdio.h>

int main(void){ float x = -0.54321e6;

printf("The value %f expressed as an integer is %d\n", x, __fixsfsi(x)); return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than –231, the result is forced to the hexadecimal value 0x80000000. If the result after rounding is greater than 231 – 1, the result is forced to the hexadecimal value 0x7FFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x80000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0x7FFFFFFF.





13.7.18 __fixunsdfdi

Syntax: unsigned long long__fixunsdfdi(double x);

Description: The function __fixunsdfdi converts a 64-bit double precision floating point value into a 64-bit unsigned integer. The argument x may be any valid positive double precision value.

Example 281. Function __fixunsdfdi

#include <stdio.h>

int main(void){ double x = 0.54321e12;

printf("The value %lf expressed as an integer is %lu\n", x, __fixunsdfdi(x));

return 0;}


The value 0.54321e12 expressed as an integer is 543210000000

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552

Diagnostics:

Out of RangeIf the result after rounding is less than 0, the result is forced to the hexadecimal value 0x0000000000000000. If the result after rounding is greater than 264 – 1, the result is forced to the hexadecimal value 0xFFFFFFFFFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x0000000000000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0xFFFFFFFFFFFFFFFF.





Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589



13.7.19 __fixunsdfsi

Syntax: unsigned long__fixunsdfsi(double x);

Description: The function __fixunsdfsi converts a 64-bit double precision floating point value into a 32-bit unsigned integer. The argument x may be any valid positive double precision value.

Example 282. Function __fixunsdfsi

#include <stdio.h>


printf("The value %lf expressed as an integer is %u\n", x, __fixunsdfsi(x)); return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.22, “__floatdidf” on page 552Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than 0, the result is forced to the hexadecimal value 0x00000000. If the result after rounding is greater than 232 – 1, the result is forced to the hexadecimal value 0xFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x00000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0xFFFFFFFF.





13.7.20 __fixunssfdi

Syntax: unsigned long long__fixunssfdi(float x);

Description: The function __fixunssfdi converts a 32-bit single precision floating point value into a 64-bit unsigned integer. The argument x may be any valid positive single precision value.

Example 283. Function __fixunssfdi

#include <stdio.h>

int main(void){ float x = 0.54321e12;

printf("The value %f expressed as an integer is %lu\n", x, __fixunssfdi(x));

return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than 0, the result is forced to the hexadecimal value 0x0000000000000000. If the result after rounding is greater than 264 – 1, the result is forced to the hexadecimal value 0xFFFFFFFFFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x0000000000000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0xFFFFFFFFFFFFFFFF.





13.7.21 __fixunssfsi

Syntax: unsigned long__fixunssfsi(float x);

Description: The function __fixunssfsi converts a 32-bit single precision floating point value into a 32-bit unsigned integer. The argument x may be any valid positive single precision value.

Example 284. Function __fixunssfsi

#include <stdio.h>

int main(void){ float x = 0.54321e6;

printf("The value %f expressed as an integer is %u\n", x, __fixunssfsi(x)); return 0;}



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.23, “__floatdisf” on page 553Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Out of RangeIf the result after rounding is less than 0, the result is forced to the hexadecimal value 0x00000000. If the result after rounding is greater than 232 – 1, the result is forced to the hexadecimal value 0xFFFFFFFF.

InfinityIf the given operand is -infinity, the result is forced to the hexadecimal value 0x00000000. If the given operand is +infinity, the result is forced to the hexadecimal value 0xFFFFFFFF.





13.7.22 __floatdidf

Syntax: double__floatdidf(long long x);

Description: The function __floatdidf converts a 64-bit signed integer into a 64-bit double precision floating point value. The argument x may be any valid 64-bit signed integer.

Example 285. Function __floatdidf

#include <stdio.h>

int main(void){ long long x = -12345;

printf("The value %ld expressed as a double is %.6lf\n", x, __floatdidf(x)); return 0;}


The value -12345 expressed as a double is -1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:

Zero A given integer of 0 will result in +0.0




13.7.23 __floatdisf

Syntax: float__floatdisf(long long x);

Description: The function __floatdisf converts a 64-bit signed integer into a 32-bit single precision floating point value. The argument x may be any valid 64-bit signed integer.

Example 286. Function __floatdisf

#include <stdio.h>

int main(void){ long long x = -12345;

printf("The value %ld expressed as a float is %.6f\n", x, __floatdisf(x)); return 0;}


The value -12345 expressed as a float is -1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.24 __floatsidf

Syntax: double__floatsidf(long x);

Description: The function __floatsidf converts a 32-bit signed integer into a 64-bit double precision floating point value. The argument x may be any valid 32-bit signed integer.

Example 287. Function __floatsidf

#include <stdio.h>

int main(void){ unsigned long x = -12345;

printf("The value %d expressed as a double is %.6lf\n", x, __floatsidf(x)); return 0;}


The value -12345 expressed as a double is -1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.25 __floatsisf

Syntax: float__floatsisf(long x);

Description: The function __floatsisf converts a 32-bit signed integer into a 32-bit single precision floating point value. The argument x may be any valid 32-bit signed integer.

Example 288. Function __floatsisf

#include <stdio.h>

int main(void){ unsigned long x = -12345;

printf("The value %d expressed as a float is %.6f\n", x, __floatsisf(x)); return 0;}


The value -12345 expressed as a float is -1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.26 __floatunsdidf

Syntax: double__floatunsdidf(unsigned long long x);

Description: The function __floatunsdidf converts a 64-bit unsigned integer into a 64-bit double precision floating point value. The argument x may be any valid 64-bit unsigned integer.

Example 289. Function __floatunsdidf

#include <stdio.h>

int main(void){ unsigned long x = 12345;

printf("The value %lu expressed as a double is %.6lf\n", x, __floatunsdidf(x)); return 0;}


The value 12345 expressed as a double is 1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552Section 13.7.24, “__floatsidf” on page 554Section 13.7.28, “__floatunssidf” on page 558Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.27 __floatunsdisf

Syntax: float__floatunsdisf(unsigned long long x);

Description: The function __floatunsdisf converts a 64-bit unsigned integer into a 32-bit single precision floating point value. The argument x may be any valid 64-bit unsigned integer.

Example 290. Function __floatunsdisf

#include <stdio.h>


printf("The value %lu expressed as a float is %.6f\n", x, __floatunsdisf(x)); return 0;}


The value 12345 expressed as a float is 1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553Section 13.7.25, “__floatsisf” on page 555Section 13.7.29, “__floatunssisf” on page 559Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.28 __floatunssidf

Syntax: double__floatunssidf(unsigned long x);

Description: The function __floatunssidf converts a 32-bit unsigned integer into a 64-bit double precision floating point value. The argument x may be any valid 32-bit unsigned integer.

Example 291. Function __floatunssidf

#include <stdio.h>


printf("The value %u expressed as a double is %.6lf\n", x, __floatunssidf(x)); return 0;}


The value 12345 expressed as a double is 1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.22, “__floatdidf” on page 552Section 13.7.24, “__floatsidf” on page 554Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.29 __floatunssisf

Syntax: float__floatunssisf(unsigned long x);

Description: The function __floatunssisf converts a 32-bit unsigned integer into a 32-bit single precision floating point value. The argument x may be any valid 32-bit unsigned integer.

Example 292. Function __floatunssisf

#include <stdio.h>


printf("The value %u expressed as a float is %.6f\n", x, __floatunssisf(x)); return 0;}


The value 12345 expressed as a float is 1.234500e4

Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.23, “__floatdisf” on page 553Section 13.7.25, “__floatsisf” on page 555Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.49, “__truncdfsf2” on page 589

Diagnostics:





13.7.30 __gedf2

Syntax: long__gedf2(double x, double y);

Description: The function __gedf2 compares two 64-bit double precision floating point values being greater than or equal to, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid double precision values.

The return value of this function is:

Value Description

-1 if x is less than y, or an operand is a NaN.

0 if x is equal to y.

1 if x is greater than y.

Diagnostics:



NaNs If either or both inputs are NaNs, the result is considered to be unordered which results in the N, Z and Q flags being cleared and the C and V flags being set.



Example 293. Function __gedf2

#include <stdio.h>


if( __gedf2(x, y) >= 0) printf("%.2lf is greater than or equal to %.2lf\n", y, x); else printf("%.2lf is less than %.2lf\n", y, x); return 0;}


6.70 is greater than or equal to 1.23

Further Information:Section 13.7.11, “__eqdf2” on page 536Section 13.7.32, “__gtdf2” on page 564Section 13.7.34, “__ledf2” on page 568Section 13.7.37, “__ltdf2” on page 573Section 13.7.43, “__nedf2” on page 581



13.7.31 __gesf2

Syntax: long__gesf2(float x, float y);

Description: The function __gesf2 compares two 32-bit single precision floating point values on being greater than or equal to, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid single precision values.


Value Description




Diagnostics:






Example 294. Function __gesf2

#include <stdio.h>


if( __gesf2(x, y) >= 0) printf("%.2f is greater than or equal to %.2f\n", y, x); else printf("%.2f is less than %.2f\n", y, x); return 0;}


6.70 is less than 12.35

Further Information:Section 13.7.12, “__eqsf2” on page 538Section 13.7.33, “__gtsf2” on page 566Section 13.7.35, “__lesf2” on page 570Section 13.7.38, “__ltsf2” on page 575Section 13.7.46, “__nesf2” on page 585



13.7.32 __gtdf2

Syntax: long__gtdf2(double x, double y);

Description: The function __gtdf2 compares two 64-bit double precision floating point values for being greater than, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid double precision values.


Value Description




Diagnostics:






Example 295. Function __gtdf2

#include <stdio.h>


if( __gtdf2(x, y) > 0) printf("%.2lf is greater than %.2lf\n", y, x); else printf("%.2lf is less than or equal to %.2lf\n", y, x); return 0;}


6.70 is greater than 1.23

Further Information:Section 13.7.11, “__eqdf2” on page 536Section 13.7.30, “__gedf2” on page 560Section 13.7.34, “__ledf2” on page 568Section 13.7.37, “__ltdf2” on page 573Section 13.7.43, “__nedf2” on page 581



13.7.33 __gtsf2

Syntax: long__gtsf2(float x, float y);

Description: The function __gtsf2 compares two 32-bit single precision floating point values for being greater than, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid single precision values.


Value Description




Diagnostics:



NaN If either or both inputs are NaNs, the result is considered to be unordered which results in the N,Z and Q flags being cleared and the C and V flags being set.



Example 296. Function __gtsf2

#include <stdio.h>


if( __gtsf2(x, y) > 0) printf("%.2f is greater than %.2f\n", y, x); else printf("%.2f is less than or equal to %.2f\n", y, x); return 0;}


6.70 is less than or equal to 12.35

Further Information:Section 13.7.12, “__eqsf2” on page 538Section 13.7.31, “__gesf2” on page 562Section 13.7.35, “__lesf2” on page 570Section 13.7.38, “__ltsf2” on page 575Section 13.7.46, “__nesf2” on page 585



13.7.34 __ledf2

Syntax: long__ledf2(double x, double y);

Description: The function __ledf2 compares two 64-bit double precision floating point values being less than or equal to, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid double precision values.


Value Description

-1 If x is less than y.


1 if x is greater than y, or an operand is a NaN.

Diagnostics:






Example 297. Function __ledf2

#include <stdio.h>


if( __ledf2(x, y) <= 0) printf("%.2lf is less than or equal to %.2lf\n", y, x); else printf("%.2lf is greater than %.2lf\n", y, x); return 0;}


6.70 is greater than 1.23

Further Information:Section 13.7.11, “__eqdf2” on page 536Section 13.7.30, “__gedf2” on page 560Section 13.7.32, “__gtdf2” on page 564Section 13.7.37, “__ltdf2” on page 573Section 13.7.43, “__nedf2” on page 581



13.7.35 __lesf2

Syntax: long__lesf2(float x, float y);

Description: The function __lesf2 compares two 32-bit single precision floating point values being less than or equal to, returning the result as a 32-bit signed integer. The function carries out x-y,setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid single precision values.


Value Description




Diagnostics:






Example 298. Function __lesf2

#include <stdio.h>


if( __lesf2(x, y) <= 0) printf("%.2f is less than or equal to %.2f\n", y, x); else printf("%.2f is greater than %.2f\n", y, x); return 0;}


6.70 is less than or equal to 12.35

Further Information:Section 13.7.12, “__eqsf2” on page 538Section 13.7.31, “__gesf2” on page 562Section 13.7.33, “__gtsf2” on page 566Section 13.7.38, “__ltsf2” on page 575Section 13.7.46, “__nesf2” on page 585



13.7.36 __lshrdi3

Syntax: long long__lshrdi3(long long x, unsigned long long y);

Description: The function __lshrdi3 carries out a logical shift right. The argument x is shifted right y value of times, and the result returned. Shifting by 64 or more places will yield a zero result. The x value to be shifted is any valid 64-bit signed integer, while the value of times to be shifted y may be any valid 64-bit unsigned integer.

Example 299. Function __lshrdi3

#include <stdio.h>

int main(void){ unsigned long x = 0x800; unsigned long y = 3;

printf("The value %ld shifted %lu times is %ld\n", x, y, __lshrdi3(x, y));

return 0;}


The value of 2048 shifted 3 times is 256

Further Information:Section 13.7.5, “__ashldi3” on page 530Section 13.7.6, “__ashrdi3” on page 531



13.7.37 __ltdf2

Syntax: long__ltdf2(double x, double y);

Description: The function __ltdf2 compares two 64-bit double precision floating point values being less than, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid double precision values.


Value Description

-1 x is less than y.



Diagnostics:






Example 300. Function __ltdf2

#include <stdio.h>


if( __ltdf2(x, y) < 0) printf("%.2lf is less than %.2lf\n", y, x); else printf("%.2lf is greater than or equal to %.2lf\n", y, x); return 0;}


6.70 is greater than or equal to 1.23

Further Information:Section 13.7.11, “__eqdf2” on page 536Section 13.7.30, “__gedf2” on page 560Section 13.7.22, “__floatdidf” on page 552Section 13.7.34, “__ledf2” on page 568Section 13.7.43, “__nedf2” on page 581



13.7.38 __ltsf2

Syntax: long__ltsf2(float x, float y);

Description: The function __ltsf2 compares two 32-bit single precision floating point values for the first being greater than the second, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid single precision values.


Value Description




Diagnostics:






Example 301. Function __ltsf2

#include <stdio.h>


if( __ltsf2(x, y) < 0) printf("%.2f is less than %.2f\n", y, x); else printf("%.2f is greater than or equal to %.2f\n", y, x); return 0;}


6.70 is less than 12.35

Further Information:Section 13.7.12, “__eqsf2” on page 538Section 13.7.31, “__gesf2” on page 562Section 13.7.33, “__gtsf2” on page 566Section 13.7.35, “__lesf2” on page 570Section 13.7.46, “__nesf2” on page 585



13.7.39 __moddi3

Syntax: long long__moddi3(long long x, long long y);

Description: The function __moddi3 carries out a modulus division of one 64-bit signed integer value by another to form a 64-bit signed integer result. The result is integer remainder of x/y. Both x and y may be any valid 64-bit signed integers.

Example 302. Function __moddi3

#include <stdio.h>

int main(void){ long x = -7, y = -2;

printf("The remainder of %ld / %ld is %ld\n", x, y, __moddi3(x, y));

return 0;}


The remainder of -7 / -2 is -1

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0x7FFFFFFFFFFFFFFF.



13.7.40 __modsi3

Syntax: long__modsi3(long x, long y);

Description: The function __modsi3 carries out a modulus division of one 32-bit signed integer value by another to form a 32-bit signed integer result. The result is integer remainder of x/y.Both x and y may be any valid 32-bit signed integers.

Example 303. Function __modsi3

#include <stdio.h>

int main(void){ long x = -11, y = 3;

printf("The remainder of %d / %d is %d\n", x, y, __modsi3(x, y));

return 0;}


The remainder of -11 / 3 is -2

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0x7FFFFFFF.



13.7.41 __muldf3

Syntax: double__muldf3(double x, double y);

Description: The function __muldf3 multiplies two 64-bit double precision floating point values to form a 64-bit double precision floating point result.

Example 304. Function __muldf3

#include <stdio.h>


printf("The value of %.2lf * %.2lf is %.2lf\n", x, y, __muldf3(x, y));

return 0;}


The value of 0.50 * 10.00 is 5.00

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.7, “__divdf3” on page 532Section 13.7.44, “__negdf2” on page 583Section 13.7.47, “__subdf3” on page 587Section 13.7.56, “ftp8” on page 597

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a double precision floating point value. +∞ for positive, and -∞ for negative values.

InfinityIf both inputs are ±infinity, this produces ±infinity with the correct sign. If one input is ±infinity with the other a non-zero value, this produces ±infinity with the correct sign. If one input is zero and the other ±infinity, this produces a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. If one input is zero and the other ±infinity, this produces a NaN.



13.7.42 __mulsf3

Syntax: float__mulsf3(float x, float y);

Description: The function __mulsf3 multiplies two 32-bit single precision floating point values to form a 32-bit single precision floating point result.

Example 305. Function __mulsf3

#include <stdio.h>

int main(void){ float x = .5, y = 10.;

printf("The value of %.2f * %.2f is %.2f\n", x, y, __mulsf3(x, y));

return 0;}


The value of 0.50 * 10.00 is 5.00

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.9, “__divsf3” on page 534Section 13.7.45, “__negsf2” on page 584Section 13.7.48, “__subsf3” on page 588

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a single precision floating point value. +∞ for positive, and -∞ for negative values.

InfinityIf both inputs are ±infinity, this produces ±infinity with the correct sign. If one input is ±infinity with the other a non-zero value, this produces ±infinity with the correct sign. If one input is zero and the other ±infinity, this produces a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. If one input is zero and the other ±infinity, this produces a NaN.



13.7.43 __nedf2

Syntax: long__nedf2(double x, double y);

Description: The function __nedf2 compares two 64-bit double precision floating point values, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid double precision values.


Value Description

0 if x is equal to y, or an operand is a NaN.

1 if x is not equal to y.

Diagnostics:






Example 306. Function __nedf2

#include <stdio.h>


if( __nedf2(x, y)) printf("%.2lf is not equal to %.2lf\n", x, y); else printf("%.2lf is equal to %.2lf\n", x, y); return 0;}



Further Information:Section 13.7.11, “__eqdf2” on page 536Section 13.7.30, “__gedf2” on page 560Section 13.7.32, “__gtdf2” on page 564Section 13.7.34, “__ledf2” on page 568Section 13.7.37, “__ltdf2” on page 573



13.7.44 __negdf2

Syntax: double__negdf2(double x);

Description: The function __negdf2 negates a 64-bit double precision floating point value. Its sign is changed. The given argument x may be any valid double precision floating point value, and the function returns a double precision floating point value.

Example 307. Function __negdf2

#include <stdio.h>


printf("The negative value of %.2lf is %.2lf\n", x, __negdf2(x));

return 0;}


The negative value of 9.579711e7 is -9.579711e7

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.7, “__divdf3” on page 532Section 13.7.41, “__muldf3” on page 579Section 13.7.47, “__subdf3” on page 587Section 13.7.56, “ftp8” on page 597



13.7.45 __negsf2

Syntax: float__negsf2(float x);

Description: The function __negsf2 negates a 32-bit single precision floating point value. Its sign is changed. The given argument x may be any valid single precision floating point value, and the function returns a single precision floating point value.

Example 308. Function __negsf2

#include <stdio.h>

int main(void){ float x = 1.2345;

printf("The negative value of %.2f is %.2f\n", x, __negsf2(x));

return 0;}


The negative value of 1.23 is -1.23

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.9, “__divsf3” on page 534Section 13.7.42, “__mulsf3” on page 580Section 13.7.48, “__subsf3” on page 588



13.7.46 __nesf2

Syntax: long__nesf2(float x, float y);

Description: The function __nesf2 compares two 32-bit single precision floating point values, returning the result as a 32-bit signed integer. The function carries out x-y, setting the return value according to the result, the result itself being thrown away. The parameters x and y may be any valid single precision values.


Value Description

0 if x is equal to y, or an operand is a NaN.

1 if x is not equal to y.

Diagnostics:






Example 309. Function __nesf2

#include <stdio.h>


if( __nesf2(x, y)) printf("%.2lf is not equal to %.2f\n", x, y); else printf("%.2lf is equal to %.2f\n", x, y); return 0;}


1.23 is equal to 1.23

Further Information:Section 13.7.12, “__eqsf2” on page 538Section 13.7.31, “__gesf2” on page 562Section 13.7.33, “__gtsf2” on page 566Section 13.7.35, “__lesf2” on page 570Section 13.7.38, “__ltsf2” on page 575



13.7.47 __subdf3

Syntax: double__subdf3(double x, double y);

Description: The function __subdf3 subtracts one 64-bit double precision floating point value from another to form a 64-bit double precision floating point result. The result is x-y. Both x and y may be any valid double precision values.

Example 310. Function __subdf3

#include <stdio.h>


printf("The value of %.2lf - %.2lf is %.2lf\n", x, y, __subdf3(x, y));

return 0;}


The value of 0.50 - 10.00 is -9.50

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.7, “__divdf3” on page 532Section 13.7.41, “__muldf3” on page 579Section 13.7.44, “__negdf2” on page 583Section 13.7.56, “ftp8” on page 597

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a double precision floating point value. +∞ for positive, and -∞ for negative values.

InfinityIf only one input is +infinity the result is +infinity. If only one input is –infinity the result is –infinity. +infinity minus –infinity produces +infinity. –infinity minus +infinity produces –infinity. If both inputs are +infinity, or both –infinity the result is a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. If both inputs are +infinity, or both –infinity the result is a NaN.



13.7.48 __subsf3

Syntax: float__subsf3(float x, float y);

Description: The function __subsf3 subtracts one 32-bit single precision floating point value from another to form a 32-bit single precision floating point result. The result is x-y. Both x and y may be any valid single precision values.

Example 311. Function __subsf3

#include <stdio.h>

int main(void){ float x = .5, y = 10.;

printf("The value of %.2f - %.2f is %.2f\n", x, y, __subsf3(x, y));

return 0;}


The value of 0.50 - 10.00 is -9.50

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.9, “__divsf3” on page 534Section 13.7.42, “__mulsf3” on page 580Section 13.7.45, “__negsf2” on page 584

Diagnostics:


Overflow The result becomes infinity if it is too large to be held as a single precision floating point value. +∞ for positive, and -∞ for negative values.

InfinityIf only one input is +infinity the result is +infinity. If only one input is –infinity the result is –infinity. +infinity minus –infinity produces +infinity. –infinity minus +infinity produces –infinity. If both inputs are +infinity, or both –infinity the result is a NaN.

NaNs If either or both inputs are NaNs, this produces a NaN. If both inputs are +infinity, or both –infinity the result is a NaN.



13.7.49 __truncdfsf2

Syntax: float__truncdfsf2(double x);

Description: The function __truncdfsf2 converts a 64-bit double precision floating point value into a 32-bit single precision floating point value. The argument x may be any valid double precision floating point value, and the function returns a single precision floating point value.

Example 312. Function __truncdfsf2

#include <stdio.h>


printf("The single precision value of %.2lf is %.2f\n", x, __truncdfsf2(x));

return 0;}


The single precision value of 0.50 is 0.50

Diagnostics:

Out of Range If the value of the given operand is too large, the result will be ±infinity.

Infinity If the given operand is ±infinity, the result will be ±infinity.

NaNs If the given operand is a NaN, the result will be a NaN.



Further Information:Section 13.7.13, “__extendsfdf2” on page 540Section 13.7.14, “__fixdfdi” on page 542Section 13.7.15, “__fixdfsi” on page 543Section 13.7.16, “__fixsfdi” on page 544Section 13.7.17, “__fixsfsi” on page 546Section 13.7.18, “__fixunsdfdi” on page 547Section 13.7.19, “__fixunsdfsi” on page 549Section 13.7.20, “__fixunssfdi” on page 550Section 13.7.21, “__fixunssfsi” on page 551Section 13.7.22, “__floatdidf” on page 552Section 13.7.23, “__floatdisf” on page 553Section 13.7.24, “__floatsidf” on page 554Section 13.7.25, “__floatsisf” on page 555Section 13.7.26, “__floatunsdidf” on page 556Section 13.7.27, “__floatunsdisf” on page 557Section 13.7.28, “__floatunssidf” on page 558Section 13.7.29, “__floatunssisf” on page 559



13.7.50 __udivdi3

Syntax: unsigned long long__udivdi3(unsigned long long x, unsigned long long y);

Description: The function __udivdi3 carries out an integer division of one 64-bit unsigned integer value by another to form a 64-bit unsigned integer result. The result is integer x/y.Both x and y may be any valid 64-bit unsigned integers.

Example 313. Function __udivdi3

#include <stdio.h>

int main(void){ unsigned long long x = 7, y = 2;

printf("The value of integer %lu / %lu is %lu\n", x, y, __udivdi3(x, y));

return 0;}


The value of integer 7 / 2 is 3

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0xFFFFFFFFFFFFFFFF.



13.7.51 __udivsi3

Syntax: unsigned long__udivsi3(unsigned long x, unsigned long y);

Description: The function __udivsi3 carries out an integer division of one 32-bit unsigned integer value by another to form a 32-bit unsigned integer result. The result is integer x/y. Both x and y may be any valid 32-bit unsigned integers.

Example 314. Function __udivsi3

#include <stdio.h>

int main(void){ unsigned long x = 7, y = 2;

printf("The value of integer %u / %u is %u\n", x, y, __udivsi3(x, y));

return 0;}


The value of integer 7 / 2 is 3

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.52, “__umoddi3” on page 593Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0xFFFFFFFF.



13.7.52 __umoddi3

Syntax: unsigned long long__umoddi3(unsigned long long x, unsigned long long y);

Description: The function __umoddi3 carries out a modulus division of one 64-bit unsigned integer value by another to form a 64-bit unsigned integer result. The result being the remainder of the integer division product. Both x and y may be any valid 64-bit unsigned integers.

Example 315. Function __umoddi3

#include <stdio.h>

int main(void){ unsigned long long x = 7, y = 2;

printf("The remainder of integer %lu / %lu is %lu\n", x, y, __umoddi3(x, y));

return 0;}


The remainder of integer 7 / 2 is 1

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.53, “__umodsi3” on page 594

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0xFFFFFFFFFFFFFFFF.



13.7.53 __umodsi3

Syntax: unsigned long__umodsi3(unsigned long x, unsigned long y);

Description: The function __umodsi3 carries out a modulus division of one 32-bit unsigned integer value by another to form a 32-bit unsigned integer result. The result being the remainder of the integer division product. The result is integer remainder of x/y. Both x and y may be any valid 32-bit unsigned integers.

Example 316. Function __umodsi3

#include <stdio.h>

int main(void){ unsigned long x = 11, y = 3;

printf("The remainder of integer %u / %u is %u\n", x, y, __umodsi3(x, y));

return 0;}


The remainder of integer 11 / 3 is 2

Further Information:Section 13.7.8, “__divdi3” on page 533Section 13.7.10, “__divsi3” on page 535Section 13.7.39, “__moddi3” on page 577Section 13.7.40, “__modsi3” on page 578Section 13.7.50, “__udivdi3” on page 591Section 13.7.51, “__udivsi3” on page 592Section 13.7.52, “__umoddi3” on page 593

Diagnostics:

Divide by Zero The result becomes the largest value it can be 0xFFFFFFFF.



13.7.54 _lmul

Syntax: long long_lmul(long long x, long long y);

Description: The function _lmul multiplies two 64-bit signed integer values to form a 64-bit signed integer result.

Example 317. Function _lmul

#include <stdio.h>

int main(void){ long long x = -72, y = -3;

printf("The value of %ld * %ld is %ld\n", x, y, _lmul(x, y));

return 0;}


The value of integer -72 * -3 is 216

Further Information:Section 13.7.56, “ftp8” on page 597

Diagnostics:

Overflow The result becomes the largest value it can be 0x7FFFFFFFFFFFFFFF.




13.7.55 _memcopy

Syntax: unsigned long_memcopy(unsigned long dest, unsigned long source, unsigned long len);

Description: The function _memcopy copies one section of memory to another.

The address where to start copying to (the destination address) is taken from argument dest. The address from which the copying is to start (the source address) is taken from argument source. The number of bytes to copy is taken from argument len.

The data at memory address source is copied to the memory address dest. Then dest and source are incremented and the next byte is copied between them. This is repeated until the value of bytes copied is equal to the value len.

Since both dest and source are addresses, they must be 32-bit unsigned integers. The number of bytes to be copied, len, must be a positive value, therefore it too must be a 32-bit unsigned integer.

Warning: If the areas of memory being copied overlap and the source start address is before the destination start address (source<=dest<=source+len) then incorrect data will result.

Example 318. Function _memcopy

#include <stdio.h>

int main(void){ unsigned long x = 0x8000, y = 0x1000, z = 0x400;

printf("Destination address is %X\n", x ); printf("Source address is %X\n", y ); printf("Number of bytes to copy is %X\n", z ) printf("Final destination address is %X\n", _memcopy(x, y, z));

return 0;}

The program above produces the following output: Destination address is 0x8000

Source address is 0x1000

Number of bytes to copy is 0x400

Final destination address is 0x83FF

Further Information:Section 13.7.56, “ftp8” on page 597



13.7.56 ftp8

Syntax: longftp8(double x);

Description: The function ftp8 tests given argument x and returns an analysis. The value x being tested may be any valid 64-bit double precision floating point value.

The returned analysis is a 32-bit signed integer, whose bits are:

s000 0000 0000 0000 0000 0000 000N Idnz

where

Example 319. Function ftp8

#include <stdio.h>

int main(void){ double x = -1.67e31; printf("The analysis of %.2lf is %lx\n", x, ftp8( x )); return 0;}


The analysis of -1.67e31 is 0x8000002

Further Information:Section 13.7.3, “__adddf3” on page 528Section 13.7.7, “__divdf3” on page 532Section 13.7.41, “__muldf3” on page 579Section 13.7.47, “__subdf3” on page 587Section 13.7.44, “__negdf2” on page 583

s sign bit, 1 is negative, 0 is positive.

N if 1 then number is a NaN (Not a Number).

I if 1 then number is an infinity value.

d if 1 then number is a "de-normalized" number.

n if 1 then number is a "normal" number.

z if 1 then number has zero value.


Library-Target System Interface 14

This chapter describes the part of the C Standard Library which depends on the target system.


• Section 14.1, “Introduction to the Library-Target System Interface” on page 600 provides a brief introduction to the Library-Target System Interface. The Library-Target System Interface consists of the startup module and the System Library. An example demonstrates the usage of these target-dependent libraries.

• Section 14.2, “Startup Module” on page 603 describes the startup module. It defines the entry point of the application task. The definition of the task entry point is target-system dependent.

• Section 14.3, “ANSI-Defined System Interface Functions” on page 606 provides a detailed description of ANSI-defined system interface functions supported by the Intel® C++ Compiler, listed in alphabetical order.

• Section 14.4, “Non-ANSI System Interface Functions” on page 612 provides a detailed description of non-ANSI system interface functions supported by the Intel® C++ Compiler, listed in alphabetical order.


Library-Target System Interface

14.1 Introduction to the Library-Target System Interface

The library-target system interface is part of the C Standard Library which is target dependent. This part of the library must also be linked to your application; otherwise the application will not run on a specific target system.

The library-target system interface consists of the startup module and the System Library which is target dependent. The System Library contains a set of functions called system interface functions.

The startup module calls functions of the operating system and defines the entry point of the application task. An example file of a startup module is automatically installed in the directory

<installation-directory>\lib\<target>\

<target> specifies the target system; for example, if a target system in conjunction with the Intel® XDB Simulator Debugger is used, the directory name is angelswi.

The System Library contains system interface functions which you need to adapt to match your target system. Example source files are automatically installed in the directory

<installation-directory>\lib\<target>\

Several target specific system libraries are supplied. You can use the appropriate system libraries for your target system without adapting them

Figure 7. The System Library and Startup Module



Operating system



Example 320. C Application for the Intel® XDB Simulator Debugger

This example demonstrates how the C application mysource.c is compiled and linked to run on the Intel® XDB Simulator Debugger and how debug information is generated.

Note: It is assumed that the working directory containing mysource.c is located in the same directory as the directory \lib of the Intel® C++ Compiler,for example:


and

installation-directory\working-directory\mysource.c.


ccxsc -c -Zi mysource.c

This generates the outputfile mysource.o. The compiler option -Zi generates DWARF2.0 debug information.


ldxsc mysource.o ..\lib\angelswi\X0__A000.o ..\lib\X0__AC00.a ..\lib\angelswi\X0__AS00.a

where:



Example 321. C++ Application for the Intel® XDB Simulator Debugger

This example demonstrates how the C++ application mysource.cpp is compiled and linked to run on the Intel® XDB Simulator Debugger and how debug information is generated.

Note: It is assumed that the working directory containing mysource.cpp is located in the same directory as the directory \lib of the Intel® C++ Compiler, for example:


and

installation-directory\working-directory\mysource.cpp.

..\lib\angelswi\X0__A000.o Specifies the startup module.


..\lib\angelswi\X0__AS00.a Specifies the System Library.




ccxsc -c -Zi mysource.cpp

This generates the outputfile mysource.o. The compiler option -Zi generates DWARF2.0 debug information.


ldxsc -CPLUS mysource.o ..\lib\angelswi\X0__A000.o ..\lib\X0__AX00.a ..\lib\X0__AC00.a ..\lib\angelswi\X0__AS00.a

where:



Further Information:Intel® Linker User’s Manual

-CPLUS Is a required linker option for linking C++ applications.

..\lib\angelswi\X0__A000.o Specifies the startup module.

..\lib\X0__AX000.a Specifies the C++ Library.

..\lib\X0__AC00.a Specifies the C-Library.

..\lib\angelswi\X0__AS00.a Specifies the System Library



14.2 Startup Module

The startup module defines the entry point of the application task. The definition of the task entry point is target-system dependent. The most common method is to export a public symbol with a predefined name.

The startup module exports the following symbols:

Execution starts at the entry point. _start calls _libmain which initializes argc and argv, opens stdin, stdout and stderr, and calls the static constructors (if existing). Then, _libmain calls main(argc, argv).

Thus, startup code is required to perform the following actions in the listed order:

• Initialize registers

• Initialize malloc region and stack pointer.

• Set up the arguments that have to be passed to main and call function main().

• Call function exit and pass the return value of main to it.

It is user definable if arguments are passed to the main program. If no arguments are passed, main can be called immediately after the entry point confirming the following syntax:

int main(int argc, char *argv[]);

_start void _start(void) Entry point of the application

_div0 void _div0(void) Division by ZERO occurs

_mod0 void _mod0(void) Modulo by ZERO occurs

_ldiv0 void _ldiv0(void) Division by ZERO occurs

AngelSWI int AngelSWI (int code, void *buf) Software interrupt

__memsetdwzero long *__memsetdwzero(long *MemoryPointer, long FillValue, int NumberOfLongValues)

__CTORS_INFO void *__CTORS_INFO[2] Pointer to the beginning and the end of the ctors data section

__Environment__

char** __Environment__ Pointer to the environment array



The following constraints must be obeyed by argc and argv:

• The value of argc should be non-negative.

• argv[argc] should be a null pointer.

• If the value of argc is greater than zero, the array members argv[0] through argv[argc-1] inclusive should contain pointers to strings.

• If the value of argc is greater than zero, the string pointed to by argv[0] represents the program name or an empty string if the name cannot be supplied by the target system environment.

• The parameters argc and argv and the strings pointed to by the argv array should be modifiable by the program. They should also retain their stored values between program startup and program termination.

14.2.1 exit()

If function main does return, it returns to the startup code with a program termination code. In this case the startup code must call function exit() passing the return code from main to it. The syntax of exit() is listed below:

void exit(int);

Furthermore, a module must supply the function _exit() which performs the task termination in a system defined manner. This is commonly implemented as a system call which never returns.

Note: The _exit() function is called by the C library and should not be confused with the library function exit(), which exits the program in a ANSI-defined way. Function exit() should only be used in the startup code and in user defined applications.



14.2.2 Setting the Environment

The environment can be set within the Intel® XDB Debugger using the following macro:

set val @env_base_pointer=0xa0030000;set val @env_pointer = @env_base_pointerset val @env_buffer = @env_base_pointer + 0x1000

set val *((long *) @env_pointer) = 0

define macro /overwrite /button AddEnv "\set val *((long *) @env_pointer) = @env_buffer; \set val @env_pointer = @env_pointer + 4; \set val *((long *) @env_pointer) = 0; \set val /size=byte ((char *) @env_buffer) = \"@1\"; \while *((char *) @env_buffer) != 0 then \

set val @env_buffer = @env_buffer + 1; \end; \set val @env_buffer = @env_buffer + 1\n"

Before starting the application the __Environment__ has to be initialized:

SET val *((int *) &__Environment__)=@env_base_pointer;

Example 322. Setting Environment Within the Intel® XDB Debugger

@AddEnv(PATH=C:\\WINNT\\MS\\SMS\\CORE\\BIN;C:\\Program Files\\ARM\\ADSv1_1\\BIN;c:\\cadul\\bin;C:\\WINNT\\system32;C:\\WINNT;)



14.3 ANSI-Defined System Interface Functions

The Intel® C++ Compiler supports the following ANSI-defined system interface functions:

14.3.1 clock

Syntax: #include <time.h>clock_tclock(void );

Description: clock determines the time by counting the clock ticks of processor time used in the calling process.

The returned number of clock ticks can be converted into seconds by dividing it by CLOCKS_PER_SEC. This constant is defined in time.h to 1000, and is extremely target dependent.

Diagnostics: clock returns a close approximation of the processor time used since the start of the program, or –1 if the computation of the processor time fails.

Note: This function forces a software interrupt (SWI).

Further Information:Section 14.4.12, “AngelSWI” on page 624Section 14.4.13, “ARMSystemCall” on page 625

clock

getenv

remove

rename

system

time



14.3.2 getenv

Syntax: #include <stdlib.h>char *getenv(const char *name);

Description: getenv searches an environment list provided by the target system environment for a string that matches the string pointed to by name. The set of environment names and methods for altering the environment list are target system dependent. getenv is not accessed by any library function and may be omitted.

Diagnostics: If name matches a member of the environment list, getenv returns a pointer to the string associated with the matched list member. The string pointed to may be overwritten by a subsequent call to function getenv. If the specified name cannot be found or no environment variables are supported, a null pointer is returned.



14.3.3 remove

Syntax: #include <stdio.h>intremove(const char *filename);

Description: remove deletes the file specified by filename.

Diagnostics: remove returns zero if no error occurs; otherwise –1 is returned. The variable errno is set in a user-defined manner because remove is a system interface function.





14.3.4 rename

Syntax: #include <stdio.h>intrename(const char *oldname, const char *newname);

Description: rename renames the file with the old name oldname to the new name newname. The old name must be the path name of an existing file or directory. Whether newname needs to be the name of an existing file depends on the target system.

Diagnostics: rename returns 0 if no error occurs; otherwise a non-zero value is returned. The variable errno is set in a user-defined manner because rename is a system interface function.





14.3.5 system

Syntax: #include <stdlib.h>intsystem(const char* str);

Description: system passes the string str to the host environment where it is executed by the command processor in an implementation defined manner. If str is an empty string, system only determines whether or not a command processor exists.

Diagnostics: If the value of str is NULL, system returns zero if the command processor is present. If the command processor is present, a non-zero value is returned. If str is not NULL, the return value and the variable errno are implementation defined since system is a system interface function.





14.3.6 time

Syntax: #include <time.h>time_ttime(time_t *timer);

Description: time yields the current calendar time and stores it in the location given by timer if it is not a NULL pointer. The time represents the number of seconds elapsed since 00:00:00 Greenwich Mean Time on January 1, 1970.

Diagnostics: time returns the time in elapsed seconds. There is no error return.





14.4 Non-ANSI System Interface Functions

The Intel® C++ Compiler supports the following non-ANSI system interface functions:

_exit

_blocksizebrk

_freebrk

_gettz

_isdaylight

_isdev

_isdst

_sblockcontrbrk

_sbrk

_strerror

_tmpnampfx

AngelSWI

ARMSystemCall

close

creat

ioctl

lseek

open

read

write



14.4.1 _blocksizebrk

Syntax: size_t_blocksizebrk(size_t blksize)

Description: _blocksizebrk calculates the size of the sbrk block. The sbrk block is calculated using several calculations as described below.

_blocksizebrk is called by _malloc just before calling the _sbrk interface function. The function uses the initial size of the minimal block as parameter. An internal key determines which of the following calculations is used:

• Multiple Calculation

sbrk_block_size = M1 * min_block_size

M1 is the smallest integer for which

extended_user_size <= M1 · min_block_size

• Exponential Calculation

sbrk_block_size = 2M2 · min_block_size

M2 is the smallest integer for which extended_user_size<= 2M2 · min_block_size

In both cases, sbrk_block_size denotes the size of the block allocated by the _sbrk interface function, and min_block_size denotes the minimal size of allocated blocks used as parameter.

extended_user_size is the rounded_user_size, increased by the value 2·sizeof(alloc_t). Where rounded_user_size denotes the size of the memory block you require, rounded upward to the next multiple of sizeof(alloc_t), where sizeof(alloc_t) is the size of the elements of the pointer list used for referring to the blocks allocated by the _sbrk function.

• Default Calculation

sbrk_block_size = min_block_size

if extended_user_size <= min_block_size; else

sbrk_block _size = extended_user_size



14.4.2 _exit

Syntax: void_exit(int exit_code);

Description: The function _exit is called by the library function exit to send the message to the operating system that the task is finished.

Diagnostics: The program exit value is stored into _EXIT_VALUE_, because the semi hosting function does not support exit values. The default value is 0xbaadbeef to indicate that the value is not changed.





14.4.3 _freebrk

Syntax: void_freebrk(void *ptr, size_t size)

Description: _freebrk deallocates the sbrk block pointed to by ptr, by reducing the available memory for dynamic allocation by the given length size.The function _freebrk is the counterpart to _sbrk.

Further Information:Section 14.4.9, “_sbrk” on page 621



14.4.4 _gettz

Syntax: int_gettz(void);

Description: _gettz determines the local time zone measured in minutes westward from Greenwich.

The function _gettz is used by the ANSI library functions ctime, localtime, mktime and strftime. At least a dummy function which returns zero should be supplied.

Diagnostics: The return value is the local time zone in minutes. If the time zone information is not available, zero is returned, meaning that Greenwich Mean Time has been assumed to be the local time.

Further Information:Section 13.6.21, “ctime” on page 327Section 13.6.72, “localtime” on page 412Section 13.6.83, “mktime” on page 426Section 13.6.118, “strftime” on page 479



14.4.5 _isdaylight

Syntax: int_isdaylight (const struct tm *TimeStruct)

Description: The function _isdaylight tests whether summer or winter time is in effect.

Note: The change to summer time is on the last Sunday in March for Europe, and on the first Sunday in April for North America.The change to winter time is on the last Sunday in October for Europe and North America.The current implementation is:

Use Europe rules if

-2 * 60 <= gettz() <= 4 * 60

otherwise use North America rules.

Restrictions: TimeStruct has to be normalized.

Diagnostics: The function returns 0 if it is winter time and 1 if it is summer time.



14.4.6 _isdev

Syntax: int_isdev(int fd);

Description: _isdev detects whether the file identified by fd is a device. fd is a file descriptor obtained from open or creat. A device is a special file (i.e. terminal).

The function _isdev is used by the ANSI library I/O functions when a file is opened. At least a dummy function which returns zero should be supplied. This works properly as long as no devices are involved. _isdev effects all output and input functions such as printf, fprintf, vfprintf, putc, fputc, scanf, fscanf, vfscanf, getc, etc. read, write, and lseek are not affected.

Diagnostics: If 1 is returned, the C Library uses unbuffered I/O. All functions printf, fprintf, vfprintf, putc, fputc pass char by char to the output device by calling write. All functions scanf, fscanf, vfscanf, getc, ... read char by char

If zero is returned, the C Library uses buffered I/O. The I/O routines collect data as long as the buffer must be flushed; buffer is flushed for example, when buffer is full, fseek or fclose is called.



14.4.7 _isdst

Syntax: int_isdst(void);

Description: _isdst tests whether or not Daylight Saving Time is in effect.

_isdst is used by the ANSI library functions ctime, localtime, gmtime, mktime and strftime. At least a dummy function which returns zero should be supplied.

Diagnostics: _isdst returns a non-zero value if Daylight Saving Time is in effect. Zero is returned if Daylight Saving Time is not in effect or if the information is not available.

Further Information:Section 13.6.21, “ctime” on page 327Section 13.6.72, “localtime” on page 412Section 13.6.83, “mktime” on page 426Section 13.6.118, “strftime” on page 479



14.4.8 _sblockcontrbrk

Syntax: int_sblockcontrbrk(void);

Description: _sblockcontrbrk indicates whether the malloc function will fix the boundaries of the allocated sbrk blocks. It returns 1 if malloc performs a boundary fix; otherwise 0 is returned. The fixed sbrk block boundaries enable to free the sbrk blocks obtained from the operating system; this is performed by the _sbrkblockfree library function.

Diagnostics: _sblockcontrbrk returns 0 if the boundaries of the allocated sbrk blocks are not controlled; otherwise 1 is returned.

Further Information:Section 13.6.77, “malloc” on page 418



14.4.9 _sbrk

Syntax: void *_sbrk(size_t size);

Description: _sbrk is used to dynamically enlarge the space available for data. A call to _sbrk returns a pointer to a writable memory area of length size. Subsequent calls to _sbrk do not necessarily return contiguous memory blocks and memory blocks returned have not necessarily been cleared.

_sbrk is accessed by the ANSI library function malloc. If no dynamic memory management is necessary, _sbrk may return a null pointer.

The heap size, which is defined in the standard C library, has a small value by default for target systems used with the Target Execution Monitor or used without operating systems. The compiler automatically adjusts the available heap size as it requires by use of this function.

Diagnostics: _sbrk returns a pointer to a memory block. If no more memory is available or dynamic memory allocation is not supported, a null pointer is returned.

Further Information:Section 13.6.77, “malloc” on page 418




14.4.10 _strerror

Syntax: const char *_strerror(int errnum);

Description: _strerror maps errnum to an error message string and returns a pointer to that string. errnum corresponds to the global variable errno whose values are defined in the header file errno.h. For each possible error number, an appropriate error message string is to be returned.

_strerror is accessed by the ANSI library functions perror and strerror. At least a dummy function which returns a null pointer should be supplied.

Diagnostics: _strerror returns a pointer to the error message string. This string can be overwritten by subsequent calls to _strerror. If the value of errnum is not defined in errno.h or no error message strings are available, a null pointer is returned.

Further Information:Section 13.6.85, “perror” on page 430Section 13.6.117, “strerror” on page 478



14.4.11 _tmpnampfx

Syntax: const char *_tmpnampfx(void);

Description: _tmpnampfx supplies a prefix for temporary file names which are generated by the ANSI library. Note that this prefix must result in a valid file name if a string of 8 characters is appended to it. Usually the prefix represents the name of a file system directory for temporary files such as /tmp/. Note that directory names must end with a delimiter character.

_tmpnampfx is accessed by the ANSI library functions tmpnam and tmpfile. At least a dummy which returns an empty string (not a null pointer) should be supplied.

Diagnostics: _tmpnampfx returns a pointer to the prefix string. The return value must not be a null pointer but can be an empty string.

Further Information:Section 13.6.138, “tmpfile” on page 509Section 13.6.139, “tmpnam” on page 510



14.4.12 AngelSWI

Syntax: intAngelSWI(int code, void *buf);

Description: AngelSWI forces a software interrupt (SWI) if one of the system functions listed in the table below is called.

code is the code number of the SWI. The system dependent library is using the following code values:

buf is a pointer to a buffer which is built as an integer array from the functions’ parameters by the function ARMSystemCall.

Diagnostics: The function sets the register R0 and returns the register’s value.

Further Information:Section 14.4.13, “ARMSystemCall” on page 625

code Description

1 SWI for function open.

2 SWI for function close.

5 SWI for function write.

6 SWI for function read.

0xA SWI for function lseek.

0xE SWI for function remove.

0xF SWI for function rename.

0x10 SWI for function clock.

0x11 SWI for function time.

0x12 SWI for function system.

0x18 SWI for function _exit.It is also used for division by zero.



14.4.13 ARMSystemCall

Syntax: intARMSystemCall(int code, int first, int second, int third, int forth);

Description: ARMSystemCall builds an integer array from the parameters of the system function which has forced the SWI with the code number code. The array can contain up to four parameters. It is passed to the function AngelSWI.

code is the code number of the software interrupt. The system dependent library is using the following code values:

first, second, third, forth are the parameters of the function which has forced the software interrupt.

Diagnostics: ARMSystemCall returns an integer value from the function AngelSWI which sets the register R0.

Further Information:Section 14.4.12, “AngelSWI” on page 624

code Description

1 Software interrupt for function open.

2 Software interrupt for function close.

5 Software interrupt for function write.

6 Software interrupt for function read.

0xA Software interrupt for function lseek.

0xE Software interrupt for function remove.

0xF Software interrupt for function rename.

0x10 Software interrupt for function clock.

0x11 Software interrupt for function time.

0x12 Software interrupt for function system.

0x18 Software interrupt for function _exit. It is also used for division by zero.



14.4.14 close

Syntax: intclose(int fd);

Description: close closes the file identified by the file descriptor fd, as returned by creat or open. This file descriptor is then available for other files. close is accessed by the ANSI library I/O functions. At least a dummy function which returns a non-zero value should be supplied. However, using a dummy function will disable the I/O functions in the ANSI library.

Diagnostics: close returns zero if no error occurs; otherwise a non-zero value is returned.





14.4.15 creat

Syntax: intcreat(const char *path, int mode);

Description: creat creates a new ordinary file or opens for rewriting an existing file which has been named by the pathname pointed to by path. If the file already exists, its previous contents is overwritten. The argument mode is passed for compatibility with the UNIX* operating system and normally always has the value 0x666, though this is operating system dependent. creat is accessed by the ANSI library I/O functions. Therefore, at least a dummy function which returns a negative value must be supplied. However, if a dummy function is used, the ANSI library I/O functions are disabled.

Diagnostics: creat returns a file descriptor which is a non-negative integer if no error occurs; otherwise a negative value is returned.



14.4.16 ioctl

Syntax: intioctl(int fd,int action,...);

Description: ioctl performs device specific actions. The function ioctl is not supported by ARM* semi hosting. This function always returns -1. It can be adapted to support customer based I/O devices.



14.4.17 lseek

Syntax: longlseek(int fd, long offset, int whence);

Description: lseek changes the location of the next read or write operation on the file identified by the file descriptor fd. Each read or write operates on the current seek position and increments it by the number of successfully transferred bytes.

The seek position is modified by offset and whence as follows:

• If whence is 0, the position is set to offset bytes from the beginning of the file.

• If whence is 1, the position is set to its current location plus offset.

• If whence is 2, the position is set to the size of the file plus offset.

• If lseek fails, the seek position remains unchanged.

lseek is accessed by the ANSI library I/O functions. Therefore, at least a dummy which returns a negative value should be supplied. However, using a dummy function will disable the ANSI library I/O functions.

Diagnostics: lseek returns the resulting seek position, as measured in bytes from the beginning of the file, if no error occurs; otherwise a negative value is returned.





14.4.18 open

Syntax: intopen(const char *path, int mode);

Description: open opens the file which is identified by the name stored in a string pointed to by path. The value of mode is interpreted as follows:

• If mode is 0, the file is opened for reading.

• If mode is 1, the file is opened for writing.

• If mode is 2, the file is opened for reading and writing (updating).

open is accessed by the ANSI library I/O functions. At least a dummy function which returns a negative value should be supplied. Using a dummy function will disable the ANSI library I/O functions.

Diagnostics: open returns a file descriptor which is a non-negative integer if no error occurs; otherwise a negative value is returned.





14.4.19 read

Syntax: intread(int fd, void *buf, unsigned int nbyte);

Description: read reads nbyte bytes from the file fd into the buffer pointed to by buf. fd is a file descriptor returned by creat or open. The number of bytes read may be less than nbyte if the number of bytes left in the file is less than nbyte bytes, or if the file is associated with a device.

When reading files capable of seeking, read starts at the current seek position. read is accessed by the ANSI library I/O functions. At least a dummy function which returns a negative value should be supplied. Using a dummy function will disable the ANSI library I/O functions.

Diagnostics: read returns a non-negative integer which indicates the number of bytes actually read and the seek position is incremented by the number of bytes actually read if no error occurs. A value of 0 is returned when an end-of-file marker is reached. A negative value is returned when an error occurs.





14.4.20 write

Syntax: intwrite(int fd, const void *buf, unsigned int nbyte);

Description: write writes nbyte bytes from the buffer pointed to by buf to the file associated with the file descriptor fd. If nbyte is zero, write returns zero and has no other effects on the file if the file is a regular file.

On a regular file or another file capable of seeking, data is written from the actual seek position. When this is completed successfully, the seek position is incremented by the number of bytes actually written.

write is accessed by the ANSI library I/O functions. At least a dummy function which returns a negative value should be supplied. Using a dummy function will disable the ANSI library I/O functions.

Diagnostics: write returns the actual number of bytes written to the file if no error occurs; this number is never greater than nbyte. Otherwise a negative value is returned.




The C++ Run-Time Library 15

The C++ Run-Time Library contains all functions, which are used implicitly by the Intel® C++ Compiler or explicitly by the programmer to implement and use various C++ language features.

This chapter comprises the following sections:

• Section 15.1, “Global Symbols” on page 634 describes all the global symbols associated with the library.

• Section 15.2, “Thread-Local Exception Handling” on page 640 explains how local thread handing operates.

• Section 15.3, “Thread-Safe I/O Stream Library” on page 643 details the library functions associated with I/O threads.

• Section 15.4, “C++ Header Files” on page 644 details the various header files associated with the library and their contents.

• Section 15.5, “Run-Time Library Functions” on page 654 details the various run-time library functions.

• Section 15.6, “Callout Functions” on page 686 explains the various callout functions used for accessing the C++ TLS by global pointers.


The C++ Run-Time Library

15.1 Global Symbols

This section contains a summary of all global symbols being exported by the C++ run-time library.

15.1.1 C++ Defined Library Functions

The table below lists C++-defined library functions. These symbols are explicitly exported by the library and are recommended to be used where required.

Table 44. C++ Defined Library Functions

Function Mangled Symbol NameName of Defining Module

Include File with

Prototype

set_terminate set_terminate__FPFv_v eh_util exception.h

set_unexpected set_unexpected__FPFv_v eh_util exception.h

terminate terminate__Fv eh_util exception.h

uncaught_exception uncaught_exception__Fv eh_util exception.h

unexpected unexpected__Fv eh_util exception.h

__lib_assert__ __lib_assert__ libfatal libfatal.h

__lib_fatal__ __lib_fatal__ libfatal libfatal.h

__lib_fatal_default_terminate_routine

__lib_fatal_default_terminate_routine

libfatal libfatal.h

set_new_handler set_new_handler__FPFv_v set_new new.h

operator new __nw__FUi new new.h

operator new[] __nwa__FUi array_new new.h

operator delete __dl__FPv delete new.h

operator delete[] __dla__FPv array_del new.h



15.1.2 C++ Support Functions

The table below lists C++ support functions contained in the library. They can be considered as implementation specific supplementation of the ANSI-defined functions.

Table 45. C++ Support Functions

Function Mangled Symbol Name Name of Defining Module

Include File with Prototy

pe

__cxx_tls_alloc_hook __cxx_tls_alloc_hook __cxxtls_util libcxx.h

__cxx_tls_create_callout __cxx_tls_create_callout __cxxtls_util none

__cxx_tls_delete __cxx_tls_delete __cxxtls libcxx.h

__cxx_tls_delete_hook __cxx_tls_delete_hook __cxxtls_util libcxx.h

__cxx_tls_delete_root_hook __cxx_tls_delete_root_hook __cxxtls_util libcxx.h

__cxx_tls_exit_hook __cxx_tls_exit_hook __cxxtls_util libcxx.h

__cxx_tls_free_hook __cxx_tls_free_hook __cxxtls_util libcxx.h

__cxx_tls_get_hook __cxx_tls_get_hook __cxxtls_util libcxx.h

__cxx_tls_get_root __cxx_tls_get_root __cxxtls libcxx.h

__cxx_tls_init __cxx_tls_init __cxxtls libcxx.h

__cxx_tls_init_hook __cxx_tls_init_hook __cxxtls_util libcxx.h

__cxx_tls_kill_callout __cxx_tls_kill_callout __cxxtls_util none

__cxx_tls_restart_callout __cxx_tls_restart_callout __cxxtls_util none

__cxx_tls_set __cxx_tls_set __cxxtls libcxx.h

__cxx_tls_set_hook __cxx_tls_set_hook __cxxtls_util libcxx.h

__cxx_tls_setup __cxx_tls_setup __cxxtls none

__cxx_tls_size __cxx_tls_size __cxxtls libcxx.h

__cxx_tls_switch_callout __cxx_tls_switch_callout __cxxtls_util none

_main _main _main none

__cxx_disable_critical_section_lock


iossem libcxx.h

__cxx_enable_critical_section_lock


iossem libcxx.h

__cxx_enter_critical_section


iossem libcxx.h

__cxx_exit_critical_section


iossem libcxx.h

__cxx_share_critical_section_lock


iossem libcxx.h

__pure_virtual_called __pure_virtual_called pure_virt none



15.1.3 C++ Internal Library Symbols

The C++ internal library symbols which are shown in the following table should not be used by applications.

Table 46. C++ Internal Library Symbols

Mangled Symbol Name Name of Defining Module

_Raise__9exceptionCFv stdexcept

_Set_raise_handler__9exceptionSFPFRC9exception_v stdexcept

_Throw__FRC9exception stdexcept

__TBC_9exception bad_alloc

__TID_v throw

__T_10bad_typeid typeinfo

__T_13bad_exception exception

__T_8bad_cast typeinfo

__T_9bad_alloc bad_alloc

__T_9exception stdexcept

__T_9type_info typeinfo

__already_marked_for_destruction dtor_list

__array_delete vec_newdel

__array_new vec_newdel

__array_new_prefix_size vec_newdel

__as__10bad_typeidFRC10bad_typeid typeinfo

__as__13bad_exceptionFRC13bad_exception exception

__as__8bad_castFRC8bad_cast typeinfo

__as__9bad_allocFRC9bad_alloc bad_alloc

__as__9exceptionFRC9exception stdexcept

__call_ctors__Fv static_init

__call_dtors__Fv static_init

__call_terminate eh_util

__call_unexpected eh_util

__cleanup_vec_new_or_delete vec_newdel

__ct__10bad_typeidFPCc typeinfo

__ct__10bad_typeidFRC10bad_typeid typeinfo

__ct__13bad_exceptionFPCc exception

__ct__13bad_exceptionFRC13bad_exception exception

__ct__8bad_castFPCc typeinfo

__ct__8bad_castFRC8bad_cast typeinfo

__ct__9bad_allocFPCc bad_alloc

__ct__9bad_allocFRC9bad_alloc bad_alloc



__ct__9exceptionFPCc stdexcept

__ct__9exceptionFRC9exception stdexcept

__derived_to_base_conversion rtti

__dt__10bad_typeidFv typeinfo

__dt__13bad_exceptionFv exception

__dt__8bad_castFv typeinfo

__dt__9bad_allocFv bad_alloc

__dt__9exceptionFv stdexcept

__dt__9type_infoFv typeinfo

__dynamic_cast rtti

__dynamic_cast_ref rtti

__edg_exit__Fi edg_exit

__eh_exit_processing throw

__eq__9type_infoCFRC9type_info typeinfo

__exception_caught throw

__exception_started throw

__free_thrown_object throw

__get_typeid rtti

__internal_rethrow throw

__main_called_more_than_once _main

__memcpy memzero

__memzero memzero

__ne__9type_infoCFRC9type_info typeinfo

__placement_array_new vec_newdel

__process_needed_destructions__Fv dtor_list

__record_needed_destruction dtor_list

__rethrow throw

__suppress_optim_on_vars_in_try throw

__throw throw

__throw_alloc throw

__throw_bad_cast__Fv rtti

__throw_bad_typeid__Fv rtti

__throw_setup throw

__vec_cctor vec_cctor

__vec_cctor_eh vec_newdel

__vec_delete vec_newdel

__vec_new vec_newdel

__vec_new_eh vec_newdel





__vtbl__10bad_typeid typeinfo

__vtbl__13bad_exception exception

__vtbl__8bad_cast typeinfo

__vtbl__9bad_alloc bad_alloc

__vtbl__9exception stdexcept

__vtbl__9type_info typeinfo

_array_pointer_not_from_vec_new vec_newdel

before__9type_infoCFRC9type_info typeinfo

dummy_ctors munch_ctors

dummy_dtors munch_dtors

exit__Fi exit

name__9type_infoCFv typeinfo

what__10bad_typeidCFv typeinfo

what__13bad_exceptionCFv exception

what__8bad_castCFv typeinfo

what__9bad_allocCFv bad_alloc

what__9exceptionCFv stdexcept

__TID_10bad_typeid typeinfo

__TID_13bad_exception exception

__TID_8bad_cast typeinfo

__TID_9bad_alloc bad_alloc

__TID_9exception stdexcept

__TID_9type_info typeinfo

_ctors static_init

_dtors static_init

_stderr stdexcept

abort libfatal, stdexcept

atexit static_init

exit edg_exit

fputs stdexcept

free delete, __cxxtls_util, throw

longjmp throw

malloc new, newnothrow, __cxxtls_util, throw

memcpy memzero, throw

memset memzero

setjmp newnothrow





__cxxtls __cxxtls_util

__cxxtls_init __cxxtls

__root_cxx_tls __cxxtls





15.2 Thread-Local Exception Handling

This section describes how the Intel® C++ Compiler supports the thread-local exception handling.

15.2.1 Implementation

Thread-local exception handling means that each thread can set up its own exception stack. This is achieved by setting up a data structure called C++ TLS which holds the relevant data for exception handling. “Thread” refers to any part of the program which runs in parallel, and also applies to objects such as tasks or process device drivers.

The C++ run-time library supplies the following set of functions to manipulate the C++ TLS for each thread:

A target-specific implementation should deal with exceptions as follows:

• Initialize the exception stack when a thread is created.

• Activate the appropriate stack when a thread is scheduled.

• Clean up the exception stack when the thread terminates.

__cxx_tls_delete

__cxx_tls_init

__cxx_tls_set

__cxx_tls_setup

__cxx_tls_size



Thus, the C++ run-time library uses hook functions when target-specific services are required. The following hook functions are supported:

During the C++ startup, a default exception stack, which is also named the root TLS, is created and activated. This enables the use of exceptions without the need of adapting the hook and writing functions to a particular target as long as the exceptions do not have to be thread-local. The C++ startup code is executed by a call to the C++ run-time library function _main(). The Intel® C++ Compiler inserts a call to this function automatically if a function called main() is compiled. Thus, when an exception is thrown before _main() is called, unpredictable results occur.

The implementation maintains a data structure named C++ TLS, which holds related thread-local data. This includes the addresses of the following handler functions:

When a new C++ TLS is created, these addresses are set to default values. A thread does not inherit the handlers from its parent.

Further Information:Section 15.4.2, “C++ Header File libcxx.h” on page 646Section 15.5, “Run-Time Library Functions” on page 654

__cxx_tls_alloc_hook

__cxx_tls_delete_hook

__cxx_tls_delete_root_hook

__cxx_tls_exit_hook

__cxx_tls_free_hook

__cxx_tls_get_hook

__cxx_tls_get_root

__cxx_tls_init_hook

__cxx_tls_set_hook

set_new_handler

set_terminate

set_unexpected



15.2.2 Access to the C++ TLS

There are 2 modes to access the C++ TLS:

The following set of callout functions is supplied:

Further Information:Section 15.6, “Callout Functions” on page 686

Mode Description

static by a global pointer (default)

There is a global pointer variable __cxxtls which holds the address of the currently active C++ TLS. This pointer is initialized by the C++ startup and must be adjusted by implementing the callout functions. The following libraries for not-specific target systems use this mode:

<installation-directory>\lib\stand386\i386fx00.lib

<installation-directory>\lib\stand386\i386cx00.lib

<installation-directory>\lib\stand386\i387fx00.lib

<installation-directory>\lib\stand386\i387cx00.lib

dynamic by calling a function All accesses to the C++ TLS are carried out using a call to the hook function __cxx_tls_get_hook, which has to return the current address. A target-specific library must be used which uses this mode.

__cxx_tls_create_callout

__cxx_tls_switch_callout

__cxx_tls_kill_callout

__cxx_tls_restart_callout



15.3 Thread-Safe I/O Stream Library

The interface to hook into the I/O stream classes for thread safety defines functions which are called by the I/O stream library to lock/unlock critical sections. The requests for locking are split into 2 levels.

• Level 1 locks are stream-local. Thus, only threads operating on the same or on a tied stream (as cin and cout) are affected.

• Level 2 locks are used if common shared data for all streams are accessed. Level 2 locks should switch off scheduling. These operations are very short and not dependent on external events to avoid lock-up of the system.

This permits to keep scheduling running if a read or write operation on a stream is blocked.

The I/O stream library maintains a 32-bit integer which is used as a semaphore. The contents of this element is user-defined and can be used to perform level 1 locks.

The following set of functions is supplied:

Further Information:Section 15.4.2, “C++ Header File libcxx.h” on page 646Section 15.5, “Run-Time Library Functions” on page 654








15.4 C++ Header Files

This chapter describes C++-specific header files of the C++ Run-Time Library. These header files are designed to be used in conjunction with the libraries supplied with the Intel® C++ Compiler. If functions of the C++ Run-Time Library are used, the appropriate header file must be included.

The table below provides an overview of all supplied C++-specific header files which are automatically installed in the following directory, which is relative to the installation directory.

\include

The following pages describe the contents of every header file and are in alphabetical order. Every header file is protected against multiple inclusion.

Header File Description

exception.h Defines one class, types and functions used for exception handling.

libcxx.h Defines one structure, macros and functions used for C++ TLS.

libfatal.h Defines macros and functions for library error handling.

new.h Defines functions used for dynamic storage management.

rtti.h Defines macros used for Run-Time type information and exception handling.

stdexcept.h Defines classes and functions used for exception handling.

typeinfo.h Defines classes and functions used for RunTime Type Information.



15.4.1 C++ Header File exception.h

The header file exception.h defines a class and functions used for exception handling.

The class bad_exception is defined as follows:

class bad_exception : public exception {public: bad_exception(const char *message = BAD_EXCEPTION) THROW_NOTHING();

bad_exception(const bad_exception& copyfrom) THROW_NOTHING();

bad_exception& __FAR__ operator=(const bad_exception& copyfrom) THROW_NOTHING(); virtual ~bad_exception() THROW_NOTHING(); virtual const char* __FAR__ what() const THROW_NOTHING(); };

The header files contains the following type definitions:

typedef void (*terminate_handler)();typedef void (*unexpected_handler)();

The table below lists all functions which are defined in exception.h:


extern terminate_handler set_terminate(terminate_handler);

Changes terminate function.

extern unexpected_handler set_unexpected(unexpected_handler);

Changes unexpected function.

void __FAR__ terminate(); Terminate function.

void __FAR__ unexpected(); Unexpected function.

extern _bool uncaught_exception(); Returns TRUE in case of a thrown exception.



15.4.2 C++ Header File libcxx.h

The header file libcxx.h defines the structure __user_cxxtls, the macros ECXX_TLS_NOTINIT and NO_SEM, and functions used for C++ TLS.

The structure __user_cxxtls is defined as follows:

struct __user_cxxtls { long _PFX(magic_number1); int _PFX(eh_curr_region); int _PFX(catch_clause_number); void *_PFX(curr_eh_stack_entry); void *_PFX(caught_object_address);};

The macros have the following values and descriptions:

The table below list all functions defined in the header file libcxx.h with a brief description:


ECXX_TLS_NOTINIT 1 Defines the error code if TLS is not initialized.

NO_SEM 0 No semaphore are assigned for IOS lock/unlock.


extern "C" void __cxx_disable_critical_section_lock(void *); Disable level 1 lock.

extern "C" void __cxx_enable_critical_section_lock(void *); Enable level 1 and 2 locks.

extern "C" void __cxx_enter_critical_section(void *); Perform a lock.

extern "C" void __cxx_exit_critical_section(void *); Perform an unlock.

extern "C" void __cxx_share_critical_section_lock(void *, void *);

Share streams.

extern "C" void*__FAR__

__cxx_tls_alloc_hook(size_t, bool);

Allocate memory for a new C++ TLS.

extern "C" void__FAR__

__cxx_tls_delete(void); Clear memory containing TLS data.


__cxx_tls_delete_hook(void *); Release resources.


__cxx_tls_delete_root_hook(void *); Release resources.

extern "C" int__FAR__

__cxx_tls_exit_hook(void); Disable callout functions.


__cxx_tls_free_hook(void *, bool);

Free memory allocated for a C++ TLS.



extern "C"struct

__user_cxxtls*__FAR__

__cxx_tls_get_hook(void); Obtain a pointer to the actually active C++ TLS.


__cxx_tls_get_root(void); Obtain address of default C++ TLS.


__cxx_tls_init(void *, void *, void *, void *);

Initialize TLS area for the current process.

extern "C" int__FAR__

__cxx_tls_init_hook(void *); Initialize callout functions.


__cxx_tls_set(void *,int *); Set a pointer to the C++ TLS area for the next activation process.


__cxx_tls_set_hook(void *, int *);

Set a pointer to the C++ TLS area.

extern "C" size_t __FAR__ __cxx_tls_size(void);

Determine the size of the C++ TLS area for the corresponding library.




15.4.3 C++ Header File libfatal.h

The header file libfatal.h defines several macros and functions which are used for error handling.



__LIB_FATAL__ 1 Fatal error value

LIBFAT_BASE 0 C library range

LIBFAT_C_BASE 0 C-library range

LIBFAT_CXX_BASE 200 C++ run-time library range

LF_LIB_ASSERT 1 An internal library assertion occurs.

LF_LIB_TERMINATE_CALLED 201 The library version of terminate() was called. There was no user-version of terminate, or the user version returns back to the caller.

LF_LIB_UNEXPECTED_REACHED 202 The installed unexpected() handler returns to the caller.

LF_LIB_TERMINATE_REACHED 203 The installed terminate() handler returns to the caller.

LF_PURE_VIRTUAL_CALLED 204 A pure virtual function was called by using the base class.

LF_THROW_BAD_CAST_CALLED 205 A bad_cast() exception was thrown, but exception handling is not enabled.

LF_THROW_BAD_TYPEID_CALLED 206 A bad_typeid() exceptions was thrown, but exception handling is not enabled.

LF_LIB_DEFAULT_TERMINATE_CALLED 207 The default terminate handler was called.

LF_ARRAY_POINTER_NOT_FROM_VEC_NEW 208 A delete of an array was called with a pointer, which was not allocated by a vector-new call.

LF_MAIN_MULTIPLE_CALLED 209 The _main() function was called more than once, thus the call of static constructors run a second time.

LF_ALREADY_MARKED_FOR_DESTRUCTION 210 Try to call destructor more than once on an object.

LF_CXX_TLS_NOT_INITIALIZED 211 TLS not initialized.

LF_IOS_LOCK_FAIL 212 Lock of stream failed.

LF_IOS_UNLOCK_FAIL 213 Unlock of stream failed.

LF_IOS_CREATE_LOCK_OBJ 214 Create a lock object for a stream failed.

LF_IOS_DELETE_LOCK_OBJ 215 Delete a lock object for a stream failed.

LF_IOS_SHARE_LOCK_OBJ 216 Share a lock object between 2 streams failed.

LF_EXC_ABORT 217 Exception abort.



The table below lists three functions which are defined in the header file libfatal.h:


void __lib_fatal__(int); Call abort.

void __lib_assert__(void *,char *,int); Call __lib_fatal__ after assertion occurs.

void __lib_fatal_default_terminate_routine(void); Initialize __lib_fatal__.



15.4.4 C++ Header File new.h

The header file new.h defines one type and functions used for dynamic storage management.

The following type is defined:

typedef void (*new_handler)(); /* flat memory model */typedef void (far *new_handler)(); /* compact memory model and subsystems */

The table below lists all functions which are supplied by the header file new.h:

Further Information:Section 15.5.25, “operator delete, operator delete [ ]” on page 678Section 15.5.26, “operator new, operator new [ ]” on page 679


new_handler set_new_handler(new_handler); Change handler for new allocation errors.

void *operator new(size_t) ; Create new object which is allocated on dynamic memory.

void *operator new[](size_t) ; Create new array of objects which is allocated on dynamic memory.



15.4.5 C++ Header File rtti.h

The header file rtti.h defines several types and macros used for Run-Time Type Information (RTTI) and exception handling.

The following types are defined:

typedef void (*a_function_ptr) ();typedef a_byte a_unique_id;typedef a_unique_id *a_unique_id_ptr;typedef EDG_DELTA_TYPE an_object_offset;typedef a_byte a_base_class_spec_flag_set;typedef struct a_type_info_impl *a_type_info_impl_ptr;typedef struct a_base_class_spec *a_base_class_spec_ptr;typedef char* an_access_flag_string;



BCS_NO_FLAGS 0x00 Value when no flags are set.

BCS_VIRTUAL 0x01 The offset provides the position of a pointer to the base class. Used for virtual base classes.

BCS_LAST 0x02 TRUE if this is the last base class specifier in the array.

BCS_PUBLIC 0x04 TRUE if the base class is public. For non-direct base classes, TRUE if the cumulative access across the all derivation steps gives public access.

BCS_AMBIGUOUS 0x08 TRUE if this base class is ambiguous.

BCS_DIRECT 0x10 TRUE if this is a direct base class. Ambiguous base classes are always put out at the top level. This flag can be used to determine which ones are really top level bases.

BASE_ACCESSIBLE Y Value in an access list if the class is accessible.

BASE_NOT_ACCESSIBLE N Value in an access list if the class is not accessible. Could be caused by a base being ambiguous.



15.4.6 C++ Header File stdexcept.h

The header file stdexcept.h defines the classes and functions used for C++ exception handling.

class exception { public: static raise_hanlder __FAR__ _Set_raise_handler(raise_hanlder);

explicit exception(const char *message = UNKNOWN) THROW_NOTHING();

exception(const exception& copyfrom) THROW_NOTHING();

exception& __FAR__ operator=(const exception& copyfrom) THROW_NOTHING();

virtual ~exception() THROW_NOTHING();

virtual const char* __FAR__ what() const THROW_NOTHING();

void __FAR__ _Raise(void) const; protected:#ifndef __EXCEPTIONS_EANBLED void _Doraise() const {}#endif const char *_message; };



15.4.7 C++ Header File typeinfo.h

The header file typeinfo.h defines the classes and functions used for Run Time Type Information.

The following classes are defined:

class type_info { public: virtual ~type_info(); _bool __FAR__ operator==(const type_info&) const; _bool __FAR__ operator!=(const type_info&) const; _bool __FAR__ before(const type_info&) const; const char* __FAR__ name() const; private: type_info& __FAR__ operator=(const type_info&); // Not actually defined#if 0#else /* 0 */ protected: // Protected instead of private to suppress the "no accessible // constructor" warning#endif /* 0 */ type_info(const type_info&); // Not actually defined };

class bad_cast : public exception { public: bad_cast(const char *message = BAD_CAST) THROW_NOTHING(); bad_cast(const bad_cast&) THROW_NOTHING(); bad_cast& __FAR__ operator=(const bad_cast&) THROW_NOTHING(); virtual ~bad_cast() THROW_NOTHING(); virtual const char* __FAR__ what() const THROW_NOTHING(); };

class bad_typeid : public exception { public: bad_typeid(const char *message = BAD_TYPEID) THROW_NOTHING(); bad_typeid(const bad_typeid&) THROW_NOTHING(); bad_typeid& __FAR__ operator=(const bad_typeid&) THROW_NOTHING(); virtual ~bad_typeid() THROW_NOTHING(); virtual const char* __FAR__ what() const THROW_NOTHING(); };



15.5 Run-Time Library Functions

The C++ Run-Time Library provided with the Intel® C++ Compiler supports the following run-time library functions, which are listed in alphabetical order.

Note: All C++ run-time library functions are reentrant.

15.5.1 __cxx_disable_critical_section_lock

Syntax: extern "C" void__cxx_disable_critical_section_lock(void *psem)

Description: __cxx_disable_critical_section_lock deletes a semaphore. This function is called when a stream is closed (destructed) by an I/O stream. psem is a pointer to the assigned semaphore.

Diagnostics: __cxx_disable_critical_section_lock calls __lib_fatal__(LF_IOS_DELETE_LOCK_OBJ) if an error occurs; otherwise *psem must have the value NO_SEM to avoid multiple deletion. Multiple deletion may occur because for tied streams __cxx_disable_critical_section_lock is called for both streams with the same pointer psem while closing the streams.

Note: A prototype of this function is defined in the header file libcxx.h.

Further Information:Section 15.5.2, “__cxx_enable_critical_section_lock” on page 655Section 15.5.21, “__lib_fatal__” on page 674



15.5.2 __cxx_enable_critical_section_lock

Syntax: extern "C" void__cxx_enable_critical_section_lock(void *psem)

Description: __cxx__cxx_enable_critical_section_lock enables level 1 and level 2 locks. This function is called during the initialization (construction) of an I/O stream. __cxx_enable_critical_section_lock places a unique value into the location passed back by psem, which is used to apply level 1 lock individually to a stream.

Diagnostics: __cxx_enable_critical_section_lock calls __lib_fatal__(LF_IOS_CREATE_LOCK_OBJ) if an error occurs.


Further Information:Section 15.5.1, “__cxx_disable_critical_section_lock” on page 654Section 15.5.21, “__lib_fatal__” on page 674



15.5.3 __cxx_enter_critical_section

Syntax: extern "C" void__cxx_enter_critical_section(void *psem)

Description: __cxx_enter_critical_section performs a lock to avoid parallel execution. This function is called whenever a section of code is entered. If the parameter psem is NULL, a level 2 lock is performed. Otherwise, a level 1 lock is requested on the semaphore pointed to by psem.

Diagnostics: __cxx_enter_critical_section calls __lib_fatal__(LF_IOS_LOCK_FAIL) if an error occurs.


Further Information:Section 15.5.4, “__cxx_exit_critical_section” on page 657Section 15.5.21, “__lib_fatal__” on page 674



15.5.4 __cxx_exit_critical_section

Syntax: extern "C" void__cxx_exit_critical_section(void *psem)

Description: __cxx_exit_critical_section deletes a lock when a section of code is left. If the parameter psem is NULL, a level 2 unlock is performed;otherwise, a level 1 unlock on the semaphore pointed to by psem.

Diagnostics: __cxx_exit_critical_section calls __lib_fatal__(LF_IOS_UNLOCK_FAIL) if an error occurs.


Further Information:Section 15.5.3, “__cxx_enter_critical_section” on page 656Section 15.5.21, “__lib_fatal__” on page 674



15.5.5 __cxx_share_critical_section_lock

Syntax: extern "C" void__cxx_share_critical_section_lock(void *psem1, void *psem2)

Description: __cxx_share_critical_section_lock shares the semaphore passed by psem1 and deletes the semaphore passed by psem2. This functions is called when two streams are tied together. If a stream is tied to another, the other stream flushes the output of the tied one before performing any read or write operation. This is carried out by deleting one semaphore and copying the value of the other. A typical example of tied streams is the pair cin and cout. Whenever input from cin is requested, cout is flushed because cout is tied to cin. Tying is an asymmetrical relation. If stream1 is tied to stream2 and stream2 to stream1, an infinite loop is caused.

Diagnostics: __cxx_share_critical_section_lock calls __lib_fatal__(LF_IOS_SHARE_LOCK_OBJ) if any of the two semaphores pointed to by psem1 and psem2 are not valid.


Further Information:Section 15.5.21, “__lib_fatal__” on page 674



15.5.6 __cxx_tls_alloc_hook

Syntax: extern "C"void *__FAR____cxx_tls_alloc_hook(size_t size, bool isroot)

Description: __cxx_tls_alloc_hook. This function is called when a new C++ TLS is created. It depends upon the implementation where this memory resides. size is the size of the C++ TLS in bytes. The parameter isroot is either TRUE of FALSE; in case of TRUE, the allocated C++ TLS is the TLS of the root task, otherwise it is not the root-task TLS. The memory allocated using __cxx_tls_alloc_hook is deallocated using the library function __cxx_tls_free_hook. The return value of this function is a pointer to the C++ TLS.


Further Information:Section 15.5.11, “__cxx_tls_free_hook” on page 664



15.5.7 __cxx_tls_delete

Syntax: extern "C"void __FAR___cxx_tls_delete(void);

Description: __cxx_tls_delete clears the area containing the TLS data of the C++ run-time.

Diagnostics: __cxx_tls_delete returns ECXX_TLS_NOTINIT if there is no current initialized area, or 0 on success.




15.5.8 __cxx_tls_delete_hook

Syntax: extern "C"void __FAR__ __cxx_tls_delete_hook(void *ptls)

Description: __cxx_tls_delete_hook deletes a C++ TLS. It releases all resources required by the C++ TLS. ptls is a pointer to the C++ TLS. This functions calls __cxx_tls_free_hook to deallocate memory if necessary.





15.5.9 __cxx_tls_delete_root_hook

Syntax: extern "C"void __FAR__ __cxx_tls_delete_root_hook(void *ptls)

Description: __cxx_tls_delete_root_hook deletes the root-C++ TLS. It releases all resources required by the root-C++ TLS. ptls is a pointer to the root-C++ TLS. This functions calls __cxx_tls_free_hook to deallocate memory if necessary.





15.5.10 __cxx_tls_exit_hook

Syntax: extern "C"int __FAR__ __cxx_tls_exit_hook(void)

Description: __cxx_tls_exit_hook reverts the actions carried out by __cxx_tls_init_hook. This function should be called at the end of the application (not thread).

Diagnostics: __cxx_tls_exit_hook returns 0 if no error occurs; otherwise –1 is returned.


Further Information:Section 15.5.15, “__cxx_tls_init_hook” on page 668



15.5.11 __cxx_tls_free_hook

Syntax: extern "C"void __FAR____cxx_tls_free_hook(void *ptls,bool isroot);

Description: __cxx_tls_free_hook deallocates memory for a C++ TLS. This function is called when a C++ TLS is deleted. The parameter ptls is the pointer to the C++ TLS to be deleted. The parameter isroot is either TRUE of FALSE; in case of TRUE, the allocated C++ TLS is the TLS of the root task, otherwise it is not the root-task TLS. The memory which is deallocated was allocated using the library function __cxx_tls_alloc_hook.


Further Information:Section 15.5.6, “__cxx_tls_alloc_hook” on page 659



15.5.12 __cxx_tls_get_hook

Syntax: extern "C"__user_cxxtls * __cxx_tls_get_hook(void)

Description: __cxx_tls_get_hook obtains a pointer to the currently active C++ TLS. The functions returns a pointer to the current C++ TLS.

The return type __user_cxxtls describes the part of the C++ TLS which must be accessible from application code. This is only the top part of the whole C++ TLS.




15.5.13 __cxx_tls_get_root

Syntax: extern "C"void * __FAR____cxx_tls_get_root(void)

Description: __cxx_tls_get_root returns the address of the default C++ TLS which is installed during the C++ startup code.




15.5.14 __cxx_tls_init

Syntax: extern "c"void __FAR____cxx_tls_init(void *ptr, void *(pset)(void *, int *), void (* pdelete)(void), void *pback );

Description: __cxx_tls_init initializes an area containing the TLS data of the C++ run-time library pointed to by the argument ptr. The argument pset contains the address of the set-function of a previously generated TLS. The argument pdelete contains the address of the delete function of a previously generated TLS. The argument pback contains a pointer to a previously generated TLS. The arguments pset, pdelete, and pback are used to build up a linked list of TLS areas.

Diagnostics: __cxx_tls_init returns ECXX_TLS_BAD if the argument ptr does not point to an area, or 0 on success.




15.5.15 __cxx_tls_init_hook

Syntax: extern "C"int __FAR____cxx_tls_init_hook(void *ptls)

Description: __cxx_tls_init_hook is called during C++ startup. It is used to install the necessary callout functions to activate the appropriate C++ TLS when at thread is created or deleted or when a switch to another thread occurs. The parameter ptls points to the default C++ TLS.

Diagnostics: __cxx_tls_init_hook returns 0 if no error occurs; otherwise –1 is returned.


Further Information:Section 15.5.10, “__cxx_tls_exit_hook” on page 663



15.5.16 __cxx_tls_set

Syntax: extern "c"void * __FAR____cxx_tls_set(void *ptr, int *pecode);

Description: __cxx_tls_set sets the area containing the TLS data of the C++ run-time library to the address pointed to by the argument ptr. pecode specifies a pointer to the error code.

Diagnostics: __cxx_tls_set returns NULL and sets the argument *pecode to ECXX_TLS_NOTINIT if the argument ptr does not point to an initialized area; otherwise the pointer to the old TLS is returned




15.5.17 __cxx_tls_set_hook

Syntax: extern "C"void __FAR____cxx_tls_set_hook(void *ptls,int *pecode)

Description: __cxx_tls_set_hook installs an active C++ TLS. ptls is the pointer to the new C++ TLS. This function is called by the C++ run-time library function __cxx_tls_set. The parameter pecode is used to pass error codes back.

Diagnostics: *pecode is set to 0 if no error occurs.


Further Information:Section 15.5.16, “__cxx_tls_set” on page 669



15.5.18 __cxx_tls_setup

Syntax: extern "C"int __FAR____cxx_tls_setup(void);

Description: __cxx_tls_setup initializes the default area containing the TLS data of the C++ run-time library. This function is called by the library function _main.

Diagnostics: __cxx_tls_setup returns 0.

Further Information:Section 15.5.24, “_main” on page 677



15.5.19 __cxx_tls_size

Syntax: extern "C"size_t __FAR____cxx_tls_size(void);

Description: __cxx_tls_size returns the size of the area containing the TLS data of the C++ run-time library.




15.5.20 __lib_assert__

Syntax: void__lib_assert__(void *pio, char *file, int line)

Description: __lib_assert__ is the library assertion function. This function calls the function __lib_fatal__(LF_LIB_ASSERT) by default. pio specifies the pointer to the output functions, file is the source file of assertion and line is the source line of assertion.

Note: A prototype of this function is defined in the header file libfatal.h.




15.5.21 __lib_fatal__

Syntax: void__lib_fatal__(int error_code)

Description: __lib_fatal__ calls the abort function when a fatal library error occurs. The argument error_code represents specific fatal error codes.

error_code may have one of the following values which are described in Section 15.4.3, “C++ Header File libfatal.h”:


Further Information:Section 15.4.3, “C++ Header File libfatal.h” on page 648

LF_ARRAY_POINTER_NOT_FROM_VEC_NEW

LF_PURE_VIRTUAL_CALLED

LF_LIB_TERMINATE_CALLED

LF_LIB_UNEXPECTED_REACHED

LF_LIB_TERMINATE_REACHED

LF_THROW_BAD_CAST_CALLED

LF_THROW_BAD_TYPEID_CALLED

LF_LIB_DEFAULT_TERMINATE_CALLED

LF_LIB_ASSERT

LF_MAIN_MULTIPLE_CALLED

LF_ALREADY_MARKED_FOR_DESTRUCTION

LF_CXX_TLS_NOT_INITIALIZED

LF_EXC_ABORT



15.5.22 __lib_fatal_default_terminate_routine

Syntax: void__lib_fatal_default_terminate_routine(void)

Description: __lib_fatal_default_terminate_routine initializes the default library terminate function __lib_fatal__(LF_LIB_TERMINATE_CALLED).





15.5.23 __pure_virtual_called

Syntax: extern "C"{ void __pure_virtual_called(void);}

Description: __pure_virtual_called is called if a pure virtual function of an abstract class is called. This function calls abort() to terminate the application.



15.5.24 _main

Syntax: extern "C"void_main(void);

Description: _main performs all necessary run-time initialization of a C++ application. It calls the constructor functions for all static objects and initializes the C++ run-time library.

A call to this function is inserted by the C++ compiler automatically, when a function named main() is compiled.

If there is no main() function compiled by the C++ compiler, the _main() function needs to be called explicitly by the programmer.

Note: No class objects can be used until the _main() function is called. When this function is called explicitly by the user, this function must be in C context or a C function.

Example 323. _main

extern "C" {

void root(void)

{ _main(); entry_app();}

}



15.5.25 operator delete, operator delete [ ]

Syntax: void operator delete(void *ptr);void operator delete [ ] (void *ptr);

Description: operator delete (operator delete [ ]) frees an object which was allocated by the operator new (operator new [ ]) given by the parameter ptr. The space is deallocated via the library function free.

Note: Prototypes of this function are defined in the header file new.h.

Further Information:Section 15.5.26, “operator new, operator new [ ]” on page 679



15.5.26 operator new, operator new [ ]

Syntax: void *operator new(size_t objsize);void *operator new [ ] (size_t objsize);

Description: operator new (operator new [ ]) allocates an object of a size in bytes given by the parameter objsize. The space is allocated via the library function malloc. If malloc returns NULL, a handler is called which is previously set by set_new_handler.

Note: Check if malloc and the interface function _sbrk work. Prototypes of this function are defined in the header file new.h.

Further Information:Section 15.5.27, “set_new_handler”



15.5.27 set_new_handler

Syntax: typedef void (__FAR__ *new_handler)();__new_handlerset_new_handler(__new_handler new_fun);

Description: set_new_handler enables you to specify your own handler function, passed by the argument new_fun. This handler is called if there is no more heap memory available. If the handler returns, the C++ run-time library retries to allocate the required space. The handler may return throwing an exception or calling exit().

Note: A prototype of this function is defined in the header file new.h.



15.5.28 set_terminate

Syntax: typedef void (__FAR__ *terminate_handler)();terminate_handlerset_terminate(terminate_handler new_fun);

Description: set_terminate enables the you to specify your own handler function passed by the argument new_fun. This handler is called if there is no function for a thrown exception found or the exception stack is corrupted.

The handler is called by the run-time function terminate(). If the handler returns, the function abort() is called.

Note: A prototype of this function is defined in the header file exception.h.

Further Information:Section 15.5.30, “terminate” on page 683



15.5.29 set_unexpected

Syntax: typedef void (__FAR__ *unexpected_handler)();unexpected_handlerset_unexpected(unexpected_handler new_fun);

Description: set_unexpected enables the user to specify his own handler function passed by the argument new_fun. This handler is called, when there is an exception, which is not specified at a function exception specification, is thrown.

The handler is called by the run-time function unexpected(). If the handler returns, the function terminate() is called.


Further Information:Section 15.5.32, “unexpected” on page 685Section 15.5.30, “terminate” on page 683



15.5.30 terminate

Syntax: void __FAR__terminate(void);

Description: terminate is called when there is no function for a thrown exception has been found, or the exception stack is corrupted.

If there is an user-defined handler specified by set_terminate(), this function is called first. After this function abort() is called.


Further Information:Section 15.5.28, “set_terminate” on page 681



15.5.31 uncaught_exception

Syntax: extern _booluncaught_exception(void)

Description: uncaught_exception returns TRUE if it is called during the processing of a throw() or if terminate() was called.


Further Information:Section 15.5.30, “terminate” on page 683



15.5.32 unexpected

Syntax: void __FAR__unexpected(void);

Description: unexpected is called when there is an exception thrown, which has not been specified at a function exception specification.

If there is a user-defined handler specified by set_unexpected(), this function is called first. After this function terminate() is called.


Further Information:Section 15.5.29, “set_unexpected” on page 682Section 15.5.30, “terminate” on page 683



15.6 Callout Functions

This section describes the callout functions, listed in alphabetical order. These functions are used to access the C++ TLS statically by a global pointer.

Further Information:Section 15.2.2, “Access to the C++ TLS” on page 642

15.6.1 __cxx_tls_create_callout

Syntax: extern "C"void __FAR____cxx_tls_create_callout(void *tcb,void *parent_tcb)

Description: __cxx_tls_create_callout allocates and initializes the C++ TLS area used for the C++ run-time library. This function should be called every time a new task, thread, or process is generated. The new allocated C++ TLS should be bound to the task, thread, or process which is created. __cxx_tls_create_callout does not change the currently active C++ TLS. tcb specifies the pointer to the created task and parent_tcp specifies the parent task.



15.6.2 __cxx_tls_kill_callout

Syntax: extern "C"void __FAR____cxx_tls_kill_callout(void *new_tcb,void *parent_tcb)

Description: __cxx_tls_kill_callout deletes the C++ TLS of a task which was created by __cxx_tls_create_callout. new_tcb points to the new task and parent_tcb points to the parent task.



15.6.3 __cxx_tls_restart_callout

Syntax: extern "C"void __cxx_tls_restart_callout(void *new_tcb, void *parent_tcb)

Description: __cxx_tls_restart_callout reinitializes the C++ TLS before the task, thread, process is restarted. new_tcb points to the new task and parent_tcb points to the parent task.



15.6.4 __cxx_tls_switch_callout

Syntax: extern "C"void __FAR____cxx_tls_switch_callout(void *newtcb,void *parent_tcb)

Description: __cxx_tls_switch_callout activates the C++ TLS which is assigned to the new running task, thread, process. new_tcb points to the new task and parent_tcb to the parent task. __cxx_tls_switch_callout needs to be called whenever a task switch occurs.


Intel® Wireless MMX™ Technology Intrinsic Support 16

Intel® Wireless MMX™ Technology is a high-performance, low-power, 64-bit multimedia coprocessor for the Intel® XScale™ processor family. It is a media-enhancement technology that exploits data parallelism. Intel® Wireless MMX™ Technology gives developers all the components for developing, debugging and running multimedia applications on a handheld platform. And this technology offers its powerful new capabilities in a model already familiar to programmers who have used Intel MMX™ and integer Intel® SSE (Streaming SIMD Extensions).

Intel® Wireless MMX™ Technology exploits the data parallelism present in a large number of multimedia algorithms by executing the same operation on different data elements in parallel. Data parallelism requires that the same operations are performed on many data samples. It requires that this be done concurrently, with multiple pixels in an image going through the same operations independently. This is accomplished this by packing multiple data elements into one 64-bit register. To process this packed data, the Intel® Wireless MMX™ Technology extends the existing Intel XScale™ Microarchitecture with new instructions for operating on packed-data formats.

Intrinsics are special coding extensions that allow using the syntax of C function calls and C variables to access the Intel® Wireless MMX™ Technology. Most Intel® Wireless MMX™ Technology instructions have a corresponding C intrinsic that implements these instructions. This frees the user from managing registers and allows the compiler to optimize the instruction scheduling.

Intel® Wireless MMX™ Technology instructions use the following new features:

• New registers enable packed data of up to 64 bits in length for SIMD processing.

• New data types enable packing of up to 8 elements of data in one register.


Intel® Wireless MMX™ Technology Intrinsic Support

16.1 Intel® Wireless MMX™ Technology Data Types

Intel® Wireless MMX™ Technology Intrinsic functions use the data type __m64 for Intel® Wireless MMX™ Technology registers and intrinsic function operands. The __m64 data type can hold eight 8-bit values, four 16-bit values, two 32-bit values, or one 64-bit value.

16.1.1 New Data Types Usage Guidelines

Since the new data type is not one of the basic ANSI C data types, you must observe the following usage restrictions:

• The __m64 data type can be used only on either side of an assignment, as a return value, or as a parameter. You cannot use it with other arithmetic expressions (“+”, “-”, etc.).

• The __m64 data type can be used as objects in aggregates (such as unions) to access the byte elements and structures.

• The __m64 data type can be used only with the respective intrinsics described in this documentation. The new data type is supported on both sides of an assignment statement: as parameters to a function call, and as a return value from a function call.



16.2 Naming and Usage Syntax

Most of the Intel® Wireless MMX™ Technology intrinsic names use a notational convention as follows:

_mm_intrin_suffix

A number appended to a variable name indicates the element of a packed object. For example, r0 is the lowest part of r. The packed values are represented in right-to-left order, with the lowest value being used for scalar operations.

Due to the nature of the instruction, some intrinsics require their arguments to be immediate values (integer literals). Some intrinsics are “composite” because they require more than one instruction to map.

16.2.1 Intrinsic Syntax

To use Intel® Wireless MMX™ Technology intrinsics, the mmintrin.h file must be included. This file contains __m64 data type definitions and ANSI C prototypes for the Intel® Wireless MMX™ Technology intrinsic functions.

The syntax of Intel® Wireless MMX™ Technology intrinsic prototype is as follows:

Syntax: data_type intrinsic_name (parameters);

intrin Indicates the intrinsics basic operation; for example, add for addition and sub for subtraction.

suffix Denotes the type of data operated on by the instruction. The first one or two letters of each suffix denotes whether the data is packed (p), or scalar (s).The remaining letters denote the type:i64 for signed 64-bit integeru64 for unsigned 64-bit integeri32 signed 32-bit integeru32 unsigned6 32-bit integeri16 signed 16-bit integeru16 unsigned 16-bit integeri8 signed 8-bit integeru8 unsigned 8-bit integer

data_type Is the return data type, which is usually void, int, or __m64. Intrinsics may return other data types that is described in the intrinsic syntax definitions.

intrinsic_name Is the name of the intrinsic, which behaves like a function that you can use in your C/C++ code instead of inlining the actual instruction.

parameters Represents the parameters required by each intrinsic.



16.3 Intel® Wireless MMX™ Technology Arithmetic Intrinsics

Table 47. Overview of Intel® Wireless MMX™ Technology Arithmetic IntrinsicsIn

trin

sic

Nam

e

Inte

l® W

irel

ess

MM

X™

Tec

hn

olo

gy

Inst

ruct

ion

Op

erat

ion

Sig

ned

Argument: Result:

Nu

mb

er o

f va

lues

Bits

per

val

ue

Nu

mb

er o

f va

lues

Bits

per

val

ue

_mm_add_pi8 WADDB Addition -- 8 8 8 8

_mm_add_pi16 WADDH Addition -- 4 16 4 16

_mm_add_pi32 WADDW Addition -- 2 32 2 32

_mm_adds_pi8 WADDBSS Addition Yes 8 8 8 8

_mm_adds_pi16 WADDHSS Addition Yes 4 16 4 16

_mm_adds_pi32 WADDWSS Addition Yes 2 32 2 32

_mm_adds_pu8 WADDBUS Addition No 8 8 8 8

_mm_adds_pu16 WADDHUS Addition No 4 16 4 16

_mm_adds_pu32 WADDWUS Addition No 2 32 2 32

_mm_sub_pi8 WSUBB Subtraction -- 8 8 8 8

_mm_sub_pi16 WSUBH Subtraction -- 4 16 4 16

_mm_sub_pi32 WSUBW Subtraction -- 2 32 2 32

_mm_subs_pi8 WSUBBSS Subtraction Yes 8 8 8 8

_mm_subs_pi16 WSUBHSS Subtraction Yes 4 16 4 16

_mm_subs_pi32 WSUBWSS Subtraction Yes 2 32 2 32

_mm_subs_pu8 WSUBBUS Subtraction No 8 8 8 8

_mm_subs_pu16 WSUBHS Subtraction No 4 16 4 16

_mm_subs_pu32 WSUBWUS Subtraction No 2 32 2 32

_mm_madd_pi16 WMADDS Multiplication -- 4 16 2 32

_mm_madd_pu16 WMADDU Multiplication No 4 16 2 32

_mm_mulhi_pi16 WMULSH Multiplication Yes 4 16 4 16

_mm_mulhi_pu16 WMULUH Multiplication Yes 4 16 4 16

_mm_mullo_pi16 WMULSLWMULUL Multiplication -- 4 16 4 16

_mm_mac_pi16 WMACS Multiply-Accumulation Yes 4 16 4 16



16.3.1 _mm_add_pi8

Syntax: __m64 _mm_add_pi8 (__m64 m1, __m64 m2)

Description: Adds the eight 8-bit values in m1 to the eight 8-bit values in m2.

_mm_mac_pu16 WMACU Multiply-Accumulation No 4 16 4 16

_mm_macz_pi16 WMACSZ Multiply-Accumulation Yes 4 16 4 16

_mm_macz_pu16 WMACUZ Multiply-Accumulation No 4 16 4 16

_mm_acc_pu8 WACCB Accumulation No 8 8 1 8

_mm_acc_pu16 WACCH Accumulation No 4 16 1 16

_mm_acc_pu32 WACCW Accumulation No 2 32 1 32

_mm_mia_si64 TMIA Multiply-Accumulation Yes 2 32 1 64

_mm_miaph_si64 TMIAPH Multiply-Accumulation Yes 2 16 1 64

_mm_miabb_si64 TMIABB Multiply-Accumulation Yes 2 16 1 64

_mm_miabt_si64 TMIABT Multiply-Accumulation Yes 2 16 1 64

_mm_miatb_si64 TMIATB Multiply-Accumulation Yes 2 16 1 64

_mm_miatt_si64 TMIATT Multiply-Accumulation Yes 2 16 1 64

Table 47. Overview of Intel® Wireless MMX™ Technology Arithmetic Intrinsics

Intr

insi

c N

ame

Inte

l® W

irel

ess

MM

X™

Tec

hn

olo

gy

Inst

ruct

ion

Op

erat

ion

Sig

ned

Argument: Result:

Nu

mb

er o

f va

lues

Bits

per

val

ue

Nu

mb

er o

f va

lues

Bits

per

val

ue



16.3.2 _mm_add_pi16


Description: Adds the four 16-bit values in m1 to the four 16-bit values in m2.

16.3.3 _mm_add_pi32


Description: Adds the two 32-bit values in m1 to the two 32-bit values in m2.

16.3.4 _mm_adds_pi8

Syntax: __m64 _mm_adds_pi8 (__m64 m1, __m64 m2)

Description: Adds the eight signed 8-bit values in m1 to the eight signed 8-bit values in m2 using saturating arithmetic.

16.3.5 _mm_adds_pi16


Description: Adds the four signed 16-bit values in m1 to the four signed 16-bit values in m2 using saturating arithmetic.

16.3.6 _mm_adds_pi32


Description: Adds the two signed 32-bit values in m1 to the two signed 32-bit values in m2 using saturating arithmetic.



16.3.7 _mm_adds_pu8

Syntax: __m64 _mm_adds_pu8 (__m64 m1, __m64 m2)

Description: Adds the eight unsigned 8-bit values in m1 to the eight unsigned 8-bit values in m2 using saturating arithmetic.

16.3.8 _mm_adds_pu16


Description: Adds the four unsigned 16-bit values in m1 to the four unsigned 16-bit values in m2 using saturating arithmetic.

16.3.9 _mm_adds_pu32


Description: Two unsigned 32-bit values in m1 to the two unsigned 16-bit values in m2 using saturating arithmetic.

16.3.10 _mm_sub_pi8

Syntax: __m64 _mm_sub_pi8 (__m64 m1, __m64 m2)

Description: Subtracts the eight 8-bit values in m2 from the eight 8-bit values in m1.

16.3.11 _mm_sub_pi16


Description: Subtracts the four 16-bit values in m2 from the four 16-bit values in m1.



16.3.12 _mm_sub_pi32


Description: Subtracts the two 32-bit values in m2 from the two 32-bit values in m1.

16.3.13 _mm_subs_pi8

Syntax: __m64 _mm_subs_pi8 (__m64 m1, __m64 m2)

Description: Subtracts the eight signed 8-bit values in m2 from the eight signed 8-bit values in m1 using saturating arithmetic.

16.3.14 _mm_subs_pi16


Description: Subtracts the four signed 16-bit values in m2 from the four signed 16-bit values in m1 using saturating arithmetic.

16.3.15 _mm_subs_pi32


Description: Subtracts the two signed 32-bit values in m2 from the two signed 32-bit values in m1 using saturating arithmetic.

16.3.16 _mm_subs_pu8

Syntax: __m64 _mm_subs_pu8 (__m64 m1, __m64 m2)

Description: Subtracts the eight unsigned 8-bit values in m2 from the eight unsigned 8-bit values in m1 using saturating arithmetic.



16.3.17 _mm_subs_pu16


Description: Subtracts the four unsigned 16-bit values in m2 from the four unsigned 16-bit values in m1 using saturating arithmetic.

16.3.18 _mm_subs_pu32


Description: Subtracts the two unsigned 32-bit values in m2 from the two unsigned 32-bit values in m1 using saturating arithmetic.

16.3.19 _mm_madd_pi16

Syntax: __m64 _mm_madd_pi16 (__m64 m1, __m64 m2)

Description: Multiplies four 16-bit values in m1 by four 16-bit values in m2 producing four 32-bit intermediate results, which are then summed up: The sum of the lower two products yield the lower word and the sum of the upper two products yield the upper word of the result.

16.3.20 _mm_madd_pu16

Syntax: __m64 _mm_madd_pu16 (__m64 m1, __m64 m2)

Description: Multiplies four unsigned 16-bit values in m1 by four unsigned 16-bit values in m2 producing four 32-bit intermediate results, which are then summed the lower products into the bottom word and the upper two products into the upper word of result.

16.3.21 _mm_mulhi_pi16

Syntax: __m64 _mm_mulhi_pi16(__m64 a, __m64 b)

Description: Multiplies four signed 16-bit values in m1 by four unsigned 16-bit values in m2 and produces the upper 16 bits of the four results.

If r = _mm_mulhi_pi16(a, b), the action is



r0 = hiword(a0 * b0);r1 = hiword(a1 * b1);r2 = hiword(a2 * b2);r3 = hiword(a3 * b3);

16.3.22 _mm_mulhi_pu16

Syntax: __m64 _mm_mulhi_pu16(__m64 a, __m64 b)

Description: Multiplies four unsigned 16-bit values in m1 by four unsigned 16-bit values in m2 and produces the upper 16 bits of the four results.

If r = _mm_mulhi_pu16(a, b), the action is

r0 = hiword(a0 * b0);r1 = hiword(a1 * b1);r2 = hiword(a2 * b2);r3 = hiword(a3 * b3);

16.3.23 _mm_mullo_pi16

Syntax: __m64 _mm_mullo_pi16 (__m64 m1, __m64 m2)

Description: Multiplies four 16-bit values in m1 by four 16-bit values in m2 and produces the lower 16 bits of the four results.

If r = _mm_mullo_pu16(a, b), the action is

r0 = lowword(a0 * b0);r1 = lowword(a1 * b1);r2 = lowword(a2 * b2);r3 = lowword(a3 * b3);

16.3.24 _mm_mac_pi16

Syntax: __m64 _mm_mac_pi16 (__m64 m1, __m64 m2, __m64 m3)

Description: Multiplies four signed 16-bit values in signed m2 by four 16-bit values in m3 and accumulates result with value in m1.



16.3.25 _mm_mac_pu16

Syntax: __m64 _mm_mac_pu16 (__m64 m1, __m64 m2, __m64 m3)

Description: Multiplies four unsigned 16-bit values in unsigned m2 by four 16-bit values in m3 and accumulates result with value in m1.

16.3.26 _mm_macz_pi16

Syntax: __m64 _mm_macz_pi16 (__m64 m1, __m64 m2)

Description: Multiplies four signed 16-bit values in signed m1 by four 16-bit values in m2 and accumulates zero.

16.3.27 _mm_macz_pu16

Syntax: __m64 _mm_macz_pu16 (__m64 m1, __m64 m2)

Description: Multiplies four unsigned 16-bit values in unsigned m1 by four 16-bit values in m2 and accumulates result with zero.

16.3.28 _mm_acc_pu8

Syntax: __m64 _mm_acc_pu8 (__m64 m1)

Description: Unsigned accumulate across eight 8-bit values in m1.

16.3.29 _mm_acc_pu16


Description: Unsigned accumulate across four 16-bit values in m1.



16.3.30 _mm_acc_pu32


Description: Unsigned accumulate across two 32-bit values in m1.

16.3.31 _mm_mia_si64

Syntax: __m64 _mm_mia_si64 (__m64 m1, int a, int b)

Description: Multiplies two signed 32-bit values in a & b and accumulates the result with 64-bit value in m1.

16.3.32 _mm_miaph_si64

Syntax: __m64 _mm_miaph_si64 (__m64 m1, int a, int b)

Description: Multiplies accumulate signed 16-bit values in a & b and accumulates the result with 64-bit values in m1.

Result = sign_extend((a[31:16] * b[31:16]) + (a[15:0] * b[15:0])) + m1;

16.3.33 _mm_miabb_si64

Syntax: __m64 _mm_miabb_si64(__m64 m1, int a, int b)

Multiplies bottom half of signed 16-bit values in a and bottom half of signed 16-bit value in b and accumulates the result with 64-bit values in m1.

Result = sign_extend(a[15:0] * b[15:0]) + m1;

16.3.34 _mm_miabt_si64

Syntax: __m64 _mm_miabt_si64(__m64 m1, int a, int b)

Description: Multiplies bottom half of signed 16-bit values in a and top half of signed 16-bit value in b and accumulates the result with 64-bit values in m1.




16.3.35 _mm_miatb_si64

Syntax: __m64 _mm_miatb_si64(__m64 m1, int a, int b)

Description: Multiplies top half of signed 16-bit values in a and bottom half of signed 16-bit value in b and accumulates the result with 64-bit values in m1.


16.3.36 _mm_miatt_si64

Syntax: __m64 _mm_miatt_si64(__m64 m1, int a, int b)

Description: Multiplies top half of signed 16-bit values in a and top half of signed 16-bit value in b and accumulates the result with 64-bit values in m1.




16.4 Intel® Wireless MMX™ Technology Shift Intrinsics

Table 48. Overview of Intel® Wireless MMX™ Technology Shift Intrinsics

Intrinsic Name Shift Direction Shift Type Intel® Wireless MMX™ Technology Instruction

_mm_sll_pi16 Left Logical WSLLH

_mm_slli_pi16 Left Logical Composite

_mm_sll_pi32 Left Logical WSLLW

_mm_slli_pi32 Left Logical Composite

_mm_sll_si64 Left Logical WSLLD

_mm_slli_si64 Left Logical Composite

_mm_sra_pi16 Right Arithmetic WSRAH

_mm_srai_pi16 Right Arithmetic Composite

_mm_sra_pi32 Right Arithmetic WSRAW

_mm_srai_pi32 Right Arithmetic Composite

_mm_sra_si64 Right Arithmetic WSRAD

_mm_srai_si64 Right Arithmetic Composite

_mm_srl_pi16 Right Logical WSRLH

_mm_srli_pi16 Right Logical Composite

_mm_srl_pi32 Right Logical WSRLW

_mm_srli_pi32 Right Logical Composite

_mm_srl_si64 Right Logical WSRLD

_mm_srli_si64 Right Logical Composite

_mm_ror_pi16 Rotate right Logical WRORH

_mm_ror_pi32 Rotate right Logical WRORW

_mm_ror_si64 Rotate right Logical WRORD

_mm_rori_pi16 Rotate right Logical Composite

_mm_rori_pi32 Rotate right Logical Composite

_mm_rori_si64 Rotate right Logical Composite



16.4.1 _mm_sll_pi16

Syntax: __m64 _mm_sll_pi16 (__m64 m, __m64 count)

Description: Shifts four 16-bit values in m left the amount specified by count while shifting in zeros.

16.4.2 _mm_slli_pi16

Syntax: __m64 _mm_slli_pi16 (__m64 m, int count)

Description: Shifts four 16-bit values in m left the amount specified by count while shifting in zeros.

16.4.3 _mm_sll_pi32

Syntax: __m64 _mm_sll_pi32 (__m64 m, __m64 count)

Description: Shifts two 32-bit values in m left the amount specified by count while shifting in zeros.

16.4.4 _mm_slli_pi32

Syntax: __m64 _mm_slli_pi32 (__m64 m, int count)

Description: Shifts two 32-bit values in m left the amount specified by count while shifting in zeros.

16.4.5 _mm_sll_si64

Syntax: __m64 _mm_sll_si64 (__m64 m, __m64 count)

Description: Shifts the 64-bit value in m left the amount specified by count while shifting in zeros.

16.4.6 _mm_slli_si64

Syntax: __m64 _mm_slli_si64 (__m64 m, int count)

Description: Shifts the 64-bit value in m left the amount specified by count while shifting in zeros.



16.4.7 _mm_sra_pi16

Syntax: __m64 _mm_sra_pi16 (__m64 m, __m64 count)

Description: Shifts four 16-bit values in m right the amount specified by count while shifting in the sign bit.

16.4.8 _mm_srai_pi16

Syntax: __m64 _mm_srai_pi16 (__m64 m, int count)

Description: Shifts four 16-bit values in m right the amount specified by count while shifting in the sign bit.

16.4.9 _mm_sra_pi32

Syntax: __m64 _mm_sra_pi32 (__m64 m, __m64 count)

Description: Shifts two 32-bit values in m right the amount specified by count while shifting in the sign bit.

16.4.10 _mm_srai_pi32

Syntax: __m64 _mm_srai_pi32 (__m64 m, int count)

Description: Shifts two 32-bit values in m right the amount specified by count while shifting in the sign bit.

16.4.11 _mm_sra_si64

Syntax: __m64 _mm_sra_si64 (__m64 m, __m64 count)

Description: Shifts 64-bit value in m right the amount specified by count while shifting in the sign bit.

16.4.12 _mm_srai_si64

Syntax: __m64 _mm_srai_si64 (__m64 m, int count)

Description: Shifts 64-bit value in m right the amount specified by count while shifting in the sign bit.



16.4.13 _mm_srl_pi16

Syntax: __m64 _mm_srl_pi16 (__m64 m, __m64 count)

Description: Shifts four 16-bit values in m right the amount specified by count while shifting in zeros.

16.4.14 _mm_srli_pi16

Syntax: __m64 _mm_srli_pi16 (__m64 m, int count)

Description: Shifts four 16-bit values in m right the amount specified by count while shifting in zeros.

16.4.15 _mm_srl_pi32

Syntax: __m64 _mm_srl_pi32 (__m64 m, __m64 count)

Description: Shifts two 32-bit values in m right the amount specified by count while shifting in zeros.

16.4.16 _mm_srli_pi32

Syntax: __m64 _mm_srli_pi32 (__m64 m, int count)

Description: Shifts two 32-bit values in m right the amount specified by count while shifting in zeros.

16.4.17 _mm_srl_si64

Syntax: __m64 _mm_srl_si64 (__m64 m, __m64 count)

Description: Shifts the 64-bit value in m right the amount specified by count while shifting in zeros.

16.4.18 _mm_srli_si64

Syntax: __m64 _mm_srli_si64 (__m64 m, int count)

Description: Shifts the 64-bit value in m right the amount specified by count while shifting in zeros.



16.4.19 _mm_ror_pi16

Syntax: __m64 _mm_ror_pi16 (__m64 m, __m64 count)

Description: Rotates four 16-bit values in m right the amount specified by count.

16.4.20 _mm_ror_pi32

Syntax: __m64 _mm_ror_pi32 (__m64 m, __m64 count)

Description: Rotates two 32-bit values in m right the amount specified by count.

16.4.21 _mm_ror_si64

Syntax: __m64 _mm_ror_si64 (__m64 m, __m64 count)

Description: Rotates 64-bit value in m right the amount specified by count.

16.4.22 _mm_rori_pi16

Syntax: __m64 _mm_rori_pi16 (__m64 m, int count)

Description: Rotates four 16-bit values in m right the amount specified by count.

16.4.23 _mm_rori_pi32

Syntax: __m64 _mm_rori_pi32 (__m64 m, int count)

Description: Rotates two 32-bit values in m right the amount specified by count.

16.4.24 _mm_rori_si64

Syntax: __m64 _mm_rori_si64 (__m64 m, int count)

Description: Rotates 64-bit value in m right the amount specified by count.



16.5 Intel® Wireless MMX™ Technology Logical Intrinsics

16.5.1 _mm_and_si64

Syntax: __m64 _mm_and_si64 (__m64 m1, __m64 m2)

Description: Performs a bitwise AND of the 64-bit value in m1 with the 64-bit value in m2.

16.5.2 _mm_andnot_si64

Syntax: __m64 _mm_andnot_si64 (__m64 m1, __m64 m2)

Description: Performs a logical NOT on the 64-bit value in m1 and use the result in a bitwise AND with the 64-bit value in m2.

16.5.3 _mm_or_si64

Syntax: __m64 _mm_or_si64 (__m64 m1, __m64 m2)

Description: Performs a bitwise OR of the 64-bit value in m1 with the 64-bit value in m2.

16.5.4 _mm_xor_si64

Syntax: __m64 _mm_xor_si64 (__m64 m1, __m64 m2)

Description: Performs a bitwise XOR of the 64-bit value in m1 with the 64-bit value in m2.

Table 49. Overview of Intel® Wireless MMX™ Technology Logical Intrinsics

Intrinsic Name Operation Intel® Wireless MMX™ Technology Instruction

_mm_and_si64 Bitwise AND WAND

_mm_andnot_si64 Logical NOT WANDN

_mm_or_si64 Bitwise OR WOR

_mm_xor_si64 Bitwise Exclusive OR WXOR



16.6 Intel® Wireless MMX™ Technology Compare Intrinsics

16.6.1 _mm_cmpeq_pi8

Syntax: __m64 _mm_cmpeq_pi8 (__m64 m1, __m64 m2)

Description: If the respective 8-bit values in m1 are equal to the respective 8-bit values in m2, the function sets the respective 8-bit resulting values to all ones, otherwise it sets them to all zeros.




Table 50. Overview of Intel® Wireless MMX™ Technology Compare Intrinsics

Intrinsic Name ComparisonNumber

of Elements

Element Bit Size

Intel® Wireless MMX™ Technology Instruction

_mm_cmpeq_pi8 equal 8 8 WCMPEQB

_mm_cmpeq_pi16 equal 4 16 WCMPEQH

_mm_cmpeq_pi32 equal 2 32 WCMPEQW

_mm_cmpgt_pi8 signed greater than 8 8 WCMPGTSB

_mm_cmpgt_pu8 unsigned greater than 8 8 WCMPGTUB

_mm_cmpgt_pi16 signed greater than 4 16 WCMPGTSH

_mm_cmpgt_pu16 unsigned greater than 4 16 WCMPGTUH

_mm_cmpgt_pi32 signed greater than 2 32 WCMPGTSW

_mm_cmpgt_pu32 unsigned greater than 2 32 WCMPGTUW






16.6.4 _mm_cmpgt_pi8

Syntax: __m64 _mm_cmpgt_pi8 (__m64 m1, __m64 m2)

Description: If the respective 8-bit values in m1 are greater than the respective 8-bit values in m2, the function sets the respective 8-bit resulting values to all ones, otherwise it sets them to all zeros.



Description: If the respective 16-bit values in m1 are greater than the respective 16-bit values in m2, the function sets the respective 16-bit resulting values to all ones, otherwise it sets them to all zeros.



Description: If the respective 32-bit values in m1 are greater than the respective 32-bit values in m2, the function sets the respective 32-bit resulting values to all ones, otherwise it sets them all to zeros.

16.6.7 _mm_cmpgt_pu8

Syntax: __m64 _mm_cmpgt_pu8 (__m64 m1, __m64 m2)

Description: If the respective 8-bit values in m1 are unsigned greater than the respective 8-bit values in m2, the function sets the respective 8-bit resulting values to all ones, otherwise it sets them to all zeros.





Description: If the respective 16-bit values in m1 are unsigned greater than the respective 16-bit values in m2, the function sets the respective 16-bit resulting values to all ones, otherwise it sets them to all zeros.



Description: If the respective 32-bit values in m1 are unsigned greater than the respective 32-bit values in m2, the function sets the respective 32-bit resulting values to all ones, otherwise it sets them all to zeros.



16.7 Intel® Wireless MMX™ Technology PACK/UNPACK Intrinsics

Table 51. Overview of Intel® Wireless MMX™ Technology PACK/UNPACK Intrinsics

Intrinsic Name Intel® Wireless MMX™ Technology Instruction Operation Signed Saturation

_mm_packs_pi16 WPACKHSS Pack Yes Yes

_mm_packs_pi32 WPACKWSS Pack Yes Yes

_mm_packs_pu16 WPACKHUS Pack No Yes

_mm_unpackhi_pi8 WUNPCKIHB Interleave -- --

_mm_unpackhi_pi16 WUNPCKIHH Interleave -- --

_mm_unpackhi_pi32 WUNPCKIHW Interleave -- --

_mm_unpacklo_pi8 WUNPCKILB Interleave -- --

_mm_unpacklo_pi16 WUNPCKILH Interleave -- --

_mm_unpacklo_pi32 WUNPCKILW Interleave -- --

_mm_packs_si64 WPACKDSS Pack Yes Yes

_mm_packs_su64 WPACKDUS Pack No Yes

_mm_packs_pu32 WPACKWUS Pack No Yes

_mm_unpackeh_pi8 WUNPCKEHSB Sign-extended Yes No

_mm_unpackeh_pi16 WUNPCKEHSH Sign-extended Yes No

_mm_unpackeh_pi32 WUNPCKEHSW Sign-extended Yes No

_mm_unpackeh_pu8 WUNPCKEHUB Zero-extended No No

_mm_unpackeh_pu16 WUNPCKEHUH Zero-extended No No

_mm_unpackeh_pu32 WUNPCKEHUW Zero-extended No No

_mm_unpackel_pi8 WUNPCKELSB Sign-extended Yes No

_mm_unpackel_pi16 WUNPCKELSH Sign-extended Yes No

_mm_unpackel_pi32 WUNPCKELSW Sign-extended Yes No

_mm_unpackel_pu8 WUNPCKELUB Zero-extended No No

_mm_unpackel_pu16 WUNPCKELUH Zero-extended No No

_mm_unpackel_pu32 WUNPCKELUW Zero-extended No No



16.7.1 _mm_packs_pi16

Syntax: __m64 _mm_packs_pi16 (__m64 m1, __m64 m2)

Description: Packs the four 16-bit values from m1 into the lower four 8-bit values of the result with signed saturation, and packs the four 16-bit values from m2 into the upper four 8-bit values of the result with signed saturation.

16.7.2 _mm_packs_pi32

Syntax: __m64 _mm_packs_pi32 (__m64 m1, __m64 m2)

Description: Packs the two 32-bit values from m1 into the lower two 16-bit values of the result with signed saturation, and packs the two 32-bit values from m2 into the upper two 16-bit values of the result with signed saturation.

16.7.3 _mm_packs_pu16

Syntax: __m64 _mm_packs_pu16 (__m64 m1, __m64 m2)

Description: Packs the four 16-bit values from m1 into the lower four 8-bit values of the result with unsigned saturation, and packs the four 16-bit values from m2 into the upper four 8-bit values of the result with unsigned saturation.

16.7.4 _mm_unpackhi_pi8

Syntax: __m64 _mm_unpackhi_pi8 (__m64 m1, __m64 m2)

Description: Interleaves the four 8-bit values from the upper half of m1 with the four values from the upper half of m2. The interleaving begins with the data from m1.



Description: Interleaves the two 16-bit values from the upper half of m1 with the two values from the upper half of m2. The interleaving begins with the data from m1.





Description: Interleaves the 32-bit value from the upper half of m1 with the 32-bit value from the upper half of m2. The interleaving begins with the data from m1.

16.7.7 _mm_unpacklo_pi8

Syntax: __m64 _mm_unpacklo_pi8 (__m64 m1, __m64 m2)

Description: Interleaves the four 8-bit values from the lower half of m1 with the four values from the lower half of m2. The interleaving begins with the data from m1.



Description: Interleaves the two 16-bit values from the lower half of m1 with the two values from the lower half of m2. The interleaving begins with the data from m1.



Description: Interleaves the 32-bit value from the lower half of m1 with the 32-bit value from the lower half of m2. The interleaving begins with the data from m1.

16.7.10 _mm_packs_si64

Syntax: __m64 _mm_packs_si64 (__m64 m1, __m64 m2)

Description: Packs the 64-bit value from m1 into the lower 32-bit value of the result with signed saturation, and packs the one 32-bit value from m2 into the upper 32-bit value of the result with signed saturation.



16.7.11 _mm_packs_su64

Syntax: __m64 _mm_packs_su64 (__m64 m1, __m64 m2)

Description: Packs the 64-bit value from m1 into the lower 32-bit value of the result with signed saturation, and packs the upper 32-bit value from m2 into the upper 32-bit value of the result with signed saturation.

16.7.12 _mm_packs_pu32

Syntax: __m64 _mm_packs_pu32 (__m64 m1, __m64 m2)

Description: Packs the two 32-bit values from m1 into the lower two 16-bit values of the result with unsigned saturation, and packs the two 32-bit values from m2 into the upper two 16-bit values of the result with unsigned saturation.

16.7.13 _mm_unpackeh_pi8

Syntax: __m64 _mm_unpackeh_pi8 (__m64 m1)

Description: Unpacks the four 8-bit values from the upper half of m1 and sign-extends each value.



Description: Unpacks the two 16-bit values from the upper half of m1 and sign-extends each value.



Description: Unpacks the 32-bit value from the upper half of m1 and sign-extends each value.



16.7.16 _mm_unpackeh_pu8

Syntax: __m64 _mm_unpackeh_pu8 (__m64 m1)

Description: Unpacks the four 8-bit values from the upper half of m1 and zero-extends each value.



Description: Unpacks the two 16-bit values from the upper half of m1 and zero-extends each value.



Description: Unpacks the 32-bit value from the upper half of m1 and zero-extends each value.

16.7.19 _mm_unpackel_pi8

Syntax: __m64 _mm_unpackel_pi8 (__m64 m1)

Description: Unpacks the four 8-bit values from the lower half of m1 and sign-extends each value.



Description: Unpacks the two 16-bit values from the lower half of m1 and sign-extends each value.



Description: Unpacks the 32-bit value from the lower half of m1 and sign-extends each value.



16.7.22 _mm_unpackel_pu8

Syntax: __m64 _mm_unpackel_pu8 (__m64 m1)

Description: Unpacks the four 8-bit values from the lower half of m1 and zero-extends each value.



Description: Unpacks the two 16-bit values from the lower half of m1 and zero-extends each value.



Description: Unpacks the 32-bit value from the lower half of m1 and zero-extends each value.



16.8 Intel® Wireless MMX™ Technology Set Intrinsics

Note: In the following descriptions regarding the order of bits of the Intel® Wireless MMX™ Technology registers, bit 0 is the least significant one and bit 63 is the most significant one.

Table 52. Overview of Intel® Wireless MMX™ Technology Set Intrinsics

Intrinsic Name OperationNumber

of Elements

Instruction Element Bit Size Signed Reverse

Order

_mm_setzero_si64 Set to zero 1 WZERO 64 No No

_mm_set_pi32 Set integer values 2 Composite 32 No No



_mm_set1_pi32 Set integer values 2 TBCSTW 32 Yes No

_mm_set1_pi16 Set integer values 4 TBCSTH 16 Yes No

_mm_set1_pi8 Set integer values 8 TBCSTB 8 Yes No

_mm_setr_pi32 Set integer values 2 Composite 32 No Yes



_mm_setwcx Set control register -- TMCR -- -- --

_mm_getwcx Get control register -- TMRC -- -- --



16.8.1 _mm_setzero_si64

Syntax: __m64 _mm_setzero_si64 ()

Description: Sets the 64-bit value to zero.

If r = _mm_setzero_si64(), the action is

r = 0x0;

16.8.2 _mm_set_pi32

Syntax: __m64 _mm_set_pi32 (int i1, int i0)

Description: Sets the 2 signed 32-bit integer values.

If r = _mm_set_pi32(i1, i0), the action is

r0 = i0;r1 = i1;

16.8.3 _mm_set_pi16

Syntax: __m64 _mm_set_pi16 (short w3, short w2, short w1, short w0)


If r = _mm_set_pi16 (w3, w2, w1, w0), the action is

r0 = w0;r1 = w1;r2 = w2;r3 = w3;



16.8.4 _mm_set_pi8

Syntax: __m64 _mm_set_pi8 (char b7, char b6, char b5, char b4, char b3, char b2, char b1, char b0)


If r = _mm_set_pi8 (b7, b6, b5, b4, b3, b2, b1, b0), the action is

r0 = b0;r1 = b1;...r7 = b7;

16.8.5 _mm_set1_pi32

Syntax: __m64 _mm_set1_pi32 (int i)

Description: Sets the 2 signed 32-bit integer values to i.

If r = _mm_set1_pi32 (i), the action is

r0 = i;r1 = i;

16.8.6 _mm_set1_pi16

Syntax: __m64 _mm_set1_pi16 (short w)

Description: Sets the 4 signed 16-bit integer values to w.

If r = _mm_set1_pi16 (w), action is

r0 = w;r1 = w;r2 = w;r3 = w;



16.8.7 _mm_set1_pi8

Syntax: __m64 _mm_set1_pi8 (char b)

Description: Sets the 8 signed 8-bit integer values to b.

If r = _mm_set1_pi8 (b), the action is

r0 = b;r1 = b;...r7 = b;

16.8.8 _mm_setr_pi32

Syntax: __m64 _mm_setr_pi32 (int i0, int i1)

Description: Sets the 2 signed 32-bit integer values in reverse order.

If r = _mm_setr_pi32 (i0, i1), the action is

r0 = i0;r1 = i1;


Syntax: __m64 _mm_setr_pi16 (short w0, short w1,short w2, short w3)

If r = _mm_setr_pi16 (w0, w1, w2, w3), the action is

r0 = w0;r1 = w1;r2 = w2;r3 = w3;




Syntax: __m64 _mm_setr_pi8 (char b0, char b1,char b2, char b3, char b4, char b5, char b6, char b7)

Description: Sets the 8 signed 8-bit integer values in reverse order.

If r = _mm_setr_pi8 (b0, b1, b2, b3, b4, b5, b6, b7), the action is

r0 = b0;r1 = b1;...r7 = b7;

16.8.11 _mm_setwcx

Syntax: void __mm_setwcx(int value, int number)

Description: Sets the Intel® Wireless MMX™ Technology control register specified by number to the contents of value.

16.8.12 _mm_getwcx

Syntax: int __mm_getwcx(int number)

Description: Returns contents of Intel® Wireless MMX™ Technology control register, which is specified with number. Where number is the coprocessor register number.



16.9 Intel® Wireless MMX™ Technology General Support Intrinsics

Table 53. Intel® Wireless MMX™ Technology General Support Intrinsics

Intrinsic Name Operation Intel® Wireless MMX™ Technology Instruction Sign

_mm_extract_pi8 Extract one of eight bytes TEXTRMSB Yes

_mm_extract_pi16 Extract one of four halfwords TEXTRMSH Yes

_mm_extract_pi32 Extract one of two words TEXTRMSW Yes

_mm_extract_pu8 Extract one of eight bytes TEXTRMUB No

_mm_extract_pu16 Extract one of four half words TEXTRMUH No

_mm_extract_pu32 Extract one of two words TEXTRMUW No

_mm_insert_pi8 Insert a byte TINSRB --

_mm_insert_pi16 Insert a halfword TINSRH --

_mm_insert_pi32 Insert a word TINSRW --

_mm_max_pi8 Compute the maximum WMAXSB

_mm_max_pi16 Compute the maximum WMAXSH

_mm_max_pi32 Compute the maximum WMAXSW

_mm_max_pu8 Compute the maximum, unsigned WMAXUB

_mm_max_pu16 Compute the maximum, unsigned WMAXUH

_mm_max_pu32 Compute the maximum, unsigned WMAXUW

_mm_min_pi8 Compute the minimum WMINSB

_mm_min_pi16 Compute the minimum WMINSH

_mm_min_pi32 Compute the minimum WMINSW

_mm_min_pu8 Compute the minimum, unsigned WMINUB

_mm_min_pu16 Compute the minimum, unsigned WMINUH

_mm_min_pu32 Compute the minimum, unsigned WMINUW

_mm_movemask_pi8 Create a eight-bit mask TMOVMSKB

_mm_movemask_pi16 Create a four halfword mask TMOVMSKH

_mm_movemask_pi32 Create a two-word mask TMOVMSKW

_mm_shuffle_pi16 Return a combination of four words WSHUFH

_mm_avg_pu8 Compute rounded average WAVG2BR

_mm_avg_pu16 Compute rounded average WAVG2HR

_mm_avg2_pu8 Compute rounded average without rounding +1 WAVG2B

_mm_avg2_pu16 Compute rounded average without rounding +1 WAVG2H

_mm_sad_pu8 Compute sum of absolute differences WSADBZ

_mm_sad_pu16 Compute sum of absolute differences WSADHZ



16.9.1 _mm_extract_pi8

Syntax: int _mm_extract_pi8(__m64 a, const int n)

Description: Extracts one of the eight bytes of a. The selector n must be an immediate. The n variable selects the byte that should be extracted.

If r = _mm_extract_pi8(a, n), the action is

r[7:0] = a[Byte n[2:0]];r[31:8] = SignReplicate(a[Byte n[2:0]], 24);

_mm_sada_pu8 Accumulate sum of absolute differences WSADB

_mm_sada_pu16 Accumulate sum of absolute differences WSADH

_mm_align_si64 Extract a 64-bit value WALIGNI/WALIGNR --

_mm_cvtsi64_m64 Transfer TMCRR --

_mm_cvtm64_si64 Transfer TMRRC --

_mm_cvtsi32_si64 Convert from integer TMCRR --

_mm_cvtsi64_si32 Convert to integer TMRRC --

Table 53. Intel® Wireless MMX™ Technology General Support Intrinsics

Intrinsic Name Operation Intel® Wireless MMX™ Technology Instruction Sign





Description: Extracts one of the four half words of a. The selector n must be an immediate.


r[15:0] = a[Halfword n[1:0]];r[31:16] = SignReplicate(a[Byte n[1:0]], 16);



Description: Extracts one of the two words of a. The selector n must be an immediate.


r[31:0] = a[Byte n[0]];

16.9.4 _mm_extract_pu8

Syntax: int _mm_extract_pu8(__m64 a, const int n)

Description: Extracts one of the eight bytes of a. The selector n must be an immediate.

If r = _mm_extract_pu8(a, n), the action is

r[7:0] = a[Byte n[2:0]];r[31:8] = 0;





Description: Extracts one of the four half words of a. The selector n must be an immediate.

If r = _mm_extract_pu16(a, n), the action is

r [15:0] = a[Halfword n[1:0]];r[31:16] = 0;



Description: This provides same functionality as _mm_extract_pi32.

16.9.7 _mm_insert_pi8

Syntax: __m64 _mm_insert_pi8(__m64 a, int d, int n)

Description: Inserts byte d into one of eight bytes of a. The selector n must be an immediate.

If r = _mm_insert_pi8(a, d, n), the action is

r0 = (n==0) ? d[7:0] : a0;r1 = (n==1) ? d[7:0] : a1;r2 = (n==2) ? d[7:0] : a2;r3 = (n==3) ? d[7:0] : a3;r4 = (n==4) ? d[7:0] : a4;r5 = (n==5) ? d[7:0] : a5;r6 = (n==6) ? d[7:0] : a6;r7 = (n==7) ? d[7:0] : a7;





Description: Inserts half word d into one of four half words of a. The selector n must be an immediate.


r0 = (n==0) ? d[15:0] : a0;r1 = (n==1) ? d[15:0] : a1;r2 = (n==2) ? d[15:0] : a2;r3 = (n==3) ? d[15:0] : a3;



Description: Inserts word d into one of two half words of a. The selector n must be an immediate.


r0 = (n==0) ? d[31:0] : a0;r1 = (n==1) ? d[31:0] : a1;

16.9.10 _mm_max_pi8

Syntax: __m64 _mm_max_pi8(__m64 a, __m64 b)

Description: Computes the element-wise maximum of the bytes in a and b.

If r = _mm_max_pi8(a, b), the action is

r0 = max(a0, b0);r1 = max(a1, b1);...r7 = max(a7, b7);



16.9.11 _mm_max_pi16


Description: Computes the element-wise maximum of the half words in a and b.


r0 = max(a0, b0);r1 = max(a1, b1);r2 = max(a2, b2);r3 = max(a3, b3);

16.9.12 _mm_max_pi32


Description: Computes the element-wise maximum of the words in a and b.


r0 = max(a0, b0);r1 = max(a1, b1);

16.9.13 _mm_max_pu8

Syntax: __m64 _mm_max_pu8(__m64 a, __m64 b)

Description: Computes the element-wise maximum of the unsigned bytes in a and b.

If r = _mm_max_pu8(a, b), the action is

r0 = max(a0, b0);r1 = max(a1, b1);...r7 = max(a7, b7);



16.9.14 _mm_max_pu16


Description: Computes the element-wise maximum of the unsigned half words in a and b.


r0 = max(a0, b0);r1 = max(a1, b1);r2 = max(a2, b2);r3 = max(a3, b3);

16.9.15 _mm_max_pu32


Description: Computes the element-wise maximum of the unsigned words in a and b.


r0 = max(a0, b0);r1 = max(a1, b1);

16.9.16 _mm_min_pi8

Syntax: __m64 _mm_min_pi8(__m64 a, __m64 b)

Description: Computes the element-wise minimum of the bytes in a and b.

If r = _mm_min_pi8(a, b), the action is

r0 = min(a0, b0);r1 = min(a1, b1);...r7 = min(a7, b7);



16.9.17 _mm_min_pi16


Description: Computes the element-wise minimum of the half words in a and b.


r0 = min(a0, b0);r1 = min(a1, b1);r2 = min(a2, b2);r3 = min(a3, b3);

16.9.18 _mm_min_pi32


Description: Computes the element-wise minimum of the words in a and b.


r0 = min(a0, b0);r1 = min(a1, b1);

16.9.19 _mm_min_pu8

Syntax: __m64 _mm_min_pu8(__m64 a, __m64 b)

Description: Computes the element-wise minimum of the unsigned bytes in a and b.

If r = _mm_min_pu8(a, b), the action is

r0 = min(a0, b0);r1 = min(a1, b1);...r7 = min(a7, b7);



16.9.20 _mm_min_pu16


Description: Computes the element-wise minimum of the unsigned half words in a and b.


r0 = min(a0, b0);r1 = min(a1, b1);r2 = min(a2, b2);r3 = min(a3, b3);

16.9.21 _mm_min_pu32


Description: Computes the element-wise minimum of the unsigned words in a and b.


r0 = min(a0, b0);r1 = min(a1, b1);

16.9.22 _mm_movemask_pi8

Syntax: int _mm_movemask_pi8(__m64 a)

Description: Creates an 8-bit mask from the most significant bits of the bytes in a.

If r = _mm_movemask_pi8(a), the action is

r = 0;r = sign(a7)<<7 | sign(a6)<<6 |... | sign(a0);





Description: Creates an 4-bit mask from the most significant bits of the half words in a.


r = 0;r = sign(a3)<<3 | sign(a2)<<2 |... | sign(a0);



Description: Creates an 2-bit mask from the most significant bits of the bytes in a.


r = 0;r = sign(a1)<<1 | sign(a0);

16.9.25 _mm_shuffle_pi16

Syntax: __m64 _mm_shuffle_pi16(__m64 a, int n)

Description: Returns a combination of the four half words of a. The selector n must be an immediate.

If r = _mm_shuffle_pi16(a, n), the action is

r0 = Half word (n&0x3) of ar1 = Half word ((n>>2)&0x3) of ar2 = Half word ((n>>4)&0x3) of ar3 = Half word ((n>>6)&0x3) of a



16.9.26 _mm_avg_pu8

Syntax: __m64 _mm_avg_pu8(__m64 a, __m64 b)

Description: Computes the (rounded) averages of the unsigned bytes in a and b.

If r = _mm_avg_pu8(a, b), the action is

t = (unsigned short)a0 + (unsigned short)b0;r0 = (t >> 1) | (t & 0x01);...t = (unsigned short)a7 + (unsigned short)b7;r7 = (unsigned char)((t >> 1) | (t & 0x01));

16.9.27 _mm_avg_pu16

Syntax: __m64 _mm_avg_pu16(__m64 a, __m64 b)

Description: Computes the (rounded) averages of the unsigned words in a and b.

If r = _mm_avg_pu16(a, b), the action is

t = (unsigned int)a0 + (unsigned int)b0;r0 = (t >> 1) | (t & 0x01);...t = (unsigned word)a7 + (unsigned word)b7;r7 = (unsigned short)((t >> 1) | (t & 0x01));



16.9.28 _mm_avg2_pu8

Syntax: __m64 _mm_avg2_pu8(__m64 a, __m64 b)

Description: Computes the without rounded averages of the unsigned bytes in a and b.

If r = _mm_avg2_pu8(a, b), the action is

t = (unsigned byte)a0 + (unsigned byte)b0;r0 = (t >> 1);...t = (unsigned byte)a7 + (unsigned byte)b7;r7 = (unsigned char)(t >> 1);

16.9.29 _mm_avg2_pu16

Syntax: __m64 _mm_avg2_pu16(__m64 a, __m64 b)

Description: Computes the with out rounded averages of the unsigned words in a and b.

If r = _mm_avg2_pu16(a, b), the action is

t = (unsigned half word)a0 + (unsigned half word)b0;r0 = (t >> 1);...t = (unsigned half word)a3 + (unsigned half word)b3;r3 = (unsigned short)(t >> 1);



16.9.30 _mm_sad_pu8

Syntax: __m64 _mm_sad_pu8(__m64 a, __m64 b)

Description: Computes the sum of the absolute differences of the unsigned bytes in a and b, returning the value in the lower word. The upper word of the result is cleared.

If r = _mm_sad_pu8(a, b), the action is

r [0:31] = abs(a0-b0) +... + abs(a7-b7);r[32:63] = 0;

16.9.31 _mm_sad_pu16

Syntax: __m64 _mm_sad_pu16(__m64 a, __m64 b)

Description: Computes the sum of the absolute differences of the unsigned half words in a and b, returning the value in the lower word. The upper word of the result is cleared.

If r = _mm_sad_pu16(a, b), the action is

r [0:31] = abs(a0-b0) +... + abs(a3-b3);r[32:63] = 0;

16.9.32 _mm_sada_pu8

Syntax: __m64 _mm_sada_pu8(__m64 a, __m64 b, __m64 c)

Description: Computes the sum of the absolute differences of the bytes in b and c, and accumulates the result with the lower word of a. The upper word of the result is cleared.

If r = _mm_sada_pu8(a, b, c), the action is

r [0:31] = a[0:31] + abs(b0-c0) +... + abs(b7-c7);r[32:63] = 0;



16.9.33 _mm_sada_pu16

Syntax: __m64 _mm_sada_pu16(__m64 a, __m64 b, __m64 c)

Description: Computes the sum of the absolute differences of the half words in b and c, and accumulates the result with the lower word of a.The upper word of the result is cleared.

If r = _mm_sada_pu16(a, b, c), the action is

r [0:31] = a[0:31] + abs(b0-c0) +... + abs(b3-c3);r[32:63] = 0;

16.9.34 __mm_align_si64

Syntax: __m64 __mm_align_si64(__m64 m1, __m64 m2, int count)

Description: Extracts an 64-bit value from the two 64-bit input values m1, m2 with count byte offset.

If r = __mm_align_si64(m1, m2, count), the action is

r = Low_DB_word((m1, m2) >> (count * 8));

16.9.35 _mm_cvtsi64_m64

Syntax: __m64 _mm_cvtsi64_m64 (__int64 i)

Description: Converts the __int64 integer i to a 64-bit __m64 object.

If r = _mm_cvtsi64_m64(a), then the action is

r [31:0] = a0; (lower word)r[63:32] = a1; (upper word)



16.9.36 _mm_cvtm64_si64

Syntax: __int64 _mm_cvtm64_si64 (__m64 m)

Description: Converts the 64-bit __m64 object m to __int64 bit integer.

If r = _mm_cvtm64_si64(a), then the action is

r0 = a[31:0]; (lower word)r1 = a[63:32]; (upper word)

16.9.37 _mm_cvtsi64_si32

Syntax: int _mm_cvtsi64_si32 (__m64 m)

Description: Converts the lower 32 bits of the __m64 object m to an integer.

If i = _mm_cvtsi64_si32(m), then the action is

i = a[31:0]; (lower word)

16.9.38 _mm_cvtsi32_si64

Syntax: __m64 _mm_cvtsi32_si64 (int i)

Description: Converts the integer object i to a 64 bit __m64 object. The integer value is zero-extended to 64 bits.

If r = _mm_cvtsi32_si64(i), then the action is

r [0:31] = i;r[32:63] = 0;


Diagnostics and Messages 17

This chapter provides a detailed description of the many diagnostic and other messages which can be generated by the Intel® C++ Compiler.

The chapter is divided into several parts:

• Section 17.1, “Overview” on page 740 explains the mechanism for diagnostics and other messages generated by the Intel® C++ Compiler.

• Section 17.2, “Diagnostics” on page 741 describes command line and language diagnostics and provides a description of how you can control the severity of diagnostics.

• Section 17.3, “Messages” on page 745 describes compiler information messages, diagnostic messages including remark, warning, and error messages.


Diagnostics and Messages

17.1 Overview

During its compilation process the Intel® C++ Compiler can generate a number of diagnostic and other messages. These may be due to errors in the command line, or problems within the source code. Syntactic and semantic problems within the source code may result in simple remarks or warnings which won’t stop the compilation process from completing, and are generated as a way of information to the user. Other problems may result in messages informing of errors, which are fatal and must be corrected, since they stop the compilation and linking process from completing.

The severity of these diagnostic messages may be altered, allowing the user to select which messages are generated, and their type. All messages generated by the Intel® C++ Compiler are displayed on the standard output stream.



17.2 Diagnostics

This section describes command line and language diagnostics, and provides a description of how you can control the severity of diagnostics.

17.2.1 Command Line Diagnostics

Command Line Diagnostics report improper and unrecognized command line arguments of filenames and options, and constitute both warning and error messages. Warning messages are generated where the compiler is able to make assumptions about the interpretation of the arguments and continue. Error messages are generated when the compiler is not able to continue.

Command line diagnostics take the form:

• Command line warning: message describing the warning.

• Command line error: message describing the error.

Example 324. Command Line Error

The following command

ccxsc

will generate the error:

ccxsc: Command line error: no files specified; for help type "ccxsc -HELP"



17.2.2 Language Diagnostics

These diagnostic messages provide information relating to the source code being compiled, and include semantic as well as syntactic information. Examples of syntactic information would include syntax errors and use of nonstandard code while examples of semantic information would include unreachable code and unnecessary loops and branching.

Diagnostic messages include remarks, warnings and errors. Remarks and warnings are informational messages to the user and do not stop the compilation and linking process. The user may then choose to act upon these messages or not. Errors on the other hand interrupt the compilation process, the Intel® C++ Compiler attempting to continue but with no linking taking place. These errors must be corrected before an executable file can be made.

For a diagnostic message the Intel® C++ Compiler will display the name of the source file and the line to which the diagnostic refers, a diagnostic number, and a brief description of the problem. A typical diagnostic message has the following format:

filename(linenumber): type [#nn]: message

Example 325. Remark Message

The following example shows you how to generate remarks with the compiler by setting option -W5

ccxsc alpha.c -W5

can generate the following output

alpha.c:alpha.c(257): remark #177: variable "inst" was declared but never referenced.

The compiler can also issue internal error messages on the standard error stream; these take the form:

FATAL COMPILER ERROR: message

Should this occur contact Intel customer support for advice.

filename Name of source file being compiled.

linenumber Line number of source file to which diagnostic refers.

type Type of diagnostic (remark, warning or error).

#nn Number of diagnostic (hard errors do not have numbers associated with them)

message Brief description of problem.



17.2.3 Controlling the Severity of the Diagnostics

The compiler returns two types of diagnostics:

Example 326. Changing Severity of a Soft Diagnostic

In the following example the soft diagnostics numbered 68 and 152 have their severity changed to be remarks only while the source file alpha.c is being compiled and linked:

ccxsc -Qwr68,152 alpha.c

Type Description

Hard errors An error diagnostic is always generated if the source code is definitely wrong or questionable. Hard errors do not have any message numbers associated with them. A hard error leads to a direct abort.

Soft errors All other diagnostics, including warnings and remarks, are considered soft diagnostics, and these always have message numbers associated with them. Their severity can be changed by use of the options described in the table below.

Table 54. Soft Error Severity Changes

-Qwd[number, . . . ] Disable the diagnostics having the listed corresponding numbers

-Qwr[number, . . . ] Override the severity of the diagnostics having the listed corresponding numbers, and make them to remarks

-Qww[number, . . . ] Override the severity of the diagnostics having the listed corresponding numbers, and make them to warnings

-Qwe[number, . . . ] Override the severity of the diagnostics having the listed corresponding numbers, and make them to errors



Note: Only soft diagnostic messages, those having numbers generated with them, can have their severity changed. Should it not be known if a particular message carries a number, that is if it is a soft diagnostic, then in the first instance the compiler can be allowed to generate the message, with its error number. Once the soft errors are identified the compilation can be repeated with any changes of severity made that are required to the soft diagnostic messages.

Example 327. Changing Severity of a Warning Message

The following compilation

ccxsc alpha.c

can produce a soft diagnostic message:

alpha.c:alpha.c(341): warning#191: type qualifier is meaningless on cast type

This identifies this warning as being a soft diagnostic, that is it has a number generated with it.To remove this warning it can be reduced to a remark. By default remarks are not generated by a compilation. You can repeat the above exercise to remove the warning.

ccxsc --Qwr191 alpha.c

will produce no diagnostic messages:

alpha.c



17.3 Messages

This section describes compiler information messages and diagnostic messages including remark, warning, and error messages.

17.3.1 Compiler Information Messages

These messages consist of the Intel® C++ Compiler start message and the help list of the more useful Intel® C++ Compiler options. Both messages are optional, being controlled by options on the command line.

The start message is controlled by the option:

-nologo

It disables the display of the compiler version (or start) message. When the compiler is invoked, it displays the following information:

The help list is controlled by the option:

-HELP or -?

It displays help messages. You can display a list of the most useful compiler options by specifying the -HELP (or -?) option to the compiler. To display this list, use this command:

ID The unique identification number for this compiler.

a.b.c Version number, for example, 2.3.10

Years Years for which the compiler is copyrighted.



17.3.2 Diagnostic Messages

Diagnostic messages provide syntactic and semantic information about your source text. Syntactic information can include syntax errors and use of nonstandard C or C++. Semantic information includes such things as unreachable code. Diagnostic messages can be any of the following:

• Remark messages

• Warning messages

• Error message

The severity of some of the diagnostic messages can be changed by compiler options. Some warnings can become errors, and remarks become warnings.

17.3.2.1 Remark Messages

Remark messages report common but sometimes unconventional usage of the C/C++ language within the source code. Such remarks do not interfere with the compilation process, compilation and linking proceed to their final stages producing the required output files with no alterations.

The compiler does not generate remark messages unless requested by specifying the -W option to be at level 4. That is option -W4 informational messages.

Examples 328. Remark Messages

Some examples of remark messages:

alpha.c (321): Remark #193: Zero used for undefined preprocessing identifier.

alpha.c (456): Remark #577: Use of local type to specify an exception.

alpha.c (501): Remark #981: Operands are evaluated in unspecified order.



17.3.2.2 Warning Messages

Warning messages report legal but questionable use of the C/C++ language within the source code. Such warnings do not interfere with the compilation process, compilation and linking proceed to their final stages producing the required output files with no alterations.

The Intel® C++ Compiler generates warning messages by default, unless suppressed by specifying the -W option to be at level 0. The option -W0 generates no warnings.

Examples 329. Warning Messages

Some examples of warning messages:

alpha.c (123): Warning #170: Pointer points outside of underlying object.

alpha.c (321): Warning #457: Delete of pointer to incomplete class.

alpha.c (405): Warning #945: Type qualifier ignored.

17.3.2.3 Error Messages

Error messages report C/C++ language syntactic and semantic errors within the source code. Such errors suppress the generation of object code for the source module in which the error occurred, but parsing continues to allow any other errors to be found. Linking is prevented if any errors are found to occur within the source code being compiled.

The Intel® C++ Compiler error messages cannot be suppressed.

Examples 330. Error Messages

Some examples of error messages:

alpha.c (101): Error #226: asm macro parameter must have basic or pointer type.

alpha.c (235): Error #611: Invalid C output file.

alpha.c (312): Error #936: A variable length array cannot have static storage duration.


Index

Symbols/Fo, option 100/o, option 114/Qprec, option 141/Qprec_div, option 142/Zg, option 179? option 86-?, option 86@, option 51__adddf3, floating point function 528, 529__ashldi3, floating point function 530__ashrdi3, floating point function 531__cplusplus, included macro 255__cxx_disable_critical_section_lock, run-time library func-

tion 654__cxx_enter_critical_section, run-time library function 656__cxx_exit_critical_section, run-time library functions 657__cxx_share_critical_section_lock, run-time library function

658__cxx_tls_alloc_hook, run-time library function 659__cxx_tls_create_callout, callout function 686__cxx_tls_delete, run-time library function 660__cxx_tls_delete_hook, run-time library function 661__cxx_tls_delete_root_hook, run-time library function 662__cxx_tls_exit_hook, run-time library functions 663__cxx_tls_free_hook, run-time library function 664__cxx_tls_get_hook, run-time library functions 665__cxx_tls_get_root, run-time library function 666__cxx_tls_init, run-time library function 667__cxx_tls_init_hook, run-time library function 668__cxx_tls_kill_callout, callout function 687__cxx_tls_restart_callout, callout function 688__cxx_tls_set, run-time library function 669__cxx_tls_set_hook, run-time library function 670__cxx_tls_setup, run-time library function 671__cxx_tls_size, run-time library function 672__cxx_tls_switch_callout, callout function 689__DATE__, included macro 255__divdf3, floating point function 532__divdi3, floating point function 533__divsf3, floating point function 534__divsi3, floating point function 535__eqdf2, floating point function 536__eqsf2, floating point function 538__extendsfdf2, floating point function 540__FILE__, included macro 255__fixdfdi, floating point function 542__fixdfsi, floating point function 543__fixsfdi, floating point function 544__fixsfsi, floating point function 546__fixunsdfdi, floating point function 547__fixunsdfsi, floating point function 549__fixunssfdi, floating point function 550

__fixunssfsi, floating point function 551__floatdidf, floating point function 552__floatdisf, floating point function 553__floatsidf, floating point function 554__floatsisf, floating point function 555__floatunsdidf, floating point function 556__floatunsdisf, floating point function 557__floatunssidf, floating point function 558__floatunssisf, floating point function 559__ftp8, floating point function 597__gedf2, floating point function 560__gesf2, floating point function 562__gtdf2, floating point function 564__gtsf2, floating point function 566__ledf2, floating point function 568__lesf2, floating point function 570__lib_assert__, run-time library function 673__lib_fatal__, run-time library function 674__lib_fatal_default_terminate_routine, run-time library func-

tion 675__LINE__, included macro 255__lshrdi3, floating point function 572__ltdf2, floating point function 573__ltsf2, floating point function 575__moddi3, floating point function 577__modsi3, floating point function 578__muldf3, floating point function 579__mulsf3, floating point function 580__nedf2, floating point function 581__negdf2, floating point function 583__negsf2, floating point function 584__nesf2, floating point function 585__pure_virtual_called, run-time library function 676__STDC__, included macro 255__subdf3, floating point function 587__subsf3, floating point function 588__TIME__, included macro 255__TIMESTAMP__, included macro 255__truncdfsf2, floating point function 589__udivdi3, floating point function 591__udivsi3, floating point function 592__umoddi3, floating point function 593__umodsi3, floating point function 594_lmul, floating point function 595_main, run-time library function 677_memcopy, memory function 596

Aabort, library function 306abs, library function 307acos, library function 308add run time information to object code 157


add text string within object files 165additional library functions 266, 275aliasing

switch off 123within functions 115

alignstructure members 181, 199, 207

align pragma 207alloc_text pragma 185allocating

function definitions 185alternative assembler 137alternative assembler specification 87alternative linker 137alternative linker specification 89alternative path to assembler 87alternative path to linker 89alternative tools 137analyzing effects, multifile IPO 224AngleSWI, system interface function 624ANSI C functions, C Library 266ANSI C, extended

language conformance 252ANSI C, strict

language conformance 252ANSI conformance 129ANSI/ISO C standard

extensions 253predefined macros 255

ANSI/ISO C++ standardexceptions 256

ANSI-defined non-reentrant library functions 270See also library functions

ANSI-defined reentrant library functions 268See also library functions

ANSI-defined system interface functions 606–611arguments 30arithmetic, floating point arithmetic precision 220ARMSystemCall, system interface function 625asctime, library function 309asin, library function 310assembler listings file name 96assembly language

output files 211, 212example 214generation 212

assembly language output files 158assert, macro 300assert.h, header file 279, 280associate a symbol with values 128atan, library function 311atan2, library function 312atexit, library function 313atof, library function 314atoi, library function 316atol, library function 317atoll, library function 318automatic precompiled header file 174

B-Ba, option 87Ba, option 87-Bd, option 88, 90Bd, option 88, 90_blocksizebrk, system interface function 613-Bl, option 89Bl, option 89bool, data type 111bsearch, library function 319bss_seg pragma 186

CC dialect, set for extended C dialect 254C Library 266

additional library functions 266ANSI C functions 266C run-time functions 266

C option 91c option 92C run-time functions, C Library 266C Standard Library 265

introduction 266additional library functions 275ANSI-defined non-reentrant functions 270ANSI-defined reentrant functions 268C Library 266data symbols 277description 258global symbols 268header files 279–299internal library symbols 274introduction to the System Library 600library functions 305–523macros 300–304non-ANSI system interface functions 612–632startup module 266, 600, 603system interface functions 276, 600System Library 266, 600

C++language conformance 256

C++ defined library functions 634C++ internal library symbols 636C++ Library

description 258C++ Run-Time Library 633–689

C++ defined library functions 634C++ support functions 635callout functions 686–689exception handling 640global symbols 634header files 644–653internal library symbols 636library functions 654–685

C++ support functions 635-C, option 91-c, option 34, 92callee


minimum criteria 227caller

minimum criteria 226calloc, library function 321callout functions 642, 686–689

__cxx_tls_create_callout 686__cxx_tls_kill_callout 687__cxx_tls_restart_callout 688__cxx_tls_switch_callout 689

calls to functiongenerating 192

calls to functions 192call-site

minimum criteria 226ceil, library function 322change diagnostic messages 152, 155, 156change warnings to error messages 167check_stack pragma 201checking

stack limit violation 201clearerr, library function 323clock, library function 324clock, system interface function 606close, system interface function 626code_seg pragma 187collecting

dependency information 189command files 51command line

environment 71options 71

command line environment 71command line syntax 30commands

set 49commands and execute

print 88commands only, no execution 90comment

creating in output file 188comment pragma 188compilation

saving status 193compilation process

stopping upon assembly file generation 158stopping upon object file generation 92workbench 34

compiler arguments 30compiler features 21compiler optimizations 198compiler options

overview 38–43introduction 70

component pragma 189const_seg pragma 190constant data

default section 190controlling inline expansion 225conventions

of this manual 27

cos, library function 325cosh, library function 326creat, system interface function 627create precompiled header file 170creating a comment in an output file 188creating multifile IPO executable 223criteria for inline function expansion 226ctime, library function 327ctype.h, header file 279, 280customizing

environment 49

DD option 93-D, option 93data

default section 186, 191grouping 209

data symbols 277errno 277stderr 277stdin 277stdout 278

data_seg pragma 191debug information 202debug pragma 202debug tables 202

generating 202debugging

symbol and line numbering 177debugging information, generation 180default character type 107default section for constant data 190default section for data 191default section for functions 187default section for uninitialized data 186defining macros 93dependencies

collecting information 189dependency file 138diagnostic and other messages 739diagnostic messages

change to errors 152change to remarks 155change to warnings 156change warnings to error messages 167compiler information messages 745disable 151error messages 747introduction 740language diagnostic messages 742remark message 746warning messages 747

difftime, library function 328disable diagnostic messages 151disable division to multiplication optimization 142disable inlining 132disable standard directory 169disable type bool 111


div, library function 329DLL generation 109, 110documents, related 24

EE option 94-E, option 94effects of multifile IPO 224enable C++ exception handling 108enabling predefined macros 127entire program interprocedural optimizations 154entry point 603environment

customizing 49environment variables 49environment variables/setting 49EP option 95-EP, option 95errno, data symbol 277errno.h, header file 279, 281error messages, limit of 153examples

how to link a C application 263, 601how to link a C++ application 264, 601of libraries and startup modules 263

exception handling 640access C++ TLS 642

exception.h, C++ header file 644, 645exceptions

ANSI/ISO C++ standard 256executable file name 98_exit, system interface function 614exit, library function 330exp, library function 332extended C dialect/setting 254extended C language 178extension types

files and data storage 253pointers 253predicates 254semantics with warnings 254syntax with warnings 254types and syntax 253

extensionsANSI/ISO C standard 253

extensions to C language only 178

FFa option 96-Fa, option 96fabs, library function 333fclose, library function 334FD option 97-FD, option 97Fe option 98-Fe, option 98features, of the compiler 21

feof, library function 335ferror, library function 337fflush, library function 338fgetc, library function 339fgetpos, library function 341fgets, library function 343FI option 99-FI, option 99file dependencies, generate 97filename

use short names 194filename encoding 259files

assembly language output file 158, 211command files 51header files, C Standard Library 279–299header files, C++ Run-Time Library 644–653input files 32object file 92output files 33, 114

files and data storage, extension types 253__FIXEDPARAMS__, macro 279float.h, header file 279, 282floating point arithmetic

restricting 220floating point arithmetic precision 220floating point consistency

specifying improvement 120floating point functions

__adddf3 528, 529__ashldi3 530__ashrdi3 531__divdf3 532__divdi3 533__divsf3 534__divsi3 535__eqdf2 536__eqsf2 538__extendsfdf2 540__fixdfdi 542__fixdfsi 543__fixsfdi 544__fixsfsi 546__fixunsdfdi 547__fixunsdfsi 549__fixunssfdi 550__fixunssfsi 551__floatdidf 552__floatdisf 553__floatsidf 554__floatsisf 555__floatunsdidf 556__floatunsdisf 557__floatunssidf 558__floatunssisf 559__ftp8 597__gedf2 560__gesf2 562__gtdf2 564__gtsf2 566


__ledf2 568__lesf2 570__lshrdi3 572__ltdf2 573__ltsf2 575__moddi3 577__modsi3 578__mulkdf3 579__mulsf3 580__nedf2 581__negdf2 583__negsf2 584__nesf2 585__subdf3 587__subsf3 588__truncdfsf2 589__udivdi3 591__udivsi3 592__umoddi3 593__umodsi3 594_lmul 595

Floating Point Libraryoverview 524overview of 32-bit FP numbers 525overview of 64-bit FP numbers 526, 527

floating point optimization 141floor, library function 345fmod, library function 346Fo option 100-Fo, option 100Fo, option 100fopen, library function 347-Fp, option 101Fp, option 101fprintf, library function 350fputc, library function 354fputs, library function 356fread, library function 358free, library function 360_freebrk, system interface function 615freopen, library function 361frexp, library function 363fscanf, library function 364fseek, library function 368fsetpos, library function 371ftell, library function 373function expansion, criteria for inline functions expansion 226function pragma 192functions

allocating definitions 185callout functions 686–689default section 187list prototypes 179system interface functions 266, 276, 600

functions, floating point__adddf3 528, 529__ashldi3 530__ashrdi3 531__divdf3 532__divdi3 533

__divsf3 534__divsi3 535__eqdf2 536__eqsf2 538__extendsfdf2 540__fixdfdi 542__fixdfsi 543__fixsfdi 544__fixsfsi 546__fixunsdfdi 547__fixunsdfsi 549__fixunssfdi 550__fixunssfsi 551__floatdidf 552__floatdisf 553__floatsidf 554__floatsisf 555__floatunsdidf 556__floatunsdisf 557__floatunssidf 558__floatunssisf 559__ftp8 597__gedf2 560__gesf2 562__gtdf2 564__gtsf2 566__ledf2 568__lesf2 570__lshrdi3 572__ltdf2 573__ltsf2 575__moddi3 577__modsi3 578__muldf3 579__mulsf3 580__nedf2 581__negdf2 583__negsf2 584__nesf2 585__subdf3 587__subsf3 588__truncdfsf2 589__udivdi3 591__udivsi3 592__umoddi3 593__umodsi3 594_lmul 595

functions, memory_memcopy 596

fwrite, library function 375

Ggenerate a debug DLL 110generate a DLL 109generation

assembly language output file 158, 212object file 92symbol and line numbering 177symbolic debugging information 180


generic C source files 159generic C++ source files 161getc, library function 377getchar, library function 379getenv, library function 380getenv, system interface function 607gets, library function 381_gettz, system interface function 616global optimizations of compilation process 118global symbols 268, 634

additional library functions 275ANSI-defined non-reentrant library functions 270ANSI-defined reentrant library functions 268C++ defined library functions 634C++ internal library symbols 636C++ support functions 635internal library symbols 274system interface functions 276

gmtime, library function 382grouping

text and data objects 209Gy option 102-Gy, option 102

HH option 103-H, option 103header files

assert.h 279, 280C++

exception.h 644, 645libcxx.h 644, 646libfatal.h 644, 648new.h 644, 650rtti.h 651stdexcept.h 644, 652typeinfo.h 644, 653

ctype.h 279, 280errno.h 279, 281float.h 279, 282limits.h 279, 283locale.h 279, 284math.h 279, 285setjmp.h 279, 286signal.h 279, 287stdarg.h 279, 288stddef.h 279, 289stdio.h 279, 290stdlib.h 279, 293string.h 279, 296time.h 279, 298version.h 279, 299

header files, C Standard Library 279–299header files, C++ Run-Time Library 644–653Help 86, 104, 105HELP option 104-HELP, option 104-help, option 105high-level language optimizations 228

hrdstop pragma 193

I-I, option 106I/O Stream Library

thread-safe 643improve floating point consistency 120include file directory 106, 169include file directory, specifying 106include files 99

forcing 99include files, listing of 130include_alias pragma 194included macros

__cplusplus 255__DATE__ 255__FILE__ 255__LINE__ 255__STDC__ 255__TIME__ 255__TIMESTAMP__ 255

individually package functions 102inline expansion 116

specifying functions 116specifying standard library functions 119

inline expansion of library functions 225inline expansion of standard library functions 119inline function expansion

minimum call-site criteria 226minimum criteria for the callee 227minimum criteria for the caller 226

inliningdisabled 132

input files 32internal library symbols 274interprocedural optimizations 222

entire program 154real object files 135single file 131specifying multiple files 133

interrupt service routines 208Intrinsic Function

__adddf3 528, 529__ashldi3 530__ashrdi3 531__divdf3 532__divdi3 533__divsf3 534__divsi3 535__eqdf2 536__eqsf2 538__extendsfdf2 540__fixdfdi 542__fixdfsi 543__fixsfdi 544__fixsfsi 546__fixunsdfdi 547__fixunsdfsi 549__fixunssfdi 550


__fixunssfsi 551__floatdidf 552__floatdisf 553__floatsidf 554__floatsisf 555__floatunsdidf 556__floatunsdisf 557__floatunssidf 558__floatunssisf 559__gedf2 560__gesf2 562__gtdf2 564__gtsf2 566__ledf2 568__lesf2 570__lshrdi3 572__ltdf2 573__ltsf2 575__moddi3 577__modsi3 578__muldf3 579__mulsf3 580__nedf2 581__negdf2 583__negsf2 584__nesf2 585__subdf3 587__subsf3 588__truncdfsf2 589__udivdi3 591__udivsi3 592__umoddi3 593__umodsi3 594_lmul 595_memcopy 596ftp8 597

introductioncompiler options 70options 70

ioctl, system interface function 628isalnum, library function 383isalpha, library function 384iscntrl, library function 385_isdev, system interface function 618isdigit, library function 387_isdst, system interface function 619isgraph, library function 389islower, library function 391isprint, library function 393ispunct, library function 395isr pragma 208isspace, library function 397isupper, library function 399isxdigit, library function 401itoa, library function 403

JJ option 107-J, option 107

KKc++eh option 108-Kc++eh, option 108

Llabs, library function 404language conformance 251–256

C++ 256extended ANSI C 252strict ANSI C 252

LD option 109-LD, option 109LDd option 110-LDd, option 110ldexp, library function 405ldiv, library function 406length of external names 103libcxx.h, C++ header file 644, 646libfatal.h, C++ header file 644, 648libraries

additional library functions 275C Standard Library 265

C Library 266startup module 266, 600system interface functions 600System Library 266, 600

C++ defined functions of the C++ Run-Time library 634C++ internal library symbols 636C++ Run-Time Library 633–689C++ support functions of the C++ Run-Time library 635data symbols of the C Standard library 277exception handling 640filename encoding 259global symbols of the C Standard library 268global symbols of the C++ Run-Time library 634header files of the C Standard library 279–299header files of the C++ Run-Time library 644–653internal library symbols 274introduction to the C Standard library 266introduction to the System Library 600library functions of the C Standard library 305–523library functions of the C++ Run-Time Library 654–685,

686–689macros files of the C Standard library 300–304naming of 259non-ANSI system interface functions of the C Standard

Library 612–632overview FP library 524overview of 32-bit FP numbers 525overview of 64-bit FP numbers 526, 527startup module of the C Standard Library 603system interface functions 276system library 599–632thread-safe I/O Stream Library 643

library functions 305–523, 654–685, 686–689abort 306abs 307acos 308


asctime 309asin 310atan 311atan2 312atexit 313atof 314atoi 316atol 317atoll 318bsearch 319C++

__cadul_disable_critical_section_lock 654__cadul_enter_critical_section 656__cadul_exit_critical_section 657__cadul_share_critical_section_lock 658__cxx_tls_alloc_hook 659__cxx_tls_create_callout 686__cxx_tls_delete 660__cxx_tls_delete_hook 661__cxx_tls_delete_root_hook 662__cxx_tls_exit_hook 663__cxx_tls_free_hook 664__cxx_tls_get_hook 665__cxx_tls_get_root 666__cxx_tls_init 667__cxx_tls_init_hook 668__cxx_tls_kill_callout 687__cxx_tls_restart_callout 688__cxx_tls_set 669__cxx_tls_set_hook 670__cxx_tls_setup 671__cxx_tls_size 672__cxx_tls_switch_callout 689__lib_assert__ 673__lib_fatal__ 674__lib_fatal_default_terminate_routine 675__pure_virtual_called 676_main 677operator delete 678operator new 679set_new_handler 680set_terminate 681set_unexpected 682terminate 683uncaught_exception 684unexpected 685

calloc 321ceil 322clearerr 323clock 324cos 325cosh 326ctime 327difftime 328div 329exit 330exp 332fabs 333fclose 334feof 335

ferror 337fflush 338fgetc 339fgetpos 341fgets 343floor 345fmod 346fopen 347fprintf 350fputc 354fputs 356fread 358free 360freopen 361frexp 363fscanf 364fseek 368fsetpos 371ftell 373fwrite 375getc 377getchar 379getenv 380gets 381gmtime 382isalnum 383isalpha 384iscntrl 385isdigit 387isgraph 389islower 391isprint 393ispunct 395isspace 397isupper 399isxdigit 401itoa 403labs 404ldexp 405ldiv 406llabs 407lltoa 408localeconv 409localtime 412log 413log10 414longjmp 415ltoa 417malloc 418memchr 420memcmp 421memcpy 423memmove 424memset 425mktime 426modf 429perror 430pow 431pow10 432printf 433


putc 435putchar 437puts 439qsort 440raise 442rand 444realloc 445remove 447rename 448rewind 449scanf 451setbuf 454setjmp 455setlocale 457setvbuf 458signal 460sin 462sinh 463sprintf 464sqrt 466srand 467sscanf 468strcat 470strchr 471strcmp 472strcoll 474strcpy 475strcspn 477strerror 478strftime 479strlen 481strncat 482strncmp 483strncpy 485strpbrk 487strrchr 488strspn 489strstr 490strtod 491strtok 493strtol 495strtoll 497strtoul 499strtoull 501strxfrm 503system 505tan 506tanh 507time 508tmpfile 509tmpnam 510tolower 511toupper 513ungetc 515vfprintf 517vprintf 519vsprintf 521

library functions, C Standard Library 305–523library functions, C++ Run-Time Library 654–685, 686–689library functions, inline expansion 225

library system 257–264introduction 258C Standard Library 258C++ Library 258examples of libraries and startup modules 263naming of libraries 259naming of startup modules 259

library system of CAD-ULC++ Run-Time Library 633–689

limit of errors 153limits.h, header file 279, 283linkage

software floating point 206list

include files 130list prototypes 179llabs, library function 407lltoa, library function 408locale.h, header file 279, 284localeconv, library function 409localtime, library function 412log, library function 413log10, library function 414__LONGLONG__, macro 279longjmp, library function 415loop unrolling 228lseek, system interface function 629ltoa, library function 417

Mmacro definitions, suppressing 163macro definitions, suppressing all 164macros

__FIXEDPARAMS__ 279__LONGLONG__ 279__STDC__ 279__T_WCHAR__ 279__VARPARAMS__ 279_T_SIZE 279assert 300predefined for ANSI/ISO C standard 255va_arg 301va_copy 302va_end 303va_start 304

macros, defining 93macros, predefined 127malloc, library function 418math.h, header file 279, 285maximum speed optimizations 124maximum unrolling loop value 149memchr, library function 420memcmp, library function 421memcpy, library function 423memmove, library function 424memory functions

_memcopy 596memset, library function 425message pragma 197


messages 197printing to standard output 197warning 200

mixed mode working 143mktime, library function 426modf, library function 429multifile Assembly file 136

specifying 136multifile IPO overview 222multifile IPO, creating executable 223multifile object 134

specifying 134multiple file interprocedural optimizations 133

Nname of output file 114naming

of libraries 259of startup modules 259

new.h, C++ header file 644, 650no optimizations 117no optimizations of compilation process 117no warning messages

specify 168noBool option 111-noBool, option 111nologo option 112-nologo,option 112non-ANSI system interface functions 612–632non-reentrant 270

O-O option 113o option 114-O, option 113-o, option 114-O3, option 228Oa option 115-Oa, option 115Ob option 116-Ob, option 116-Ob0, option 225-Ob1, option 225-Ob2, option 225object file

generation 92Object file name 100object file name 100Od option 117-Od, option 117-Od, restricting optimization 219Og option 118-Og, option 118Oi option 119-Oi, option 119-Oi-, restricting optimization 219omit frame pointers 125

onum pragma 205Op option 120-Op, option 120, 220-Op, restricting optimization 219open, system interface function 630operator delete, operator delete [ ], run-time library function

678operator new, operator new [ ], run-time library function 679optimization

floating point precision 141optimization level 205

specifying 205optimization levels 218optimization levels, set 218optimization, restricting optimizations 219optimizations 198

code size 121interprocedural 77, 222space 203specifying 113specifying global optimizations 118specifying no optimizations 117speed 122time 204

optimizations in favour of small code size 121optimizations in favour of speed 122optimizations of compilation process 113optimizations, high-level language optimizations 228optimize pragma 198option and version details

disable 147enable 147

options/Fo 100/o 114/Qprec 141/Qprec_div 142/Zg 179-? 86@ 51-Ba 87-Bd 88, 90-Bl 89-C 91-c 34, 92code generation 81command line environment 71-D 93debugging 83-E 94-EP 95error handling 80-Fa 96-FD 97-Fe 98-FI 99-Fo 100-Fp 101-Gy 102-H 103


-HELP 104-help 105-I 106interprocedural optimization 77interrupting compilation 84introduction 70-J 107-Kc++eh 108language 73-LD 109-LDd 110-noBool 111-nologo 112-O 113-o 114-O3 228-Oa 115-Ob 116-Ob0 225-Ob1 225-Ob2 225-Od 117-Og 118-Oi 119-Op 120, 220optimization 76-Os 121-Ot 122output files 82overview 72-Ow 123-Ox 124-Oy 125-P 126precompiled header 75preprocessor 74-QA 127, 128-Qansi 129-QH 130-Qinline_debug_info 225-Qip 131, 222-Qip_no_inlining 132, 225-Qip_no_pinlining 225-QIPF_fma 220-Qipo 133, 222-Qipo_c 134, 224-Qipo_obj 135-Qipo_S 136, 224-Qlocation 137-Qlong_double 220-QM 138-Qnobss_init 139-Qoption 140-Qprec 141-Qprec_div 142-QRinterwork-return 143-Qropi 144-Qrwpi 145-QRxscale 146-Qsox 147

-QTP 148-Qunroll 149, 228-Qvec_report 150-Qwd 151-Qwe 152-Qwn 153-Qwp_ipo 154-Qwr 155-Qww 156-rtti 157-S 158-TC 159-Tc 160-TP 161-Tp 162-U 163-u 164-V 165-W 166-w 168-WX 167-X 169-Yc 170-Yu 172-YX 174-Za 176, 252-Zd 177-Ze 178, 252-Zg 179-Zi 180-Zp 181-Zs 182

options help 86, 104, 105options, passing to tools 140Os option 121-Os, option 121ospace pragma 203Ot option 122-Ot, option 122otime pragma 204output files

assembly language 212overview 33specifying name 114

overviewcode generation options 81debugging options 83error handling options 80language options 73optimization levels 218optimization options 76options 72output file options 82pragmas 44–45precompiled header options 75preprocessor options 74

overview, multifile IPO 222Ow option 123-Ow, option 123Ox option 124


-Ox, option 124Oy option 125-Oy, option 125

PP option 126-P, option 126pack pragma 199passing options to tools 140perror, library function 430PIC, enabling 144PID, enabling 145pointers, extension types 253position independent code 144

enabling 144position independent data 145

enabling 145pow, library function 431pow10, library function 432pragma

include_alias 194pragmas 183–209

definition 184Microsoft compatible 185–200overview 44–45syntax description 184align 207alloc_text 185ARM* compatible 201–206bss_seg 186check_stack 201code_seg 187comment 188component 189const_seg 190data_seg 191debug 202function 192general usage 184GNU compatible 207–209hrdstop 193isr 208message 197onum 205optimize 198ospace 203otime 204pack 199section 209softp_linkage 206warning 200

precompiled header file name 101predefined macros, enabling 127predicates, extension types 254prepocessing only 94prepocessing only with no #line directives 95prepocessing to a file only 126preserve comments in preprocessing 91printf, library function 433

putc, library function 435putchar, library function 437puts, library function 439

QQA option 127, 128-QA, option 127, 128Qansi option 129-Qansi, option 129QH option 130-QH, option 130-Qinline_debug_info, option 225Qip option 131-Qip, option 131, 222Qip_no_inlining option 132-Qip_no_inlining, option 132, 225-Qip_no_pinlining, option 225-QIPF_fma, option 220Qipo option 133-Qipo, option 133, 222Qipo_c option 134-Qipo_c, option 134, 224Qipo_obj option 135-Qipo_obj, option 135-Qipo_S, option 136, 224Qlocation option 137-Qlocation, option 137-Qlong_double, option 220QM option 138-QM, option 138Qnobss_init option 139-Qnobss_init, option 139Qoption option 140-Qoption, option 140-Qprec, option 141Qprec, option 141-Qprec_div, option 142Qprec_div, option 142-QRinterwork-return option 143QRinterwork-return, option 143-Qropi, option 144-Qrwpi, option 145QRxscale option 146-QRxscale, option 146qsort, library function 440Qsox option 147-Qsox, option 147-QTP, option 148Qunroll option 149-Qunroll, option 149, 228-Qvec_report, option 150Qwd option 151-Qwd, option 151Qwe option 152-Qwe, option 152Qwn option 153-Qwn, option 153Qwp_ipo option 154-Qwp_ipo, option 154


Qwr option 155-Qwr, option 155Qww option 156-Qww, option 156

Rraise, library function 442rand, library function 444read, system interface function 631real object files interprocedural optimizations 135realloc, library function 445reentrant 268related documents 24remove, library function 447remove, system interface function 608rename, library function 448rename, system interface function 609report

vectorization 150requirements 25restricting optimizations 219

-Od 219-Oi- 219-Op 219

rewind, library function 449routines, selecting for inlining 227rtti option 157-rtti, option 157rtti.h, C++ header file 651run-time library functions

__cxx_disable_critical_section_lock 654__cxx_enter_critical_section 656__cxx_exit_critical_section 657__cxx_share_critical_section_lock 658__cxx_tls_alloc_hook 659__cxx_tls_create_callout 686__cxx_tls_delete 660__cxx_tls_delete_hook 661__cxx_tls_delete_root_hook 662__cxx_tls_exit_hook 663__cxx_tls_free_hook 664__cxx_tls_get_hook 665__cxx_tls_get_root 666__cxx_tls_init 667__cxx_tls_init_hook 668__cxx_tls_kill_callout 687__cxx_tls_restart_callout 688__cxx_tls_set 669__cxx_tls_set_hook 670__cxx_tls_setup 671__cxx_tls_size 672__cxx_tls_switch_callout 689__lib_assert__ 673__lib_fatal__ 674__lib_fatal_default_terminate_routine 675__pure_virtual_called 676_main 677operator delete, operator delete [] 678operator new, operator new [] 679

set_new_handler 680set_terminate 681set_unexpected 682terminate 683uncaught_exception 684unexpected 685

SS option 158-S, option 158saving

compilation status 193_sblockcontrbrk, system interface function 620_sbrk, system interface function 621_sbrkblockfree, library function 305library functions

_sbrkblockfree 305sbrk-blocks

free 305scanf, library function 451section pragma 209selecting routines for inlining 227semantics with warnings, extension types 254set_new_handler, run-time library function 680set_terminate, run-time library function 681set_unexpected, run-time library function 682setbuf, library function 454setjmp, library function 455setjmp.h, header file 279, 286setlocale, library function 457setvbuf, library function 458short filenames 194signal library, function 460signal.h, header file 279, 287sin, library function 462single file interprocedural optimizations 131sinh, library function 463softp_linkage pragma 206software floating point linkage 206software interrupt 624, 625space optimization 203sprintf, library function 464sqrt, library function 466srand, library function 467sscanf, library function 468stack

limit violation 201standard C language only 176

specify 176standard include directory

specify 169startup code 603startup module 266, 600, 603startup modules 258

naming of 259stdarg.h, header file 279, 288__STDC__, macro 279stddef.h, header file 279, 289stderr, data symbol 277


stdexcept.h, C++ header file 644, 652stdin, data symbol 277stdio.h, header file 279, 290stdlib.h, header file 279, 293stdout, data symbol 278stopping

compilation process upon assembly file generation 158compilation process upon object file generation 92

strcat, library function 470strchr, library function 471strcmp, library function 472strcoll, library function 474strcpy, library function 475strcspn, library function 477_strerror, system interface function 622strerror, library function 478strftime, library function 479string.h, header file 279, 296strlen, library function 481strncat, library function 482strncmp, library function 483strncpy, library function 485strpbrk, library function 487strrchr, library function 488strspn, library function 489strstr, library function 490strtod, library function 491strtok, library function 493strtol, library function 495strtoll, library function 497strtoul, library function 499strtoull, library function 501structure members, align 181structures

aligning 199, 207strxfrm, library function 503suppressing

all macro definitions 164macro definitions 163

suppressing compiler version information 112SWI 624, 625SWI codes, overview 624, 625SWI system functions, overview 624, 625symbols

C++ internal library symbols 636data symbols 277global symbols 268, 634internal library symbols 274

syntaxcommand line 30

syntax checking 182specify 182

syntax of pragmas 184syntax with warnings, extension types 254system interface 606–611system interface functions 266, 276, 600

non-ANSI 612–632_blocksizebrk 613_exit 614_freebrk 615

_gettz 616_isdev 618_isdst 619_sblockcontrbrk 620_sbrk 621_strerror 622_tmpnampfx 623AngleSWI 624ARMSystemCall 625clock 606close 626creat 627getenv 607ioctl 628lseek 629open 630read 631remove 608rename 609SWI system interface functions, overview 624, 625system 610time 611write 632

System Library 258, 266introduction 600ANSI-defined system interface functions 606–611non-ANSI system interface functions 612–632supported libraries 600

system library 599–632system, library function 505system, system interface function 610

T_T_SIZE, macro 279tan, library function 506tanh, library function 507target processor option 148TC option 159Tc option 160-TC, option 159-Tc, option 160terminate, run-time library function 683text

grouping 209time optimization 204time, library function 508time, system interface function 611time.h, header file 279, 298tmpfile, library function 509tmpnam, library function 510_tmpnampfx, system interface function 623tolower, library function 511tool chain 34Tool Suite 21toupper, library function 513TP option 161Tp option 162-TP, option 161-Tp, option 162


treatingall source files as C source files 159all source files as C++ source files 161specified file as C source 160specified file as C++ source 162

typeinfo.h, C++ header file 644, 653types and syntax, extension types 253

UU option 163u option 164-U, option 163-u, option 164uncaught_exception, run-time library function 684unexpected, run-time library function 685ungetc, library function 515unrolling loop 228unrolling loops 149usage of options

alternative include directory 56generate function prototypes 64multiple source files 61non-standard source files 62using standard ANSI C 64

use precompiled header file 172user functions, controlling inline expansion 225

VV option 165-V, option 165va_arg, macro 301va_copy, macro 302va_end, macro 303va_start, macro 304__VARPARAMS__, macro 279vectorization report 150version.h, header file 279, 299vfprintf, library function 517vprintf, library function 519vsprintf, library function 521

WW option 166w option 168

-W, option 166-w, option 168warning message levels

specify 166warning messages 200

none 168setting level 166

warning pragma 200__T_WCHAR__, macro 279workbench

compilation process 34write, system interface function 632WX option 167-WX, option 167

XX option 169-X, option 169XScale Microarchitecture 146

YYc option 170-Yc, option 170Yu option 172-Yu, option 172YX option 174-YX, option 174

ZZa option 176-Za, option 176, 252Zd option 177-Zd, option 177Ze option 178-Ze, option 178, 252zero-initialized data into DATA section 139-Zg, option 179Zg, option 179Zi option 180-Zi, option 180Zp option 181-Zp, option 181Zs option 182-Zs, option 182


intel c++ compiler user's manualmvtool.co.kr/hb/data/pds/ccxsc.pdfintel® c++ compiler user’s...

Documents