I, " D[Ji)mos~ ANSI C Language and Libraries Reference Manual INMOS Limited ~ SGS-1HOMSON ~.,I® ~D©rnJ@~[b~©'ITOO@~D©~ INMOS is a member of the SGS-THOMSON Microelectronics Group 72 TDS 347 01 October 1992 © INMOS Limited 1992. This document may not be copied. in whole or in part. without prior written consent of INMOS. • ®. ~l1ilmos® J IMS and occam are trademarks of INMOS Limited. INMOS Limited is a member of the SGS-THOMSON Microelectronics Group. ~ I~ is a registered trademark of the SGS-THOMSON Microelectronics Group. The Ccompiler irrlplementation was developed from the Perihelion Software "C" Compiler and the Codemist Norcroft "c" Compiler. INMOS Document Number: 72 TDS 347 01 Contents overview Contents Preface Runtime Library 1 Introduction and run- An introduction to the Runtime Library with time library summary summaries of the header 'files. 2 Alphabetical list of Detailed descriptions of each library 'function, functions listed in alphabetical order. 3 Modifying the runtime Describes how the runtime startup code can be starlup system tailored. Language Reference 4 New features in ANSI Describes the new features in the ANSI stan- G dard. 5 Language extensions Describes the ANSI C toolset language exten- sions. 6 Implementation Contains data for implen1entation-defined details characteristics. Appendices A Syntax of language Defines the language extensions. extensions B ANSI G compliance Lists implementation data required by the ANSI data standard. C GRG resume Provides additional information about the CRC functions supplied with the toolset and docu- mented in chapter 2. Index 72 TDS 347 01 October 1992 ii Contents overview 72 TDS 347 01 October 1992 I Contents Contents overview . Contents ...... iii Preface.. .. .. ix Host versions ix About this manual ix About the toolset documentation set ix Other documents ... .......................................... xi occam and FORTRAN toolsets ................................ xi Documentation conventions. ................................... xi Runtime Library ......................................... 1 1 Introduction and runtime library summary 3 1.1 Introduction ........................................... 3 1.1.1 Accessing library functions . 4 1.1.2 Linking libraries with programs .................. 4 1.1.3 iserver protocols 4 1.1.4 Functions which store data in static. ............. 4 1.2 Header tiles. .......................................... 5 1.3 ANSI functions .. ...................................... 6 1.3.1 Diagnostics <assert.h> 7 1.3.2 Character handling <ctype.h> 7 1.3.3 Error handling <errno.h> ....................... 7 1.3.4 Floating point constants <float.h> 8 1.3.5 Implementation limits <Iimits.h> ................. 9 1.3.6 Localization <Iocale.h> 9 1.3.7 Mathematics library <math.h> 11 1.3.8 Non-local jumps <seljmp.h> 12 1.3.9 Signal handling <signal.h> 12 1.3.10 Variable arguments <stdarg.h> 13 1.3.11 Standard definitions <stddef.h> 13 1.3.12 Standard I/O <stdio.h> ......................... 14 Characteristics of tile handling. ................. 16 1.3.13 Reduced library I/O functions <stdiored.h> 17 1.3.14 General utilities <stdlib.h> ...................... 17 1.3.15 String handling <string.h> ...................... 20 1.3.16 Date and time <time.h> ...... 21 iv Contents 1.4 Concurrency functions 22 1.4.1 Process control <process.h> 23 1.4.2 Channel communication <channel.h> ............ 24 1.4.3 Semaphore handling <semaphor.h> . 25 1.5 Other 'functions. ....................................... 25 1.5.1 110 primitives <iocntrl.h> 26 1.5.2 'noat maths <mathf.h> 26 1.5.3 Host utilities <host.h> .......................... 28 1.5.4 Host channel access utilities <hostlink.h> 28 1.5.5 Boot link channel functions <bootlink.h> 29 1.5.6 MS-DOS system functions <dos.h> 29 1.5.7 Dynamic code loading functions <fnload.h> 29 1.5.8 Miscellaneous functions <misc.h> ............... 30 1.6 Fatal runtime errors. ................................... 32 1.6.1 Runtime error messages ....................... 32 2 Alphabetical list of functions ....................... .. 35 2.1 Format ............................................... 35 2.1.1 Reduced library. .............................. 35 2.1.2 Macros. ..................................... 35 2.2 List of functions 36 3 Modifying the runtime startup system 357 3.1 Introduction ......................................... .. 357 3.2 Overview of system .................................. .. 358 3.3 The gsb and use of the IMS_nolink pragma '. 359 3.4 Interface to runtime startup code 360 3.5 Details of stage 1 of the runtime startup code 361 3.5.1 Initialize static 361 3.5.2 Call stage 2 startup code and set up gsb ....... .. 362 3.6 Details of stage 2 of the runtime startup code 363 3.6.1 Set up bounds of stack 363 3.6.2 Initialize heap 363 3.6.3 Initialize pointer to configuration process structure. 364 3.6.4 Initialize 110 system 364 3.6.5 Get command line arguments 365 3.6.6 Save exit return point ........................ .. 365 3.6.7 Initialize clock 365 3.6.8 Call main 365 3.6.9 Terminate server if required 366 3.7 Interface to main 366 3.8 Static initialization 367 3.9 Source files supplied and rebuilding. ................... .. 368 Contents v UNIX based toolsets: 369 MS-DOS based toolsets: 369 VMS based toolsets: 369 3.10 Notes. ............................................. .. 370 3.11 Example. .......................................... .. 371 3.11.1 Building the modified runtime system 375 For example: 375 UNIX based toolsets: 375 MS-DOSNMS based toolsets: 375 Language Reference 377 4 New features in ANSI C 379 4.1 Summary of new features in the ANSI standard 379 4.2 Details of new features ............................... .. 381 4.2.1 Function declarations ........................ .. 381 4.2.2 Function prototypes 381 4.2.3 Functions without prototypes 381 4.2.4 Declarations. ............................... .. 382 4.2.5 Types, type qualifiers and type speci'fiers ....... .. 382 4.2.6 Constants .................................. .. 384 4.2.7 Preprocessor extensions ..................... .. 384 Compiler directives .......................... .. 384 Predefined macros: 385 4.2.8 Structures and unions 385 4.2.9 Trigraphs. ................................. .. 386 Trigraph escape codes 386 5 Language extensions 387 5.1 Concurrency support ................................. .. 387 5.2 Pragmas. .......................................... .. 387 5.3 Predefined macros 388 5.4 Assembly language support 389 5.4.1 Directives and operations 389 5.4.2 size option on _asm statement 391 5.4.3 Labels ..................................... .. 391 5.4.4 Notes on transputer code programming ........ .. 391 5.4.5 Useful built-in variables 391 5.4.6 Transputer code examples 392 Setting the transputer error flag 392 Loading constants using literal operands ....... .. 392 Labels and jumps 393 Jump tables ... ............................. .. 393 vi Contents Loading floating point registers 394 Using align/word to return an element of a table. .. 394 Inserting raw machine code 394 6 Implementation details 395 6.1 Data type representation 395 6.1.1 Scalar types ................................ .. 395 6.1.2 Arrays ..................................... .. 396 6.1.3 Structures .................................. .. 397 Example 1 (structuring on a 32-bit processor): .. .. 398 Example 2 (structuring on a 32-bit processor): .. .. 398 6.1.4 Unions. ................................... .. 399 6.2 Type conversions .................................... .. 399 6.2.1 Integers. .................................. .. 399 6.2.2 Floating point. .............................. .. 400 6.3 Compiler diagnostics. ................................ .. 400 6.4 Environment '. .......................... .. 400 6.4.1 Arguments to main .......................... .. 400 Configured case: ............................ .. 401 Unconfigured case 401 6.4.2 Interactive devices 402 6.5 Identifiers. .......................................... .. 402 6.6 Source and execution character sets. .................. .. 402 Shift states for encoding multibyte characters ... .. 402 Integer character constants 402 Locale used to convert multibyte characters 402 Plain chars ................................. .. 403 6.7 Integer operations. .................................. .. 403 Bitwise operations on signed integers. ......... .. 403 Sign of the remainder on integer division .. ..... .. 403 Right shifts on negative-valued signed integral types 403 6.8 Registers ........................................... .. 403 6.9 Enumeration types. .................................. .. 403 6.1 0 Bit fields -. .. .. ... .. .. .. 403 6.11 volatile qualifier 404 6.12 Declarators. ........................................ .. 404 6.13 Switch statement. .... .. .. .......................... .. 404 6.14 Preprocessing directives 404 Constants controlling conditional inclusion. ..... .. 404 Date and time defaults ....................... .. 405 6.15 Static data layout .................................... .. 405 6.15.1 Local static data layout 405 Contents vii 6.15.2 Constant static objects. ...................... .. 406 6.16 Calling conventions. ................................. .. 407 6.16.1 Parameter Passing 407 6.16.2 Calling Sequence 407 6.16.3 Rules for aliasing between formal parameters 409 6.17 Runtime library ...................................... .. 409 Appendices 411 A Syntax of language extensions 413 A.1 Notation ............................................ .. 413 A.2 #pragma directive 413 A.3 _asm statement. ..................................