Watcom C Library Reference Version 1.8 Notice of Copyright Copyright 2002-2008 the Open Watcom Contributors. Portions Copyright 1984-2002 Sybase, Inc. and its subsidiaries. All rights reserved. Any part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of anyone. For more information please visit http://www.openwatcom.org/ ii Preface This manual describes the Watcom C Library. It includes the Standard C Library (as defined in the ANSI C Standard) plus many additional library routines which make application development for personal computers much easier. Acknowledgements This book was produced with the Watcom GML electronic publishing system, a software tool developed by WATCOM. In this system, writers use an ASCII text editor to create source files containing text annotated with tags. These tags label the structural elements of the document, such as chapters, sections, paragraphs, and lists. The Watcom GML software, which runs on a variety of operating systems, interprets the tags to format the text into a form such as you see here. Writers can produce output for a variety of printers, including laser printers, using separately specified layout directives for such things as font selection, column width and height, number of columns, etc. The result is type-set quality copy containing integrated text and graphics. July, 1997. Trademarks Used in this Manual IBM is a registered trademark of International Business Machines Corp. Intel is a registered trademark of Intel Corp. Microsoft, MS, MS-DOS, Windows, Win32, Win32s, Windows NT and Windows 2000 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. NetWare, NetWare 386, and Novell are registered trademarks of Novell, Inc. UNIX is a registered trademark of The Open Group. WATCOM is a trademark of Sybase, Inc. and its subsidiaries. iii iv Table of Contents Watcom C Library Reference ......................................................................................................................... 1 1 C Library Overview .......................................................................................................................... 3 1.1 Classes of Functions ........................................................................................................... 3 1.1.1 Character Manipulation Functions ...................................................................... 5 1.1.2 Wide Character Manipulation Functions ............................................................. 6 1.1.3 Multibyte Character Manipulation Functions ...................................................... 6 1.1.4 Memory Manipulation Functions ........................................................................ 8 1.1.5 String Manipulation Functions ............................................................................ 8 1.1.6 Wide String Manipulation Functions .................................................................. 10 1.1.7 Multibyte String Manipulation Functions ........................................................... 11 1.1.8 Conversion Functions .......................................................................................... 13 1.1.9 Memory Allocation Functions ............................................................................. 14 1.1.10 Heap Functions .................................................................................................. 15 1.1.11 Math Functions .................................................................................................. 15 1.1.12 Searching Functions .......................................................................................... 17 1.1.13 Time Functions .................................................................................................. 17 1.1.14 Variable-length Argument Lists ........................................................................ 17 1.1.15 Stream I/O Functions ......................................................................................... 18 1.1.16 Wide Character Stream I/O Functions ............................................................... 19 1.1.17 Process Primitive Functions .............................................................................. 20 1.1.18 Process Environment ......................................................................................... 22 1.1.19 Directory Functions ........................................................................................... 22 1.1.20 Operating System I/O Functions ....................................................................... 23 1.1.21 File Manipulation Functions .............................................................................. 23 1.1.22 Console I/O Functions ....................................................................................... 24 1.1.23 Default Windowing Functions ........................................................................... 24 1.1.24 BIOS Functions ................................................................................................. 24 1.1.25 DOS-Specific Functions .................................................................................... 25 1.1.26 Intel 80x86 Architecture-Specific Functions ..................................................... 25 1.1.27 Intel Pentium Multimedia Extension Functions ................................................ 26 1.1.28 Miscellaneous Functions ................................................................................... 27 1.2 Header Files ....................................................................................................................... 28 1.2.1 Header Files in /watcom/h ................................................................................... 28 1.2.2 Header Files in /watcom/h/sys ............................................................................. 31 1.3 Global Data ........................................................................................................................ 32 1.4 The TZ Environment Variable ........................................................................................... 36 2 Graphics Library ............................................................................................................................... 39 2.1 Graphics Functions ............................................................................................................ 39 2.2 Graphics Adapters .............................................................................................................. 39 2.3 Classes of Graphics Functions ........................................................................................... 40 2.3.1 Environment Functions ........................................................................................ 40 2.3.2 Coordinate System Functions .............................................................................. 41 2.3.3 Attribute Functions .............................................................................................. 42 2.3.4 Drawing Functions .............................................................................................. 42 2.3.5 Text Functions ..................................................................................................... 43 2.3.6 Graphics Text Functions ...................................................................................... 43 2.3.7 Image Manipulation Functions ............................................................................ 44 2.3.8 Font Manipulation Functions ............................................................................... 44 2.3.9 Presentation Graphics Functions ......................................................................... 45 2.3.9.1 Display Functions .................................................................................. 45 v Table of Contents 2.3.9.2 Analyze Functions ................................................................................. 46 2.3.9.3 Utility Functions .................................................................................... 46 2.4 Graphics Header Files ........................................................................................................ 46 3 DOS Considerations ......................................................................................................................... 47 3.1 DOS Devices ...................................................................................................................... 47 3.2 DOS Directories ................................................................................................................. 47 3.3 DOS File Names ................................................................................................................ 48 3.4 DOS Files ........................................................................................................................... 49 3.5 DOS Commands ................................................................................................................. 50 3.6 DOS Interrupts ................................................................................................................... 50 3.7 DOS Processes ................................................................................................................... 50 4 Library Functions and Macros