z/OS

UNIX System ServicesProgramming: Assembler Callable ServicesReferenceVersion 2 Release 3

SA23-2281-30

IBM

NoteBefore using this information and the product it supports, read the information in Notices on page 1369.

This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modificationsuntil otherwise indicated in new editions.

Last updated: July 17, 2017

Copyright IBM Corporation 1996, 2017.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . xv

Tables . . . . . . . . . . . . . . xvii

About this document . . . . . . . . xixWho should use this document . . . . . . . xixz/OS information . . . . . . . . . . . . xix

z/OS UNIX courses . . . . . . . . . . xixz/OS UNIX home page . . . . . . . . . xxDiscussion list . . . . . . . . . . . . xx

How to send your comments to IBM xxiIf you have a technical problem . . . . . . . xxi

Summary of changes. . . . . . . . xxiiiSummary of changes for z/OS UNIX for Version 2Release 3 (V2R3) . . . . . . . . . . . . xxiiiSummary of changes for z/OS UNIX for Version 2Release 2 (V2R2) . . . . . . . . . . . . xxivSummary of changes for z/OS UNIX for Version 2Release 1 (V2R1) as updated February, 2015 . . . xxviz/OS Version 2 Release 1 summary of changes xxvi

Chapter 1. Invocation details for callableservices. . . . . . . . . . . . . . . 1Connecting to and disconnecting from z/OS UNIX . 1Syntax conventions for the callable services . . . . 1

CALL. . . . . . . . . . . . . . . . 2Service_name . . . . . . . . . . . . . 2Parm parameters . . . . . . . . . . . . 2Return_value . . . . . . . . . . . . . 2Return_code . . . . . . . . . . . . . 3Reason_code . . . . . . . . . . . . . 3

Determining the callable service release level . . . 4Linkage conventions for the callable services . . . 4Parameter descriptions for the callable services . . . 4

Call parameter lists . . . . . . . . . . . 5Mapping macros . . . . . . . . . . . . . 5Examples . . . . . . . . . . . . . . . 5

Reentrant coding versus nonreentrant coding . . 6Environmental restrictions . . . . . . . . . . 6Restrictions in a multiprocess, multiuser environment 7Abend conditions and environments . . . . . . 7Callable service failures. . . . . . . . . . . 8Authorization . . . . . . . . . . . . . . 8Using callable services in a 64-bit environment . . . 9

Call parameter lists . . . . . . . . . . . 9Parameters . . . . . . . . . . . . . 10System control offsets . . . . . . . . . . 13Support for multiple AMODES in a singleprocess . . . . . . . . . . . . . . . 13Support for SRB callers . . . . . . . . . 14

Chapter 2. Callable servicesdescriptions . . . . . . . . . . . . 15accept (BPX1ACP, BPX4ACP) Accept aconnection request from a client socket . . . . . 15accept_and_recv (BPX1ANR, BPX4ANR) Accept aconnection and receive the first block of data . . . 18access (BPX1ACC, BPX4ACC) Determine if a filecan be accessed . . . . . . . . . . . . . 23aio_suspend (BPX1ASP, BPX4ASP) Wait for anasynchronous I/O request . . . . . . . . . 26alarm (BPX1ALR, BPX4ALR) Set an alarm . . . 29asyncio (BPX1AIO, BPX4AIO) Asynchronous I/Ofor sockets . . . . . . . . . . . . . . . 31attach_exec (BPX1ATX, BPX4ATX) Attach a z/OSUNIX program . . . . . . . . . . . . . 50attach_execmvs (BPX1ATM, BPX4ATM) Attachan MVS program . . . . . . . . . . . . 60auth_check_resource_np (BPX1ACK, BPX4ACK) Determine a user's access to a RACF-protectedresource . . . . . . . . . . . . . . . 67bind (BPX1BND, BPX4BND) Bind a unique localname to a socket descriptor . . . . . . . . . 72bind2addrsel (BPX1BAS, BPX4BAS) Bind thesocket descriptor to the best source address . . . 74chattr (BPX1CHR, BPX4CHR) Change theattributes of a file or directory . . . . . . . . 77chaudit (BPX1CHA, BPX4CHA) Change auditflags for a file by path . . . . . . . . . . . 86chdir (BPX1CHD, BPX4CHD) Change theworking directory . . . . . . . . . . . . 89chmod (BPX1CHM, BPX4CHM) Change themode of a file or directory . . . . . . . . . 92chown (BPX1CHO, BPX4CHO) Change theowner or group of a file or directory . . . . . . 95chpriority (BPX1CHP, BPX4CHP) Change thescheduling priority of a process . . . . . . . 98chroot (BPX1CRT, BPX4CRT) Change the rootdirectory . . . . . . . . . . . . . . . 102close (BPX1CLO, BPX4CLO) Close a file . . . 105closedir (BPX1CLD, BPX4CLD) Close a directory 107cond_cancel (BPX1CCA, BPX4CCA) Cancelinterest in events . . . . . . . . . . . . 109cond_post (BPX1CPO, BPX4CPO) Post a threadfor an event . . . . . . . . . . . . . . 111cond_setup (BPX1CSE, BPX4CSE) Set up toreceive event notifications . . . . . . . . . 113cond_timed_wait (BPX1CTW, BPX4CTW) Suspend a thread for a limited time or an event . . 116cond_wait (BPX1CWA, BPX4CWA) Suspend athread for an event . . . . . . . . . . . 120connect (BPX1CON, BPX4CON) Establish aconnection between two sockets . . . . . . . 123__console() (BPX1CCS, BPX4CCS) Communicatewith console (modify/stop/WTO/DOM) . . . . 126__cpl (BPX1CPL) CPL interface service . . . . 130

Copyright IBM Corp. 1996, 2017 iii

deletehfs (BPX1DEL, BPX4DEL) Delete aprogram from storage . . . . . . . . . . 133exec (BPX1EXC, BPX4EXC) Run a program . . 135execmvs (BPX1EXM, BPX4EXM) Run an MVSprogram . . . . . . . . . . . . . . . 148_exit (BPX1EXI, BPX4EXI) End a process andbypass the cleanup . . . . . . . . . . . 154extlink_np (BPX1EXT, BPX4EXT) Create anexternal symbolic link . . . . . . . . . . 157fchattr (BPX1FCR, BPX4FCR) Change theattributes of a file or directory by descriptor . . . 160fchaudit (BPX1FCA, BPX4FCA) Change auditflags for a file by descriptor . . . . . . . . 167fchdir (BPX1FCD, BPX4FCD) Change theworking directory . . . . . . . . . . . . 170fchmod (BPX1FCM, BPX4FCM) Change themode of a file or directory by descriptor . . . . 172fchown (BPX1FCO, BPX4FCO) Change theowner and group of a file or directory bydescriptor . . . . . . . . . . . . . . 175fcntl (BPX1FCT, BPX4FCT) Control open filedescriptors . . . . . . . . . . . . . . 177fork (BPX1FRK, BPX4FRK) Create a new process 188fpathconf (BPX1FPC, BPX4FPC) Determineconfigurable path name variables using adescriptor . . . . . . . . . . . . . . 194freeaddrinfo (BPX1FAI, BPX4FAI) FreeAddr_Info structures . . . . . . . . . . . 198fstat (BPX1FST, BPX4FST) Get statusinformation about a file by descriptor . . . . . 200fstatvfs (BPX1FTV, BPX4FTV) Get the file systemstatus . . . . . . . . . . . . . . . . 202fsync (BPX1FSY, BPX4FSY) Write changes topermanent storage. . . . . . . . . . . . 205ftruncate (BPX1FTR, BPX4FTR) Change the sizeof a file . . . . . . . . . . . . . . . 207getaddrinfo (BPX1GAI, BPX4GAI) Get the IPaddress and information for a service name orlocation . . . . . . . . . . . . . . . 209getclientid (BPX1GCL, BPX4GCL) Obtain thecalling program's identifier . . . . . . . . . 217getcwd (BPX1GCW, BPX4GCW) Get the pathname of the working directory . . . . . . . 219getegid (BPX1GEG, BPX4GEG) Get the effectivegroup ID . . . . . . . . . . . . . . . 222geteuid (BPX1GEU, BPX4GEU) Get the effectiveuser ID . . . . . . . . . . . . . . . 223getgid (BPX1GID, BPX4GID) Get the real groupID . . . . . . . . . . . . . . . . . 224getgrent (BPX1GGE, BPX4GGE) Sequentiallyaccess the group database . . . . . . . . . 225getgrgid (BPX1GGI, BPX4GGI) Access the groupdatabase by ID . . . . . . . . . . . . . 227getgrnam (BPX1GGN, BPX4GGN) Access thegroup database by name . . . . . . . . . 230getgroups (BPX1GGR, BPX4GGR) Get a list ofsupplementary group IDs . . . . . . . . . 233getgroupsbyname (BPX1GUG, BPX4GUG) Get alist of supplementary group IDs by user name . . 236

gethostbyaddr (BPX1GHA, BPX4GHA) Get the IPaddress and alias of a host name for the specifiedIP address . . . . . . . . . . . . . . 239gethostbyname (BPX1GHN, BPX4GHN) Get IPinformation for specified host domain names. . . 242gethostid or gethostname (BPX1HST, BPX4HST) Get ID or name information about a socket host. . 245getitimer (BPX1GTR, BPX4GTR) Get the valueof the interval timer . . . . . . . . . . . 247getlogin (BPX1GLG, BPX4GLG) Get the userlogin name . . . . . . . . . . . . . . 249getpeername or getsockname (BPX1GNM,BPX4GNM) Get the name of a socket or of thepeer connected to a socket . . . . . . . . . 251getnameinfo (BPX1GNI, BPX4GNI) Get the hostname and service name from a socket address . . 251getpgid (BPX1GEP, BPX4GEP) Get the processgroup ID . . . . . . . . . . . . . . . 255getpgrp (BPX1GPG, BPX4GPG) Get the processgroup ID . . . . . . . . . . . . . . . 257getpid (BPX1GPI, BPX4GPI) Get the process ID 258getppid (BPX1GPP, BPX4GPP) Get the parentprocess ID . . . . . . . . . . . . . . 259getpriority (BPX1GPY, BPX4GPY) Get thescheduling priority of a process . . . . . . . 260getpwent (BPX1GPE, BPX4GPE) Sequentiallyaccess the user database . . . . . . . . . . 263getpwnam (BPX1GPN, BPX4GPN) Access theuser database by user name . . . . . . . . 265getpwuid (BPX1GPU, BPX4GPU) Access theuser database by user ID . . . . . . . . . 268getrlimit (BPX1GRL, BPX4GRL) Get resourcelimits . . . . . . . . . . . . . . . . 271getrusage (BPX1GRU, BPX4GRU) Get resourceusage . . . . . . . . . . . . . . . . 273getsid (BPX1GES, BPX4GES) Get the processgroup ID of the session leader . . . . . . . . 275getsockname or getpeername (BPX1GNM,BPX4GNM) - Get the name of a socket orconnected peer . . . . . . . . . . . . . 277getsockopt or setsockopt (BPX1OPT, BPX4OPT) Get or set options associated with a socket . . . 280__getthent (BPX1GTH, BPX4GTH) Get threaddata . . . . . . . . . . . . . . . . 284getuid (BPX1GUI, BPX4GUI) Get the real userID . . . . . . . . . . . . . . . . . 288getwd (BPX1GWD, BPX4GWD) Get the pathname of the working directory . . . . . . . 289givesocket (BPX1GIV, BPX4GIV) Give a socketto another program . . . . . . . . . . . 291grantpt (BPX1GPT, BPX4GPT) Grant access tothe slave pseudoterminal . . . . . . . . . 295IPCSDumpOpenClose (BPXGMCDE, BPXGMCD4) MVS IPCS dump open/close service . . . . 297IPCSDumpAccess (BPXGMPTR, BPXGMPT4) PTRACE IPCS dump access service . . . . . . 302isatty (BPX1ITY) (POSIX Version) Determinewhether a file descriptor represents a terminal . . 307isatty (BPX2ITY, BPX4ITY) (X/Open Version) Determine whether a file descriptor represents aterminal . . . . . . . . . . . . . . . 309

iv z/OS UNIX System Services Programming: Assembler Callable Services Reference

