XL C/C++ for z/VM

Runtime Library Referenceversion 1 release 3

SC09-7624-05

���

XL C/C++ for z/VM

Runtime Library Referenceversion 1 release 3

SC09-7624-05

���

Note:Before using this information and the product it supports, read the information in “Notices” on page 1329.

This edition applies to version 1, release 3, modification 0 of IBM XL C/C++ for z/VM (product number 5654-A22)and to all subsequent releases and modifications until otherwise indicated in new editions.

The edition replaces SC09-7624-04.

© Copyright IBM Corporation 2002, 2011.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii

About This Document . . . . . . . . . . . . . . . . . . . . . xxvIntended Audience . . . . . . . . . . . . . . . . . . . . . . . xxvWhere to Find More Information . . . . . . . . . . . . . . . . . . xxv

How to Send Your Comments to IBM . . . . . . . . . . . . . . . xxviiIf You Have a Technical Problem . . . . . . . . . . . . . . . . . xxvii

Summary of Changes . . . . . . . . . . . . . . . . . . . . . xxixSC09-7624-05, XL C/C++ for z/VM, Version 1 Release 3 . . . . . . . . . xxix

Upgraded C/C++ Compiler for z/VM . . . . . . . . . . . . . . . xxixUpgraded Language Environment for z/VM . . . . . . . . . . . . . xxixUpgraded Program Management Binder for CMS. . . . . . . . . . . xxix

SC09-7624-04, XL C/C++ for z/VM, Version 1 Release 2 . . . . . . . . . xxixUpgraded C/C++ Compiler for z/VM . . . . . . . . . . . . . . . xxixUpgraded Language Environment for z/VM . . . . . . . . . . . . . xxixAdditional Changes . . . . . . . . . . . . . . . . . . . . . . xxxUpgraded Program Management Binder for CMS . . . . . . . . . . . xxx

SC09-7624-03, C/C++ for z/VM Version 1 Release 1.0 . . . . . . . . . . xxxDelete DEVICE and LINK Support . . . . . . . . . . . . . . . . xxxSO-LINGER Socket Option . . . . . . . . . . . . . . . . . . . xxx

Chapter 1. About IBM XL C/C++ for z/VM . . . . . . . . . . . . . . . 1XL C/C++ Compiler. . . . . . . . . . . . . . . . . . . . . . . . 1

The C Language. . . . . . . . . . . . . . . . . . . . . . . . 1The C++ Language. . . . . . . . . . . . . . . . . . . . . . . 1Common Features of the C Compiler and C++ Compiler Functions . . . . . 2Specific Features of the z/VM C Compiler Function . . . . . . . . . . . 3Specific Features of the z/VM C++ Compiler Function . . . . . . . . . . 3

IBM XL C/C++ for z/VM Runtime Library . . . . . . . . . . . . . . . . 3Class Libraries . . . . . . . . . . . . . . . . . . . . . . . . . 3Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Language Environment . . . . . . . . . . . . . . . . . . . . . . 4About Prelinking, Linking, and Binding . . . . . . . . . . . . . . . . . 5

Notes on the Prelinking Process . . . . . . . . . . . . . . . . . . 6The Program Management Binder . . . . . . . . . . . . . . . . . 6

OpenExtensions Services . . . . . . . . . . . . . . . . . . . . . 7IBM XL C/C++ for z/VM Applications with OpenExtensions Services . . . . . 8IBM XL C/C++ for z/VM Applications with OpenExtensions Interoperability . . 8

Input and Output. . . . . . . . . . . . . . . . . . . . . . . . . 9I/O Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 9File Types. . . . . . . . . . . . . . . . . . . . . . . . . . 10Additional I/O Features . . . . . . . . . . . . . . . . . . . . . 11

Additional Features of IBM XL C/C++ for z/VM . . . . . . . . . . . . . 11

Chapter 2. Header Files . . . . . . . . . . . . . . . . . . . . . 13Feature Test Macros . . . . . . . . . . . . . . . . . . . . . . . 13Header File Descriptions . . . . . . . . . . . . . . . . . . . . . 19

aio.h. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19arpa/inet.h . . . . . . . . . . . . . . . . . . . . . . . . . 19

© Copyright IBM Corp. 2002, 2011 iii

arpa/nameser.h. . . . . . . . . . . . . . . . . . . . . . . . 19assert.h . . . . . . . . . . . . . . . . . . . . . . . . . . 19bpxhmnt.h . . . . . . . . . . . . . . . . . . . . . . . . . 19cassert . . . . . . . . . . . . . . . . . . . . . . . . . . . 20_Ccsid.h . . . . . . . . . . . . . . . . . . . . . . . . . . 20cctype . . . . . . . . . . . . . . . . . . . . . . . . . . . 20ceeedcct.h . . . . . . . . . . . . . . . . . . . . . . . . . 20cerrno . . . . . . . . . . . . . . . . . . . . . . . . . . . 20cfloat . . . . . . . . . . . . . . . . . . . . . . . . . . . 20cics.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 20ciso646. . . . . . . . . . . . . . . . . . . . . . . . . . . 20climits . . . . . . . . . . . . . . . . . . . . . . . . . . . 21clocale . . . . . . . . . . . . . . . . . . . . . . . . . . . 21cmath . . . . . . . . . . . . . . . . . . . . . . . . . . . 21collate.h . . . . . . . . . . . . . . . . . . . . . . . . . . 21cpio.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 21csetjmp. . . . . . . . . . . . . . . . . . . . . . . . . . . 21csignal . . . . . . . . . . . . . . . . . . . . . . . . . . . 21csp.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cstdarg . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cstddef . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cstdio . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cstdlib . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cstring . . . . . . . . . . . . . . . . . . . . . . . . . . . 22ctest.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 22ctime . . . . . . . . . . . . . . . . . . . . . . . . . . . 23ctype.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 23cwchar . . . . . . . . . . . . . . . . . . . . . . . . . . . 23cwctype . . . . . . . . . . . . . . . . . . . . . . . . . . 23decimal.h . . . . . . . . . . . . . . . . . . . . . . . . . . 23dirent.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 24dll.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24dynit.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 24env.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 24errno.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 24exception . . . . . . . . . . . . . . . . . . . . . . . . . . 25fcntl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 25features.h . . . . . . . . . . . . . . . . . . . . . . . . . . 26float.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 26fmtmsg.h . . . . . . . . . . . . . . . . . . . . . . . . . . 26fnmatch.h . . . . . . . . . . . . . . . . . . . . . . . . . . 27fpxcp.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27__ftp.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27ftw.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27glob.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27grp.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27iconv.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27_Ieee754.h . . . . . . . . . . . . . . . . . . . . . . . . . 27ims.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 27inttypes.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28iso646.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28langinfo.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28lc_core.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28lc_sys.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28leawi.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 28libgen.h . . . . . . . . . . . . . . . . . . . . . . . . . . 28

iv XL C/C++ for z/VM: Runtime Library Reference

limits.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 29localdef.h . . . . . . . . . . . . . . . . . . . . . . . . . . 30locale.h. . . . . . . . . . . . . . . . . . . . . . . . . . . 30math.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 32memory.h . . . . . . . . . . . . . . . . . . . . . . . . . . 33monetary.h . . . . . . . . . . . . . . . . . . . . . . . . . 33msgcat.h . . . . . . . . . . . . . . . . . . . . . . . . . . 33mtf.h. . . . . . . . . . . . . . . . . . . . . . . . . . . . 33_Nascii.h . . . . . . . . . . . . . . . . . . . . . . . . . . 34ndbm.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 34net/if.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 34net/rtrouteh.h . . . . . . . . . . . . . . . . . . . . . . . . 34netdb.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 34netinet/in.h . . . . . . . . . . . . . . . . . . . . . . . . . 34new . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34new.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 35nlist.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 35nl_langinfo.h . . . . . . . . . . . . . . . . . . . . . . . . . 36nl_types.h. . . . . . . . . . . . . . . . . . . . . . . . . . 36poll.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 36pthread.h . . . . . . . . . . . . . . . . . . . . . . . . . . 36pwd.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 37re_comp.h . . . . . . . . . . . . . . . . . . . . . . . . . 37regex.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 37regexp.h . . . . . . . . . . . . . . . . . . . . . . . . . . 38resolv.h. . . . . . . . . . . . . . . . . . . . . . . . . . . 38rexec.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 38saiucv.h . . . . . . . . . . . . . . . . . . . . . . . . . . 38search.h . . . . . . . . . . . . . . . . . . . . . . . . . . 38setjmp.h . . . . . . . . . . . . . . . . . . . . . . . . . . 38signal.h. . . . . . . . . . . . . . . . . . . . . . . . . . . 38spawn.h . . . . . . . . . . . . . . . . . . . . . . . . . . 39spc.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 39stdarg.h . . . . . . . . . . . . . . . . . . . . . . . . . . 39stddef.h . . . . . . . . . . . . . . . . . . . . . . . . . . 40stdefs.h . . . . . . . . . . . . . . . . . . . . . . . . . . 40stdio.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 40stdlib.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 42string.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 43strings.h . . . . . . . . . . . . . . . . . . . . . . . . . . 44stropts.h . . . . . . . . . . . . . . . . . . . . . . . . . . 44syslog.h . . . . . . . . . . . . . . . . . . . . . . . . . . 44sys/acl.h . . . . . . . . . . . . . . . . . . . . . . . . . . 44sys/__cpl.h . . . . . . . . . . . . . . . . . . . . . . . . . 44sys/file.h . . . . . . . . . . . . . . . . . . . . . . . . . . 44sys/_getipc.h. . . . . . . . . . . . . . . . . . . . . . . . . 44sys/ioctl.h . . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/ipc.h . . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/layout.h . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/mman.h . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/__messag.h . . . . . . . . . . . . . . . . . . . . . . . 45sys/mntent.h . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/modes.h . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/msg.h . . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/ps.h . . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/resource.h . . . . . . . . . . . . . . . . . . . . . . . . 45

Contents v

