z/OS Version 2 Release 3 Metal C Programming Guide and Reference IBM SC14-7313-30 Note Before using this information and the product it supports, read the information in “Notices” on page 159. This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: 2019-02-15 © Copyright International Business Machines Corporation 1998, 2017. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents List of Figures...................................................................................................... vii List of Tables........................................................................................................ ix About this document.............................................................................................xi Who should read this document................................................................................................................. xi Where to find more information..................................................................................................................xi z/OS Basic Skills in IBM Knowledge Center.......................................................................................... xi How to read syntax diagrams......................................................................................................................xi How to send your comments to IBM......................................................................xv If you have a technical problem.................................................................................................................xv Summary of changes for z/OS Version 2 Release 3............................................... xvi Chapter 1. About IBM z/OS Metal C........................................................................ 1 Metal C environment....................................................................................................................................1 Programming with Metal C...........................................................................................................................1 Metal C and MVS linkage conventions................................................................................................... 2 Compiler-generated HLASM source code..............................................................................................4 Prolog and epilog code.........................................................................................................................12 Supplying your own HLASM statements..............................................................................................20 Inserting HLASM instructions into the generated source code.......................................................... 21 AMODE-switching support...................................................................................................................29 RENT mode support............................................................................................................................. 30 argc argv parsing support.....................................................................................................................33 AR-mode programming support.......................................................................................................... 33 Metal C function descriptor support.................................................................................................... 41 Defining an alternative name for function "main"............................................................................. 41 Building Metal C programs...................................................................................................................41 Summary of useful references for the Metal C programmer.................................................................... 49 Chapter 2. Header files........................................................................................ 51 builtins.h — Declare built-in functions...................................................................................................... 51 ctype.h — Declare character classification functions .............................................................................. 51 float.h — Define ANSI constants for floating-point data types.................................................................51 inttypes.h — Define macros for sprintf and sscanf family.........................................................................53 limits.h — Declare symbolic names for resource limits............................................................................ 55 math.h — Define macros for floating-point support .................................................................................56 metal.h — Define Metal C related function prototypes and data..............................................................56 stdarg.h — Define macros for accessing variable-length argument lists in functions............................. 56 stddef.h — Define ptrdiff_t, size_t, and ssize_t data types....................................................................... 57 stdio.h — Define I/O related functions...................................................................................................... 57 stdint.h — Define integer types and related limits and macros................................................................57 stdlib.h — Define standard library functions............................................................................................. 59 string.h — Declare string manipulation functions..................................................................................... 59 Chapter 3. C functions available to Metal C programs............................................61 Characteristics of Metal C runtime library functions................................................................................ 61 System and static object libraries............................................................................................................. 61 User-replaceable heap services................................................................................................................62 abs() — Calculate integer absolute value.................................................................................................. 64 atoi() — Convert character string to integer.............................................................................................. 65 iii atol() — Convert character string to long...................................................................................................65 atoll() — Convert character string to signed long long ............................................................................. 66 calloc() — Reserve and initialize storage...................................................................................................67 __cinit() - Initialize a Metal C environment............................................................................................... 67 __cterm() - Terminate a Metal C environment..........................................................................................70 div() — Calculate quotient and remainder.................................................................................................70 free() — Free a block of storage.................................................................................................................71 isalnum() to isxdigit() — Test integer value............................................................................................... 71 isalpha() — Test for alphabetic character classification........................................................................... 73 isblank() — Test for blank character classification....................................................................................73 iscntrl() — Test for control classification................................................................................................... 73 isdigit() — Test for decimal-digit classification......................................................................................... 73 isgraph() — Test for graphic classification.................................................................................................73 islower() — Test for lowercase...................................................................................................................73 isprint() — Test for printable character classification............................................................................... 73 ispunct() — Test for punctuation classification......................................................................................... 73 isspace() — Test for space character classification.................................................................................. 73 isupper() — Test for uppercase letter classification..................................................................................73 isxdigit() — Test for hexadecimal digit Classification................................................................................73 labs() — Calculate long absolute value......................................................................................................74 ldiv() — Compute quotient and remainder of integral division................................................................