kill (BPX1KIL, BPX4KIL) Send a signal to aprocess . . . . . . . . . . . . . . . 310__login, __login__applid, __certificate (BPX1SEC,BPX4SEC) Provides an interface to the securityproduct . . . . . . . . . . . . . . . 315lchattr (BPX1LCR, BPX4LCR) Change theattributes of a file or directory or symbolic link . . 322lchown (BPX1LCO, BPX4LCO) Change theowner or group of a file, directory, or symbolic link 330link (BPX1LNK, BPX4LNK) Create a link to afile . . . . . . . . . . . . . . . . . 333listen (BPX1LSN, BPX4LSN) Prepare a serversocket to queue incoming connection requests fromclients . . . . . . . . . . . . . . . . 337loadhfs (BPX1LOD, BPX4LOD) Load a programinto storage by path name . . . . . . . . . 339loadHFS extended (BPX1LDX, BPX4LDX) Directthe loading of an executable into storage . . . . 345lseek (BPX1LSK, BPX4LSK) Change a file's offset 353lstat (BPX1LST, BPX4LST) Get statusinformation about a file or symbolic link by pathname . . . . . . . . . . . . . . . . 356__map_init (BPX1MMI, BPX4MMI) Create amapped megabyte area . . . . . . . . . . 359__map_service (BPX1MMS, BPX4MMS) Mappedmegabyte area services . . . . . . . . . . 363mkdir (BPX1MKD, BPX4MKD) Make a directory 368mknod (BPX1MKN, BPX4MKN) Make adirectory, a FIFO, a character special, or a regularfile . . . . . . . . . . . . . . . . . 371mmap (BPX1MMP, BPX4MMP) Map pages ofmemory . . . . . . . . . . . . . . . 375mount (BPX1MNT) Make a file system available 384__mount (BPX2MNT, BPX4MNT) Make a filesystem available . . . . . . . . . . . . 388mprotect (BPX1MPR, BPX4MPR) Set protectionof memory mapping . . . . . . . . . . . 392msgctl (BPX1QCT, BPX4QCT) Perform messagequeue control operations . . . . . . . . . 395msgget (BPX1QGT, BPX4QGT) Create or find amessage queue . . . . . . . . . . . . . 399msgrcv (BPX1QRC, BPX4QRC) Receive from amessage queue . . . . . . . . . . . . . 403msgsnd (BPX1QSN, BPX4QSN) Send to amessage queue . . . . . . . . . . . . . 407msync (BPX1MSY, BPX4MSY) Synchronizememory with physical storage. . . . . . . . 410munmap (BPX1MUN, BPX4MUN) Unmappreviously mapped addresses . . . . . . . . 414mvsiptaffinity (BPX1IPT, BPX4IPT) Run aprogram on the IPT thread . . . . . . . . . 418mvspause (BPX1MP, BPX4MP) Wait on userevents plus signals . . . . . . . . . . . 421mvspauseinit (BPX1MPI, BPX4MPI) Set up towait on user events plus signals . . . . . . . 423mvsprocclp (BPX1MPC, BPX4MPC) Clean upkernel resources . . . . . . . . . . . . 426mvssigsetup (BPX1MSS, BPX4MSS) Set up MVSsignals. . . . . . . . . . . . . . . . 429MVSThreadAffinity (BPX1TAF, BPX4TAF) MVSthread affinity service . . . . . . . . . . 434

mvsunsigsetup (BPX1MSD, BPX4MSD) Detachthe signal setup . . . . . . . . . . . . 438nice (BPX1NIC, BPX4NIC) Change the nicevalue of a process . . . . . . . . . . . . 440oe_env_np (BPX1ENV, BPX4ENV) Examine,change, or examine and change an environmentalattribute . . . . . . . . . . . . . . . 442open (BPX1OPN, BPX4OPN) Open a file . . . 454opendir (BPX1OPD, BPX4OPD) Open adirectory . . . . . . . . . . . . . . . 460openstat (BPX2OPN, BPX4OPS) Open a file andobtain status information . . . . . . . . . 462__passwd, __passwd__applid (BPX1PWD,BPX4PWD) Verify or change securityinformation . . . . . . . . . . . . . . 467pathconf (BPX1PCF, BPX4PCF) Determineconfigurable path name variables using a pathname . . . . . . . . . . . . . . . . 472pause (BPX1PAS, BPX4PAS) Suspend a processpending a signal . . . . . . . . . . . . 476pfsctl (BPX1PCT, BPX4PCT) Physical file systemcontrol . . . . . . . . . . . . . . . 478__pid_affinity (BPX1PAF, BPX4PAF) Add ordelete an entry in a process's affinity list . . . . 486pipe (BPX1PIP, BPX4PIP) Create an unnamedpipe . . . . . . . . . . . . . . . . 489__poe() (BPX1POE, BPX4POE) Port of entryinformation . . . . . . . . . . . . . . 491poll (BPX1POL, BPX4POL) Monitor activity onfile descriptors and message queues . . . . . . 497Pread() and Pwrite() (BPX1RW, BPX4RW) Readfrom or write to a file without changing the filepointer . . . . . . . . . . . . . . . 501pthread_cancel (BPX1PTB, BPX4PTB) Cancel athread . . . . . . . . . . . . . . . . 503pthread_create (BPX1PTC, BPX4PTC) Create athread . . . . . . . . . . . . . . . . 506pthread_detach (BPX1PTD, BPX4PTD) Detach athread . . . . . . . . . . . . . . . . 512pthread_exit_and_get (BPX1PTX, BPX4PTX) Exitand get a new thread. . . . . . . . . . . 514pthread_join (BPX1PTJ, BPX4PTJ) Wait on athread . . . . . . . . . . . . . . . . 518pthread_kill (BPX1PTK, BPX4PTK) Send a signalto a thread . . . . . . . . . . . . . . 521pthread_quiesce (BPX1PTQ, BPX4PTQ) Quiescethreads in a process . . . . . . . . . . . 524pthread_security_np, pthread_security_applid_np(BPX1TLS, BPX4TLS) Create or deletethread-level security . . . . . . . . . . . 527pthread_self (BPX1PTS, BPX4PTS) Query thethread ID. . . . . . . . . . . . . . . 536pthread_setintr (BPX1PSI, BPX4PSI) Examineand change the interrupt state . . . . . . . . 537pthread_setintrtype (BPX1PST, BPX4PST) Examine and change the interrupt type. . . . . 540pthread_tag_np (BPX1PTT, BPX4PTT) Set, query,or both set and query the caller's thread tag data . 542pthread_testintr (BPX1PTI, BPX4PTI) Cause acancellation point to occur . . . . . . . . . 545

Contents v

ptrace (BPX1PTR, BPX4PTR) Control anotherprocess for debugging . . . . . . . . . . 547querydub (BPX1QDB, BPX4QDB) Obtain thedub status of the current task . . . . . . . . 574queue_interrupt (BPX1SPB, BPX4SPB) Returnthe last interrupt delivered . . . . . . . . . 576quiesce (BPX1QSE, BPX4QSE) Quiesce a filesystem . . . . . . . . . . . . . . . 578read (BPX1RED, BPX4RED) Read from a file orsocket . . . . . . . . . . . . . . . . 580readdir (BPX1RDD, BPX4RDD) Read an entryfrom a directory . . . . . . . . . . . . 585readdir2 (BPX1RD2, BPX4RD2) Read an entryfrom a directory . . . . . . . . . . . . 588read_extlink (BPX1RDX, BPX4RDX) Read anexternal symbolic link . . . . . . . . . . 592readlink (BPX1RDL, BPX4RDL) Read the valueof a symbolic link . . . . . . . . . . . . 595readv (BPX1RDV, BPX4RDV) Read data andstore it in a set of buffers . . . . . . . . . 598realpath (BPX1RPH, BPX4RPH) Resolve a pathname . . . . . . . . . . . . . . . . 602recv (BPX1RCV, BPX4RCV) Receive data on asocket and store it in a buffer . . . . . . . . 606recvfrom (BPX1RFM, BPX4RFM) Receive datafrom a socket and store it in a buffer . . . . . 609recvmsg (BPX2RMS, BPX4RMS) Receivemessages on a socket and store them in messagebuffers . . . . . . . . . . . . . . . 612rename (BPX1REN, BPX4REN) Rename a file ordirectory . . . . . . . . . . . . . . . 616resource (BPX1RMG, BPX4RMG) Measureresources . . . . . . . . . . . . . . . 620rewinddir (BPX1RWD, BPX4RWD) Reposition adirectory stream to the beginning. . . . . . . 622rmdir (BPX1RMD, BPX4RMD) Remove adirectory . . . . . . . . . . . . . . . 624select/selectex (BPX1SEL, BPX4SEL) Select onfile descriptors and message queues . . . . . . 627semctl (BPX1SCT, BPX4SCT) Perform semaphorecontrol operations . . . . . . . . . . . . 635semget (BPX1SGT, BPX4SGT) Create or find aset of semaphores . . . . . . . . . . . . 641semop (BPX1SOP, BPX4SOP) Performsemaphore serialization operations . . . . . . 645send (BPX1SND, BPX4SND) Send data on asocket . . . . . . . . . . . . . . . . 649send_file (BPX1SF, BPX4SF) Send a file on asocket . . . . . . . . . . . . . . . . 653sendmsg (BPX2SMS, BPX4SMS) Send messageson a socket . . . . . . . . . . . . . . 658sendto (BPX1STO, BPX4STO) Send data on asocket . . . . . . . . . . . . . . . . 661server_init (BPX1SIN, BPX4SIN) Serverinitialization . . . . . . . . . . . . . . 665server_pwu (BPX1SPW, BPX4SPW) Serverprocess work unit . . . . . . . . . . . . 669set_dub_default (BPX1SDD, BPX4SDD) Set thedub default service . . . . . . . . . . . 676setegid (BPX1SEG, BPX4SEG) Set the effectivegroup ID . . . . . . . . . . . . . . . 680

seteuid (BPX1SEU, BPX4SEU) Set the effectiveuser ID . . . . . . . . . . . . . . . 682setgid (BPX1SGI, BPX4SGI) Set the group ID 684setgrent (BPX1SGE, BPX4SGE) Reset the groupdatabase . . . . . . . . . . . . . . . 687setgroups (BPX1SGR, BPX4SGR) Set thesupplementary group IDs list . . . . . . . . 688setitimer (BPX1STR, BPX4STR) Set the value ofthe iterval timer . . . . . . . . . . . . 690setpeer (BPX1SPR, BPX4SPR) Preset the peeraddress associated with a socket . . . . . . . 694setpgid (BPX1SPG, BPX4SPG) Set a processgroup ID for job control . . . . . . . . . . 696setpriority (BPX1SPY, BPX4SPY) Set thescheduling priority of a process . . . . . . . 698setpwent (BPX1SPE, BPX4SPE) Reset the userdatabase . . . . . . . . . . . . . . . 702setregid (BPX1SRG, BPX4SRG) Set the realand/or effective GIDs . . . . . . . . . . 703setreuid (BPX1SRU, BPX4SRU) Set the real andeffective UIDs . . . . . . . . . . . . . 705setrlimit (BPX1SRL, BPX4SRL) Set resourcelimits . . . . . . . . . . . . . . . . 708setsid (BPX1SSI, BPX4SSI) Create a session andset the process group ID. . . . . . . . . . 713setsockopt or getsockopt (BPX1OPT, BPX4OPT) Get or set options associated with a socket . . . 714set_thread_limits (BPX1STL, BPX4STL) Changetask or thread limits for pthread_created threads . 715set_timer_event (BPX1STE, BPX4STE) SetDIE-mode timer event . . . . . . . . . . 718setuid (BPX1SUI, BPX4SUI) Set user IDs . . . 720shmat (BPX1MAT, BPX4MAT) Attach to ashared memory segment . . . . . . . . . 725shmctl (BPX1MCT, BPX4MCT) Perform sharedmemory control operations . . . . . . . . . 729shmdt (BPX1MDT, BPX4MDT) Detach a sharedmemory segment . . . . . . . . . . . . 733shmem_lock (BPX1SLK, BPX4SLK) Sharedmemory lock service . . . . . . . . . . . 735shmem_mutex_condvar (BPX1SMC, BPX4SMC) Shared mutex and condition variable service . . . 740shmget (BPX1MGT, BPX4MGT) Create/find ashared memory segment . . . . . . . . . 749shutdown (BPX1SHT, BPX4SHT) Shut down allor part of a duplex socket connection . . . . . 755sigaction (BPX1SIA, BPX4SIA) Examine orchange a signal action . . . . . . . . . . 757__sigactionset (BPX1SA2, BPX4SA2) Examine orchange a set of signal actions . . . . . . . . 762sigpending (BPX1SIP, BPX4SIP) Examinepending signals . . . . . . . . . . . . 767sigprocmask (BPX1SPM, BPX4SPM) Examine orchange a process's signal mask . . . . . . . 768sigqueue (BPX1SGQ, BPX4SGQ) Queue a signalto a process . . . . . . . . . . . . . . 771sigsuspend (BPX1SSU, BPX4SSU) Change thesignal mask and suspend the thread until a signalis delivered . . . . . . . . . . . . . . 775sigtimedwait (BPX1STW, BPX4STW) Wait for asignal with a specified timeout . . . . . . . 778