sys/sem.h . . . . . . . . . . . . . . . . . . . . . . . . . . 45sys/server.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/shm.h . . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/socket.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/stat.h . . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/statfs.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/statvfs.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/time.h . . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/timeb.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/times.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/ttydev.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/types.h . . . . . . . . . . . . . . . . . . . . . . . . . 46sys/uio.h . . . . . . . . . . . . . . . . . . . . . . . . . . 48sys/un.h . . . . . . . . . . . . . . . . . . . . . . . . . . 48sys/__ussos.h . . . . . . . . . . . . . . . . . . . . . . . . 48sys/utsname.h . . . . . . . . . . . . . . . . . . . . . . . . 48sys/wait.h . . . . . . . . . . . . . . . . . . . . . . . . . . 48sys/__wlm.h . . . . . . . . . . . . . . . . . . . . . . . . . 48tar.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48terminat.h . . . . . . . . . . . . . . . . . . . . . . . . . . 48termios.h . . . . . . . . . . . . . . . . . . . . . . . . . . 49time.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 49typeinfo . . . . . . . . . . . . . . . . . . . . . . . . . . 49typeinfo.h . . . . . . . . . . . . . . . . . . . . . . . . . . 51ucontext.h. . . . . . . . . . . . . . . . . . . . . . . . . . 51uheap.h . . . . . . . . . . . . . . . . . . . . . . . . . . 51ulimit.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 51unexpect.h . . . . . . . . . . . . . . . . . . . . . . . . . 51unistd.h . . . . . . . . . . . . . . . . . . . . . . . . . . 51utime.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 52utmpx.h . . . . . . . . . . . . . . . . . . . . . . . . . . 52varargs.h . . . . . . . . . . . . . . . . . . . . . . . . . . 52variant.h . . . . . . . . . . . . . . . . . . . . . . . . . . 52wchar.h. . . . . . . . . . . . . . . . . . . . . . . . . . . 53wcstr.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 54wctype.h . . . . . . . . . . . . . . . . . . . . . . . . . . 54wordexp.h. . . . . . . . . . . . . . . . . . . . . . . . . . 54xti.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 3. Library Functions . . . . . . . . . . . . . . . . . . . 59Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . 60Online Examples . . . . . . . . . . . . . . . . . . . . . . . . 61Built-in Functions . . . . . . . . . . . . . . . . . . . . . . . . 61IEEE floating-point . . . . . . . . . . . . . . . . . . . . . . . 62External Variables . . . . . . . . . . . . . . . . . . . . . . . . 63

errno . . . . . . . . . . . . . . . . . . . . . . . . . . . 63daylight. . . . . . . . . . . . . . . . . . . . . . . . . . . 63getdate_err . . . . . . . . . . . . . . . . . . . . . . . . . 63_loc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 63loc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63loc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64locs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64optarg . . . . . . . . . . . . . . . . . . . . . . . . . . . 64opterr . . . . . . . . . . . . . . . . . . . . . . . . . . . 64optind . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

vi XL C/C++ for z/VM: Runtime Library Reference

optopt . . . . . . . . . . . . . . . . . . . . . . . . . . . 64signgam . . . . . . . . . . . . . . . . . . . . . . . . . . 64stdin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64stderr . . . . . . . . . . . . . . . . . . . . . . . . . . . 64stdout . . . . . . . . . . . . . . . . . . . . . . . . . . . 64timezone . . . . . . . . . . . . . . . . . . . . . . . . . . 64tzname . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Library Function Descriptions. . . . . . . . . . . . . . . . . . . . 65abort() — Stop a Program. . . . . . . . . . . . . . . . . . . . 66abs(), absf(), absl() — Calculate Integer Absolute Value . . . . . . . . . 68accept() — Accept a New Connection on a Socket. . . . . . . . . . . 70access() — Determine Whether a File Can be Accessed . . . . . . . . 73acos(), acosf(), acosl() — Calculate Arccosine . . . . . . . . . . . . 75acosh() — Calculate Hyperbolic Arcosine . . . . . . . . . . . . . . 77alarm() — Set an Alarm . . . . . . . . . . . . . . . . . . . . 78asctime() — Convert Time to Character String . . . . . . . . . . . . 80asin(), asinf(), asinl() — Calculate Arcsine . . . . . . . . . . . . . . 82asinh() — Calculate Hyperbolic Arcsine . . . . . . . . . . . . . . . 84assert() — Verify Condition . . . . . . . . . . . . . . . . . . . 85atan(), atanf(), atanl(), atan2(), atan2f(), atan2l() — Calculate Arctangent 87atanh() — Calculate Hyperbolic Arctangent . . . . . . . . . . . . . 89atexit() — Register Program Termination Function . . . . . . . . . . . 90__atoe() — Convert ISO8859-1 String to EBCDIC . . . . . . . . . . . 92__atoe_l() — Convert ISO8859-1 Bytes to EBCDIC . . . . . . . . . . 93atof() — Convert Character String to Double . . . . . . . . . . . . . 94atoi() — Convert Character String to Integer . . . . . . . . . . . . . 95atol() — Convert Character String to Long . . . . . . . . . . . . . . 96a64l() — Convert Base-64 String Representation to Long Integer . . . . . 97basename() — Return the Last Component of a Path Name . . . . . . . 98bcmp() — Compare Bytes in Memory . . . . . . . . . . . . . . . 99bcopy() — Copy Bytes in Memory . . . . . . . . . . . . . . . . 100bind() — Bind a Name to a Socket . . . . . . . . . . . . . . . . 101brk() — Change Space Allocation . . . . . . . . . . . . . . . . 109bsd_signal() — Establish BSD Version of signal() . . . . . . . . . . . 110bsearch() — Search Arrays . . . . . . . . . . . . . . . . . . . 111bzero() — Zero Out Bytes in Memory . . . . . . . . . . . . . . . 113calloc() — Reserve and Initialize Storage . . . . . . . . . . . . . . 114cbrt() — Calculate Cube Root . . . . . . . . . . . . . . . . . . 116cclass() — Return Characters in a Character Class . . . . . . . . . . 117cds() — Compare Double and Swap . . . . . . . . . . . . . . . 118cdump() — Request Main Storage Dump . . . . . . . . . . . . . . 119ceil(), ceilf(), ceill()— Round Up to Integral Value . . . . . . . . . . . 120cfgetispeed() — Determine Input Baud Rate . . . . . . . . . . . . 121cfgetospeed() — Determine Output Baud Rate. . . . . . . . . . . . 124cfsetispeed() — Set Input Baud Rate in the Termios. . . . . . . . . . 126cfsetospeed() — Set Output Baud Rate in the Termios . . . . . . . . . 128chaudit() — Change Audit Flags for a File by Path . . . . . . . . . . 130chdir() — Change the Working Directory . . . . . . . . . . . . . . 132chmod() — Change the Mode of a File or Directory . . . . . . . . . . 134chown() — Change the Owner or Group of a File or Directory . . . . . . 137clearenv() — Clear Environment Variables . . . . . . . . . . . . . 140clearerr() — Reset Error and End-of-File . . . . . . . . . . . . . . 143clock() — Determine Processor Time . . . . . . . . . . . . . . . 144close() — Close a File. . . . . . . . . . . . . . . . . . . . . 146closedir() — Close a Directory . . . . . . . . . . . . . . . . . . 149clrmemf() — Clear Memory Files . . . . . . . . . . . . . . . . . 151

Contents vii

collequiv() — Return List of Equivalent Collating Elements . . . . . . . 153collorder() — Return List of Collating Elements . . . . . . . . . . . 155collrange() — Calculate the Range List of Collating Elements . . . . . . 157colltostr() — Return a String for a Collating Element. . . . . . . . . . 159confstr() — Get Configurable Variables . . . . . . . . . . . . . . 161connect() — Connect a Socket . . . . . . . . . . . . . . . . . 162cos(), cosf(), cosl()— Calculate Cosine . . . . . . . . . . . . . . 169cosh(), coshf(), coshl()— Calculate Hyperbolic Cosine . . . . . . . . . 171creat() — Create a New File or Rewrite an Existing One . . . . . . . . 173cs() — Compare and Swap . . . . . . . . . . . . . . . . . . . 176csid() — Character Set ID for Multibyte Character . . . . . . . . . . 177csnap() — Request a Condensed Dump . . . . . . . . . . . . . . 178__csplist() — Retrieve CSP Parameters . . . . . . . . . . . . . . 179ctermid() — Generate Path Name for Controlling Terminal . . . . . . . 180ctest() — Start Debug Tool . . . . . . . . . . . . . . . . . . . 181ctime() — Convert Time to a Character String . . . . . . . . . . . . 182ctrace() — Request a Traceback . . . . . . . . . . . . . . . . . 184cuserid() — Return Character Login of the User . . . . . . . . . . . 186dbm_clearerr() — Clear Database Error Indicator . . . . . . . . . . . 187dbm_close() — Close a Database . . . . . . . . . . . . . . . . 188dbm_delete() — Delete Database Record . . . . . . . . . . . . . 189dbm_error() — Check Database Error Indicator . . . . . . . . . . . 190dbm_fetch() — Get Database Content . . . . . . . . . . . . . . . 191dbm_firstkey() — Get First Key in Database. . . . . . . . . . . . . 192dbm_nextkey() — Get Next Key in Database . . . . . . . . . . . . 193dbm_open() — Open a Database . . . . . . . . . . . . . . . . 194dbm_store() — Store Database Record . . . . . . . . . . . . . . 196difftime() — Compute Time Difference . . . . . . . . . . . . . . . 198dirname() — Report the Parent Directory of a Path Name . . . . . . . 200div() — Calculate Quotient and Remainder . . . . . . . . . . . . . 201dlclose() — Close a dlopen() object . . . . . . . . . . . . . . . . 202dlerror() — Get Diagnostic Information . . . . . . . . . . . . . . . 204dlopen() — Gain Access to a Dynamic Link Library (DLL). . . . . . . . 205dlsym() — Obtain the Address of a Symbol from a dlopen() Object . . . . 208dllfree() — Free the Supplied DLL . . . . . . . . . . . . . . . . 209dllload() — Load the DLL and Connect it to the Application . . . . . . . 210dllqueryfn() — Obtain a Pointer to a DLL Function . . . . . . . . . . 211dllqueryvar() — Obtain a Pointer to a DLL Variable . . . . . . . . . . 212dn_comp() — Resolver Domain Name Compression . . . . . . . . . 213dn_expand() — Resolver Domain Name Expansion . . . . . . . . . . 214dn_find() — Resolver Domain Name Find . . . . . . . . . . . . . 215dn_skipname() — Resolver Domain Name Skipping . . . . . . . . . . 216drand48() — Generate Pseudo-Random Number . . . . . . . . . . . 217dup() — Duplicate an Open File Descriptor . . . . . . . . . . . . . 219dup2() — Duplicate an Open File Descriptor to Another . . . . . . . . 221ecvt() — Convert Double to String . . . . . . . . . . . . . . . . 224endhostent() — Work with a Host Entry . . . . . . . . . . . . . . 225endnetent() — Close Network Information Data Set . . . . . . . . . . 226endprotoent() — Work with a Protocol Entry. . . . . . . . . . . . . 227endservent() — Close Network Services Information Data Sets . . . . . 228endutxent() — Close the utmpx Database . . . . . . . . . . . . . 229erand48() — Generate Pseudo-Random Number . . . . . . . . . . . 230erf() - erfc() — Calculate Error and Complementary Error Functions . . . . 232__errno2() — Return Reason Code Information . . . . . . . . . . . 234__etoa() — Convert EBCDIC String to ISO8859-1 . . . . . . . . . . 235__etoa_l() — Convert EBCDIC Bytes to ISO8859-1 . . . . . . . . . . 236

viii XL C/C++ for z/VM: Runtime Library Reference

