IBM C/2™ Computer Language Series Language Reference Programming Family ------ ---- --- ----.- --- ----------_ ... - First Edition (September 1987) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or infor­ mation about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for copies of this publication and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative. Operating System/2 is a trademark of the International Business Machines Corporation. C/2 is a trademark of the International Business Machines Corpo­ ration. © Copyright International Business Machines Corporation 1987. All rights reserved. No part of this publication may be reproduced or distributed in any form or by any means without prior permission in writing from the International Business Machines Corporation. Preface This book is volume 3 of the three - volume set explaining IBM C/2.™ It contains descriptions of each of the functions of the C r~n-time library. The keywords and commands are listed in alphabetical order. This product attempts to conform to the forthcoming American National Standards Institute (ANSI) standard whenever possible. IBM C/2 does make minor changes to what is considered ANSI standard C; these changes are documented in this and other IBM publications for the IBM C/2 Compiler. First-time users of this book are expected to be computer science stu­ dents who are studying C in their seco.nd or third year of school. Experienced users are expected to be experienced appl ications pro­ grammers or system programmers. Users should also be familiar with their computer and operating system. Related Publications The following books contain topics related to information in the IBM C/2 Library: • IBM CI2 Fundamentals • IBM C/2 Compile, Link, and Run • IBM Disk Operating System User's Guide • IBM Disk Operating System User's Reference • IBM Disk Operating System Technical Reference • IBM Operating Systeml2™ (OS/2TM) User's Guide • IBM Operating Systeml2 User's Reference • IBM Operating Systeml2 Programmer's Guide • IBM Operating Systeml2 Technical Reference IBM (;/2 is a trademark of International Business Machines Corporation Operating System/2 (OS/2) is a trademark of International Business Machines Corporation. iii • IBM Personal Systeml2™ (PSI2TM) Quick Reference • IBM Personal Systeml2 Mode1 50 Technical Reference • IBMPersonal Systeml2 Model 60 Technical Reference • IBMPersonal Systeml2 Model 80 Technical Reference • IBM Personal Computer Personal Editor • IBM Personal Computer Guide to Operations • IBM Personal Computer Technical Reference. • iAPX 86,88 User's Manual Copyright 1981, Intel Corp. Santa Clara, CA. • iAPX 286 Hardware Reference Manual Copyright 1983, Intel Corp. Santa Clara, CA. • iAPX 286 Programmer's Reference Manual Copyright 1985, Intel Corp. Santa Clara, CA. You can use the following table as a cross reference for information in the IBM C/2 library. If You Want To ... Refer to... Install the product Compile, Link, and Run Learn basic facts about the Fundamentals language Know the syntax of an i nstruc- Language Reference tion Understand error messages Language Reference Debug a program Compile, Link, and Run Compile a program Compile, Link, and Run Link a program Compile, Link, and Run Write a program Fundamentals, Language Ref- erence, and Compile, Link, and Run Personal System/2 (PS/2) is a trademark of the International Business Machines Corporation. iv Contents Chapter 1. About the IBM C/2 Library .................. 1-1 How This Book Is Organized ......................... 1-2 Hardware Requirements ........................... 1-3 Software Requirements ............. '. .. 1-4 Notation Used In This Book ......................... 1-4 Typeface Notation .............................. 1-4 Command Syntax Notation .......................... 1-7 Syntax Diagram Terms Used .. 1-7 Reading Syntax Diagrams ........................ 1-8 Using C Library Routines ........................... 1-9 Identifying Functions and Macros ................... 1-9 Including Files ............................... 1-11 Declaring Functions . .. 1-12 Stack Checki ng ............................... 1-13 Argument Type-Checking ........................ 1-14 Error Handling ............................... 1-15 Filenames and Pathnames ....................... 1-17 Binary and Text Modes 1-18 DOS Considerations 1-20 Using Floating-Point Data ........................ 1-21 Huge Models ................................ 1-23 Using Huge Arrays with Library Functions .............. 1-24 Chapter 2. Global Variables and Standard Types .......... 2-1 Global Variables in Run-Time Routines ................. 2-1 _pgm ptr ...................................... 2-2 _amblksiz ..................................... 2-3 daylight, timezone, tzname . 2-4 _doserrno, errno, sys_errlist, sys_nerr .................. 2-6 fmode ....................................... 2-7 _osmajor, _osminor, _osmode ....................... 2-8 environ, _psp ................................... 2-9 Standard Data Types in Run-Time Routines ............. 2-10 Chapter 3. Run-Time Routines by Category .............. 3-1 Buffer Manipulation .............................. 3-1 Character Classification and Conversion ................ 3-2 Data Conversion ................................. 3-4 v Directory Control ................................ 3-4 File Handl.ing ................................... 3~5 Input and Output ................................. 3-6 Stream Routi hes ................................. 3-6 Controlling Stream Buffering ..................... 3-10 Closing Streams .............................. 3-11 Reading and Writing Data ................. .. 3-11 Detecting Errors .............................. 3-12 Low~Level Routines ............................. 3-12 Opening a File ............................... 3-13 Predefined Handles ............................ 3-14 Reading and Writing Data ........................ 3-15 Closing Files ................................ 3-15 Keyboard and Port I/O Routi nes ..................... 3-16 Math ........................................ 3-17 Reserving Storage .............................. 3-20 DOS Interface .. .. 3-24 Process Control ................................ 3-25 Searching and Sorting ............................ 3-28 Manipulating Strings ............................. 3-29 Time ........................................ 3-30 Variable-Length Argument Lists ..................... 3-31 Miscellaneous Routines ........................... 3-32 Chapter 4. Include Files ........................... 4-1 assert.h .. 4-2 conio.h ....................................... 4-2 ctype.h ....................................... 4-2 direct.h ....................................... 4-3 dos.h ........................................ 4-3 errno.h ....................................... 4-4 fcntl. h ........................................ 4-4 float.h ... ;.................................... 4-5 iO.h .......................................... 4-5 limits.h ....................................... 4-5 locking.h ...................................... 4-6 malloc.h ...................................... 4-6 math.h ....................................... 4-6 memory.h ..................................... 4-7 process.h ..................................... 4-7 search.h ...................................... 4-8 setjmp.h ...................................... 4-8 share.h ....................................... 4-8 vi signal.h ....................................... 4-8 stat.h ........................................ 4-8 stdarg.h ...................................... 4-9 stddef. h ....................................... 4-9 stdio.h ...................................... 4-10 stdlib.h ...................................... 4-12 string.h ...................................... 4-13 timeb.h ...................................... 4-13 time.h ....................................... 4-13 types.h ...................................... 4-14 utime.h ...................................... 4-14 Chapter 5. Library Routines ......................... 5-1 abort ........................................ 5-2 abs .......................................... 5-4 access 5-5 acos ......................................... 5-7 alloca ........................................ 5-9 asctime ...................................... 5-11 asin ........................................ 5-13 assert ......................................