vi z/OS UNIX System Services Programming: Assembler Callable Services Reference

sigwait (BPX1SWT, BPX4SWT) Wait for a signal 781sleep (BPX1SLP, BPX4SLP) Suspend execution ofa process for an interval of time . . . . . . . 783smf_record (BPX1SMF, BPX4SMF) Write an SMFrecord . . . . . . . . . . . . . . . . 786socket or socketpair (BPX1SOC, BPX4SOC) Create a socket or a pair of sockets . . . . . . 789spawn (BPX1SPN, BPX4SPN) Spawn a process 793srx_np (BPX1SRX, BPX4SRX) Send or receiveCSM buffers on a socket. . . . . . . . . . 812stat (BPX1STA, BPX4STA) Get statusinformation about a file by pathname . . . . . 818statvfs (BPX1STV, BPX4STV) Get the file systemstatus . . . . . . . . . . . . . . . . 822sw_sigdlv (BPX1DSD, BPX4DSD) Switch thesetting for signal delivery . . . . . . . . . 824symlink (BPX1SYM, BPX4SYM) Create asymbolic link to a path name . . . . . . . . 826sync (BPX1SYN, BPX4SYN) Schedule file systemupdates . . . . . . . . . . . . . . . 831sysconf (BPX1SYC, BPX4SYC) Determine systemconfiguration options . . . . . . . . . . . 832takesocket (BPX1TAK, BPX4TAK) Acquire asocket from another program . . . . . . . . 835tcdrain (BPX1TDR, BPX4TDR) Wait until outputhas been transmitted . . . . . . . . . . . 837tcflow (BPX1TFW, BPX4TFW) Suspend orresume data flow on a terminal . . . . . . . 839tcflush (BPX1TFH, BPX4TFH) Flush input oroutput on a terminal . . . . . . . . . . . 842tcgetattr (BPX1TGA, BPX4TGA) Get theattributes for a terminal . . . . . . . . . . 844tcgetcp (BPX1TGC, BPX4TGC) Get terminalcode page names . . . . . . . . . . . . 847tcgetpgrp (BPX1TGP, BPX4TGP) Get theforeground process group ID . . . . . . . . 850tcgetsid (BPX1TGS, BPX4TGS) Get a processgroup ID for the session leader for the controllingterminal . . . . . . . . . . . . . . . 852tcsendbreak (BPX1TSB, BPX4TSB) Send a breakcondition to a terminal . . . . . . . . . . 853tcsetattr (BPX1TSA, BPX4TSA) Set the attributesfor a terminal . . . . . . . . . . . . . 856tcsetcp (BPX1TSC, BPX4TSC) Set terminal codepage names . . . . . . . . . . . . . . 859tcsetpgrp (BPX1TSP, BPX4TSP) Set theforeground process group ID . . . . . . . . 862tcsettables (BPX1TST, BPX4TST) Set terminalcode page names and conversion tables . . . . 865times (BPX1TIM, BPX4TIM) Get process andchild process times . . . . . . . . . . . 869truncate (BPX1TRU, BPX4TRU) Change the sizeof a file . . . . . . . . . . . . . . . 872ttyname (BPX1TYN, BPX4TYN) (POSIX version) Get the name of a terminal . . . . . . . . . 875ttyname (BPX2TYN, BPX4TYN) (X/Open version) Get the name of a terminal . . . . . . . . 877umask (BPX1UMK, BPX4UMK) Set the filemode creation mask . . . . . . . . . . . 879umount (BPX1UMT, BPX4UMT) Remove avirtual file system . . . . . . . . . . . . 880

uname (BPX1UNA, BPX4UNA) Obtain thename of the current operating system . . . . . 883unlink (BPX1UNL, BPX4UNL) Remove adirectory entry . . . . . . . . . . . . . 885unlockpt (BPX1UPT, BPX4UPT) Unlock apseudoterminal master/slave pair . . . . . . 888unquiesce (BPX1UQS, BPX4UQS) Unquiesce afile system . . . . . . . . . . . . . . 890utime (BPX1UTI, BPX4UTI) Set file access andmodification times. . . . . . . . . . . . 892wait (BPX1WAT, BPX4WAT) Wait for a childprocess to end . . . . . . . . . . . . . 895wait-extension (BPX1WTE, BPX4WTE) Obtainstatus information for children . . . . . . . 899w_getipc (BPX1GET, BPX4GET) Queryinterprocess communications . . . . . . . . 903w_getmntent (BPX1GMN, BPX4GMN) Getinformation on mounted file systems . . . . . 907w_getpsent (BPX1GPS) Get process data . . . 911w_ioctl (BPX1IOC, BPX4IOC) Control I/O. . . 916__wlm (BPX1WLM, BPX4WLM) WLM interfaceservice. . . . . . . . . . . . . . . . 931w_pioctl (BPX1PIO, BPX4PIO) Path name I/Ocontrol . . . . . . . . . . . . . . . 938w_statvfs (BPX1STF, BPX4STF) Get the filesystem status . . . . . . . . . . . . . 941write (BPX1WRT, BPX4WRT) Write to a file or asocket . . . . . . . . . . . . . . . . 943writev (BPX1WRV, BPX4WRV) Write data froma set of buffers . . . . . . . . . . . . . 948

Appendix A. System control offsets tocallable services . . . . . . . . . . 953Example . . . . . . . . . . . . . . . 953List of offsets . . . . . . . . . . . . . 953

Appendix B. MappingmacrosAMODE 31 . . . . . . . . 959Macros mapping parameter options . . . . . . 959BPXYACC Map flag values for access . . . . 959BPXYAIO Map asyncio parameter list . . . . 960BPXYATT Map file attributes for chattr andfchattr . . . . . . . . . . . . . . . . 962BPXYAUDT Map flag values for chaudit andfchaudit . . . . . . . . . . . . . . . 963BPXYBRLK Map byte range lock request forfcntl . . . . . . . . . . . . . . . . 964BPXYCCA Map input/output structure for__console() . . . . . . . . . . . . . . 964BPXYCID Map the returning structure forgetclientid() . . . . . . . . . . . . . . 965BPXYCONS Constants used by services . . . 966BPXYCW Serialization constants used by manyservices . . . . . . . . . . . . . . . 973BPXYDCOR dbx cordump cache information 973BPXYDIRE Map directory entries for readdir 979BPXYENFO ENF signal constants . . . . . 979BPXYERNO Component return and reasoncodes . . . . . . . . . . . . . . . . 980BPXYFCTL Command values and flags for fcntl 980

Contents vii

BPXYFDUM Logical file system dumpparameter list . . . . . . . . . . . . . 981BPXYFTYP File type definitions . . . . . . 981BPXYFUIO Map file system user I/O block . . 982BPXYGIDN Map data returned for getpwnamand getpwuid . . . . . . . . . . . . . 983BPXYGIDS Map data returned for getgrnamand getgrpid . . . . . . . . . . . . . 984BPXYINHE Spawn Inheritance Structure . . . 984BPXYIOCC Ioctl command definitions . . . . 985BPXYIOC6 Map IPV6 prerouter structures. . . 996BPXYIOV Map the I/O vector structure . . . 1000BPXYIPCP Map interprocess communicationpermissions . . . . . . . . . . . . . 1001BPXYIPCQ Map w_getipc structure . . . . 1001BPXYITIM Map getitimer, setitimer structure 1004BPXYMMG Map interface for _map_init and_map_service . . . . . . . . . . . . . 1005BPXYMNTE Map response and elementstructure of w_getmntent . . . . . . . . . 1007BPXYMODE Map the mode constants of thefile services. . . . . . . . . . . . . . 1010BPXYMSG Map interprocess communicationmessage queues . . . . . . . . . . . . 1011BPXYMSGF Map the message flags . . . . 1012BPXYMSGH Map the message header. . . . 1013BPXYMSGX Map the message header . . . . 1014BPXYMTM Map the modes for mount andunmount . . . . . . . . . . . . . . 1015BPXYOCRT Map the OE certificate supportstructure . . . . . . . . . . . . . . 1016BPXYOEXT Map the common external controlblock . . . . . . . . . . . . . . . . 1017BPXYOPNF Map flag values for open . . . . 1019BPXYPCF Command values for pathconf andpathconf. . . . . . . . . . . . . . . 1019BPXYPEDB Mapping of process exit data block 1020BPXYPGPS Map the response structure forw_getpsent . . . . . . . . . . . . . . 1022BPXYPGTH Map the __getthent input/outputstructure . . . . . . . . . . . . . . 1025BPXYPOE Map poe syscall parameters . . . 1030BPXYPOLL Map poll syscall parameters . . . 1030BPXYPPSD Map signal delivery data . . . . 1031BPXYPRLI Process-level information . . . . 1033BPXYPTAT Map attributes forpthread_exit_and_get . . . . . . . . . . 1033BPXYPTRC Map parameters for ptrace . . . 1034BPXYPTXL Map the parameter list forpthread_create. . . . . . . . . . . . . 1050BPXYRFIS Map the register file intereststructures . . . . . . . . . . . . . . 1050BPXYRLIM Map the rlimit, rusage, and timevalstructures . . . . . . . . . . . . . . 1051BPXYRMON Map resource monitor data . . . 1051BPXYSECI Map the output of BPX1IOC for theSECIGET request . . . . . . . . . . . . 1053BPXYSECO Map the input/output of BPX1IOCfor the SIOCSECENVR request . . . . . . . 1053BPXYSECT Map the output of BPX1IOC forthe SECIGET_T request. . . . . . . . . . 1053

BPXYSEEK Constants for lseek . . . . . . 1053BPXYSEL Map the select options . . . . . 1054BPXYSELT Map the timeout value for theselect syscall . . . . . . . . . . . . . 1054BPXYSEM Map interprocess communicationsemaphores . . . . . . . . . . . . . 1055BPXYSFDL Map the server file descriptor liststructure . . . . . . . . . . . . . . 1055BPXYSFPL Map the send_file parameter list 1056BPXYSHMMap interprocess communicationshared memory segments . . . . . . . . . 1056BPXYSIGH Signal constants . . . . . . . 1057BPXYSINF Map SIGINFO_T structure . . . . 1059BPXYSMC Map shared mutex/condvardeclares and constants . . . . . . . . . . 1060BPXYSOCK Map SOCKADDR structure andconstants . . . . . . . . . . . . . . 1061BPXYSSET Map the sigaction set . . . . . 1073BPXYSSTF Map response structure for filesystem status . . . . . . . . . . . . . 1073BPXYSTAT Map the response structure for stat 1074BPXYTCCP Map the terminal control codepage structure . . . . . . . . . . . . . 1076BPXYTHDQ Mapping of THDQ structure forBPX1PQG . . . . . . . . . . . . . . 1076BPXYTHLI Thread-level information . . . . 1078BPXYTIMS Map the response structure fortimes . . . . . . . . . . . . . . . . 1082BPXYTIOS Map the termios structure . . . . 1082BPXYUTSN Map the response structure foruname . . . . . . . . . . . . . . . 1086BPXYWAST Map the wait status word . . . 1086BPXYWLM WLM constants and parameter listDSECTs . . . . . . . . . . . . . . . 1087BPXYWNSZ Map the winsize structure . . . 1095BPXZOAPB z/OS UNIX address spaceper-process extension . . . . . . . . . . 1095BPXZOCVT Base control block for z/OS UNIX 1095BPXZOTCB z/OS UNIX extension to the TCB 1096