exec Functions . . . . . . . . . . . . . . . . . . . . . . . 237_exit() — End a Process and Bypass the Cleanup . . . . . . . . . . 241exit() — End Program . . . . . . . . . . . . . . . . . . . . . 243exp(), expf(), expl()— Calculate Exponential Function . . . . . . . . . 245expm1() — Calculate Exponential Minus One . . . . . . . . . . . . 246fabs(), fabsf(), fabsl() — Calculate Floating-Point Absolute Value . . . . . 247fchaudit() — Change Audit Flags for a File by Descriptor . . . . . . . . 248fchmod() — Change the Mode of a File or Directory by Descriptor . . . . 250fchown() — Change the Owner or Group by File Descriptor . . . . . . . 252fclose() — Close File . . . . . . . . . . . . . . . . . . . . . 254fcntl() — Control Open File Descriptors . . . . . . . . . . . . . . 256fcvt() — Convert Double to String . . . . . . . . . . . . . . . . 266fdelrec() — Delete a VSAM Record . . . . . . . . . . . . . . . . 267fdopen() — Associate a Stream with an Open File Descriptor . . . . . . 269feof() — Test End-of-File Indicator . . . . . . . . . . . . . . . . 271ferror() — Test for Read/Write Errors . . . . . . . . . . . . . . . 273fetch() — Get a Load Module . . . . . . . . . . . . . . . . . . 274fetchep() — Share Writable Static . . . . . . . . . . . . . . . . 286fflush() — Write Buffer to File . . . . . . . . . . . . . . . . . . 289ffs() — Find First Set Bit in an Integer . . . . . . . . . . . . . . . 291fgetc() — Read a Character. . . . . . . . . . . . . . . . . . . 292fgetpos() — Get File Position . . . . . . . . . . . . . . . . . . 294fgets() — Read a String from a Stream . . . . . . . . . . . . . . 296fgetwc() — Get Next Wide Character . . . . . . . . . . . . . . . 298fgetws() — Get a Wide-Character String . . . . . . . . . . . . . . 300fileno() — Get the File Descriptor from an Open Stream . . . . . . . . 302fldata() — Retrieve File Information . . . . . . . . . . . . . . . . 304flocate() — Locate a VSAM Record . . . . . . . . . . . . . . . . 307floor(), floorf(), floorl() — Round Down to Integral Value . . . . . . . . 310fmod(), fmodf(), fmodl() — Calculate Floating-Point Remainder . . . . . . 311fmtmsg() — Display a Message in the Specified Format . . . . . . . . 313fnmatch() — Match File Name or Path Name . . . . . . . . . . . . 316fopen() — Open a File . . . . . . . . . . . . . . . . . . . . 317fork() — Create a New Process . . . . . . . . . . . . . . . . . 322fpathconf() — Determine Configurable Path Name Variables. . . . . . . 325fprintf() - printf() - sprintf() — Format and Write Data . . . . . . . . . 328fputc() — Write a Character. . . . . . . . . . . . . . . . . . . 337fputs() — Write a String . . . . . . . . . . . . . . . . . . . . 339fputwc() — Output a Wide Character . . . . . . . . . . . . . . . 341fputws() — Output a Wide-Character String . . . . . . . . . . . . . 343fread() — Read Items . . . . . . . . . . . . . . . . . . . . . 345free() — Free a Block of Storage . . . . . . . . . . . . . . . . . 347freeaddrinfo() — Free Addrinfo Storage . . . . . . . . . . . . . . 349freopen() — Redirect an Open File . . . . . . . . . . . . . . . . 350frexp() — Extract Mantissa and Exponent of the Floating-Point Value . . . 352fscanf() - scanf() - sscanf() — Read and Format Data . . . . . . . . . 354fseek() — Change File Position . . . . . . . . . . . . . . . . . 364fsetpos() — Set File Position . . . . . . . . . . . . . . . . . . 367fstat() — Get Status Information about a File . . . . . . . . . . . . 369fstatvfs() — Get File System Information . . . . . . . . . . . . . . 371fsync() — Write Changes to Direct-Access Storage . . . . . . . . . . 373ftell() — Get Current File Position . . . . . . . . . . . . . . . . 375ftime() — Get the Date and Time. . . . . . . . . . . . . . . . . 377ftok() — Generate an Interprocess Communication (IPC) Key . . . . . . 378ftruncate() — Truncate a File . . . . . . . . . . . . . . . . . . 379ftw() — Traverse a File Tree . . . . . . . . . . . . . . . . . . 381

Contents ix

fupdate() — Update a VSAM Record . . . . . . . . . . . . . . . 383fwrite() — Write Items . . . . . . . . . . . . . . . . . . . . . 385gai_strerror() — Address and Name Information Error Description. . . . . 387gamma() — Calculate Gamma Function . . . . . . . . . . . . . . 388gcvt() — Convert Double to String . . . . . . . . . . . . . . . . 389getc() - getchar() — Read a Character. . . . . . . . . . . . . . . 390getaddrinfo() — Get Address Information . . . . . . . . . . . . . . 392getclientid() — Get Identifier for Calling Application . . . . . . . . . . 396getcontext() — Get User Context . . . . . . . . . . . . . . . . . 398getcwd() — Get Path Name of the Working Directory . . . . . . . . . 401getdate() — Convert User Format Date and Time. . . . . . . . . . . 403getdtablesize() — Get File Descriptor Table Size . . . . . . . . . . . 406getegid() — Get the Effective Group ID . . . . . . . . . . . . . . 407getenv() — Get Value of Environment Variables . . . . . . . . . . . 408geteuid() — Get the Effective User ID . . . . . . . . . . . . . . . 410getgid() — Get the Real Group ID . . . . . . . . . . . . . . . . 412getgrgid() — Access the Group Database by ID . . . . . . . . . . . 413getgrnam() — Access the Group Database by Name . . . . . . . . . 415getgroups() — Get a List of Supplementary Group IDs . . . . . . . . . 417getgroupsbyname() — Get Supplementary Group IDs by User Name . . . 419gethostbyaddr() — Get a Host Entry by Address . . . . . . . . . . . 421gethostbyname() — Get a Host Entry by Name . . . . . . . . . . . 423gethostent() — Get Next Host Entry. . . . . . . . . . . . . . . . 425gethostid() — Get Unique Identifier of Current Host . . . . . . . . . . 427gethostname() — Get Name of Host Processor . . . . . . . . . . . 428getibmsockopt() — Get Options Associated with a Bulk Mode Socket . . . 429getlogin() — Get the User Login Name . . . . . . . . . . . . . . 432getmccoll() — Get Next Collating Element from String . . . . . . . . . 434getnameinfo() — Get Name Information . . . . . . . . . . . . . . 435getnetbyaddr() — Get a Network Entry by Address . . . . . . . . . . 437getnetbyname() — Get a Network Entry by Name . . . . . . . . . . 439getnetent() — Get Next Network Entry . . . . . . . . . . . . . . . 441getopt() — Parse Command Option . . . . . . . . . . . . . . . . 442getpagesize() — Get the Current Page Size. . . . . . . . . . . . . 444getpass() — Read a Character String Without Echo . . . . . . . . . . 445getpeername() — Get Name of Peer Connected to a Socket . . . . . . 446getpgrp() — Get the Process Group ID . . . . . . . . . . . . . . 448getpid() — Get the Process ID. . . . . . . . . . . . . . . . . . 449getppid() — Get the Parent Process ID . . . . . . . . . . . . . . 450getprotobyname() — Get a Protocol Entry by Name . . . . . . . . . . 452getprotobynumber() — Get a Protocol Entry by Number . . . . . . . . 453getprotoent() — Get Next Protocol Entry . . . . . . . . . . . . . . 454getpwnam() — Access the User Database by User Name . . . . . . . 455getpwuid() — Access the User Database by User ID . . . . . . . . . 457gets() — Read a String . . . . . . . . . . . . . . . . . . . . 459getservbyname() — Get a Server Entry by Name. . . . . . . . . . . 461getservbyport() — Get a Service Entry by Port . . . . . . . . . . . . 462getservent() — Get Next Service Entry . . . . . . . . . . . . . . 463getsockname() — Get Name of a Socket . . . . . . . . . . . . . . 464getsockopt() — Get Options Associated with a Socket . . . . . . . . . 466getstablesize() — Get Socket Table Size . . . . . . . . . . . . . . 472getsubopt() — Parse Suboption Arguments . . . . . . . . . . . . . 473getsyntx() — Return LC_SYNTAX Characters . . . . . . . . . . . . 474gettimeofday() — Get Date and Time . . . . . . . . . . . . . . . 476getuid() — Get the Real User ID . . . . . . . . . . . . . . . . . 478getutxent() — Read Next Entry in utmpx Database . . . . . . . . . . 480

x XL C/C++ for z/VM: Runtime Library Reference

getutxid() — Search by ID utmpx Database . . . . . . . . . . . . . 482getutxline() — Search by Line utmpx Database . . . . . . . . . . . 484getw() — Get a Machine Word from a Stream . . . . . . . . . . . . 486getwc() — Get a Wide Character . . . . . . . . . . . . . . . . . 487getwchar() — Get a Wide Character . . . . . . . . . . . . . . . 489getwmccoll() — Get Next Collating Element from Wide String . . . . . . 491givesocket() — Make Specified Socket Available . . . . . . . . . . . 492glob() — Generate Path names Matching a Pattern . . . . . . . . . . 494globfree() — Free Storage Allocated by glob() . . . . . . . . . . . . 497gmtime() — Convert Time to Broken-Down UTC Time . . . . . . . . . 498hcreate() — Create Hash Search Tables . . . . . . . . . . . . . . 500hdestroy() — Destroy Hash Search Tables . . . . . . . . . . . . . 501hsearch() — Search Hash Tables . . . . . . . . . . . . . . . . 502htonl() — Translate Address Host to Network Long . . . . . . . . . . 503htons() — Translate an Unsigned Short Integer into Network Byte Order 504hypot() — Calculate Hypotenuse . . . . . . . . . . . . . . . . . 505ibmsflush() — Flush Application-side Datagram Queue. . . . . . . . . 506iconv() — Code Conversion. . . . . . . . . . . . . . . . . . . 508iconv_close() — Deallocate Code Conversion Descriptor . . . . . . . . 511iconv_open() — Allocate Code Conversion Descriptor . . . . . . . . . 512if_freenameindex() — Free the Memory Allocated by if_nameindex(). . . . 514if_indextoname() — Map a Network Interface Index to Its Corresponding

Name . . . . . . . . . . . . . . . . . . . . . . . . . . 515if_nameindex() — Return All Network Interface Names and Indexes . . . . 516if_nametoindex() — Map a Network Interface Name to Its Corresponding