Appendix C. MappingmacrosAMODE 64 . . . . . . . . 1103Macros mapping parameter options . . . . . 1103BPXYAIO Map asyncio parameter list . . . . 1103BPXYCCA Map input/output structure for__console() . . . . . . . . . . . . . . 1106BPXYDCOR dbx cordump cache information 1107BPXYINHE Spawn inheritance structure . . . 1113BPXYIOC6 Map IPV6 prerouter structures . . 1114BPXYIOV Map the I/O vector structure . . . 1118BPXYIPCQ Map w_getipc structure. . . . . 1118BPXYITIM Map getitimer, setitimer structure 1121BPXYMMG Map Interface for _map_init and_map_service . . . . . . . . . . . . . 1122BPXYMSG Map interprocess communicationmessage queues . . . . . . . . . . . . 1124BPXYMSGH Map the message header . . . . 1125BPXYOCRT Map the OE certificate supportstructure. . . . . . . . . . . . . . . 1125BPXYPPSD Map signal delivery data . . . . 1126

viii z/OS UNIX System Services Programming: Assembler Callable Services Reference

BPXYPTXL Map the parameter pist forpthread_create. . . . . . . . . . . . . 1128BPXYRLIM Map the rlimit, rusage, and timevalstructures . . . . . . . . . . . . . . 1128BPXYSELT Map the timeout value for theselect syscall . . . . . . . . . . . . . 1129BPXYSEM Map interprocess communicationsemaphores. . . . . . . . . . . . . . 1129BPXYSFPL Map the send_file parameter list 1130BPXYSHMMap interprocess communicationshared memory segments . . . . . . . . . 1131BPXYSINF Map SIGINFO_T structure . . . . 1131BPXYSSET Map the sigaction set . . . . . 1132BPXYWLM WLM constants and parameter listDSECTs . . . . . . . . . . . . . . . 1132

Appendix D. Callable servicesexamplesAMODE 31 . . . . . . . 1141Reentrant entry linkage. . . . . . . . . . 1141BPX1ACC (access) example . . . . . . . . 1142BPX1ACK (auth_check_resource_np) example 1142BPX1ACP (accept) example . . . . . . . . 1143BPX1AIO (asyncio) example . . . . . . . . 1143BPX1ALR (alarm) example . . . . . . . . 1143BPX1ANR (accept_and_recv) example . . . . . 1144BPX1ASP (aio_suspend) example . . . . . . 1144BPX1ATM (attach_execmvs) example . . . . . 1145BPX1ATX (attach_exec) example. . . . . . . 1145BPX1BND (bind) example . . . . . . . . . 1146BPX1BAS (bind with source address selection)example . . . . . . . . . . . . . . . 1146BPXICCA (cond_cancel) example . . . . . . 1147BPX1CCS (__console()) example . . . . . . . 1147BPX1CHA (chaudit) example . . . . . . . . 1147BPX1CHD (chdir) example . . . . . . . . 1148BPX1CHM (chmod) example . . . . . . . . 1148BPX1CHO (chown) example . . . . . . . . 1148BPX1CHP (chpriority) example . . . . . . . 1149BPX1CHR (chattr) example . . . . . . . . 1149BPX1CLD (closedir) example . . . . . . . . 1150BPX1CLO (close) example . . . . . . . . . 1150BPX1CON (connect) example . . . . . . . . 1150BPX1CPO (cond_post) example . . . . . . . 1150BPX1CRT (chroot) example . . . . . . . . 1151BPX1CSE (cond_setup) example . . . . . . . 1151BPX1CTW (cond_timed_wait) example . . . . 1151BPX1CWA (cond_wait) example . . . . . . . 1152BPX1DEL (deleteHFS) example . . . . . . . 1152BPX1ENV (oe_env_np) example . . . . . . . 1152BPX1EXC (exec) example . . . . . . . . . 1153BPX1EXI (_exit) example . . . . . . . . . 1154BPX1EXM (execmvs) example . . . . . . . 1154BPX1EXT (extlink_np) example . . . . . . . 1154BPX1FAI (freeaddrinfo) example. . . . . . . 1155BPX1FCA (fchaudit) example . . . . . . . . 1155BPX1FCD (fchdir) example . . . . . . . . 1155BPX1FCM (fchmod) example . . . . . . . . 1156BPX1FCO (fchown) example . . . . . . . . 1156BPX1FCR (fchattr) example . . . . . . . . 1156BPX1FCT (fcntl) example . . . . . . . . . 1157BPX1FPC (fpathconf) example . . . . . . . 1158

BPX1FRK (fork) example . . . . . . . . . 1158BPX1FST (fstat) example . . . . . . . . . 1158BPX1FSY (fsync) example . . . . . . . . . 1158BPX1FTR (ftruncate) example. . . . . . . . 1159BPX1FTV (fstatvfs) example . . . . . . . . 1159BPX1GAI (getaddrinfo) example. . . . . . . 1159BPX1GCL (getclientid) example . . . . . . . 1160BPX1GCW (getcwd) example . . . . . . . . 1160BPX1GEG (getegid) example . . . . . . . . 1160BPX1GEP (getpgid) example . . . . . . . . 1160BPX1GES (getsid) example . . . . . . . . 1161BPX1GET (w_getipc) example . . . . . . . 1161BPX1GEU (geteuid) example . . . . . . . . 1162BPX1GGE (getgrent) example. . . . . . . . 1162BPX1GGI (getgrgid) example . . . . . . . . 1162BPX1GGN (getgrnam) example . . . . . . . 1163BPX1GGR (getgroups) example . . . . . . . 1163BPX1GHA (gethostbyaddr) example . . . . . 1163BPX1GHN (gethostbyname) example . . . . . 1164BPX1GID (getgid) example . . . . . . . . 1164BPX1GIV (givesocket) example . . . . . . . 1165BPX1GLG (getlogin) example. . . . . . . . 1165BPX1GMN (w_getmntent) example. . . . . . 1165BPX1GNI (getnameinfo) example . . . . . . 1166BPX1GPG (getpgrp) example . . . . . . . . 1166BPX1GNM (getpeername or getsockname)example . . . . . . . . . . . . . . . 1166BPX1GPE (getpwent) example . . . . . . . 1167BPX1GPI (getpid) example . . . . . . . . 1167BPX1GPN (getpwnam) example . . . . . . . 1167BPX1GPP (getppid) example . . . . . . . . 1168BPX1GPS (w_getpsent) example . . . . . . . 1168BPX1GPT (grantpt) example . . . . . . . . 1168BPX1GPU (getpwuid) example . . . . . . . 1169BPX1GPY (getpriority) example . . . . . . . 1169BPX1GRL (getrlimit) example. . . . . . . . 1169BPX1GRU (getrusage) example . . . . . . . 1170BPX1GTH (__getthent) example . . . . . . . 1170BPX1GTR (getitimer) example . . . . . . . 1170BPX1GUG (getgroupsbyname) example . . . . 1171BPX1GUI (getuid) example . . . . . . . . 1171BPX1GWD (getwd) example . . . . . . . . 1171BPX1HST (gethostid or gethostname) example 1172BPX1IOC (w_ioctl) example . . . . . . . . 1172BPX1IPT (mvsiptaffinity) example . . . . . . 1172BPX1ITY (isatty) example . . . . . . . . . 1173BPX2ITY (isatty) example . . . . . . . . . 1173BPX1KIL (kill) example . . . . . . . . . . 1173BPX1LCO (lchown) example . . . . . . . . 1174BPX1LCR (lchattr) example . . . . . . . . 1174BPX1LDX (loadHFS extended) example . . . . 1174BPX1LOD (loadHFS) example . . . . . . . 1176BPX1LNK (link) example . . . . . . . . . 1177BPX1LSK (lseek) example . . . . . . . . . 1177BPX1LSN (listen) example . . . . . . . . . 1177BPX1LST (lstat) example . . . . . . . . . 1178BPX1MAT (shmat) example . . . . . . . . 1178BPX1MCT (shmctl) example . . . . . . . . 1178BPX1MDT (shmdt) example . . . . . . . . 1179BPX1MGT (shmget) example . . . . . . . . 1179BPX1MKD (mkdir) example . . . . . . . . 1179

Contents ix

BPX1MKN (mknod) example . . . . . . . . 1180BPX1MMI (__map_init) example . . . . . . 1180BPX1MMP (mmap) example . . . . . . . . 1181BPX1MMS (__map_service) example . . . . . 1181BPX1MNT (mount) example . . . . . . . . 1181BPX2MNT (__mount) example . . . . . . . 1182BPX1MP (mvspause) example . . . . . . . 1182BPX1MPC (mvsprocclp) examples . . . . . . 1182BPX1MPI (mvspauseinit) example . . . . . . 1183BPX1MPR (mprotect) example . . . . . . . 1184BPX1MSD (mvsunsigsetup) example . . . . . 1184BPX1MSS (mvssigsetup) example . . . . . . 1184BPX1MSY (msync) example . . . . . . . . 1185BPX1MUN (munmap) example . . . . . . . 1185BPX1NIC (nice) example . . . . . . . . . 1185BPX1OPD (opendir) example . . . . . . . . 1186BPX1OPN (open) example. . . . . . . . . 1186BPX2OPN (openstat) example . . . . . . . 1186BPX1OPT (getsockopt or setsockopt) example 1187BPX1PAF (__pid_affinity) example . . . . . . 1188BPX1PAS (pause) example. . . . . . . . . 1188BPX1PCF (pathconf) example. . . . . . . . 1188BPX1PCT (pfsctl) example . . . . . . . . . 1188BPX1PIP (pipe) example . . . . . . . . . 1189BPX1POE (__poe) example . . . . . . . . 1189BPX1POL (poll) example . . . . . . . . . 1189BPX1PSI (pthread_setintr) example . . . . . . 1190BPX1PST (pthread_setintrtype) example . . . . 1190BPX1PTB (pthread_cancel) example . . . . . 1190BPX1PTC (pthread_create) example. . . . . . 1191BPX1PTD (pthread_detach) example . . . . . 1191BPX1PTI (pthread_testintr) example . . . . . 1191BPX1PTJ (pthread_join) example. . . . . . . 1192BPX1PTK (pthread_kill) example . . . . . . 1192BPX1PTQ (pthread_quiesce) example . . . . . 1192BPX1PTR (ptrace) example . . . . . . . . 1192BPX1PTS (pthread_self) example . . . . . . 1193BPX1PTT (pthread_tag_np) example . . . . . 1193BPX1PTX (pthread_exit_and_get) example . . . 1193BPX1PWD (__passwd, __passwd__applid)example . . . . . . . . . . . . . . . 1194BPX1QCT (msgctl) example . . . . . . . . 1194BPX1QDB (querydub) example . . . . . . . 1194BPX1QGT (msgget) example . . . . . . . . 1195BPX1QRC (msgrcv) example . . . . . . . . 1195BPX1QSE (quiesce) example . . . . . . . . 1195BPX1QSN (msgsnd) example . . . . . . . . 1196BPX1RCV (recv) example . . . . . . . . . 1196BPX1RDD (readdir) example . . . . . . . . 1197BPX1RDL (readlink) example . . . . . . . . 1197BPX1RDV (readv) example . . . . . . . . 1197BPX1RDX (read extlink) example . . . . . . 1198BPX1RD2 (readdir2) example . . . . . . . . 1198BPX1RED (read) example . . . . . . . . . 1199BPX1REN (rename) example . . . . . . . . 1199BPX1RFM (recvfrom) example . . . . . . . 1199BPX1RMD (rmdir) example . . . . . . . . 1200BPX1RMG (resource) example . . . . . . . 1200BPX2RMS (recvmsg) example . . . . . . . 1200BPX1RPH (realpath) example. . . . . . . . 1201BPX1RW (Pwrite) example . . . . . . . . 1201