Index . . . . . . . . . . . . . . . . . . . . . . . . . . 517ilogb() — Integer Unbiased Exponent . . . . . . . . . . . . . . . 518index() — Search for Character . . . . . . . . . . . . . . . . . 519inet_addr() — Translate an Internet Address into Network Order . . . . . 520inet_lnaof() — Translate a Local Network Address into Host Byte Order 522inet_makeaddr() — Create an Internet Host Address . . . . . . . . . 523inet_netof() — Get Network Number from Internet Host Address . . . . . 524inet_network() — Get Network Number from Decimal Host Address . . . . 525inet_ntoa() — Get Decimal Internet Host Address. . . . . . . . . . . 526inet_ntop() — Convert Internet Address Format from Binary to Text . . . . 527inet_pton() — Convert Internet Address Format from Text to Binary . . . . 529initstate() — Initialize Generator for random() . . . . . . . . . . . . 531insque() — Insert an Element into a Doubly Linked List . . . . . . . . 532ioctl() — Control Device . . . . . . . . . . . . . . . . . . . . 533isalnum() to isxdigit() — Test Integer Value . . . . . . . . . . . . . 536isascii() — Test for 7-bit US-ASCII Character . . . . . . . . . . . . 539isatty() — Test if Descriptor Represents a Terminal . . . . . . . . . . 544isblank() — Test for Blank Character Classification . . . . . . . . . . 546iscics() — Verify Whether CICS is Running . . . . . . . . . . . . . 548iscntrl() — Test for Control Classification . . . . . . . . . . . . . . 549isdigit() — Test for Hexadecimal-Digit Classification . . . . . . . . . . 550isgraph() — Test for Graphic Classification . . . . . . . . . . . . . 551islower() — Test for Lowercase . . . . . . . . . . . . . . . . . 552ismccollel() — Identify a Multicharacter Collating Element. . . . . . . . 553isnan() — Test for NaN . . . . . . . . . . . . . . . . . . . . 555isprint() — Test for Printable Character Classification . . . . . . . . . 556ispunct() — Test for Punctuation Classification . . . . . . . . . . . . 557isspace() — Test for Space Character Classification . . . . . . . . . . 558isupper() — Test for Uppercase Letter Classification. . . . . . . . . . 559iswalnum() to iswxdigit() — Test Wide Integer Value . . . . . . . . . . 560iswblank() — Test for Blank Character Classification. . . . . . . . . . 562

Contents xi

iswcntrl() — Test for Control Classification . . . . . . . . . . . . . 563iswctype() — Test for Character Property . . . . . . . . . . . . . . 564iswdigit() — Test for Hexadecimal-Digit Classification . . . . . . . . . 566iswgraph() — Test for Graphic Classification . . . . . . . . . . . . 567iswlower() — Test for Lowercase . . . . . . . . . . . . . . . . . 568iswprint() — Test for Printable Character Classification . . . . . . . . . 569iswpunct() — Test for Punctuation Classification . . . . . . . . . . . 570iswspace() — Test for Space Character Classification . . . . . . . . . 571iswupper() — Test for Uppercase Letter Classification . . . . . . . . . 572iswxdigit() — Test for Hexadecimal-Digit Classification . . . . . . . . . 573isxdigit() — Test for Hexadecimal-Digit Classification . . . . . . . . . 574jrand48() — Generate Pseudorandom Number. . . . . . . . . . . . 575j0() - j1() - jn() — Bessel Functions of the First Kind . . . . . . . . . . 577kill() — Send a Signal to a Process . . . . . . . . . . . . . . . . 579killpg() — Send a Signal to a Process Group . . . . . . . . . . . . 582labs() — Calculate Long Absolute Value . . . . . . . . . . . . . . 584lcong48() — Initialize Pseudorandom Number . . . . . . . . . . . . 585ldexp(), ldexpf(), ldexpl() — Multiply by a Power of Two . . . . . . . . 587ldiv() — Compute Quotient and Remainder of Integral Division . . . . . . 589lfind() — Linear Search Routine . . . . . . . . . . . . . . . . . 590lgamma() — Log Gamma Function . . . . . . . . . . . . . . . . 591__librel() — Query Release Level . . . . . . . . . . . . . . . . 593link() — Create a Link to a File . . . . . . . . . . . . . . . . . 594listen() — Prepare Server for Incoming Client Requests . . . . . . . . 596localdtconv() — Date/Time Formatting Convention Inquiry . . . . . . . 598localeconv() — Query Numeric Conventions . . . . . . . . . . . . 599localtime() — Convert Time and Correct for Local Time . . . . . . . . 601lockf() — Record Locking on Files . . . . . . . . . . . . . . . . 603log(), logf(), logl() — Calculate Natural Logarithm . . . . . . . . . . . 605logb() — Calculate Unbiased Exponent . . . . . . . . . . . . . . 607log1p() — Calculate Natural Log of x plus 1 . . . . . . . . . . . . . 608log10(), log10f(), log10l() — Calculate Base 10 Logarithm . . . . . . . 609_longjmp() — Nonlocal Goto . . . . . . . . . . . . . . . . . . 611longjmp() — Restore Stack Environment . . . . . . . . . . . . . . 613lrand48() — Generate Pseudorandom Number. . . . . . . . . . . . 616lsearch() — Linear Search and Update . . . . . . . . . . . . . . 618lseek() — Change the Offset of a File . . . . . . . . . . . . . . . 619lstat() — Get Status of File, External Link, or Symbolic Link . . . . . . . 621l64a() — Convert Long to Base-64 String Representation . . . . . . . . 625makecontext() — Modify User Context . . . . . . . . . . . . . . . 626malloc() — Reserve Storage Block . . . . . . . . . . . . . . . . 629maxcoll() — Return Maximum Collating Element . . . . . . . . . . . 631maxdesc() — Get Socket Numbers to Extend Beyond Default Range . . . 632mblen() — Calculate Length of Multibyte Character . . . . . . . . . . 634mbrlen() — Calculate Length of Multibyte Character . . . . . . . . . . 636mbrtowc() — Convert a Multibyte Character to a Wide Character . . . . . 638mbsinit() — Test State Object for Initial State . . . . . . . . . . . . 641mbsrtowcs() — Convert a Multibyte String to a Wide-Character String . . . 643mbstowcs() — Convert Multibyte Characters to Wide Characters . . . . . 645mbtowc() — Convert Multibyte Character to Wide Character. . . . . . . 647memccpy() — Copy Bytes in Memory . . . . . . . . . . . . . . . 649memchr() — Search Buffer . . . . . . . . . . . . . . . . . . . 650memcmp() — Compare Bytes . . . . . . . . . . . . . . . . . . 651memcpy() — Copy Buffer . . . . . . . . . . . . . . . . . . . 653memmove() — Move Buffer. . . . . . . . . . . . . . . . . . . 654memset() — Set Buffer to Value . . . . . . . . . . . . . . . . . 655

xii XL C/C++ for z/VM: Runtime Library Reference

mkdir() — Make a Directory. . . . . . . . . . . . . . . . . . . 656mkfifo() — Make a FIFO Special File . . . . . . . . . . . . . . . 658mknod() — Make a FIFO or Charcter Special File . . . . . . . . . . 661mkstemp() — Make a Unique File Name . . . . . . . . . . . . . . 663mktemp() — Make a Unique File Name . . . . . . . . . . . . . . 664mktime() — Convert Local Time . . . . . . . . . . . . . . . . . 665modf() — Extract Fractional and Integral Parts of a FLoating-Point Value 668mount() — Make a File System Available . . . . . . . . . . . . . . 669mrand48() — Generate Pseudorandom Number . . . . . . . . . . . 672msgctl() — Message Control Operations . . . . . . . . . . . . . . 674msgget() — Get Message Queue . . . . . . . . . . . . . . . . 676msgrcv() — Read and Receive a Message . . . . . . . . . . . . . 678msgsnd() — Send a Message . . . . . . . . . . . . . . . . . . 680msgxrcv() — Read and Receive an Extended Message . . . . . . . . 682nextafter() — Calculate Next Representable Double Float. . . . . . . . 684nftw() — Traverse a File Tree . . . . . . . . . . . . . . . . . . 685nl_langinfo() — Retrieve Locale Information . . . . . . . . . . . . . 688nrand48() — Pseudo-Random Number Generator . . . . . . . . . . 690ntohl() — Translate a Long Integer into Host Byte Order . . . . . . . . 692ntohs() — Translate an Unsigned Short Integer into Host Byte Order . . . 693open() — Open a File . . . . . . . . . . . . . . . . . . . . . 694opendir() — Open a Directory . . . . . . . . . . . . . . . . . . 699pathconf() — Determine Configurable Path Name Variables . . . . . . . 701pause() — Suspend a Thread Pending a Signal . . . . . . . . . . . 704pclose() — Close a Pipe Stream to or from a Process . . . . . . . . . 706perror() — Print Error Message . . . . . . . . . . . . . . . . . 707pipe() — Create an Unnamed Pipe . . . . . . . . . . . . . . . . 709popen() — Initiate a Pipe Stream to or from a Process. . . . . . . . . 712pow() — Raise to Power . . . . . . . . . . . . . . . . . . . . 714printf() — Format and Write Data. . . . . . . . . . . . . . . . . 716pthread_attr_destroy() — Destroy the Thread Attributes Object . . . . . . 717pthread_attr_getdetachstate() — Get the Detach State Attribute . . . . . 719pthread_attr_getstacksize() — Get the Thread Attribute Stacksize. . . . . 721pthread_attr_getweight_np() — Get Weight of Thread Attribute Object . . . 723pthread_attr_init() — Initialize a Thread Attribute Object . . . . . . . . 725pthread_attr_setdetachstate() — Set the Detach State Attribute Object 727pthread_attr_setstacksize() — Set the Stacksize Attribute Object . . . . . 729pthread_attr_setweight_np() — Set Weight of Thread Attribute Object . . . 731pthread_cancel() — Cancel a Thread . . . . . . . . . . . . . . . 733pthread_cleanup_pop() — Remove a Cleanup Handler. . . . . . . . . 736pthread_cleanup_push() — Establish a Cleanup Handler . . . . . . . . 738pthread_cond_broadcast() — Broadcast a Condition . . . . . . . . . 740pthread_cond_destroy() — Destroy the Condition Variable Object . . . . . 742pthread_cond_init() — Initialize a Condition Variable. . . . . . . . . . 744pthread_cond_signal() — Signal a Condition . . . . . . . . . . . . 745pthread_cond_timedwait() — Wait on a Condition Variable . . . . . . . 747pthread_cond_wait() — Wait on a Condition Variable . . . . . . . . . 749pthread_condattr_destroy() — Destroy Condition Variable Attribute Object 751pthread_condattr_getkind_np() — Get Kind Attribute from a Condition

Variable Attribute Object . . . . . . . . . . . . . . . . . . . 753pthread_condattr_init() — Initialize a Condition Attribute Object . . . . . . 755pthread_condattr_setkind_np() — Set Kind Attribute from a Condition

Variable Attribute Object . . . . . . . . . . . . . . . . . . . 757pthread_create() — Create a Thread . . . . . . . . . . . . . . . 759pthread_detach() — Detach a Thread . . . . . . . . . . . . . . . 761pthread_equal() — Compare Thread IDs . . . . . . . . . . . . . . 763