BPX1RWD (rewinddir) example . . . . . . . 1202BPX1SA2 (__sigactionset) example . . . . . . 1202BPX1SCT (semctl) example . . . . . . . . 1202BPX1SDD (setdubdefault) example . . . . . . 1203BPX1SEC (__login, __login__applid, __certificate)example . . . . . . . . . . . . . . . 1203BPX1SEG (setegid) example . . . . . . . . 1203BPX1SEL (select) example . . . . . . . . . 1204BPX1SEU (seteuid) example . . . . . . . . 1204BPX1SF (send_file) example . . . . . . . . 1205BPX1SGE (setgrent) example . . . . . . . . 1205BPX1SGI (setgid) example . . . . . . . . . 1205BPX1SGQ (sigqueue) example . . . . . . . 1205BPX1SGR (setgroups) example . . . . . . . 1206BPX1SGT (semget) example . . . . . . . . 1206BPX1SHT (shutdown) example . . . . . . . 1207BPX1SIA (sigaction) example . . . . . . . . 1207BPX1SIN (server_init) example . . . . . . . 1207BPX1SIP (sigpending) example . . . . . . . 1208BPX1SLK (shmem_lock) example . . . . . . 1208BPX1SLP (sleep) example . . . . . . . . . 1208BPX1SMF (smf_record) example . . . . . . . 1209BPX2SMS (sendmsg) example . . . . . . . 1209BPX1SND (send) example . . . . . . . . . 1210BPX1SOC (socket or socketpair) example . . . . 1210BPX1SOP (semop) example . . . . . . . . 1211BPX1SPB (queue_interrupt) example . . . . . 1211BPX1SPE (setpwent) example. . . . . . . . 1211BPX1SPG (setpgid) example . . . . . . . . 1212BPX1SPM (sigprocmask) example . . . . . . 1212BPX1SPN (spawn) example . . . . . . . . 1212BPX1SPR (setpeer) example . . . . . . . . 1213BPX1SPW (server_pwu) example . . . . . . 1213BPX1SPY (setpriority) example . . . . . . . 1214BPX1SRG (setregid) example . . . . . . . . 1214BPX1SRL (setrlimit) example . . . . . . . . 1215BPX1SRU (setreuid) example . . . . . . . . 1215BPX1SRX (srx_np) example . . . . . . . . 1215BPX1SSI (setsid) example . . . . . . . . . 1216BPX1SSU (sigsuspend) example . . . . . . . 1216BPX1STA (stat) example . . . . . . . . . 1216BPX1STE (set_timer_event) example . . . . . 1217BPX1STF (w_statvfs) example . . . . . . . 1217BPX1STL (set_thread_limits) example . . . . . 1217BPX1STO (sendto) example . . . . . . . . 1218BPX1STR (setitimer) example. . . . . . . . 1218BPX1STV (statvfs) example . . . . . . . . 1218BPX1STW (sigtimedwait) example . . . . . . 1219BPX1SUI (setuid) example. . . . . . . . . 1219BPX1SWT (sigwait) example . . . . . . . . 1219BPX1SYC (sysconf) example . . . . . . . . 1220BPX1SYM (symlink) example. . . . . . . . 1220BPX1SYN (sync) example . . . . . . . . . 1220BPX1TAF (MVSThreadAffinity) example . . . . 1221BPX1TAK (takesocket) example . . . . . . . 1221BPX1TDR (tcdrain) example . . . . . . . . 1221BPX1TFH (tcflush) example . . . . . . . . 1222BPX1TFW (tcflow) example . . . . . . . . 1222BPX1TGA (tcgetattr) example. . . . . . . . 1222BPX1TGC (tcgetcp) example . . . . . . . . 1222BPX1TGP (tcgetpgrp) example . . . . . . . 1223

x z/OS UNIX System Services Programming: Assembler Callable Services Reference

BPX1TGS (tcgetsid) example . . . . . . . . 1223BPX1TIM (times) example . . . . . . . . . 1223BPX1TLS (pthread_security_np) example . . . . 1223BPX1TRU (truncate) example. . . . . . . . 1224BPX1TSA (tcsetattr) example . . . . . . . . 1224BPX1TSB (tcsendbreak) example. . . . . . . 1224BPX1TSC (tcsetcp) example . . . . . . . . 1225BPX1TSP (tcsetpgrp) example . . . . . . . 1225BPX1TST (tcsettables) example . . . . . . . 1225BPX1TYN (ttyname) example. . . . . . . . 1226BPX2TYN (ttyname) example. . . . . . . . 1226BPX1UMK (umask) example . . . . . . . . 1226BPX1UMT (umount) example . . . . . . . 1227BPX1UNA (uname) example . . . . . . . . 1227BPX1UNL (unlink) example . . . . . . . . 1227BPX1UPT (unlockpt) example . . . . . . . 1228BPX1UQS (unquiesce) example . . . . . . . 1228BPX1UTI (utime) example . . . . . . . . . 1228BPX1WAT (wait) example . . . . . . . . . 1228BPX1WLM (__WLM) example . . . . . . . 1229BPX1WRT (write) example . . . . . . . . 1229BPX1WRV (writev) example . . . . . . . . 1230BPX1WTE (wait extension) example . . . . . 1230Reentrant return linkage . . . . . . . . . 1230

Appendix E. Callable servicesexamplesAMODE 64 . . . . . . . 1233Reentrant entry linkage . . . . . . . . . 1233BPX4ACC (access) example . . . . . . . . 1234BPX4ACK (auth_check_resource_np) example 1234BPX4ACP (accept) example . . . . . . . . 1235BPX4AIO (asyncio) example . . . . . . . . 1235BPX4ALR (alarm) example . . . . . . . . 1235BPX4ANR (accept_and_recv) example . . . . . 1236BPX4ASP (aio_suspend) example . . . . . . 1236BPX4ATM (attach_execmvs) example . . . . . 1236BPX4ATX (attach_exec) example. . . . . . . 1237BPX4BND (bind) example . . . . . . . . . 1237BPX4BAS (bind with source address selection)example . . . . . . . . . . . . . . . 1238BPX4CCA (cond_cancel) example . . . . . . 1238BPX4CCS (__console()) example . . . . . . . 1238BPX4CHA (chaudit) example . . . . . . . . 1239BPX4CHD (chdir) example . . . . . . . . 1239BPX4CHM (chmod) example . . . . . . . . 1239BPX4CHO (chown) example . . . . . . . . 1240BPX4CHP (chpriority) example . . . . . . . 1240BPX4CHR (chattr) example . . . . . . . . 1241BPX4CLD (closedir) example . . . . . . . . 1241BPX4CLO (close) example . . . . . . . . . 1241BPX4CON (connect) example. . . . . . . . 1242BPX4CPO (cond_post) example . . . . . . . 1242BPX4CRT (chroot) example . . . . . . . . 1242BPX4CSE (cond_setup) example . . . . . . . 1243BPX4CTW (cond_timed_wait) example . . . . 1243BPX4CWA (cond_wait) example . . . . . . . 1243BPX4DEL (deleteHFS) example . . . . . . . 1243BPX4ENV (oe_env_np) example . . . . . . . 1244BPX4EXC (exec) example . . . . . . . . . 1245BPX4EXI (_exit) example . . . . . . . . . 1245BPX4EXM (execmvs) example . . . . . . . 1246

BPX4EXT (extlink_np) example . . . . . . . 1246BPX4FAI (freeaddrinfo) example . . . . . . 1246BPX4FCA (fchaudit) example . . . . . . . . 1247BPX4FCD (fchdir) example . . . . . . . . 1247BPX4FCM (fchmod) example . . . . . . . . 1247BPX4FCO (fchown) example . . . . . . . . 1248BPX4FCR (fchattr) example . . . . . . . . 1248BPX4FCT (fcntl) example . . . . . . . . . 1248BPX4FPC (fpathconf) example . . . . . . . 1249BPX4FRK (fork) example . . . . . . . . . 1250BPX4FST (fstat) example . . . . . . . . . 1250BPX4FSY (fsync) example . . . . . . . . . 1250BPX4FTR (ftruncate) example . . . . . . . 1250BPX4FTV (fstatvfs) example . . . . . . . . 1251BPX4GAI (getaddrinfo) example. . . . . . . 1251BPX4GCL (getclientid) example . . . . . . . 1251BPX4GCW (getcwd) example. . . . . . . . 1252BPX4GEG (getegid) example . . . . . . . . 1252BPX4GEP (getpgid) example . . . . . . . . 1252BPX4GES (getsid) example . . . . . . . . 1252BPX4GET (w_getipc) example . . . . . . . 1253BPX4GEU (geteuid) example . . . . . . . . 1253BPX4GGE (getgrent) example . . . . . . . 1253BPX4GGI (getgrgid) example . . . . . . . . 1254BPX4GGN (getgrnam) example . . . . . . . 1254BPX4GGR (getgroups) example . . . . . . . 1255BPX4GHA (gethostbyaddr) example . . . . . 1255BPX4GHN (gethostbyname) example . . . . . 1256BPX4GID (getgid) example . . . . . . . . 1256BPX4GIV (givesocket) example . . . . . . . 1256BPX4GLG (getlogin) example. . . . . . . . 1257BPX4GMN (w_getmntent) example. . . . . . 1257BPX4GNI (getnameinfo) example . . . . . . 1257BPX4GPG (getpgrp) example . . . . . . . . 1258BPX4GNM (getpeername or getsockname)example . . . . . . . . . . . . . . . 1258BPX4GPE (getpwent) example . . . . . . . 1258BPX4GPI (getpid) example . . . . . . . . 1259BPX4GPN (getpwnam) example . . . . . . . 1259BPX4GPP (getppid) example . . . . . . . . 1259BPX4GPT (grantpt) example . . . . . . . . 1259BPX4GPU (getpwuid) example . . . . . . . 1260BPX4GPY (getpriority) example . . . . . . . 1260BPX4GRL (getrlimit) example . . . . . . . 1260BPX4GRU (getrusage) example . . . . . . . 1261BPX4GTH (__getthent) example . . . . . . . 1261BPX4GTR (getitimer) example . . . . . . . 1261BPX4GUG (getgroupsbyname) example . . . . 1262BPX4GUI (getuid) example . . . . . . . . 1262BPX4GWD (getwd) example . . . . . . . . 1262BPX4HST (gethostid or gethostname) example 1263BPX4IOC (w_ioctl) example . . . . . . . . 1263BPX4IPT (mvsiptaffinity) example . . . . . . 1263BPX4ITY (isatty) example . . . . . . . . . 1264BPX4KIL (kill) example. . . . . . . . . . 1264BPX4LCO (lchown) example . . . . . . . . 1264BPX4LCR (lchattr) example . . . . . . . . 1265BPX4LDX (loadHFS extended) example . . . . 1265BPX4LOD (loadHFS) example . . . . . . . 1267BPX4LNK (link) example . . . . . . . . . 1267BPX4LSK (lseek) example . . . . . . . . . 1268

Contents xi

BPX4LSN (listen) example. . . . . . . . . 1268BPX4LST (lstat) example . . . . . . . . . 1268BPX4MAT (shmat) example . . . . . . . . 1269BPX4MCT (shmctl) example . . . . . . . . 1269BPX4MDT (shmdt) example . . . . . . . . 1269BPX4MGT (shmget) example . . . . . . . . 1270BPX4MKD (mkdir) example . . . . . . . . 1270BPX4MKN (mknod) example . . . . . . . . 1270BPX4MMI (__map_init) example . . . . . . 1271BPX4MMP (mmap) example . . . . . . . . 1271BPX4MMS (__map_service) example . . . . . 1272BPX4MNT (__mount) example . . . . . . . 1272BPX4MP (mvspause) example . . . . . . . 1273BPX4MPC (mvsprocclp) example . . . . . . 1273BPX4MPI (mvspauseinit) example . . . . . . 1273BPX4MPR (mprotect) example . . . . . . . 1274BPX4MSD (mvsunsigsetup) example . . . . . 1274BPX4MSS (mvssigsetup) example . . . . . . 1274BPX4MSY (msync) example . . . . . . . . 1275BPX4MUN (munmap) example . . . . . . . 1275BPX4NIC (nice) example . . . . . . . . . 1275BPX4OPD (opendir) example . . . . . . . . 1275BPX4OPN (open) example. . . . . . . . . 1276BPX4OPS (openstat) example. . . . . . . . 1276BPX4OPT (getsockopt or setsockopt) example 1277BPX4PAF (__pid_affinity) example . . . . . . 1277BPX4PAS (pause) example. . . . . . . . . 1278BPX4PCF (pathconf) example. . . . . . . . 1278BPX4PCT (pfsctl) example . . . . . . . . . 1278BPX4PIP (pipe) example . . . . . . . . . 1279BPX4POE (__poe) example . . . . . . . . 1279BPX4POL (poll) example . . . . . . . . . 1279BPX4PSI (pthread_setintr) example . . . . . . 1280BPX4PST (pthread_setintrtype) example . . . . 1280BPX4PTB (pthread_cancel) example . . . . . 1280BPX4PTC (pthread_create) example . . . . . 1280BPX4PTD (pthread_detach) example . . . . . 1281BPX4PTI (pthread_testintr) example . . . . . 1281BPX4PTJ (pthread_join) example . . . . . . 1281BPX4PTK (pthread_kill) example . . . . . . 1282BPX4PTQ (pthread_quiesce) example . . . . . 1282BPX4PTR (ptrace) example . . . . . . . . 1282BPX4PTS (pthread_self) example . . . . . . 1283BPX4PTT (pthread_tag_np) example . . . . . 1283BPX4PTX (pthread_exit_and_get) example . . . 1283BPX4PWD (__passwd, __passwd__applid)example . . . . . . . . . . . . . . . 1283BPX4QCT (msgctl) example . . . . . . . . 1284BPX4QDB (querydub) example . . . . . . . 1284BPX4QGT (msgget) example . . . . . . . . 1284BPX4QRC (msgrcv) example . . . . . . . . 1285BPX4QSE (quiesce) example . . . . . . . . 1285BPX4QSN (msgsnd) example . . . . . . . . 1285BPX4RCV (recv) example . . . . . . . . . 1286BPX4RDD (readdir) example . . . . . . . . 1286BPX4RDL (readlink) example. . . . . . . . 1287BPX4RDV (readv) example . . . . . . . . 1287BPX4RDX (read extlink) example . . . . . . 1287BPX4RD2 (readdir2) example. . . . . . . . 1288BPX4RED (read) example . . . . . . . . . 1288BPX4REN (rename) example . . . . . . . . 1289

BPX4RFM (recvfrom) example . . . . . . . 1289BPX4RMD (rmdir) example . . . . . . . . 1289BPX4RMG (resource) example . . . . . . . 1290BPX4RMS (recvmsg) example . . . . . . . 1290BPX4RPH (realpath) example. . . . . . . . 1290BPX4RW (Pwrite) example . . . . . . . . 1291BPX4RWD (rewinddir) example . . . . . . . 1291BPX4SA2 (__sigactionset) example . . . . . . 1292BPX4SCT (semctl) example . . . . . . . . 1292BPX4SDD (setdubdefault) example . . . . . . 1292BPX4SEC (__login, __login__applid, __certificate)example . . . . . . . . . . . . . . . 1293BPX4SEG (setegid) example . . . . . . . . 1293BPX4SEL (select) example . . . . . . . . . 1293BPX4SEU (seteuid) example . . . . . . . . 1294BPX4SF (send_file) example . . . . . . . . 1294BPX4SGE (setgrent) example . . . . . . . . 1295BPX4SGI (setgid) example . . . . . . . . . 1295BPX4SGQ (sigqueue) example . . . . . . . 1295BPX4SGR (setgroups) example . . . . . . . 1295BPX4SGT (semget) example . . . . . . . . 1296BPX4SHT (shutdown) example . . . . . . . 1296BPX4SIA (sigaction) example . . . . . . . . 1296BPX4SIN (server_init) example . . . . . . . 1297BPX4SIP (sigpending) example . . . . . . . 1297BPX4SLK (shmem_lock) example . . . . . . 1298BPX4SLP (sleep) example . . . . . . . . . 1298BPX4SMF (smf_record) example . . . . . . . 1298BPX4SMS (sendmsg) example . . . . . . . 1299BPX4SND (send) example . . . . . . . . . 1300BPX4SOC (socket or socketpair) example . . . . 1300BPX4SOP (semop) example . . . . . . . . 1300BPX4SPB (queue_interrupt) example . . . . . 1301BPX4SPE (setpwent) example. . . . . . . . 1301BPX4SPG (setpgid) example . . . . . . . . 1301BPX4SPM (sigprocmask) example . . . . . . 1302BPX4SPN (spawn) example . . . . . . . . 1302BPX4SPR (setpeer) example . . . . . . . . 1303BPX4SPW (server_pwu) example . . . . . . 1303BPX4SPY (setpriority) example . . . . . . . 1304BPX4SRG (setregid) example . . . . . . . . 1304BPX4SRL (setrlimit) example . . . . . . . . 1304BPX4SRU (setreuid) example . . . . . . . . 1305BPX4SRX (srx_np) example . . . . . . . . 1305BPX4SSI (setsid) example . . . . . . . . . 1306BPX4SSU (sigsuspend) example . . . . . . . 1306BPX4STA (stat) example . . . . . . . . . 1306BPX4STE (set_timer_event) example . . . . . 1306BPX4STF (w_statvfs) example . . . . . . . 1307BPX4STL (set_thread_limits) example . . . . . 1307BPX4STO (sendto) example . . . . . . . . 1307BPX4STR (setitimer) example. . . . . . . . 1308BPX4STV (statvfs) example . . . . . . . . 1308BPX4STW (sigtimedwait) example . . . . . . 1309BPX4SUI (setuid) example. . . . . . . . . 1309BPX4SWT (sigwait) example . . . . . . . . 1309BPX4SYC (sysconf) example . . . . . . . . 1310BPX4SYM (symlink) example. . . . . . . . 1310BPX4SYN (sync) example . . . . . . . . . 1310BPX4TAF (MVSThreadAffinity) example . . . . 1310BPX4TAK (takesocket) example . . . . . . . 1311

xii z/OS UNIX System Services Programming: Assembler Callable Services Reference

BPX4TDR (tcdrain) example . . . . . . . . 1311BPX4TFH (tcflush) example . . . . . . . . 1311BPX4TFW (tcflow) example . . . . . . . . 1312BPX4TGA (tcgetattr) example. . . . . . . . 1312BPX4TGC (tcgetcp) example . . . . . . . . 1312BPX4TGP (tcgetpgrp) example . . . . . . . 1313BPX4TGS (tcgetsid) example . . . . . . . . 1313BPX4TIM (times) example . . . . . . . . . 1313BPX4TLS (pthread_security_np) example . . . . 1313BPX4TRU (truncate) example. . . . . . . . 1314BPX4TSA (tcsetattr) example . . . . . . . . 1314BPX4TSB (tcsendbreak) example. . . . . . . 1314BPX4TSC (tcsetcp) example . . . . . . . . 1315BPX4TSP (tcsetpgrp) example . . . . . . . 1315BPX4TST (tcsettables) example . . . . . . . 1315BPX4TYN (ttyname) example. . . . . . . . 1316BPX4UMK (umask) example . . . . . . . . 1316BPX4UMT (umount) example . . . . . . . 1316BPX4UNA (uname) example . . . . . . . . 1317BPX4UNL (unlink) example . . . . . . . . 1317BPX4UPT (unlockpt) example . . . . . . . 1317BPX4UQS (unquiesce) example . . . . . . . 1318BPX4UTI (utime) example . . . . . . . . . 1318BPX4WAT (wait) example . . . . . . . . . 1318BPX4WLM (__WLM) example . . . . . . . 1319BPX4WRT (write) example . . . . . . . . 1319BPX4WRV (writev) example . . . . . . . . 1319BPX4WTE (wait extension) example . . . . . 1320Reentrant return linkage . . . . . . . . . 1320

Appendix F. Examples ofnonreentrant entry linkage . . . . . 1325Example of nonreentrant entry linkageAMODE31 . . . . . . . . . . . . . . . . . 1325Example of nonreentrant entry linkageAMODE64 . . . . . . . . . . . . . . . . . 1327

Appendix G. The relationship of z/OSUNIX signals to callable services . . 1331High-level-language signal interfaces . . . . . 1331

How high-level languages use signals . . . . 1332Signal setup when linking to callable services 1332

ESPIE or ESTAE and the SIGILL, SIGFPE, andSIGSEGV signals . . . . . . . . . . . . 1333

When signals are and are not supported . . . 1333Signal delivery keys . . . . . . . . . . . 1334Delayed signal delivery . . . . . . . . . 1335When signals cannot be delivered . . . . . . 1336Signals and multiple tasks created by ATTACH 1336Signals and multiple tasks created bypthread_create. . . . . . . . . . . . . 1336Signal defaults . . . . . . . . . . . . 1337

Appendix H. Using threads withcallable services . . . . . . . . . 1339Creating threads . . . . . . . . . . . . 1339

The pthread_create task initialization routine 1339

Terminating pthreads . . . . . . . . . . 1340Heavyweight thread (HWT) . . . . . . . 1340Mediumweight thread (MWT) . . . . . . 1340Terminating multiple pthreads and tasks . . . 1340Pthread termination scenarios . . . . . . 1341

Appendix I. Optimizing performanceusing process- and thread-levelinformation . . . . . . . . . . . . 1347Optimization processing for BPX1PSI, BPX4PSI(pthread_setintr) . . . . . . . . . . . . 1347Optimization processing for BPX1PST, BPX4PST(pthread_setintrtype) . . . . . . . . . . 1348Optimization processing for BPX1SPM, BPX4SPM(sigprocmask) . . . . . . . . . . . . . 1348Optimization processing for BPX1GPI, BPX4GPI(getpid) . . . . . . . . . . . . . . . 1349

Appendix J. Callable servicesavailable to SRB mode routines . . . 1351Overview of callable services available to SRBmode routines . . . . . . . . . . . . . 1351Recovery . . . . . . . . . . . . . . 1351

Task mode routine responsibilities . . . . . 1352Task and address space dynamic resourcemanager. . . . . . . . . . . . . . 1352

Callable services supported in SRB mode. . . . 1352

Appendix K. Process start and endexits for z/OS UNIX . . . . . . . . 1355Exit environment . . . . . . . . . . . . 1356Errno and errnoJrs . . . . . . . . . . . 1357Restrictions. . . . . . . . . . . . . . 1357Usage notes . . . . . . . . . . . . . 1357

Appendix L. Dynamic syscall exitsfor z/OS UNIX . . . . . . . . . . . 1359Enabling syscalls for exits . . . . . . . . . 1359Defining exit points for syscalls . . . . . . . 1359

Appendix M. Accessibility . . . . . 1365Accessibility features . . . . . . . . . . 1365Consult assistive technologies . . . . . . . 1365Keyboard navigation of the user interface . . . 1365Dotted decimal syntax diagrams . . . . . . 1365

Notices . . . . . . . . . . . . . 1369Terms and conditions for product documentation 1371IBM Online Privacy Statement . . . . . . . 1372Policy for unsupported hardware . . . . . . 1372Minimum supported hardware . . . . . . . 1372Acknowledgments . . . . . . . . . . . 1373Trademarks . . . . . . . . . . . . . 1373

Index . . . . . . . . . . . . . . 1375

Contents xiii

|||||||

xiv z/OS UNIX System Services Programming: Assembler Callable Services Reference

Figures

1. Call parameter list . . . . . . . . . . 52. setuid() parameters AMODE 31 and

AMODE 64 . . . . . . . . . . . . 103. shmget() parameters AMODE 31 and

AMODE 64 . . . . . . . . . . . . 114. loadhfs() parameters AMODE 31 and

AMODE 64 . . . . . . . . . . . . 12

5. readv iov structure AMODE 31 andAMODE 64 . . . . . . . . . . . . 13

6. Program flow of mvssigsetup and sigactionwith signal interface routine (SIR) . . . . 1333

Copyright IBM Corp. 1996, 2017 xv

xvi z/OS UNIX System Services Programming: Assembler Callable Services Reference

Tables

1. Callable services with no BPX4xxx counterparts 92. Attribute fields that can be modified by chattr 813. Attribute fields that can be modified by

fchattr . . . . . . . . . . . . . . 1634. Dcor_Request options . . . . . . . . . 3055. PTRACE service options for the

Dcor_Request parameter . . . . . . . . 3066. BPX1SEC/BPX4SEC return values for

certificate registration or deregistration withinitACEE return code 8 . . . . . . . . 319

7. BPX1SEC/BPX4SEC parameter usage basedon function requested . . . . . . . . . 319

8. Attribute fields that can be modified bylchattr . . . . . . . . . . . . . . 326

9. Number of input and output arguments andthe scope of each defined Function_code . . 447

10. RACF return and reason codes. . . . . . 47011. Poecb control block: Socket scope . . . . . 49412. Poecb control block: Process scope . . . . 49413. Poecb control block: Thread scope . . . . 49514. RACROUTE parameters for POE data 49615. POE data propagation for z/OS UNIX

services . . . . . . . . . . . . . 49616. Return codes for ptrace . . . . . . . . 54917. RACF return and reason codes for the ptrace