Contents xiii

pthread_exit() — Exit a Thread . . . . . . . . . . . . . . . . . 765pthread_getspecific() — Get the Thread-Specific Value for a Key . . . . . 767pthread_join() — Wait for a Thread to End . . . . . . . . . . . . . 770pthread_join_d4_np() — Wait for a Thread to End (.4a) . . . . . . . . 772pthread_key_create() — Create Thread-Specific Data Key . . . . . . . 774pthread_kill() — Send a Signal to a Thread . . . . . . . . . . . . . 777pthread_mutex_destroy() — Delete a Mutex Object . . . . . . . . . . 779pthread_mutex_init() — Initialize a Mutex Object . . . . . . . . . . . 781pthread_mutex_lock() — Wait for a Lock on a Mutex Object . . . . . . . 783pthread_mutex_trylock() — Attempt to Lock a Mutex Object . . . . . . . 785pthread_mutex_unlock() — Unlock a Mutex Object . . . . . . . . . . 787pthread_mutexattr_destroy() — Destroy a Mutex Attribute Object . . . . . 789pthread_mutexattr_getkind_np() — Get Kind from a Mutex Attribute Object 791pthread_mutexattr_init() — Initialize a Mutex Attribute Object . . . . . . 793pthread_mutexattr_setkind_np() — Set Kind for a Mutex Attribute Object 795pthread_once() — Invoke a Function Once . . . . . . . . . . . . . 797pthread_self() — Get the Caller . . . . . . . . . . . . . . . . . 800pthread_setintr() — Set the Cancelability State of a Thread . . . . . . . 802pthread_setintrtype() — Set the Cancelability Type of a Thread . . . . . 804pthread_setspecific() — Set the Thread-Specific Value for a Key . . . . . 807pthread_testintr() — Establish a Cancelability Point . . . . . . . . . . 810pthread_yield() — Release the Processor to Other Threads . . . . . . . 812putc() - putchar() — Write a Character . . . . . . . . . . . . . . . 814putenv() — Change or Add an Environment Variable . . . . . . . . . 816puts() — Write a String . . . . . . . . . . . . . . . . . . . . 818pututxline() — Write Entry to utmpx Database . . . . . . . . . . . . 820putw() — Put a Machine Word on a Stream . . . . . . . . . . . . . 822putwc() — Output a Wide Character . . . . . . . . . . . . . . . 823putwchar() — Output a Wide Character to Standard Output . . . . . . . 825qsort() — Sort Array . . . . . . . . . . . . . . . . . . . . . 827raise() — Raise Signal . . . . . . . . . . . . . . . . . . . . 829rand() — Generate Random Number . . . . . . . . . . . . . . . 832random() — Generate a Better Random Number . . . . . . . . . . . 833read() — Read From a File . . . . . . . . . . . . . . . . . . . 834readdir() — Read an Entry from a Directory . . . . . . . . . . . . . 839readlink() — Read the Value of a Symbolic Link . . . . . . . . . . . 841readv() — Read Data on a Socket and Store in a Set of Buffers . . . . . 843realloc() — Change Reserved Storage Block Size . . . . . . . . . . 846realpath() — Resolve Path Name . . . . . . . . . . . . . . . . 849recv() — Receive Data on a Socket. . . . . . . . . . . . . . . . 850recvfrom() — Receive Messages on a Socket . . . . . . . . . . . . 853recvmsg() — Receive Messages on a Socket and Store in an Array of

Message Headers . . . . . . . . . . . . . . . . . . . . . 856re_comp() — Compile Regular Expression . . . . . . . . . . . . . 859re_exec() — Match Regular Expression . . . . . . . . . . . . . . 862regcomp() — Compile Regular Expression . . . . . . . . . . . . . 863regerror() — Return Error Message . . . . . . . . . . . . . . . . 866regexec() — Execute Compiled Regular Expression . . . . . . . . . . 868regfree() — Free Memory for Regular Expression . . . . . . . . . . 870release() — Delete a Load Module . . . . . . . . . . . . . . . . 871remainder() — Remainder Function . . . . . . . . . . . . . . . . 873remove() — Delete File . . . . . . . . . . . . . . . . . . . . 874remque() — Remove an Element from a Doubly Linked List . . . . . . . 876rename() — Rename File . . . . . . . . . . . . . . . . . . . 877res_init() — Domain Name Resolver Initialization . . . . . . . . . . . 880res_mkquery() — Make Resolver Query for Domain Name Servers (DNS) 883

xiv XL C/C++ for z/VM: Runtime Library Reference

res_query() — Resolver Query for Domain Name Servers (DNS) . . . . . 884res_querydomain() — Build Domain Name and Resolver Query . . . . . 886res_search() — Resolver Query for Domain Name Servers (DNS) With

Optional Rules. . . . . . . . . . . . . . . . . . . . . . . 888res_send() — Send Resolver Query for Domain Name Servers (DNS) 890rewind() — Set File Position to Beginning of File . . . . . . . . . . . 891rewinddir() — Reposition a Directory Stream to the Beginning . . . . . . 893rindex() — Search for a Character . . . . . . . . . . . . . . . . 895rint() — Round to Nearest Integral Value . . . . . . . . . . . . . . 896rmdir() — Remove a Directory . . . . . . . . . . . . . . . . . . 897rpmatch() — Test for a Yes/No Response Match . . . . . . . . . . . 899sbrk() — Change Space Allocation . . . . . . . . . . . . . . . . 900scalb() — Load Exponent . . . . . . . . . . . . . . . . . . . 901scanf() — Read and Format Data . . . . . . . . . . . . . . . . 902seed48() — Initialize Pseudorandom Number . . . . . . . . . . . . 903select() — Monitor Activity on Files/Sockets and Message Queues . . . . 905selectex() — Monitor Activity on Files/Sockets and Message Queues . . . 912semctl() — Perform Semaphore Control Operations . . . . . . . . . . 915semget() — Get a Set of Semaphores . . . . . . . . . . . . . . . 918semop() — Perform Semaphore Operations. . . . . . . . . . . . . 921send() — Send Data on a Socket . . . . . . . . . . . . . . . . 924sendmsg() — Send Messages on a Socket . . . . . . . . . . . . . 927sendto() — Send Data on a Socket . . . . . . . . . . . . . . . . 931setbuf() — Control Buffering . . . . . . . . . . . . . . . . . . 934setcontext() — Restore User Context . . . . . . . . . . . . . . . 936setegid() — Set the Effective Group ID . . . . . . . . . . . . . . 939setenv() — Add, Delete, and Change Environment Variables . . . . . . 941seteuid() — Set the Effective User ID . . . . . . . . . . . . . . . 944setgid() — Set the Group ID . . . . . . . . . . . . . . . . . . 946sethostent() — Open Host Information Data Set . . . . . . . . . . . 948setibmsockopt() — Set Options Associated with a Bulk Mode Socket . . . 949_setjmp() — Set Jump Point for a Nonlocal Goto . . . . . . . . . . . 953setjmp() — Preserve Stack Environment . . . . . . . . . . . . . . 955setlocale() — Set Locale . . . . . . . . . . . . . . . . . . . . 958setnetent() — Open Network Information Data Set . . . . . . . . . . 967setpgid() — Set Process Group ID for Job Control . . . . . . . . . . 968setpgrp() — Set Process Group ID . . . . . . . . . . . . . . . . 970setprotoent() — Open Protocol Information File . . . . . . . . . . . 971setservent() — Open Network Services Information File . . . . . . . . 972setsid() — Create Session, Set Process Group ID . . . . . . . . . . 973setsockopt() — Set Options Associated with a Socket . . . . . . . . . 975setstate() — Change Generator for random() . . . . . . . . . . . . 981setuid() — Set the Effective User ID . . . . . . . . . . . . . . . 982setutxent() — Reset to Start of utmpx Database . . . . . . . . . . . 984setvbuf() — Control Buffering . . . . . . . . . . . . . . . . . . 985shmat() — Attach Shared Memory Segment. . . . . . . . . . . . . 987shmctl() — Shared Memory Control Operations . . . . . . . . . . . 989shmdt() — Detach Shared Memory Segment . . . . . . . . . . . . 991shmget() — Get a Shared Memory Segment . . . . . . . . . . . . 992shutdown() — Shut Down All or Part of a Duplex Connection . . . . . . 994sigaction() — Examine or Change a Signal Action . . . . . . . . . . 996sigaddset() — Add a Signal to the Signal Mask . . . . . . . . . . . 1002sigaltstack() — Set and/or Get Signal Alternate Stack Context . . . . . 1004sigdelset() — Delete a Signal from the Signal Mask . . . . . . . . . 1006sigemptyset() — Initialize a Signal Mask to Exclude All Signals . . . . . 1008sigfillset() — Initialize a Signal Mask to Include All Signals . . . . . . . 1010

Contents xv