authority check service . . . . . . . . 55218. Constant options for the ptrace request

parameter. . . . . . . . . . . . . 55219. Parameter attributes for request options 55420. Return values and return codes for request

options . . . . . . . . . . . . . 55721. Corresponding ptrace event and status that is

reported to the debugger. . . . . . . . 56122. Offsets and associate information that are

defined in BPXYPTRC . . . . . . . . 570

23. Calling parameters and commands . . . . 63824. Resources that can be limited by setrlimit 70925. Allowable thread limits for MaxThreadTasks 71726. Allowable thread limits for MaxThread 71727. Authorization requirements for __wlm

functions . . . . . . . . . . . . . 93628. System control offsets to callable services 95329. Support of signal calls . . . . . . . . 133430. Using exit or _exit when the thread is not

the IPT . . . . . . . . . . . . . 134131. Using exit or _exit when the thread is the

IPT . . . . . . . . . . . . . . 134232. Using pthread_exit_and_get when the thread

is not the IPT and not the last thread . . . 134333. Using pthread_cancel when the thread is not

the last thread and is canceled . . . . . 134434. Using pthread_exit_and_get when the thread

is the IPT and not the last thread . . . . 134435. Using pthread_exit_and_get when the thread

is not the IPT and is the last thread . . . . 134536. Using pthread_exit_and_get when the IPT is

the last thread . . . . . . . . . . . 134637. Optimization processing for BPX1PSI,

BPX4PSI (pthread_setintr) . . . . . . . 134738. Optimization processing for BPX1PST,

BPX4PST (pthread_setintrtype) . . . . . 134839. Optimization processing for BPX1SPM,

BPX4SPM (sigprocmask) . . . . . . . 134940. Environment at entry to exit routines 136041. Registers at entry to exit routines . . . . 136042. Registers at return from exit routines 136043. Values of nonzero return codes . . . . . 136144. Callable services that are not allowed from

syscall exit routines . . . . . . . . . 1362

Copyright IBM Corp. 1996, 2017 xvii

|||||||||||

xviii z/OS UNIX System Services Programming: Assembler Callable Services Reference

About this document

This document describes the features and usage requirements for the z/OS UNIXSystem Services (z/OS UNIX) callable services. These services are interfacesbetween the z/OS operating system and standard (POSIX or Single UNIXSpecification) programming functions that require operating system services. Forexample, programmers creating runtime library programs use these services. Thisbook also describes callable services that are not related to the standard interfaces.

System programmers coding programs in assembler can use these callable servicesto obtain the z/OS UNIX services they need. This document contains detailedinformationsuch as the function, requirements, syntax, linkage information,parameters, and usage informationthat is needed to use the services. In theappendixes you will find information about:v System control offsets to callable servicesv Mapping macrosv Callable service examplesv The relationship of signals to callable servicesv Using threads with callable servicesv Optimizing performance using process- and thread-level informationv Callable services available to SRB mode routinesv z/OS UNIX process start/end exitsv Accessibility featuresv Noticesv An index

Who should use this documentThis document is for assembler programmers who want to use z/OS UNIX SystemServices.

z/OS informationThis information explains how z/OS references information in other documentsand on the web.

When possible, this information uses cross document links that go directly to thetopic in reference using shortened versions of the document title. For completetitles and order numbers of the documents for all products that are part of z/OS,see z/OS Information Roadmap.

To find the complete z/OS library, go to IBM Knowledge Center(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).

z/OS UNIX coursesFor a current list of courses that you can take, go to the IBM Education home page(www.ibm.com/services/learning).

Copyright IBM Corp. 1996, 2017 xix

http://www.ibm.com/support/knowledgecenter/SSLTBW/welcomehttp://www.ibm.com/support/knowledgecenter/SSLTBW/welcomehttp://www.ibm.com/services/learninghttp://www.ibm.com/services/learning

z/OS UNIX home pageVisit the z/OS UNIX home page (www.ibm.com/systems/z/os/zos/features/unix).

Some of the tools available from the website are ported tools, and some areunsupported tools designed for z/OS UNIX. The code works in our environmentat the time we make it available, but is not officially supported. Each tool has areadme file that describes the tool and lists any restrictions.

The simplest way to reach these tools is through the z/OS UNIX home page. Fromthe home page, click the Tips tab.

The code is also available from ftp://ftp.software.ibm.com/s390/zos/tools/ throughanonymous FTP.

Because the tools are not officially supported, APARs cannot be accepted.

Discussion listCustomers and IBM participants also discuss z/OS UNIX on the mvs-oediscussion list. This list is not operated or sponsored by IBM.

To subscribe to the mvs-oe discussion, send a note to:listserv@vm.marist.edu

Include the following line in the body of the note, substituting your given nameand family name as indicated:subscribe mvs-oe given_name family_name

After you have been subscribed, you will receive further instructions on how touse the mailing list.

xx z/OS UNIX System Services Programming: Assembler Callable Services Reference

http://www.ibm.com/systems/z/os/zos/features/unixhttp://www.ibm.com/systems/z/os/zos/features/unix

How to send your comments to IBM

We appreciate your input on this documentation. Please provide us with anyfeedback that you have, including comments on the clarity, accuracy, orcompleteness of the information.

Use one of the following methods to send your comments:

Important: If your comment regards a technical problem, see instead If you havea technical problem.v Send an email to mhvrcfs@us.ibm.com.v Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/

zos/webqs.html).

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

z/OS UNIX System Services Programming: Assembler Callable ServicesReferenceSA23-2281-30

v The topic and page number or URL of the specific information to which yourcomment relates

v The text of your comment.

When you send comments to IBM, you grant IBM a nonexclusive right to use ordistribute the comments in any way appropriate without incurring any obligationto you.

IBM or any other organizations use the personal information that you supply tocontact you only about the issues that you submit.

If you have a technical problemDo not use the feedback methods that are listed for sending comments. Instead,take one or more of the following actions:v Visit the IBM Support Portal (support.ibm.com).v Contact your IBM service representative.v Call IBM technical support.

Copyright IBM Corp. 1996, 2017 xxi

mailto:mhvrcfs@us.ibm.comhttp://www.ibm.com/systems/z/os/zos/webqs.htmlhttp://www.ibm.com/systems/z/os/zos/webqs.htmlhttp://support.ibm.com

xxii z/OS UNIX System Services Programming: Assembler Callable Services Reference

Summary of changes

This information includes terminology, maintenance, and editorial changes.Technical changes or additions to the text and illustrations for the current editionare indicated by a vertical line to the left of the change.

Summary of changes for z/OS UNIX for Version 2 Release 3 (V2R3)Newv If a user has UPDATE access to the BPX.DAEMON resource, the user can now

invoke the pthread_security_np() service without a password or superuserauthority. See pthread_security_np, pthread_security_applid_np (BPX1TLS,BPX4TLS) Create or delete thread-level security on page 527.

v A new BPX.SMF.type.subtype FACILITY class profile was added to smf_record.Two reason codes were also added: JrSMFTypeSubtypeMismatch andJrSMFRecordLenMismatch. See smf_record (BPX1SMF, BPX4SMF) Write anSMF record on page 786.

v A usage note was added to smf_record. BPX.SMF.type.subtype profiles must bediscrete. See smf_record (BPX1SMF, BPX4SMF) Write an SMF record onpage 786.

v A new return code, ENOENT, was added to the symlink service. See symlink(BPX1SYM, BPX4SYM) Create a symbolic link to a path name on page 826.

v CPU usage is now tracked in microseconds. See __getthent (BPX1GTH,BPX4GTH) Get thread data on page 284 and BPXYPGTH Map the__getthent input/output structure on page 1025.

v With V2R2 APAR OA49056, a new usage note was added to select/selectex(BPX1SEL, BPX4SEL) Select on file descriptors and message queues on page627.

v With V2R2 APAR OA49896, the BPXCONS macro was updated to includeEnablePgmAuth and DisablePgmAuth. See BPXYCONS Constants used byservices on page 966.

v Support was added for both POSIX time values beyond year 2038 and z/OStime-of-day values beyond year 2042. Two new Command parameters were added to these callable services:

- msgctl (BPX1QCT, BPX4QCT) Perform message queue controloperations on page 395

- semctl (BPX1SCT, BPX4SCT) Perform semaphore control operations onpage 635

- shmctl (BPX1MCT, BPX4MCT) Perform shared memory controloperations on page 729

The Message_Flag parameter was updated. See msgrcv (BPX1QRC,BPX4QRC) Receive from a message queue on page 403.

A new field, PGTHCSTARTTIME64, was added to the BPXYPGPS andBPXYPGTH mapping macros. See BPXYPGPS Map the response structurefor w_getpsent on page 1022 and BPXYPGTH Map the __getthentinput/output structure on page 1025.

A usage note was added to utime (BPX1UTI, BPX4UTI) Set file access andmodification times on page 892.

Copyright IBM Corp. 1996, 2017 xxiii

v The new UMASK statement of the BPXPRMxx parmlib member can be used toassign a default umask value for all z/OS UNIX users, resulting in an update tothe BPXYOEXT macro. See BPXYOEXT Map the common external controlblock on page 1017.

v Support is provided for pre-syscall and post-syscall exit routines to be invokedfor select z/OS UNIX syscalls. See Appendix L, Dynamic syscall exits for z/OSUNIX, on page 1359.

Changedv The usage notes were updated for the BPX1EXC/BPXREXC callable service. See

exec (BPX1EXC, BPX4EXC) Run a program on page 135.v Two flags (AI_V4MAPPED and AI_ALL) for the getaddrinfo service were

updated for compliance with GetAddrInfo() IPv6 standards. See getaddrinfo(BPX1GAI, BPX4GAI) Get the IP address and information for a service nameor location on page 209.

v An additional condition that will cause a EPARM to be issued was added for theBPX1ENV/BPX4ENV callable service. See oe_env_np (BPX1ENV, BPX4ENV) Examine, change, or examine and change an environmental attribute on page442.

v Clarification about the required authority if the password is not needed wasadded to the BPX1TLS/BPX4TLS service. See pthread_security_np,pthread_security_applid_np (BPX1TLS, BPX4TLS) Create or deletethread-level security on page 527.

v To support the ability to unmount the version file system if it is no longer beingused in the sysplex, BPXYMNTE was updated. MntEntFSunmntVer was addedunder the MntEntBodyV3 structure. See BPXYMNTE Map response andelement structure of w_getmntent on page 1007.

v BPXYOEXT Map the common external control block on page 1017 wasupdated in support of the new BPXPRMxx statement, UMASK.

v One of the return values for the BPX1SDD service was updated to includeinformation about the DubProcessDefer option. See set_dub_default (BPX1SDD,BPX4SDD) Set the dub default service on page 676. The BPX1SDD examplewas also updated to include a complete list of return values. See BPX1SDD(setdubdefault) example on page 1203.

v BPXZOCVT Base control block for z/OS UNIX on page 1095 was updatedto include ocvtsuperuser as one of the fields that is externally documented.

Deletedv None.

Summary of changes for z/OS UNIX for Version 2 Release 2 (V2R2)Newv A usage note was added to the attach_exec service about UNIX set-user-ID or

set-group-ID privileged programs. A restriction was also documented for stickybit programs that have the set-user-ID or set-group-ID attributes. See Usagenotes for attach_exec on page 54.

v A usage note was added to the attach_execmvs service about UNIX set-user-IDor set-group-ID privileged programs. See Usage notes for attach_execmvs onpage 63.

v A usage note was added to the exec service about UNIX set-user-ID orset-group-ID privileged programs. A restriction was also documented for

xxiv z/OS UNIX System Services Programming: Assembler Callable Services Reference

external links and sticky bit programs that have the set-user-ID or set-group-IDattributes. See Usage notes for exec on page 139.

v A usage note was added to the execmvs service about UNIX set-user-ID orset-group-ID privileged programs. See Usage notes for execmvs on page 151.

v A usage note was added to the fork service about UNIX set-user-ID orset-group-ID privileged programs. See Usage notes for fork on page 190.

v Usage notes were added to the _getthent service. See Usage notes for__getthent on page 286.

v A usage note was added to the loadHFS service about UNIX set-user-ID orset-group-ID privileged programs. See Usage notes for loadhfs on page 343.

v A usage note was added to the loadHFS extended service about UNIXset-user-ID or set-group-ID privileged programs. See Usage notes for loadHFSon page 350.