sighold() — Add a Signal to a Thread . . . . . . . . . . . . . . 1012sigignore() — Set Disposition to Ignore a Signal . . . . . . . . . . . 1013siginterrupt() — Allow Signals to Interrupt Functions . . . . . . . . . 1014sigismember() — Test If a Signal Is in a Signal Mask . . . . . . . . . 1015siglongjmp() — Restore the Stack Environment and Signal Mask . . . . 1017signal() — Handle Interrupts . . . . . . . . . . . . . . . . . . 1020__signgam() — Return __signgam Reference . . . . . . . . . . . 1025sigpause() — Unblock a Signal and Wait for a Signal . . . . . . . . . 1026sigpending() — Examine Pending Signals . . . . . . . . . . . . . 1027sigprocmask() — Examine or Change a Thread . . . . . . . . . . . 1029sigrelse() — Remove a Signal from a Thread . . . . . . . . . . . . 1032sigset() — Change a Signal Action and/or a Thread . . . . . . . . . 1033sigsetjmp() — Save Stack Environment and Signal Mask . . . . . . . 1036sigstack() — Set and/or Get Signal Stack Context . . . . . . . . . . 1039sigsuspend() — Change Mask and Suspend the Thread. . . . . . . . 1040sigwait() — Wait for an Asynchronous Signal . . . . . . . . . . . . 1043sin() — Calculate Sine . . . . . . . . . . . . . . . . . . . . 1045sinh() — Calculate Hyperbolic Sine . . . . . . . . . . . . . . . 1047sleep() — Suspend Execution of a Process . . . . . . . . . . . . 1049sock_debug() — Provide OE Syscall Tracing Facility . . . . . . . . . 1051sock_debug_bulk_perf0() — Produce a Report When a Socket Configured 1052sock_do_bulkmode() — Use Bulk Mode for Messages Read by Socket 1053sock_do_teststor — Check for Attempt to Access Storage . . . . . . . 1054socket() — Create a Socket . . . . . . . . . . . . . . . . . . 1055spawn() - spawnp() — Spawn a New Process . . . . . . . . . . . 1059sprintf() — Format and Write Data to Buffer . . . . . . . . . . . . 1064sqrt() — Calculate Square Root . . . . . . . . . . . . . . . . . 1065srand() — Set Seed for rand() Function . . . . . . . . . . . . . . 1067srandom() — Use Seed to Initialize Generator for random() . . . . . . 1068srand48() — Initialize Pseudorandom Number . . . . . . . . . . . 1069sscanf() — Read and Format Data from Buffer . . . . . . . . . . . 1071stat() — Get File Information . . . . . . . . . . . . . . . . . . 1072statvfs() — Get File System Information . . . . . . . . . . . . . . 1076strcasecmp() — Compare Case-Insensitive Strings. . . . . . . . . . 1079strcat() — Concatenate Strings . . . . . . . . . . . . . . . . . 1080strchr() — Search for Character . . . . . . . . . . . . . . . . . 1081strcmp() — Compare Strings . . . . . . . . . . . . . . . . . . 1083strcoll() — Compare Strings . . . . . . . . . . . . . . . . . . 1085strcpy() — Copy String . . . . . . . . . . . . . . . . . . . . 1087strcspn() — Compare Strings. . . . . . . . . . . . . . . . . . 1088strdup() — Duplicate a String. . . . . . . . . . . . . . . . . . 1089strerror() — Get Pointer to Runtime Error Message . . . . . . . . . 1090strfmon() — Convert Monetary Value to String . . . . . . . . . . . 1091strftime() — Convert to Formatted Time . . . . . . . . . . . . . . 1095strlen() — Determine String Length . . . . . . . . . . . . . . . 1099strncasecmp() — Compare Case-Insensitive Strings . . . . . . . . . 1100strncat() — Concatenate Strings . . . . . . . . . . . . . . . . 1101strncmp() — Compare Strings . . . . . . . . . . . . . . . . . 1103strncpy() — Copy String . . . . . . . . . . . . . . . . . . . 1105strpbrk() — Find Characters in String . . . . . . . . . . . . . . . 1107strptime() — Date and Time Conversion . . . . . . . . . . . . . . 1108strrchr() — Find Last Occurrence of Character in String . . . . . . . . 1112strspn() — Search String . . . . . . . . . . . . . . . . . . . 1113strstr() — Locate Substring . . . . . . . . . . . . . . . . . . 1114strtocoll() — Return Collating Element for String . . . . . . . . . . . 1115strtod() — Convert Character String to Double . . . . . . . . . . . 1117

xvi XL C/C++ for z/VM: Runtime Library Reference

strtok() — Tokenize String . . . . . . . . . . . . . . . . . . . 1119strtol() — Convert Character String to Long . . . . . . . . . . . . 1121strtoul() — Convert String to Unsigned Integer . . . . . . . . . . . 1123strxfrm() — Transform String . . . . . . . . . . . . . . . . . . 1126swab() — Copy and Swap Bytes . . . . . . . . . . . . . . . . 1128swapcontext() — Save and Restore User Context . . . . . . . . . . 1129swprintf() — Write Wide Characters to a Wide-Character Array . . . . . 1132swscanf() — Read a Wide-Character String . . . . . . . . . . . . 1133symlink() — Create a Symbolic Link to a Path Name . . . . . . . . . 1135sysconf() — Determine System Configuration Options . . . . . . . . 1138system() — Execute a Command . . . . . . . . . . . . . . . . 1141takesocket() — Acquire a Socket from Another Program . . . . . . . . 1144tan() — Calculate Tangent . . . . . . . . . . . . . . . . . . . 1145tanh() — Calculate Hyperbolic Tangent . . . . . . . . . . . . . . 1147tcdrain() — Wait Until Output Has Been Transmitted . . . . . . . . . 1149tcflow() — Suspend or Resume Data Flow on a Terminal . . . . . . . 1150tcflush() — Flush Input or Output on a Terminal . . . . . . . . . . . 1153tcgetattr() — Get the Attributes for a Terminal . . . . . . . . . . . . 1156tcgetpgrp() — Get the Foreground Process Group ID . . . . . . . . . 1158tcperror() — Print Error Messages of a Socket Function . . . . . . . . 1160tcsendbreak() — Send a Break Condition to a Terminal . . . . . . . . 1161tcsetattr() — Set the Attributes for a Terminal . . . . . . . . . . . . 1163tcsetpgrp() — Set the Foreground Process Group ID . . . . . . . . . 1171tdelete() — Delete Binary Tree Node . . . . . . . . . . . . . . . 1173tempnam() — Generate a Temporary File Name. . . . . . . . . . . 1174tfind() — Find Binary Tree Node. . . . . . . . . . . . . . . . . 1175time() — Determine Current Time . . . . . . . . . . . . . . . . 1176times() — Get Process and Child Process Times . . . . . . . . . . 1178tmpfile() — Create Temporary File . . . . . . . . . . . . . . . . 1181tmpnam() — Produce Temporary File Name . . . . . . . . . . . . 1183toascii() — Translate Integer to a 7-Bit ASCII Character . . . . . . . . 1184tolower() - toupper() — Convert Character Case . . . . . . . . . . . 1190towlower() - towupper() — Convert Wide-Character Case . . . . . . . 1191tsearch() — Search Binary Tree . . . . . . . . . . . . . . . . . 1192ttyname() — Get the Name of a Terminal . . . . . . . . . . . . . 1194ttyslot() — Find the Slot in the utmpx File of the Current User . . . . . . 1195twalk() — Walk Binary Tree . . . . . . . . . . . . . . . . . . 1196tzset() — Set the Time Zone . . . . . . . . . . . . . . . . . . 1197umask() — Set or Display the File Mode Creation Mask . . . . . . . . 1200umount() — Remove a Virtual File System. . . . . . . . . . . . . 1202uname() — Display Current Operating System Name . . . . . . . . . 1204ungetc() — Push Character onto Input Stream . . . . . . . . . . . 1206ungetwc() — Push a Wide Character onto a Stream . . . . . . . . . 1208unlink() — Remove a Directory Entry . . . . . . . . . . . . . . . 1210usleep() — Suspend Execution for an Interval . . . . . . . . . . . 1212utime() — Set File Access and Modification Times . . . . . . . . . . 1213utimes() — Set File Access and Modification Times . . . . . . . . . 1215__utmpxname() — Change the utmpx Database Name . . . . . . . . 1217va_arg() - va_end() - va_start() — Access Function Arguments . . . . . 1218valloc() — Allocate Page-Aligned Memory . . . . . . . . . . . . . 1221vfork() — Create a New Process . . . . . . . . . . . . . . . . 1222vfprintf() — Format and Print Data to Stream . . . . . . . . . . . . 1225vprintf() — Format and Print Data to stdout . . . . . . . . . . . . 1227vsprint() — Format and Print Data to Buffer . . . . . . . . . . . . 1229vswprintf() — Write Wide Characters . . . . . . . . . . . . . . . 1231wait() — Wait for a Child Process to End . . . . . . . . . . . . . 1233

Contents xvii

waitid() — Wait for Child Process to Change State . . . . . . . . . . 1236waitpid() — Wait for a Specific Child Process to End . . . . . . . . . 1238wcrtomb() — Convert a Wide Character to a Multibyte Character . . . . 1242wcscat() — Append to Wide-Character String . . . . . . . . . . . . 1244wcschr() — Search for Wide-Character Substring . . . . . . . . . . 1246wcscmp() — Compare Wide-Character Strings . . . . . . . . . . . 1248wcscoll() — Language Collation String Comparison . . . . . . . . . 1250wcscpy() — Copy Wide-Character String . . . . . . . . . . . . . 1252wcscspn() — Find Offset of First Wide-Character Match . . . . . . . . 1254wcsftime() — Format Date and Time . . . . . . . . . . . . . . . 1256wcsid() — Character Set ID for Wide Character . . . . . . . . . . . 1258wcslen() — Calculate Length of Wide-Character String . . . . . . . . 1259wcsncat() — Append to Wide-Character String . . . . . . . . . . . 1260wcsncmp() — Compare Wide-Character Strings . . . . . . . . . . . 1262wcsncpy() — Copy Wide-Character String . . . . . . . . . . . . . 1264wcspbrk() — Locate First Wide Character in String. . . . . . . . . . 1266wcsrchr() — Locate Last Wide Character in String . . . . . . . . . . 1268wcsrtombs() — Convert Wide-Character String to Multibyte String . . . . 1270wcsspn() — Search for Wide Characters in a String . . . . . . . . . 1272wcsstr() — Locate a Wide-Character Sequence . . . . . . . . . . . 1273wcstod() — Convert Wide-Character String to a Double Floating-Point 1275wcstok() — Break a Wide-Character String into Tokens . . . . . . . . 1277wcstol() — Convert a Wide-Character String to a Long Integer . . . . . 1279wcstombs() — Convert a Wide-Character String to Multibyte Character 1281wcstoul() — Convert a Wide-Character String to an Unsigned Long 1283wcswcs() — Locate Wide-Character Substring in Wide Character String 1285wcswidth() — Determine the Display Width of a Wide-Character String 1287wcsxfrm() — Transform a Wide-Character String . . . . . . . . . . 1288wctob() — Convert Wide Character to Byte . . . . . . . . . . . . 1290wctomb() — Convert Wide Character to Multibyte Character . . . . . . 1291wctype() — Obtain Handle for Character Property Classification . . . . . 1293wcwidth() — Determine the Display Width of a Wide Character . . . . . 1294w_getpsent() — Get Process Data. . . . . . . . . . . . . . . . 1296wordexp() — Perform Shell Word Expansions . . . . . . . . . . . 1299wordfree() — Perform Shell Word Expansions . . . . . . . . . . . 1302write() — Write Data on a File or Socket . . . . . . . . . . . . . 1303writev() — Write Data on a Socket from an Array . . . . . . . . . . 1308w_statvfs() — Get File System Status . . . . . . . . . . . . . . 1311y0() - y1() - yn() — Bessel Functions of the Second Kind . . . . . . . 1313Library Functions for the System Programming C Facilities . . . . . . . 1315

Appendix. Table of C Macros . . . . . . . . . . . . . . . . . . 1317

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . 1329Programming Interface Information . . . . . . . . . . . . . . . . 1331Standards . . . . . . . . . . . . . . . . . . . . . . . . . . 1331Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . 1331

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 1333

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 1351IBM XL C/C++ for z/VM Publications . . . . . . . . . . . . . . . . 1351z/OS XL C/C++ Publications . . . . . . . . . . . . . . . . . . . 1351Other IBM C/C++ Publications . . . . . . . . . . . . . . . . . . 1351IBM Debug Tool . . . . . . . . . . . . . . . . . . . . . . . 1351z/VM Publications . . . . . . . . . . . . . . . . . . . . . . . 1351

xviii XL C/C++ for z/VM: Runtime Library Reference

Where to Get z/VM Information . . . . . . . . . . . . . . . . . 1351z/VM Base Library. . . . . . . . . . . . . . . . . . . . . . 1351z/VM Facilities and Features . . . . . . . . . . . . . . . . . . 1352Prerequisite Products . . . . . . . . . . . . . . . . . . . . 1353

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355