v Usage notes were added to the pthread_exit_and_get service as a result of APAROA44404. See Usage notes for pthread_exit_and_get on page 517.

v A usage note was added to the seteuid service about UNIX set-user-ID orset-group-ID privileged programs. SeeUsage notes for seteuid on page 684.

v A usage note was added to the setreuid service about UNIX set-user-ID orset-group-ID privileged programs. SeeUsage notes for setreuid on page 707.

v A usage note was added to the setuid service about UNIX set-user-ID orset-group-ID privileged programs. See Usage notes for setuid on page 722.

v A usage note was added to the spawn service about UNIX set-user-ID orset-group-ID privileged programs. A restriction was also documented forexternal links and sticky bit programs that have the set-user-ID or set-group-IDattributes. See Usage notes for spawn on page 799.

v Two new constants were added to the BPXYCON macro. PC#MODIFYPFS PC#THREADUNDUB

See BPXYCONS Constants used by services on page 966.

Changedv APAR OA46726 clarified security requirements in Connecting to and

disconnecting from z/OS UNIX on page 1.v APAR OA46726 updated the Accepted_socket parameter of the BPXA1ANR

callable service to indicate that the SF_REUSE option for send_file is notsupported. See accept_and_recv (BPX1ANR, BPX4ANR) Accept a connectionand receive the first block of data on page 18.

v APAR OA46726 updated the BPX1SF callable service to indicate that theSF_REUSE option is not supported. See send_file (BPX1SF, BPX4SF) Send afile on a socket on page 653.

v Updates were made to the w_ioctl service as a result of APAR OA44631. Seew_ioctl (BPX1IOC, BPX4IOC) Control I/O on page 916.

v Updates were made to the w_pioctl service as a result of APAR OA44631.w_pioctl (BPX1PIO, BPX4PIO) Path name I/O control on page 938.

v The OAPB address is now obtained from the OTCB. See Overview of callableservices available to SRB mode routines on page 1351.

Deletedv PT_THREAD_INFO_EXTENDED is not a valid ptrace request parameter. All

references to it were deleted.

Summary of changes xxv

Summary of changes for z/OS UNIX for Version 2 Release 1 (V2R1) asupdated February, 2015

Newv Support was added for vectors. See ptrace (BPX1PTR, BPX4PTR) Control

another process for debugging on page 547 for information aboutPT_READ_VR and PT_WRITE_VR.

Changedv The BPXYPTRC macro was updated as a result of the added vector support. See

BPXYPTRC Map parameters for ptrace on page 1034.

Deleted

No content was removed from this information.

z/OS Version 2 Release 1 summary of changesSee the Version 2 Release 1 (V2R1) versions of the following publications for allenhancements related to z/OS V2R1:v z/OS Migrationv z/OS Planning for Installationv z/OS Summary of Message and Interface Changesv z/OS Introduction and Release Guide

xxvi z/OS UNIX System Services Programming: Assembler Callable Services Reference

Chapter 1. Invocation details for callable services

As an interface between the z/OS operating system and the functions specified inthe Single UNIX Specification and earlier standards, z/OS UNIX System Services(z/OS UNIX) provides access to assembler callable services (syscalls). The z/OSUNIX callable services have a standard set of syntax and linkage requirements, aswell as parameter specification details necessary for successful invocation.

Connecting to and disconnecting from z/OS UNIXTo connect to the kernel for z/OS UNIX System Services, you make an addressspace known to it. This process is called dubbing. After it has been dubbed, theaddress space is considered to be a process. Address spaces that are created by forkare automatically dubbed when they are created. Other address spaces becomedubbed if they invoke a z/OS UNIX service. Dubbing also applies to MVS tasks.A dubbed task is considered a thread. Tasks that are created by pthread_create areautomatically dubbed threads; other tasks are dubbed if they invoke a z/OS UNIXservice.

Undub is the inverse of dub. Normally, a task (dubbed a thread) is undubbed whenit ends. An address space (dubbed a process) is undubbed when the last threadends.

If, when a thread or process is being dubbed, the calling task has a task-levelACEE that does not have a USP connected to it, an INITUSP is done against thetask-level ACEE. This causes z/OS UNIX security information to be associatedwith the task-level ACEE.

Every address space that is dubbed is required to have an address space levelsecurity environment with a valid OMVS segment. In a multi-user address space, ifa task is dubbed and it has a security environment different from the addressspace, then the user ID that is identified with the task must also have a validOMVS segment.

Syntax conventions for the callable servicesA callable service is a programming interface that uses the CALL macro to accesssystem services. To code a callable service, code the CALL macro followed by thename of the callable service and a parameter list. A syntax diagram for a callableservice follows.

This format does not show the assembler column conventions (columns 1, 10, 16,and 72) or parameter list options (VL and MF). The exact syntax is shown in theexamples in Appendix D, Callable services examplesAMODE 31, on page 1141.

CALL Service_name,(Parm_1,Parm_2,..Return_value,Return_code,Reason_code)

Copyright IBM Corp. 1996, 2017 1

When you code a callable service you must:v Code all the parameters in the parameter list, because parameters are positional

in a callable service interface. The function of each parameter is determined byits position with respect to the other parameters in the list. Omitting aparameter, therefore, assigns the omitted parameter's function to the nextparameter in the list.

v Place values explicitly into all supplied parameters, because callable services donot set defaults.

CALLCALL is the assembler macro that transfers control and passes a parameter list.

Service_nameFor AMODE 31 callers, the name that the assembler understands is the name of amodule in the form BPX1xxx, where xxx is a three-character symbol unique to theservice. (In a few cases, where both standard and nonstandard versions of a serviceexist, the standard version of the service is in the form BPX2xxx.) AMODE 64callers use the name of a module in the form BPX4xxx. (See Using callableservices in a 64-bit environment on page 9.)

Modules are invoked in one of the following ways:v A program can load a module, and then branch to the address where it was

loaded.v When you link-edit a program, you can link to the linkage stub. The program

can issue a call.The linkage stubs are contained in SYS1.CSSLIB. You can specify SYS1.CSSLIB inthe //SYSLIB statement of the JCL that is used to invoke the linkage editor. Thiscauses the addresses of all required linkage-assist routines to be automaticallyresolved, and saves you the trouble of having to specify individual linkage-assistroutines in INCLUDE statements.For BPX4xxx stubs, you need 64-bit binder support to do the link-edit. SeeUsing callable services in a 64-bit environment on page 9.

v You can include in the code the system control offset to the callable service. SeeAppendix A, System control offsets to callable services, on page 953 forinformation on how to use this linkage.

For information about using callable services in AMODE 64, see Using callableservices in a 64-bit environment on page 9.

Parm parametersParm_1, Parm_2, and so on are placeholders for variables that may be part of aservice's syntax.

Return_valueThe Return_value parameter is common to many callable services, and indicatesthe success or failure of the service. If the callable service fails, it returns a -1 in theReturn_value. For most successful calls to z/OS UNIX services, the return value isset to 0. However, some services, such as getgrgid (BPX1GGI, BPX4GGI) Access the group database by ID on page 227 and getgrnam (BPX1GGN,BPX4GGN) Access the group database by name on page 230, return zerosinstead of -1 when the service fails.

Invocation details

2 z/OS UNIX System Services Programming: Assembler Callable Services Reference

Some callable services, such as fork (BPX1FRK, BPX4FRK) Create a newprocess on page 188, return a positive return value to indicate success. Otherservices, such as _exit (BPX1EXI, BPX4EXI) End a process and bypass thecleanup on page 154, are unique in that they do not return when successful.

Some services do not have a return value, because under normal conditions theydo not fail. System failures, however, may cause these services to fail, in whichcase, the process that issues the call ends abnormally. See getegid (BPX1GEG,BPX4GEG) Get the effective group ID on page 222 for an example.

Return_codeThe Return_code parameter is referred to as the errno in the POSIX and X/Open Cinterfaces. The Return_code is returned only if the service fails.

In the callable service descriptions, some of the possible return codes are listed forservices that have return codes. The return codes are described in each service ifthey help to describe its function.

For each return code, any reason code that may accompany it is identified.

The return codes and their descriptions can be found in z/OS UNIX System ServicesMessages and Codes.

Some Return_code values may occur for any callable service: the return codes thatare unique to z/OS UNIX. They are not always listed under each callable service.See z/OS UNIX System Services Messages and Codes for a description of these returncodes.

The following five return codes can occur with any callable service, and are notlisted with each service because the failure may occur before the syscall getscontrol:

Return_code ExplanationEFAULT An address is incorrect, usually because it is a zero pointer, an

uninitialized pointer, or a pointer to read-only storage (for example,a program constant of zero) for a parameter that is (or could be, ina different context) an output parameter.

EMVSINITIAL A process initialization error has occurred.EMVSERR An MVS environmental or internal error has occurred.EMVSPARM Bad parameters were passed to the service.ENOMEM Not enough space is available to fill the request.

Reason_codeThe Reason_code parameter usually accompanies the Return_code value when thecallable service fails, and further defines the return code. Reason codes do not havean equivalent in the POSIX or X/Open standards.

The reason codes and their descriptions can be found in z/OS UNIX System ServicesMessages and Codes. Reason codes are listed by name and numerically by value.The value is the lower half of the reason code.

Invocation details

Chapter 1. Invocation details for callable services 3

Determining the callable service release levelNew callable services may be added with each new z/OS UNIX release.Depending on the operating environment, the caller may have to determine therelease level of z/OS UNIX before a new callable service can be issued.

The release information is indicated in the CVT feature flags. For z/OS V1R1, thefeature flag is:CVTJ7713 EQU X20 JBB7713

Linkage conventions for the callable servicesCallers must use the following linkage conventions for all z/OS UNIX callableservices:v Register 1 is set up by the CALL macro. In 31-bit mode, it contains the address

of a parameter list, which is a list of consecutive words, each containing theaddress of a parameter to be passed. The last word in this list must have a 1 inthe high-order (sign) bit. In 64-bit mode, register 1 is 8 bytes long, and containsa 64-bit address that points to a list of 64-bit addresses. See Using callableservices in a 64-bit environment on page 9.

v Register 14 is set up by the CALL macro; it contains the return address.v Register 15 is set up by the CALL macro; it contains the entry point address of

the service stub that is being called.

On return from a callable service, general and access registers 2 through 13 arerestored. General and access registers 0, 1, 14, and 15 are not restored.

The caller does not have provide the address of a save area in register 13.

The caller must be running with 31-bit or 64-bit addressing (AMODE=31 orAMODE=64), because the linkage code uses control blocks that reside above the16-MB line.

For more information about linkage, see Linkage conventions in z/OS MVSProgramming: Authorized Assembler Services Guide.

Parameter descriptions for the callable servicesAll the parameters of the callable services are required positional parameters.When you specify a call, you must specify all the parameters in the order listed.

Note: Some parameters do not require values, and allow you to substitute zerosfor the parameter. The descriptions of the parameters identify those that can bereplaced by zeros, and when to do so.

In the descriptions of the calls, each parameter is described as supplied or returned:v Supplied means that you supply a value for the parameter in the call.v Returned means that the service returns a value in the named parameter when

the call is finished (for example, Return_code).v Some parameters are both supplied and returned.

Each parameter is also described in terms of its data type and length:v Data type is one of the following: integer, address, character string, or structure.v Length depends on the data type of the parameter:

Invocation details

4 z/OS UNIX System Services Programming: Assembler Callable Services Reference

|

For an address item, the length is a fullword (for AMODE 31 callers) or adoubleword (for AMODE 64 callers).

For an integer item, the length indicates the size of the field in bytes orfullwords: bytes are 1, 2, 3, 4, or 8.

For a character string parameter, the length indicates the number of charactersthat can be contained in a character-type parameter.

For a structure parameter, the length indicates the size of the structure inbytes or fullwords, or refers to a label in the structure's mapping macro thatdefines the length.

Call parameter listsEvery callable service is called with a parameter list. As shown in Figure 1, when aservice is called:v Register 1 points to a parameter address list.v Each field in the parameter address list points to a field containing a parameter.v The "parameter list" is the set of those parameters; however they are arranged in

storage. For AMODE 31 callers, the last parameter pointer in the list must havethe high-order bit set to 1. For AMODE 64 callers, there is no end-of-parameterlist indicator; the high-order bit is part of the 64-bit address.

Mapping macrosIn many callable services, mapping macros map the parameter opt