Contents xix

xx XL C/C++ for z/VM: Runtime Library Reference

Figures

1. Libraries Comprising Language Environment . . . . . . . . . . . . . . . . . . . . . 52. Overlap of C Standards and Extensions . . . . . . . . . . . . . . . . . . . . . . 613. Program Flow of a Fetchable Module . . . . . . . . . . . . . . . . . . . . . . . 2764. Format Specification for fprintf(), printf(), and sprintf() . . . . . . . . . . . . . . . . . 3295. Syntax of Conversion Specification for fscanf(), scanf(), and sscanf() . . . . . . . . . . . 355

© Copyright IBM Corp. 2002, 2011 xxi

xxii XL C/C++ for z/VM: Runtime Library Reference

Tables

1. IBM XL C/C++ for z/VM Features . . . . . . . . . . . . . . . . . . . . . . . . . 112. Feature Test Macros and Standards . . . . . . . . . . . . . . . . . . . . . . . . 133. Definitions in float.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264. Definitions of Resource Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 295. Elements of the lconv Structure . . . . . . . . . . . . . . . . . . . . . . . . . 306. Symbolic Constants defined in sys/__cpl.h . . . . . . . . . . . . . . . . . . . . . 447. _POSIX_SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468. _OPEN_THREADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479. _XOPEN_SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

10. _XOPEN_SOURCE_EXTENDED 1 . . . . . . . . . . . . . . . . . . . . . . . . 4711. _OE_SOCKETS or _ALL_SOURCE . . . . . . . . . . . . . . . . . . . . . . . . 4712. _XOPEN_SOURCE 500 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713. _OE_SOCKETS or _XOPEN_SOURCE_EXTENDED 1 . . . . . . . . . . . . . . . . 4714. Symbolic Constants defined in xti.h . . . . . . . . . . . . . . . . . . . . . . . . 5515. Built-in Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6116. Codes to Set Baud Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . 12117. Struct f_cnvrt Element Descriptions . . . . . . . . . . . . . . . . . . . . . . . 25818. Elements Returned in fldata_t Data Structure . . . . . . . . . . . . . . . . . . . . 30419. Position Options Parameter for flocate() . . . . . . . . . . . . . . . . . . . . . . 30720. Values for the Positional Parameter . . . . . . . . . . . . . . . . . . . . . . . 31721. Keyword Parameters for File Mode. . . . . . . . . . . . . . . . . . . . . . . . 31922. Flag Characters for fprintf() Family . . . . . . . . . . . . . . . . . . . . . . . . 32923. Precision Argument in fprintf() family . . . . . . . . . . . . . . . . . . . . . . . 33124. Type Characters and their Meanings . . . . . . . . . . . . . . . . . . . . . . . 33225. Conversion Specifiers in fscanf() and scanf() . . . . . . . . . . . . . . . . . . . . 35626. Fields of the tm structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 49827. Characters for which isascii() returns nonzero. . . . . . . . . . . . . . . . . . . . 53928. Elements of the stat Structure . . . . . . . . . . . . . . . . . . . . . . . . . 62129. Control Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82930. Values for Category Arguments of setlocale . . . . . . . . . . . . . . . . . . . . 95831. Return String as Determined by Category and Locale Values . . . . . . . . . . . . . . 96432. Control Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99633. Control Signals Supported Under C only — POSIX(ON) . . . . . . . . . . . . . . . 102034. Control Signals Supported Under C — POSIX(OFF) . . . . . . . . . . . . . . . . . 102235. Values Returned in the stat Structure . . . . . . . . . . . . . . . . . . . . . . 107236. Values Returned in the statvfs Structure . . . . . . . . . . . . . . . . . . . . . 107637. Conversion Specifiers Used by strftime() . . . . . . . . . . . . . . . . . . . . . 109538. Conversion Specifiers Used by strptime() . . . . . . . . . . . . . . . . . . . . . 110839. Modified Directives Used by strptime() . . . . . . . . . . . . . . . . . . . . . . 110940. Variables Stored in Structure . . . . . . . . . . . . . . . . . . . . . . . . . 129641. VM Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1317

© Copyright IBM Corp. 2002, 2011 xxiii

xxiv XL C/C++ for z/VM: Runtime Library Reference

About This Document

This document provides descriptions of the IBM® XL C/C++ language header files,library functions, macros, and built-in functions supported under the z/VM®

operating system and Language Environment®.

Intended AudienceThis information is intended for programmers who want to write C and C++applications on the z/VM platform that conform to ANSI or POSIX standards.

Where to Find More InformationThis document is intended to be used in conjunction with the following documents:

v z/OS® XL C/C++ documents (included in the IBM XL C/C++ for z/VM library)v Other IBM C/C++ programming documents (included in the IBM XL C/C++ for

z/VM library)

v z/VM and z/OS Language Environment documents (included in the z/VM library)v z/VM OpenExtensions documents (included in the z/VM library)v z/VM and z/OS Program Management Binder documents (included in the z/VM

library)

For more information, see “Bibliography” on page 1351.

Links to Other Online DocumentsThe online version of this document contains links to other online documents.These links are to editions that were current when this document waspublished. However, due to the nature of some links, if a new edition of alinked document has been published since the publication of this document,the linked document might not be the latest edition. Also, a link from thisdocument to another document works only when both documents are in thesame directory.

© Copyright IBM Corp. 2002, 2011 xxv

xxvi XL C/C++ for z/VM: Runtime Library Reference

How to Send Your Comments to IBM

We appreciate your input on this publication. Feel free to comment on the clarity,accuracy, and completeness of the information or give us any other feedback thatyou might have.

Use one of the following methods to send us your comments:

1. Send an email to mhvrcfs@us.ibm.com.

2. Go to IBM z/VM Reader's Comments (www.ibm.com/systems/z/os/zvm/zvmforms/webqs.html).

3. Mail the comments to the following address:IBM CorporationAttention: MHVRCFS Reader CommentsDepartment H6MA, Building 7072455 South RoadPoughkeepsie, NY 12601-5400U.S.A.

4. Fax the comments to us as follows:From the United States and Canada: 1+845+432-9405From all other countries: Your international access code +1+845+432-9405

Include the following information:v Your name and addressv Your email addressv Your telephone or fax numberv The publication title and order number:

XL C/C++ for z/VM V1R3 Runtime Library ReferenceSC09-7624-05

v The topic name or page number related to your commentv The text of your comment

When you send comments to IBM, you grant IBM a nonexclusive right to use ordistribute your comments in any way it believes appropriate without incurring anyobligation to you.

IBM or any other organizations will use the personal information that you supplyonly to contact you about the issues that you submit to IBM.

If You Have a Technical ProblemDo not use the feedback methods listed above. Instead, do one of the following:

v Contact your IBM service representative.v Contact IBM technical support.v See IBM: z/VM Service Resources (www.ibm.com/vm/service/).v Go to IBM Support Portal (www.ibm.com/support/entry/portal/Overview/).

© Copyright IBM Corp. 2002, 2011 xxvii

http://www.ibm.com/systems/z/os/zvm/zvmforms/webqs.htmlhttp://www.ibm.com/vm/service/http://www.ibm.com/support/entry/portal/Overview/

xxviii XL C/C++ for z/VM: Runtime Library Reference

Summary of Changes

This book contains terminology, maintenance, and editorial changes. Technicalchanges are indicated by a vertical line to the left of the change.

SC09-7624-05, XL C/C++ for z/VM, Version 1 Release 3This edition supports the general availability of IBM XL C/C++ for z/VM, V1.3, andz/VM V6.2.

Upgraded C/C++ Compiler for z/VMIBM XL C/C++ for z/VM, V1.3, is a z/VM-enabled version of z/OS 1.12 XL C/C++.This new release of the compiler includes support for new compiler options. Formore information, see XL C/C++ for z/VM: User's Guide.

Upgraded Language Environment for z/VMThe runtime libraries included with Language Environment for z/VM, level 620,provided with z/VM V6.2, have been upgraded to the same level shipped with z/OSV1.12 Language Environment.

Upgraded Program Management Binder for CMSThe Program Management Binder for CMS included with z/VM V6.2 has beenupgraded to the same level shipped with z/OS V1.12.

SC09-7624-04, XL C/C++ for z/VM, Version 1 Release 2This edition supports the general availability of IBM XL C/C++ for z/VM, V1.2, andz/VM V5.4.

Upgraded C/C++ Compiler for z/VMIBM XL C/C++ for z/VM, V1.2, is a z/VM-enabled version of z/OS 1.9 XL C/C++. Itis an upgrade to and replacement for IBM C/C++ for z/VM. IBM XL C/C++ for z/VMincludes support for new and enhanced compiler features and options. For moreinformation, see XL C/C++ for z/VM: User's Guide.

Upgraded Language Environment for z/VMThe runtime libraries included with Language Environment for z/VM, level 540,provided with z/VM V5.4, have been upgraded to the same level shipped with z/OSV1.9 Language Environment.

The following are new and corresponding deprecated runtime functions:

v The new function, “dlopen() — Gain Access to a Dynamic Link Library (DLL)” onpage 205, deprecates the existing function, “dllload() — Load the DLL andConnect it to the Application” on page 210.

v The new function, “dlclose() — Close a dlopen() object” on page 202, deprecatesthe existing function, “dllfree() — Free the Supplied DLL” on page 209.

v The new function, “dlerror() — Get Diagnostic Information” on page 204,deprecates the existing function, “dllqueryfn() — Obtain a Pointer to a DLLFunction” on page 211.

© Copyright IBM Corp. 2002, 2011 xxix

v The new function, “dlsym() — Obtain the Address of a Symbol from a dlopen()Object” on page 208, deprecates the existing function, “dllqueryvar() — Obtain aPointer to a DLL Variable” on page 212.

Additional ChangesThe description of “fopen() — Open a File” on page 317 is updated.

Upgraded Program Management Binder for CMSThe Program Management Binder for CMS included with z/VM V5.4 has beenupgraded to the same level shipped with z/OS V1.9.

SC09-7624-03, C/C++ for z/VM Version 1 Release 1.0This edition supports the general availability of z/VM V5.3.

Delete DEVICE and LINK SupportAn additional IOCTL command has been added to allow removal of an interface.

SO-LINGER Socket OptionThe SO-LINGER socket option is now supported for AF-IUCV. The support affectsclose(), getsockopt(), and setsockopt().

xxx XL C/C++ for z/VM: Runtime Library Reference

Chapter 1. About IBM XL C/C++ for z/VM

IBM XL C/C++ for z/VM is the language-centered C/C++ application developmentenvironment on the z/VM platform. It is a z/VM-enabled version of z/OS XL C/C++.

IBM XL C/C++ for z/VM includes:

v C/C++ compiler (referred to as the XL C/C++ compiler)The XL C/C++ compiler can compile both C and C++ programs. The commonfeatures and the specific features of the C compiler function and C++ compilerfunction are described later.

v C/C++ application development utilitiesv Support for the Standard C++ Library and the Standard Template Library that are

available with the base z/VM operating system.

You will also need the XL C/C++ runtime library to compile and run your C and C++applications. The XL C/C++ runtime library is packaged with LanguageEnvironment.

XL C/C++ CompilerThe following sections describe the C and C++ language and the XL C/C++compiler.

The C LanguageThe C language is a general purpose, function-oriented programming language thatallows a programmer to create applications quickly and easily. C provides high-levelcontrol statements and data types as do other structured programming languages,and it also provides many of the benefits of a low-level language. Using the Clanguage, you can write portable code conforming to the following standards: ANSIor POSIX.

IBM offers the C language on other platforms, such as the AIX®, OS/400®,VSE/ESA, OS/390®, and z/OS operating systems.

The C++ LanguageThe C++ language is based on the C language and includes all of the advantagesof C previously listed. In addition, C++ also supports object-oriented concepts, typegenericity or templates, and an extensive library. For a detailed description of thedifferences between C and C++, see z/OS: XL C/C++ Language Reference.

The C++ language introduces classes, which are user-defined data types that maycontain data definitions and function definitions. You can use classes fromestablished class libraries, develop your own classes, or derive new classes fromexisting classes by adding data descriptions and functions. New classes can inheritproperties from one or more classes. Not only do classes describe the data typesand functions available, but they can also hide (encapsulate) the implementationdetails from user programs. An object is an instance of a class.

The C++ language also provides templates and other features that include accesscontrol to data and functions, and better type checking and exception handling. Italso supports polymorphism and the overloading of operators.

© Copyright IBM Corp. 2002, 2011 1

Common Features of the C Compiler and C++ Compiler FunctionsThe C compiler and C++ compiler functions of the XL C/C++ compiler, when usedwith Language Environment, provide you with features such as the following:

v Optimization support:– Algorithms to take advantage of S/390® architecture to get better optimization

for speed and use of computer resources through the OPTIMIZE compileroption.

– The OPTIMIZE compiler option, which instructs the compiler to optimize themachine instructions it generates to produce faster-running object code, whichimproves application performance at run time.

v DLLs (Dynamic Link Libraries) to share parts among applications or parts ofapplications, and dynamically link to exported varaibles and functions at run time.

DLLs allow a function reference or a variable reference in one executable to usea definition located in another executable at run time. You can use bothload-on-reference and load-on-demand DLLs. When your program refers to afunction or variable that resides in a DLL, XL C/C++ generates code to load theDLL and access the functions and variables within it. This is calledload-on-reference. Alternatively, your program can use C library functions to loada DLL and look up the address of functions and variables within it. This is calledload-on-demand. Your application explicitly controlls load-on-demand DLLs at thesource level.

You can use DLLs to split applications into smaller modules and improve systemmemory usage. DLLs also offer more flexibility for building, packaging, andredistributing applications.

v Full program reentrancy.With reentrancy, many users can simultaneously run a program. A reentrantprogram saved in a shared segment and run by multiple users endedsimultaneously uses less storage. It also reduces processor I/O when theprogram starts up, and improves program performance by reducing the transferof data to auxiliary storage. Programmers using the C compiler function of the XLC/C++ compiler can design programs that are naturally reentrant. For thoseprograms that are not naturally reentrant, C programmers can use constructedreentrancy by compiling them with the RENT option and using the LanguageEnvironment prelinker and program management binder to make them reentrant.The C++ compiler function of the XL C/C++ compiler always ensures that C++programs are reentrant.

v INLINE compiler optionAdditional optimization capabilities are available with the INLINE compiler option.

v Locale-based internationalization support defined in ISO/IEC DIS9945-2:1922/IEEE POSIX 1003.2-1992, Draft 12.

v The ability to call and be called by other languages such as assembler, COBOL,and PL/1, to enable programmers to integrate z/OS C/C++ code with existingapplications.

v Support for the following standards at the system level:– A subset of extended multibyte and wide character functions as defined by the

Programming Language C Amendment 1. This is ISO/IEC9899:1990/Amendment 1:1994(E)

– ISO/IEC 9945-1:1990(E)/IEEE POSIX 1003.1-1990, with the exception of thefork() function, which is not fully compliant with the standard.

– A subset of IEEE POSIX 1003.1a, Draft 6, July 1991

– IEEE Portable Operating System Interface (POSIX) Part 2, P1003.2, Draft 12

2 XL C/C++ for z/VM: Runtime Library Reference

– A subset of IEEE POSIX 1003.1c, Draft 6, February 1992 (Former name:POSIX 1003.4a)

– A subset of X/Open CAE Specification, System Interfaces and Headers, Issue4 Version 2

– A subset of IEEE 754-1985 (R1990) IEEE Standard for Binary Floating-PointArithmetic (ANSI), as applicable to the S/390 environment.

– A subset of X/Open CAE Specification, Network Services, Issue 4

v Year 2000 supportv Support for the Euro currency

Specific Features of the z/VM C Compiler FunctionIn addition to the features common to the C and C++ compiler functions of the XLC/C++ compiler, the C compiler function provides you with the following capabilities:

v The ability to write portable code that supports the following standards:– All elements of the joint ISO and IEC standard: ISO/IEC 9899:1990 (E)

– ANSI/ISO-IEC 9899:1990[1992](formerly ANSI X3J11.159–1989 C)

– X/Open Specification Programming Language Issue 3, Common Usage C

– FIPS-151

v Extensions of the standard C language definitions to provide programmers withsupport for the z/VM environment, such as fixed-point (packed) decimal datasupport.

Specific Features of the z/VM C++ Compiler FunctionIn addition to the features common to the C and C++ compiler functions of the XLC/C++ compiler, the C++ compiler function supports the International Standard forthe C++ Programming Language (ISO/IEC 14882:1998) specification.

IBM XL C/C++ for z/VM Runtime LibraryWhen compiling and running your C or C++ application, you need to be aware ofthe following conditions:

v If you have an existing C application that contains only C coding and you need torecompile, you can use the IBM C for VM/ESA® compiler, the IBM C/C++ forz/VM compiler, or the IBM XL C/C++ for z/VM compiler:

– If you use the IBM C for VM/ESA compiler, you can use the IBM C forVM/ESA runtime library, the IBM C/C++ for z/VM runtime library, or the IBMXL C/C++ for z/VM runtime library.

– If you use the C/C++ for z/VM compiler, you can use the IBM C/C++ for z/VMruntime library or the IBM XL C/C++ for z/VM runtime library.

– If you use the IBM XL C/C++ for z/VM compiler, you must use the IBM XLC/C++ for z/VM runtime library.

v If you have an existing C++ application and you need to recompile, you shoulduse the IBM XL C/C++ for z/VM compiler and the IBM XL C/C++ for z/VMruntime library.

v If you are writing a new C or C++ application, you should use the IBM XL C/C++for z/VM compiler and the IBM XL C/C++ for z/VM runtime library.

Class LibrariesIBM XL C/C++ for z/VM provides the following class library, which is thread-safe:

Chapter 1. About IBM XL C/C++ for z/VM 3

v C++ Standard Library, including the Standard Template Library (STL) and otherlibrary features of ISO C++ 1998

The C++ Standard Library includes the following:

v The C++ Standard I/O Stream Library for performing input and output (I/O)operations

v The C++ Standard Complex Mathematics Library for manipulating complexnumbers

v The Standard Template Library (STL), which is composed of C++ template-basedalgorithms, container classes, iterators, localization objects, and the string class.

See z/OS: XL C/C++ Compiler and Run-Time Migration Guide for the ApplicationProgrammer for more details on the components of this library.

UtilitiesThe IBM XL C/C++ for z/VM compiler provides the following utilities:

v The CXXFILT utility to map C++ mangled names to the original source.v The DSECT Conversion utility to convert descriptive assembler DSECTs into IBM

XL C/C++ for z/VM data structures.

v The localedef utility to read the locale definition file and produce a locale objectthat the locale-specific library functions can use.

Language Environment provides:

v The Object Library Utility (C370LIB), which updates C/370™ CMS text libraries.C370LIB must be used to update a TXTLIB with TEXT files produced bycompiling C programs with the LONGNAME option. (The CMS TXTLIB commandmay not be used to do this directly, and an error can result if this is attempted.)

v The prelinker that combines object modules that comprise an IBM XL C/C++ forz/VM application, to produce a single object module.

Language EnvironmentIBM XL C/C++ for z/VM exploits the runtime library and common library of baseroutines available with z/VM and the C/C++ Language Environment for z/VM(referred to as Language Environment.) The C/C++ Language Environment forz/VM is based on z/OS Language Environment.

The following libraries are provided with Language Environment product. LanguageEnvironment establishes a common runtime environment and common runtimeservices for language products, user programs, and other products.

4 XL C/C++ for z/VM: Runtime Library Reference

The common execution environment is made up of data items and servicesperformed by library routines available to a particular application running in theenvironment. The services that Language Environment provides to your applicationmay include:

v Services that satisfy basic requirements common to most applications. Theseinclude support for the initialization and termination of applications, allocation ofstorage, and inter-language communication (ILC) and condition handling.

v Extended services often needed by applications. These functions are containedwithin a library of callable routines and include interfaces to operating systemfunctions and a variety of other commonly used functions.

v Runtime options that help the execution, performance tuning, performance, anddiagnosis of your application.

v Access to operating system services—OpenExtensions services are available toan application programmer or program through the IBM XL C/C++ for z/VMlanguage bindings.

v Access to language-specific library routines, such as the IBM XL C/C++ for z/VMfunctions.

About Prelinking, Linking, and Binding

Note: The prelinker is supported only for IBM C for VM/ESA. It is not supported forIBM XL C/C++ for z/VM.

When describing the process to build an application, this document refers to thebind step.

Normally the Program Management Binder is used to perform the bind step.However, in many cases the prelink and link steps can be used in place of the bindstep. When they cannot be substituted, and the Program Management binder alonemust be used, it will be stated. For more information on the bind, prelink, and linksteps, see XL C/C++ for z/VM: User's Guide.

The terms bind and link have multiple meanings.

v With respect to building an application:In both instances, the Program Management Binder is performing the actualprocessing of converting the object file(s) into the application executable module.

Figure 1. Libraries Comprising Language Environment

Chapter 1. About IBM XL C/C++ for z/VM 5

Object files with longname symbols, reentrant writable static symbols, andDLL-style function calls require additional processing to build global data for theapplication.

The term link refers to the case where the binder does not perform this addtionalprocessing due to one of the following:

– The processing is not required because none of the object files in theapplication use constructed reentrancy, use long names, are DLL, or are C++.

– The processing is handled by executing the prelinker step before running thebinder.

v With respect to executing code in an application:The linkage definition refers to the program call linkage between programfunctions and methods. This includes the passing of control and parameters. Seez/OS: XL C/C++ Language Reference