IBM Command Reference z/OS UNIX System Services Command Reference
PDF
Документ
Реклама
Реклама
z/OS UNIX System Services Command Reference SA22-7802-13 Note: Before using this information and the product it supports, be sure to read the general information under “Notices” on page 981. This edition applies to version 1 release 13 modification 0 of IBM z/OS (product number 5694-A01) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SA22-7802-13. © Copyright IBM Corporation 1996, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures . . . . . . . . . . . . . . . ix Tables . . . . . . . . . . . . . . . xi About this document . . . . . . . . xiii Using this document . . . . . Where to find more information . . . . . . . . . . . . xiii . xiii How to send your comments to IBM If you have a technical problem . . . . xvii . . . xvii Summary of changes . . . . . . . . xix Changes made in z/OS Changes made in z/OS Changes made in z/OS updated April 2010 . . Changes made in z/OS Version 1 Version 1 Version 1 . . . Version 1 Release Release Release . . . Release 13 12 11, . 11 . . as . . . . . xix . xix . . . xx . xx Chapter 1. Introduction to shell commands and DBCS. . . . . . . . . 1 Reading the command descriptions . . . . Using the double-byte character set (DBCS) . . . . . . 1 . 6 Chapter 2. Shell command descriptions 11 alias — Display or create a command alias . . . . 11 amblist — Display formatted information from object and executable files for diagnostic purposes . 14 ar — Create or maintain library archives . . . . 16 as — Use the HLASM assembler to produce object files . . . . . . . . . . . . . . . . . 19 asa — Interpret ASA/FORTRAN carriage control. . 23 at — Run a command at a specified time . . . . 24 autoload — Indicate function name not defined . . 27 automount — Configure the automount facility . . 27 awk — Process programs written in the awk language . . . . . . . . . . . . . . . 34 basename — Return the nondirectory components of a path name . . . . . . . . . . . . . 51 batch — Run commands when the system is not busy . . . . . . . . . . . . . . . . . 51 bc — Use the arbitrary-precision arithmetic calculation language . . . . . . . . . . . 52 bg — Move a job to the background . . . . . . 68 bpxmtext — Display reason code text . . . . . 69 bpxtrace — Activate or deactivate traces for processes . . . . . . . . . . . . . . . 70 break — Exit from a loop in a shell script . . . . 75 c++ — Compile C and C++ source code, link-edit and create an executable file . . . . . . . . . 75 c89 — Compiler invocation using host environment variables . . . . . . . . . . . . . . . 76 c99 — Compile C source code, link-edit and create an executable file . . . . . . . . . . . . 115 cal — Display a calendar for a month or year . . 115 © Copyright IBM Corp. 1996, 2011 calendar — Display all current appointments . . . cancel — Cancel print queue requests (stub command) . . . . . . . . . . . . . . captoinfo — Print the terminal entries in the terminfo database . . . . . . . . . . . . cat — Concatenate or display text files . . . . . cc — Compile C source code, link-edit and create an executable file . . . . . . . . . . . . cd — Change the working directory . . . . . . ceebldtx — Transform message source files into assembler source files . . . . . . . . . . chaudit — Change audit flags for a file. . . . . chcp — Set or query ASCII/EBCDIC code pages for the terminal. . . . . . . . . . . . . chgrp — Change the group owner of a file or directory . . . . . . . . . . . . . . . chlabel — Set the security label of files and directories . . . . . . . . . . . . . . chmod — Change the mode of a file or directory chmount — Change the mount attributes of a file system . . . . . . . . . . . . . . . chown — Change the owner or group of a file or directory . . . . . . . . . . . . . . . chroot — Change the root directory for the execution of a command . . . . . . . . . chtag — Change file tag information . . . . . cksum — Calculate and display checksums and byte counts . . . . . . . . . . . . . . clear — Clear the screen of all previous output . . cmp — Compare two files . . . . . . . . . col — Remove reverse line feeds . . . . . . . : (colon) — Do nothing, successfully . . . . . comm — Show and select or reject lines common to two files . . . . . . . . . . . . . . command — Run a simple command . . . . . compress — Lempel-Ziv file compression . . . . confighfs — Invoke the vfs_pfsctl function for HFS file systems . . . . . . . . . . . . . . configstk — Configure the AF_UEINT stack . . . configstrm — Set and query the STREAMS physical file system configuration . . . . . . continue — Skip to the next iteration of a loop in a shell script . . . . . . . . . . . . . . copytree — Make a copy of a file hierarchy while preserving all file attributes . . . . . . . . cp — Copy a file . . . . . . . . . . . . cpio — Copy in/out file archives . . . . . . . cron daemon — Run commands at specified dates and times . . . . . . . . . . . . . . crontab — Schedule regular background jobs . . . csplit — Split text files . . . . . . . . . . ctags — Create tag files for ex, more, and vi . . . cu — Call up another system (stub only) . . . . cut — Cut out selected fields from each line of a file . . . . . . . . . . . . . . . . . 116 117 118 119 121 121 123 126 128 131 132 134 137 138 140 142 145 146 147 148 150 151 152 153 155 157 159 160 160 162 175 178 181 183 186 188 188 iii cxx — Compile C and C++ source code, link-edit and create an executable file . . . . . . . . date — Display the date and time . . . . . . dbgld — Create a module map for debugging . . dbx — Use the debugger . . . . . . . . . dbx subcommands . . . . . . . . . . . dd — Convert and copy a file . . . . . . . . df — Display the amount of free space in the file system . . . . . . . . . . . . . . . diff — Compare two text files and show the differences . . . . . . . . . . . . . . dircmp — Compare directories . . . . . . . dirname — Return the directory components of a path name . . . . . . . . . . . . . . . (dot) — Run a shell file in the current environment. . . . . . . . . . . . . . dspcat — Display all or part of a message catalog dspmsg — Display selected messages from message catalogs . . . . . . . . . . . . du — Summarize usage of file space . . . . . echo — Write arguments to standard output . . . ed — Use the ed line-oriented text editor . . . . edcmtext — Display errnojr reason code text . . . egrep — Search a file for a specified pattern . . . env — Display or set environment variables for a process . . . . . . . . . . . . . . . eval — Construct a command by concatenating arguments . . . . . . . . . . . . . . ex — Use the ex text editor. . . . . . . . . exec — Run a command and open, close, or copy the file descriptors. . . . . . . . . . . . exit — Return to the shell's parent process or to TSO/E . . . . . . . . . . . . . . . expand — Expand tabs to spaces . . . . . . . export — Set a variable for export . . . . . . expr — Evaluate arguments as an expression . . . exrecover daemon — Retrieve vi and ex files . . . extattr — Set, reset, and display extended attributes for files . . . . . . . . . . . . false — Return a nonzero exit code . . . . . . fc — Process a command history list . . . . . fg — Bring a job into the foreground . . . . . fgrep — Search a file for a specified pattern . . . file — Determine file type . . . . . . . . . find — Find a file meeting specified criteria . . . filecache — Manage file caches . . . . . . . fold — Break lines into shorter lines. . . . . . functions — Display or assign attributes to functions . . . . . . . . . . . . . . . fuser — List process IDs of processes with open files . . . . . . . . . . . . . . . . gencat — Create or modify message catalogs . . . getconf — Get configuration values . . . . . . getfacl — Display owner, group, and access control list (ACL) entries . . . . . . . . . . . . getopts — Parse utility options . . . . . . . grep — Search a file for a specified pattern . . . hash — Create a tracked alias . . . . . . . . head — Display the first part of a file . . . . . history — Display a command history list . . . . iv 190 190 193 195 200 243 247 249 253 254 255 256 257 258 259 260 269 270 270 271 273 275 276 277 278 280 282 285 287 287 290 291 291 296 304 304 305 306 307 310 314 316 319 321 322 323 z/OS V1R12.0 UNIX System Services Command Reference iconv — Convert characters from one code set to another . . . . . . . . . . . . . . . id — Return the user identity . . . . . . . . inetd daemon — Provide service management for networks . . . . . . . . . . . . . . . infocmp — Compare or print the terminal description . . . . . . . . . . . . . . integer — Mark each variable with an integer value . . . . . . . . . . . . . . . . ipcrm — Remove message queues, semaphore sets, or shared memory IDs . . . . . . . . . . ipcs — Report status of the interprocess communication facility . . . . . . . . . . jobs — Return the status of jobs in the current session . . . . . . . . . . . . . . . join — Join two sorted textual relational databases kill — End a process or job, or send it a signal . . [ (left bracket) — Test for a condition . . . . . ld — Link object files. . . . . . . . . . . let — Evaluate an arithmetic expression . . . . lex — Generate a program for lexical tasks . . . line — Copy one line of standard input . . . . link — Create a hard link to a file . . . . . . ln — Create a link to a file . . . . . . . . . locale — Get locale-specific information . . . . localedef — Define the locale environment . . . logger — Log messages . . . . . . . . . . logname — Return a user's login name . . . . . lp — Send a file to a printer . . . . . . . . lpstat — Show status of print queues (stub command) . . . . . . . . . . . . . . ls — List file and directory names and attributes mail — Read and send mail messages . . . . . mailx — Send or receive electronic mail . . . . make — Maintain program-generated and interdependent files . . . . . . . . . . . makedepend — Generate source dependency information . . . . . . . . . . . . . . man — Display sections of the online reference manual . . . . . . . . . . . . . . . mesg — Allow or refuse messages . . . . . . mkcatdefs — Preprocess a message source file . . mkdir — Make a directory . . . . . . . . . mkfifo — Make a FIFO special file . . . . . . mknod — Make a FIFO or character special file more — Display files on a page-by-page basis . . mount — Logically mount a file system . . . . mv — Rename or move a file or directory . . . . newgrp — Change to a new group . . . . . . nice — Run a command at a different priority . . nl — Number lines in a file . . . . . . . . nm — Display symbol table of object, library, or executable files . . . . . . . . . . . . . nohup — Start a process that is immune to hang ups . . . . . . . . . . . . . . . . . obrowse — Browse a z/OS UNIX file . . . . . od — Dump a file in a specified format . . . . oedit — Edit files in a z/OS UNIX file system . . pack — Compress files by Huffman coding . . . passwd — Change user passwords or password phrases . . . . . . . . . . . . . . . 324 326 328 330 334 335 336 343 345 347 350 350 358 360 362 363 364 368 372 374 376 377 378 379 385 388 408 430 437 439 440 442 444 445 446 450 454 467 469 470 472 475 476 477 480 482 484 | paste — Merge corresponding or subsequent lines of a file . . . . . . . . . . . . . . . patch — Change a file using diff output . . . . pathchk — Check a path name . . . . . . . pax — Interchange portable archives . . . . . pcat — Unpack and display Huffman packed files pg — Display files interactively . . . . . . . pr — Format a file in paginated form and send it to standard output . . . . . . . . . . . print — Return arguments from the shell . . . . printenv — Display the values of environment variables . . . . . . . . . . . . . . . printf — Write formatted output . . . . . . . ps — Return the status of a process . . . . . . pwd — Return the working directory name . . . r — Process a command history list . . . . . . read — Read a line from standard input . . . . readonly — Mark a variable as read-only . . . . renice — Change priorities of a running process return — Return from a shell function or . (dot) script . . . . . . . . . . . . . . . . rlogind — Validate rlogin requests . . . . . . rm — Remove a directory entry . . . . . . . rmdir — Remove a directory . . . . . . . . runcat — Pipe output from mkcatdefs to gencat script — Makes a typescript of a terminal session sed — Start the sed noninteractive stream editor set — Set or unset command options and positional parameters. . . . . . . . . . . setfacl — Set, remove, and change access control lists (ACLs) . . . . . . . . . . . . . . sh — Invoke a shell . . . . . . . . . . . shedit — Interactive command and history editing in the shell . . . . . . . . . . . . . . shift — Shift positional parameters . . . . . . sleep — Suspend execution of a process for an interval of time . . . . . . . . . . . . . skulker — Remove old files from a directory . . . sort — Start the sort-merge utility . . . . . . spell — Detect spelling errors in files . . . . . split — Split a file into manageable pieces . . . . stop — Suspend a process or job . . . . . . . strings — Display printable strings in binary files strip — Remove unnecessary information from an executable file . . . . . . . . . . . . . stty — Set or display terminal options . . . . . su — Change the user ID associated with a session submit — Submit a batch job for background processing . . . . . . . . . . . . . . sum — Calculate and display checksums and block counts . . . . . . . . . . . . . . . . suspend — Send a SIGSTOP to the current shell sysvar — Display static system symbols . . . . tabs — Set tab stops . . . . . . . . . . . tail — Display the last part of a file . . . . . . talk — Talk to another user. . . . . . . . . tar — Manipulate the tar archive files to copy or back up a file . . . . . . . . . . . . . tcsh — Invoke a C shell . . . . . . . . . . tcsh built-in command descriptions . . . . . . tee — Duplicate the output stream . . . . . . 485 486 490 491 521 522 526 529 530 531 533 541 542 542 544 545 547 547 549 551 552 552 554 560 563 568 597 604 605 606 609 615 617 618 619 621 622 628 631 633 635 635 636 638 639 641 649 696 716 test — Test for a condition . . . . . . . . . tic — Put terminal entries in the terminfo database time — Display processor and elapsed times for a command . . . . . . . . . . . . . . times — Get process and child process times . . . touch — Change the file access and modification times . . . . . . . . . . . . . . . . tput — Change characteristics of terminals . . . tr — Translate characters . . . . . . . . . trap — Intercept abnormal conditions and interrupts. . . . . . . . . . . . . . . true — Return a value of 0 . . . . . . . . . tso — Run a TSO/E command from the shell . . tsocmd — Run a TSO/E command from the shell (including authorized commands) . . . . . . tsort — Sort files topologically. . . . . . . . tty — Return the user's terminal name . . . . . type — Tell how the shell interprets a name . . . typeset — Assign attributes and values to variables uconvdef — Create binary conversion tables . . . ulimit — Set process limits . . . . . . . . . umask — Set or return the file mode creation mask unalias — Remove alias definitions . . . . . . uname — Display the name of the current operating system . . . . . . . . . . . . uncompress — Undo Lempel-Ziv compression of a file . . . . . . . . . . . . . . . . . unexpand — Compress spaces into tabs . . . . uniq — Report or filter out repeated lines in a file unlink — Removes a directory entry . . . . . unmount — Remove a file system from the file hierarchy . . . . . . . . . . . . . . . unpack — Decode Huffman packed files . . . . unset — Unset values and attributes of variables and functions . . . . . . . . . . . . . uptime — Report how long the system has been running . . . . . . . . . . . . . . . uucc — Compile UUCP configuration files . . . uucico daemon — Process UUCP file transfer requests . . . . . . . . . . . . . . . uucp — Copy files between remote UUCP systems uucpd daemon — Invoke uucico for TCP/IP connections from remote UUCP systems . . . . uudecode — Decode a transmitted binary file . . uuencode — Encode a file for safe transmission uulog — Display log information about UUCP events . . . . . . . . . . . . . . . . uuname — Display list of remote UUCP systems uupick — Manage files sent by uuto and uucp . . uustat — Display status of pending UUCP transfers . . . . . . . . . . . . . . . uuto — Copy files to users on remote UUCP systems . . . . . . . . . . . . . . . uux — Request command execution on remote UUCP systems . . . . . . . . . . . . . uuxqt daemon — Carry out command requests from remote UUCP systems . . . . . . . . vi — Use the display-oriented interactive text editor . . . . . . . . . . . . . . . . wait — Wait for a child process to end . . . . . wall — Broadcast a message to logged-in users . . Contents 717 721 722 723 724 726 728 731 732 733 737 739 740 741 742 744 745 746 748 749 750 751 752 754 754 757 758 759 760 761 763 767 768 769 770 772 773 774 778 779 782 784 816 817 v wc — Count newlines, words, and bytes . . . . whence — Tell how the shell interprets a command name . . . . . . . . . . . . . . . . who — Display information about current users whoami — Display your effective user name . . . write — Write to another user . . . . . . . . writedown — Set or display user's write-down mode . . . . . . . . . . . . . . . . xlc — Compiler invocation using a customizable configuration file . . . . . . . . . . . . xlC — Compile C and C++ source code, link-edit and create an executable file . . . . . . . . xlc++ — Compile C and C++ source code, link-edit and create an executable file . . . . . . . . xargs — Construct an argument list and run a command . . . . . . . . . . . . . . yacc — Use the yacc compiler . . . . . . . . zcat — Uncompress and display data . . . . . 817 819 819 821 821 823 824 845 Appendix B. Summary of tcsh shell commands . . . . . . . . . . . . 913 General use . . . . . . . Controlling your environment . Managing directories . . . . Computing and managing logic Managing files . . . . . . Controlling processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913 913 914 914 914 914 Appendix C. Regular expressions (regexp) . . . . . . . . . . . . . . 915 845 Summary. Examples . 846 849 853 Appendix D. Running shell scripts or executable files under MVS environments . . . . . . . . . . . 921 Chapter 3. TSO/E commands. . . . . 855 BPXBATCH . . . . . . . . . . . . . . 921 Using OSHELL to run shell commands and scripts from MVS . . . . . . . . . . . . . . 929 BPXBATCH — Run shell commands, shell scripts, or executable files . . . . . . . . . . . . ISHELL — Invoke the ISPF shell . . . . . . . MKDIR — Make a directory . . . . . . . . MKNOD — Create a character special file . . . . MOUNT — Logically mount a file system . . . . OBROWSE — Browse a z/OS UNIX file . . . . OCOPY — Copy an MVS data set member or z/OS UNIX file to another member or file. . . . OEDIT — Edit a z/OS UNIX file . . . . . . . OGET — Copy z/OS UNIX files into an MVS data set . . . . . . . . . . . . . . . . . OGETX — Copy z/OS UNIX files from a directory to an MVS PDS or PDSE . . . . . . . . . OMVS — Invoke the z/OS shell . . . . . . . OPUT — Copy an MVS data set member into a z/OS UNIX file . . . . . . . . . . . . OPUTX — Copy members from an MVS PDS or PDSE to a z/OS UNIX system directory . . . . OSHELL — Invokes BPXBATCH from TSO/E . . OSTEPLIB — Build a list of files . . . . . . . UNMOUNT — Remove a file system from the file hierarchy . . . . . . . . . . . . . . . 856 858 860 861 862 868 869 874 875 879 882 895 898 901 901 903 Appendix A. Summary of z/OS UNIX shell commands . . . . . . . . . . 907 General use . . . . . . . . . . . . Controlling your environment . . . . . . Daemons . . . . . . . . . . . . . Managing directories . . . . . . . . . Managing files . . . . . . . . . . . Printing files . . . . . . . . . . . Computing and managing logic . . . . . Controlling processes . . . . . . . . . Writing shell scripts . . . . . . . . . Developing or porting application programs . Communicating with the system or other users Working with archives . . . . . . . . Working with UUCP . . . . . . . . . vi . . . . . . . . . . . . . . . . . . . . . . . . . . 907 907 908 908 909 910 910 911 911 911 912 912 912 z/OS V1R12.0 UNIX System Services Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 918 . 918 Appendix E. BPXCOPY: Copying a sequential or partitioned data set or PDSE member into an HFS file . . . . 931 BPXCOPY . . . . . . . . Appendix F. Localization . . . . . . 931 . . . . . . 937 Appendix G. Stub Commands . . . . 941 Appendix H. File formats . . . . . . 943 cpio — Format of cpio archives . . . . . . magic — Format of the /etc/magic file. . . . pax — Format of pax archives and special header summary files . . . . . . . . . . . . queuedefs — Queue description for at, batch, and cron . . . . . . . . . . . . . . . tags — Format of the tags file . . . . . . . tar — Format of tar archives . . . . . . . utmpx — Format of login accounting files . . . uucp — Format of UUCP working files . . . . 943 . 944 . 947 . . . . . 951 952 952 954 955 Appendix I. Format of the TZ environment variable . . . . . . . . 961 Command format . . . . . . . . . . . Appendix J. Environment variables . 961 963 Appendix K. Specifying MVS data set names in the shell environment . . . 965 Utilities that support MVS data set names . . . . 965 Appendix L. Automatic code set conversion: default status for specific commands . . . . . . . . . . . . 967 Appendix M. Additional dbx documentation . . . . . . . . . . . 969 execution: Controlling execution . . files: Accessing source files . . . . scope: Scope. . . . . . . . . threads: Thread display and control . usage: Basic command usage . . . variables: "Set" variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 969 969 970 970 971 Appendix N. Shell commands changed for UNIX03 . . . . . . . . 975 Using assistive technologies . . . . . Keyboard navigation of the user interface . z/OS information . . . . . . . . . . . . . . . . 979 . 979 . 979 Notices . . . . . . . . . . . . . . 981 Policy for unsupported hardware. Programming Interface Information Standards . . . . . . . . Trademarks . . . . . . . . Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982 982 982 983 983 Index . . . . . . . . . . . . . . . 985 Appendix O. Accessibility . . . . . . 979 Contents vii viii z/OS V1R12.0 UNIX System Services Command Reference Figures 1. Example of a special header summary file © Copyright IBM Corp. 1996, 2011 947 ix x z/OS V1R12.0 UNIX System Services Command Reference Tables 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. Locales supplied by z/OS UNIX . . . . . . 4 The order of operations for awk . . . . . 38 Reference documentation for programs invoked by c89, cc, and c++ commands . . . 76 Possible txtflag / CCSID combinations 144 Automatic conversion and file tagging behavior: Copying UNIX files to UNIX files . 167 Automatic conversion and file tagging behavior: Copying MVS data sets to UNIX files. . . . . . . . . . . . . . . 167 Automatic conversion and file tagging behavior: Copying UNIX files to MVS data sets . . . . . . . . . . . . . . . 168 cp Format: File to File and File ... (multiple files) to directory . . . . . . . . . . 170 cp Format: File to File. . . . . . . . . 171 cp Format: File... (multiple files) to Directory 172 file command tests . . . . . . . . . . 294 Output messages of the file utility . . . . 295 Fields in the configuration file (inetd daemon) 329 Explanation of the ipcs command listing 336 Internal table sizes (lex command) . . . . 361 Automatic conversion and file tagging behavior: Moving UNIX files to UNIX files . 459 Automatic conversion and file tagging behavior: Moving MVS data sets to UNIX files. . . . . . . . . . . . . . . 459 Automatic conversion and file tagging behavior: Moving UNIX files to MVS data sets . . . . . . . . . . . . . . . 460 mv Format: File to File and File ... (multiple files) to directory . . . . . . . . . . 462 mv Format: File to File . . . . . . . . 463 mv Format: File... (multiple files) to directory 463 © Copyright IBM Corp. 1996, 2011 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. String values for exthdr.name . . . . . . String values for globexthdr.name. . . . . USTAR defaults . . . . . . . . . . . Maximum UID and GID values for tar, USTAR, cpio and pax . . . . . . . . . Charset standards . . . . . . . . . . Shell operators (sh command) . . . . . . Built-in shell variables (sh command) Shell variables for automatic conversion (sh command) . . . . . . . . . . . . Recommended options for the USTAR format Standard input/output syntax for the tcsh shell . . . . . . . . . . . . . . List of built-in commands for tcsh . . . . tcsh built-in shell variables . . . . . . . tcsh environment variables . . . . . . . tcsh shell variables for automatic conversion Example of using -M and -MF . . . . . . Compiler option conflict resolution . . . . Various formats of the OMVS CONVERT command (OMVS command) . . . . . . Locales, their conversion tables, and default escape characters (OMVS command) . . . . Regular Expression Features (regexp) Archive File: ASCII Header . . . . . . . Example of a pax format archive . . . . . Archive File: UNIX-compatible format Archive File: USTAR format . . . . . . Commands that allow automatic conversion by default. . . . . . . . . . . . . Commands that disallow automatic conversion by default . . . . . . . . . UNIX shell commands and _UNIX03 497 498 500 507 509 582 590 593 642 669 676 679 692 693 840 843 884 885 918 943 949 953 953 967 967 975 xi xii z/OS V1R12.0 UNIX System Services Command Reference About this document This document presents the information you need to use a z/OS system with the shell and utilities feature as well as TSO/E (Time Sharing Option Extensions) commands for using z/OS UNIX System Services (z/OS UNIX). These features provide an application program interface (API) and a shell interface based on open systems standards. z/OS UNIX gives the z/OS operating system an open standards interface. It consists of two features: v Shell and Utilities, which you can use to enter shell commands, write shell scripts, and work with the file system. v Debugger, which an application programmer can use to debug a z/OS UNIX application program written in the C or C++ languages. This document describes how to use the shell commands, utilities, and TSO/E commands. For information about utilities related to ported applications, see http://www.ibm.com/servers/eserver/zseries/zos/unix/port_tools.html. Using this document This document is for application programmers, system programmers, and end users working on a z/OS system and using the shell. This information supports z/OS® (5694-A01) and contains information about z/OS UNIX commands. This document also assumes that you are using Security Server for z/OS. RACF® is a component of the Security Server for z/OS. Instead of RACF, you could use an equivalent security product if it supports the system authorization facility (SAF) interfaces required by z/OS UNIX, which are documented in z/OS Security Server RACF Callable Services. Where to find more information Where necessary, this document references information in other documents about the elements and features of the z/OS system. For complete titles and order numbers for all z/OS documents, see z/OS Information Roadmap. Softcopy publications The z/OS UNIX library is available on the z/OS and Software Products DVD Collection, SK2T-4271. PDF versions of the publications are available at http://www.ibm.com/systems/ z/os/zos/bkserv/. Use Adobe Reader to view them. © Copyright IBM Corp. 1996, 2011 xiii IBM Systems Center publications IBM® Systems Centers produce IBM Redbooks® publications that can be helpful in setting up and using z/OS UNIX. See the IBM Redbooks site at http://www.ibm.com/redbooks. These documents have not been subjected to any formal review nor have they been checked for technical accuracy, but they represent current product understanding at the time of their publication and provide information on a wide range of topics. You must order them separately. A selected list of these documents is on the z/OS UNIX website at http://www.ibm.com/systems/z/os/zos/features/unix/library/. Porting information for z/OS UNIX A Porting Guide is available at http://www.ibm.com/systems/z/os/zos/features/ unix/bpxa1por.html. It covers a range of useful topics, including sizing a port, setting up a porting environment, ASCII-EBCDIC issues, performance, and much more. The porting page also features a variety of porting tips and lists porting resources that will help you in your port. z/OS UNIX courses For a current list of courses that you can take, go to http://www.ibm.com/ services/learning/. z/OS UNIX home page Visit the z/OS UNIX home page at http://www.ibm.com/systems/z/os/zos/ features/unix/. Some of the tools available from the website are ported tools, and some are unsupported tools designed for z/OS UNIX. The code works in our environment at the time we make it available, but is not officially supported. Each tool has a readme file that describes the tool and lists any restrictions. The simplest way to reach these tools is through the z/OS UNIX home page. From the home page, click on Tools and Toys. The code is also available from ftp://ftp.software.ibm.com/s390/zos/unix/ through anonymous FTP. Restrictions Because the tools are not officially supported, APARs cannot be accepted. Discussion list Customers and IBM participants also discuss z/OS UNIX on the mvs-oe discussion list. This list is not operated or sponsored by IBM. To subscribe to the mvs-oe discussion, send a note to: [email protected] Include the following line in the body of the note, substituting your given name and family name as indicated: xiv z/OS V1R12.0 UNIX System Services Command Reference subscribe mvs-oe given_name family_name After you have been subscribed, you will receive further instructions on how to use the mailing list. The z/OS Basic Skills Information Center The z/OS Basic Skills Information Center is a Web-based information resource intended to help users learn the basic concepts of z/OS, the operating system that runs most of the IBM mainframe computers in use today. The Information Center is designed to introduce a new generation of Information Technology professionals to basic concepts and help them prepare for a career as a z/OS professional, such as a z/OS system programmer. Specifically, the z/OS Basic Skills Information Center is intended to achieve the following objectives: v Provide basic education and information about z/OS without charge v Shorten the time it takes for people to become productive on the mainframe v Make it easier for new people to learn z/OS. To access the z/OS Basic Skills Information Center, open your Web browser to the following Web site, which is available to all users (no login required): http://publib.boulder.ibm.com/infocenter/zoslnctr/v1r7/index.jsp About this document xv xvi z/OS V1R12.0 UNIX System Services Command 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 that you might have. Use one of the following methods to send us your comments: 1. Send an email to [email protected] 2. Visit the Contact z/OS web page at http://www.ibm.com/systems/z/os/zos/ webqs.html 3. Mail the comments to the following address: IBM Corporation Attention: MHVRCFS Reader Comments Department H6MA, Building 707 2455 South Road Poughkeepsie, NY 12601-5400 U.S.A. 4. Fax the comments to us as follows: From the United States and Canada: 1+845+432-9405 From all other countries: Your international access code +1+845+432-9405 Include the following information: v Your name and address v Your email address v Your telephone or fax number v The publication title and order number: z/OS V1R12.0 UNIX System Services Command Reference SA22-7802-13 v The topic and page number related to your comment v The text of your comment. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you submit. If you have a technical problem Do not use the feedback methods listed above. Instead, do one of the following: v Contact your IBM service representative v Call IBM technical support v Visit the IBM zSeries support web page at http://www.ibm.com/systems/z/ support/ © Copyright IBM Corp. 1996, 2011 xvii xviii z/OS V1R12.0 UNIX System Services Command Reference Summary of changes Changes made in z/OS Version 1 Release 13 This document contains information that was previously presented in z/OS UNIX System Services Command Reference, SA22-7808-12, which supports z/OS Version 1 Release 12. New shell command: script Changed shell commands: bpxtrace df c89 ex mount obrowse oedit sh tee tcsh unmount vi xlc Changed TSO/E commands: ISHELL OBROWSE OEDIT MOUNT UNMOUNT Miscellaneous update: v Appendix L, “Automatic code set conversion: default status for specific commands,” on page 967 was updated. z/OS Summary of Message and Interface Changes lists new or changed shell and TSO/E commands for this release. It also lists new or changed environment variables for this release, if any. Changes made in z/OS Version 1 Release 12 This document contains information previously presented in z/OS UNIX System Services Command Reference, SA22-7802-12, which supports z/OS Version 1 Release 11. New shell command: tsocmd Changed shell commands: automount bpxtrace chtag © Copyright IBM Corp. 1996, 2011 ls mv pax xix chtag cp dbgld dbx extattr fuser kill rmdir skulker su test tso xlc UNMOUNT Miscellaneous updates: The following restriction was removed from the automount command: The automount function requires the zFS file system to be a compatibility mode file system. zFS file systems in multi-file system aggregates will not work with automount. A usage note was added to the dbx subcommands goto and gotoi. The list of pax extended header keywords in “pax extended header” on page 950 was moved to “Extended header keywords” on page 508. A usage note was clarified in Appendix E, “BPXCOPY: Copying a sequential or partitioned data set or PDSE member into an HFS file,” on page 931. A new restriction (MVS data sets defined with DSNTYPE=LARGE are not supported) was added to “Utilities that support MVS data set names” on page 965. The Reader's Comment form at the back of this publication has been replaced with “How to send your comments to IBM” on page xvii. Changes made in z/OS Version 1 Release 11, as updated April 2010 This document contains information previously presented in z/OS UNIX System Services Command Reference, SA22-7802-11, which supports z/OS Version 1 Release 11. Deleted TSO/E command: Because the OHELP command is no longer available, information about it was deleted. Changes made in z/OS Version 1 Release 11 This document contains information previously presented in z/OS UNIX System Services Command Reference, SA22-7802-10, which supports z/OS Version 1 Release 10. New shell command: bpxtrace Changed shell commands: automount chmount dbgld xx z/OS V1R12.0 UNIX System Services Command Reference skulker tar unmount dbx find kill makedepend ps xlc OGETX OPUTX UNMOUNT Miscellaneous updates: These commands were updated to explain that MVS fixed block data sets have a fixed record length, which means that trailing blanks could exist up to the end of each record: cp, mv, OCOPY, OPUT, OPUTX, and BPXBATCH. The descriptions of the variables for the set subcommand of dbx were updated in “set subcommand for dbx: Define a value for a dbx variable” on page 227 and “variables: "Set" variables” on page 971. The term “internationalization” was replaced with “globalization”. z/OS Summary of Message and Interface Changes lists new or changed shell and TSO/E commands for this release. It also lists new or changed environment variables for this release, if any. Summary of changes xxi xxii z/OS V1R12.0 UNIX System Services Command Reference Chapter 1. Introduction to shell commands and DBCS This section is an introduction to the shell commands and the double-byte character set (DBCS). Reading the command descriptions Each shell command appears in alphabetic order. The description for each command is divided into several topics, which are explained in the following paragraphs. Some of these topics apply only to a few command descriptions. Also, some command descriptions include special topics that are not explained here. Format The Format topic provides a quick summary of the command's format, or syntax. The syntax was chosen to conform to general UNIX usage. For example, here is the format of the ls command: ls [–AabCcdFfgiLlmnopqRrstuWx1] [pathname ...] The format takes the form of a command line as you might type it into the system; it shows what you can type in and the order in which you should do it. The parts enclosed in square brackets are optional; you can omit them if you choose. Parts outside the square brackets must be present for the command to be correct. The format begins with the name of the command itself. Command names always appear in bold font. After the command name comes a list of options, if there are any. A typical z/OS shell command option consists of a dash (–) followed by a single character, typically an uppercase or lowercase letter. For example, you might have –A or –a. Note: The case of letters is important; for example, in the format of ls, –a and –A are different options, with different effects. If you are going to specify several options for the same command, you can put all the option characters after the same dash. Or you can put each option after its own dash. Or you can rearrange the order of options. For example, the following formats are all equivalent: ls -Aa ls -a -A ls -aA The format line shows options like -a in bold font. In the description of ls, all options are shown in one long string after the single dash. But another common option form is: -x value where –x is a dash followed by a character, and value provides extra information for using that option. For example, here is the format for the sort command, which takes unsorted input and sorts it: sort [–cmu] [–o outfile] [–t char] © Copyright IBM Corp. 1996, 2011 1 [–yn] [–zn] [–bdfiMnr] [-k startpos[,endpos]] ... [file ...] sort [–cmu] [–o outfile] [–tchar] [–yn] [–zn] [–bdfiMnr] [+startposition[–endposition]] ... [file ...] You can see that there are two possibilities here; you would need to choose which of the two versions of sort met your requirements. In either possibility, however, we have the option: –o outfile This option tells the sort command where to save its sorted output. The form of the option is –o, followed by a space, followed by outfile. In a command format, anything appearing in italic serif font is a placeholder for information that you are expected to supply. Sometimes after the format, the kind of information expected in place of the placeholder is explained. In our sort example, outfile stands for the name of a file where you want sort to store its output. For example, if you wanted to store the output in the file sorted.dat, you would specify: sort -o sorted.dat (followed by the rest of the command). The format for sort also contains an option of the form: –tchar This is similar to the option form we were just discussing, except that there is no space between the –t and char. char in italics is a placeholder; in this case, it stands for any single character. If you want to use the –t option for sort, you just type –t followed immediately by another character, as in: sort -t: In this case, we use a colon (:) in the position of the placeholder char. The end of the sort format is: [file ...] This means a list of one or more file names; the ellipsis (....) stands for repetitions of whatever immediately precedes it. Since there are square brackets around the previous list, you can omit the list if you like. The format of ls ended in: [pathname ...] As you might guess, this means that an ls command can end with an optional list of one or more path names. What's the difference between this and our sort example? A path name (specified with pathname) can be the name of either a file or a directory; a file name (specified with file) is always the name of a file. 2 z/OS V1R12.0 UNIX System Services Command Reference The order of items on the command line is important. When you type a command line, you should specify its parts in the order they appear in the command format. The exceptions to this are options marked with a dash (–); they do not have to be given in the exact order shown in the format. However, all the – options must appear in the correct area of the command line. For example, you can specify: ls -l -t myfiles ls -t -l myfiles but you won't get correct results if you specify: ls myfiles -l -t ***incorrect*** or: ls -l myfiles -t ***incorrect*** and so on. If you enter the last example, for instance, ls interprets –t as the path name of a file or directory, and the command will try to list the characteristics of that item. As a special notation, most z/OS shell commands let you specify two dashes (––) to separate the options from the nonoption arguments; –– means: “There are no more options.” Thus, if you really have a directory named –t, you could specify: ls –– –t to list the contents of that directory. Description The Description topic describes what the command does. For a particularly complex command, this topic may be divided into a large number of subtopics, each dealing with a particular aspect of the command. The Description topic often mentions the standard input (stdin) and the standard output (stdout). The standard input is typically the workstation keyboard; the standard output is typically the display screen. The process of redirection can change this. Redirection is explained in z/OS UNIX System Services User's Guide. The shell differentiates between hexadecimal, octal, and decimal format as follows: v Any number that starts with 0x is in hexadecimal format. v Any number that starts with 0 is in octal format. v Any number that does not start with 0x or 0 is in decimal format. Options The Options topic describes each of the options used by the command. Examples The Examples topic is present in many command descriptions, giving examples of how the z/OS shell can be used. Trying the examples provided Before you try to run any of the provided examples, you need to know that the z/OS shell uses the EBCDIC code page 01047 (Latin-1). Characters entered on a workstation keyboard and passed to the shell by z/OS do not have the same hexadecimal encoding as the code page used by the shell. You may need to Chapter 1. Introduction to shell commands and DBCS 3 customize your keyboard so that those characters have the encoding that the shell uses. See z/OS UNIX System Services User's Guide for more information about code page conversion. Environment variables The Environment Variables topic lists the environment variables that affect the command, if any, and describes the purposes that those variables serve. For example, the ls command description lists two environment variables (COLUMNS and TZ). It also explains that COLUMNS is the terminal width and that TZ contains information about the local time zone. Localization All shell commands are affected by the following special localization variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH The Localization topic describes how the locale-related environment variables affect the behavior of the command. These environment variables allow you to access locale information, including alternate character sets; alternate numeric, monetary, and date and time formats; and foreign language translations of common messages. Locales make it easier for users around the world to use the shell and utilities. z/OS UNIX supports the IBM-supplied locales listed in Table 1. User-generated locales using IBM code page 1047 are also supported. Table 1. Locales supplied by z/OS UNIX Country or region Language Bulgaria Bulgarian Czech Republic Czech Denmark Danish Denmark Danish Switzerland German Switzerland German Germany German Germany German Greece Ellinika United Kingdom English United Kingdom English Japan English United States English United States English Spain Spanish Spain Spanish Finland Finnish Finland Finnish Belgium French Belgium French Canada French Canada French Switzerland French Switzerland French France French France French 4 z/OS V1R12.0 UNIX System Services Command Reference Locale name Bg_BG.IBM-1025 Cs_CZ.IBM-870 Da_DK.IBM-277 Da_DK.IBM-1047 De_CH.IBM-500 De_CH.IBM-1047 De_DE.IBM-273 De_DE.IBM-1047 El_GR.IBM-875 En_GB.IBM-285 En_GB.IBM-1047 En_JP.IBM-1027 En_US.IBM-037 En_US.IBM-1047 Es_ES.IBM-284 Es_ES.IBM-1047 Fi_FI.IBM-278 Fi_FI.IBM-1047 Fr_BE.IBM-500 Fr_BE.IBM-1047 Fr_CA.IBM-037 Fr_CA.IBM-1047 Fr_CH.IBM-500 Fr_CH.IBM-1047 Fr_FR.IBM-297 Fr_FR.IBM-1047 Table 1. Locales supplied by z/OS UNIX (continued) Country or region Language Croatia Croatian Hungary Hungarian Iceland Icelandic Iceland Icelandic Italy Italian Italy Italian Israel Hebrew Japan Japanese Japan Japanese Korea Korean Belgium Dutch Belgium Dutch Netherlands Dutch Netherlands Dutch Norway Norwegian Norway Norwegian Poland Polish Brazil Brazilian Brazil Brazilian Portugal Portugese Portugal Portugese Romania Romanian Russia Russian Serbia Serbian(Latin) Slovakia Slovak Slovenia Slovenian Serbia Serbian(Cyrillic) Sweden Swedish Sweden Swedish Turkey Turkish People's Republic of China Simplified Chinese Taiwan Traditional Chinese Locale name Hr_HR.IBM-870 Hu_HU.IBM-870 Is_IS.IBM-871 Is_IS.IBM-1047 It_IT.IBM-280 It_IT.IBM-1047 Iw_IL.IBM-424 Ja_JP.IBM-939 Ja_JP.IBM-1027 Ko_KR.IBM-933 Nl_BE.IBM-500 Nl_BE.IBM-1047 Nl_NL.IBM-037 Nl_NL.IBM-1047 No_NO.IBM-277 No_NO.IBM-1047 Pl_PL.IBM-870 Pt_BR.IBM-037 Pt_BR.IBM-1047 Pt_PT.IBM-037 Pt_PT.IBM-1047 Ro_RO.IBM-870 Ru_RU.IBM-1025 Sh_SP.IBM-870 Sk_SK.IBM-870 Sl_SI.IBM-870 Sr_SP.IBM-1025 Sv_SE.IBM-278 Sv_SE.IBM-1047 Tr_TR.IBM-1026 Zh_CN.IBM-935 Zh_TW.IBM-937 For more information about locales, see Appendix F, “Localization,” on page 937. Files The Files topic lists any supplementary files (files not specified on the command line) that the command refers to. Such files typically provide information the command needs; the command accesses these files during its operation. If the files cannot be found, the command issues a message to this effect. Files documented in this topic may be temporary files, output files, databases, configuration files, and so on. The z/OS XL C/C++ run-time library supports a file naming convention of // (the file name can begin with exactly two slashes). However, z/OS UNIX System Services does not support this convention. Do not use this convention (//) unless it is specifically indicated (as in the description for the c89 command). z/OS UNIX System Services does support the POSIX file naming convention, where the file name can be selected from the set of character values excluding the slash and the null character. Chapter 1. Introduction to shell commands and DBCS 5 Usage notes The usage notes section gives additional notes for those using the shell. Its purpose is similar to that of the Caution topic (see “Caution”). That is, it provides important information that the reader should not overlook. However, it typically deals with issues that are more benign than what the Caution topic deals with. Exit values The Exit Values topic presents the error messages that the shell may display, along with a description of what caused the message and a possible action you can take to avoid getting that message. Occasionally, this topic refers you to another command description for more information about an error message. This topic also contains information about the exit status returned by the command. You can test this status to determine the result of the operation that the command was asked to perform. Limits The Limits topic lists any limits on the operation of the shell. Some limits are implicit rather than explicit and may be lower than the explicitly stated limit. Portability The Portability topic includes two types of information: v Availability of a version of the command on existing UNIX systems (System V, BSD) v Compatibility with industry standards—for example, the POSIX.2 Draft Standard or the X/Open Portability Guide, Issue 4 (XPG4**). Caution The Caution topic contains important advice for users. In z/OS shell documentation, the Caution topic is often aimed at those who are familiar with UNIX systems. Since the z/OS shell primarily conforms to the emerging POSIX standards, its behavior may not precisely match the corresponding UNIX commands. The Caution topic may point out discrepancies in behavior that may catch experienced POSIX or UNIX users by surprise. Related information The Related Information topic refers to other command descriptions that may contain information relevant to the command description you have just read. For example, consider the head command; by default, head displays the first 10 lines of each file given on the command line. Its Related Information topic refers you to tail, the command that displays the last 10 lines of a file. Using the double-byte character set (DBCS) z/OS UNIX supports the double-byte character set (DBCS). It also supports a DBCS locale. The name of the IBM-supplied DBCS locale is Ja_JP. This locale uses the IBM-939 coded-character set, which is a double-byte character set. This topic discusses the following: v Requirements for using DBCS v When you must use SBCS characters and not DBCS characters v When you can use DBCS characters 6 z/OS V1R12.0 UNIX System Services Command Reference v v v v Byte sequences that are not permitted in DBCS strings Displaying DBCS characters Switching locales Problems with DBCS file names containing DBCS characters Requirements for using DBCS If you plan to use DBCS interactively, you must work at a terminal that supports DBCS, such as a PS/55, and follow the procedures for the terminal emulator being used. It is not necessary, however, to be at a terminal that supports DBCS if you just want to use files that contain DBCS data. To use DBCS, you need to do the following: 1. Specify special logmodes to access TSO/E and VTAM® support for DBCS. Typically, the system programmer has already set these up and provided you with instructions. 2. Issue the TSO/E PROFILE PLANGUAGE(JPN) command, if required, to receive TSO/E messages in the Japanese language. 3. On the OMVS command, use the null character conversion table (the default) for character conversion. You do not need to specify the CONVERT operand on the OCOPY, OGETX, OPUT, and OPUTX commands. 4. Access the shell using the OMVS command with the DBCS operand (which is the default setting). You can also access the shell by using the rlogin program. The default conversion is from ISO8859-1 to IBM-1047; users can change their conversion to use different code pages by using the chcp command. 5. Define single-byte escape characters for typing escape sequences. 6. Enable the shell and utilities for the DBCS locale, including having all shell and utility messages in Japanese, by entering the these commands: export LC_ALL=Ja_JP exec sh To receive shell and utility messages in Japanese, but not put your terminal in DBCS mode, enter the this command: export LC_MESSAGES=Ja_JP When you must use SBCS and not DBCS characters You must use the single-byte character set (SBCS) when specifying the following: v User names. v v v v v System, device, group, and terminal names. User names, passwords, and password phrases Shell command-line options. Shell commands and their operands. Environment variables (DBCS characters are not exportable). v Delimiters such as space, slash (/), braces { }, tab, parentheses, dot (.), and any other shell special characters. v Encoding for newline or null cannot be embedded in a DBCS character's code. There are other rules that define valid DBCS data: – The DBCS blank is 0x4040. – The first byte of the code defining the DBCS character must be in the range 0x41 to 0xFE. Chapter 1. Introduction to shell commands and DBCS 7 – The second byte must be in the range 0x41 to 0xFE. All others are not valid. This effectively covers the newline and null escape sequences, because they cannot be part of a valid DBCS character. For more information about invalid DBCS characters, see “Byte sequences that are not permitted in DBCS strings” on page 8. v Although file names with DBCS characters are tolerated, you should not create file names with DBCS characters. Doing so makes the file nonportable across locales, and problems may occur if file names are subsequently used in a single-byte locale. Instead, use the portable character set specified by POSIX and single-byte file names. IBM will not support any customer problems with DBCS file names. For more information about DBCS file names, see “Problems with file names containing DBCS characters” on page 9. When you can use DBCS characters When in the DBCS locale, you can use DBCS to specify the following: v sh command-line arguments, although arguments expressed as numeric values must use SBCS characters. v Text in data files. Files containing DBCS text are processed correctly by the shell and the utilities (such as ed and grep) if the DBCS locale is active. These files can be either DBCS text or mixed text (combinations of SBCS and DBCS). Both types of file can exist in the file system along with files that contain only single-byte text. Byte sequences that are not permitted in DBCS strings If you create invalid DBCS text, you may see an “illegal byte sequence” message when processing that text. The shell or command issues this error message, and the command stops processing in most cases. Valid DBCS strings must start with “shift out” (SO [0x0E]) and end with “shift in” (SI [0x0F]). The first byte of the code defining the DBCS character must be in the range 0x41 to 0xFE. The second byte must be in the range 0x41 to 0xFE. The exception is that DBCS blank is 0x4040. All others codes are invalid. Normal terminal operations do not produce incorrect DBCS strings. To prevent incorrect DBCS characters and strings: v Do not use commands that operate on the data as byte strings instead of character strings. For example, head is a utility that could truncate a DBCS string or character in an inappropriate place, thus creating an incorrect DBCS string. Using pipes between utilities can also result in incorrect DBCS strings unless you pay attention to how each command handles the data. v Do not edit text in nontext mode such as having the TSO/E editor in HEX ON mode. If the shell command is operating on a character string and not on a byte string, and the shell is in a locale that supports DBCS, and if the utility encounters an invalid DBCS string, such as the ones described in this topic—you get an “illegal byte sequence” message and the utility may fail. Note: newline (\n [0x15]) causes the shift state of any subsequent character sequence to start in the initial state (shifted into the SBCS mode). This may apply when a command is processing a DBCS string and encounters 8 z/OS V1R12.0 UNIX System Services Command Reference newline before a “shift in.” For information about rules for creating DBCS data, refer to DBCS Design Guide—System/370 Software, GG18-9095. Displaying DBCS characters In a double-byte environment, column positions are always based on the width of narrow characters. Normally, characters are “thin”; they take up only one column position when displayed. In contrast, some DBCS characters are “thick”; they take up two column positions when displayed. The number of actual characters that are displayed by the command in the column area depends on the thickness of the characters. This applies to such commands as ls, fold, and pr, which display DBCS characters in column positions. Switching locales By default, the shell starts in the POSIX locale and cannot handle DBCS text until the locale is changed, typically with the shell command export LC_ALL=Ja_JP. This export command affects the current shell environment with the following exception: if you change the locale to DBCS, the shell's LC_CTYPE locale category remains in the locale until it is replaced by means of the exec command (exec /bin/sh). Even if you change the locale to DBCS by using export LC_ALL=Ja_JP, the shell's LC_CTYPE variable remains in the previous locale (initially POSIX) until the shell is exec'd again with exec sh. Always follow the export LC_ALL=your locale with exec sh to be sure the shell and utilities are running in the desired locale. This is true even if you place the export LC_ALL=your_locale in your login profile. Problems with file names containing DBCS characters The file system treats all file names as if they contained SBCS characters. However, when you use the shell in the DBCS locale, file name and path name comparison is performed in wide mode. That is, all the characters in the name are converted to wide characters before comparison. By doing this, the shift codes are removed from the comparison and, therefore, a match can be found with the file names. For example, if you have such DBCS file names as: db/so dbfile1 si db/so dbfile2 si where so and si are the shift codes that shift out to DBCS and back to SBCS, then when in the DBCS locale (Ja_JP), ls db/so file si * lists both files. When in the POSIX locale, DBCS strings are treated as byte strings. Comparison is performed byte by byte. For example: ls db/so file si * shows the comparison string ending with an “e si”. The files in the directory would have to end with an “e si” in order to find a match. Neither of the file names in the example would be found. Chapter 1. Introduction to shell commands and DBCS 9 10 z/OS V1R12.0 UNIX System Services Command Reference Chapter 2. Shell command descriptions Following are the descriptions of all the commands for the z/OS shell. The descriptions are listed in alphabetic order. For instructions on how to read the command descriptions, see “Reading the command descriptions” on page 1. The z/OS shell is based on the KornShell that originated on a UNIX system. As implemented for z/OS UNIX System Services, this shell conforms to POSIX standard 1003.2-1992. Restriction: z/OS UNIX shell commands can only read a large format sequential data set that has no more than 65,535 tracks of data on any single volume. This information assumes that your z/OS system includes Resource Access Control Facility (RACF). Instead of RACF, your system could have an equivalent security product. alias — Display or create a command alias Format alias [–tx] [name[=value] ...] alias –r For the tcsh shell: alias [name [wordlist ]] Description When the first word of a shell command line is not a shell keyword, alias causes the shell to check for the word in the list of currently defined aliases. If it finds a match, the shell replaces the alias with its associated string value. The result is a new command line that might begin with a shell function name, a built-in command, an external command, or another alias. When the shell performs alias substitution, it checks to see if value ends with a blank. If so, the shell also checks the next word of the command line for aliases. The shell then checks the new command line for aliases and expands them, following these same rules. This process continues until there are no aliases left on the command line, or recursion occurs in the expansion of aliases. Calling alias without parameters displays all the currently defined aliases and their associated values. Values appear with appropriate quoting so that they are suitable for reinput to the shell. Calling alias with parameters of the form name=value creates an alias for each name with the given string value. If you are defining an alias where value contains a backslash character, you must precede it with another backslash. The shell interprets the backslash as the escape character when it performs the expansion. If you use double quotation marks to enclose value, you must precede each of the two back slashes with an additional © Copyright IBM Corp. 1996, 2011 11 alias backslash, because the shell escapes characters—that is, the shell does not interpret the character as it normally does—both when assigning the alias and again when expanding it. To avoid using four back slashes to represent a single backslash, use single quotation marks rather than double quotation marks to enclose value, because the shell does not escape characters enclosed in single quotation marks during assignment. As a result, the shell escapes characters in single quotation marks only when expanding the alias. Calling alias with name without any value assignment displays the function name (name) and its associated string value (value) with appropriate quoting. DBCS recommendation: Use single-byte characters when specifying an alias name, because the POSIX standard states that alias names must contain only characters in the POSIX portable character set. alias in the tcsh shell Without arguments, alias in the tcsh shell prints all aliases. With name, alias prints the alias for name. With name and wordlist, alias assigns wordlist as the alias of name. wordlist is command and filename substituted. name may not be alias or unalias. See also “unalias in the tcsh shell” on page 748. Options –r Removes all tracked aliases. –t Makes each name on the command line a tracked alias. Each tracked alias resolves to its full path name; the shell thus avoids searching the PATH directories whenever you run the command. The shell assigns the full path name of a tracked alias to the alias the first time you invoke it; the shell reassigns a path name the first time you use the alias after changing the PATH variable. When you enter the command: set –h each subsequent command you use in the shell automatically becomes a tracked alias. Running alias with the –t option, but without any specified names, displays all currently defined tracked aliases with appropriate quoting. –x Marks each alias name on the command line for export. If you specify –x without any names on the command line, alias displays all exported aliases. Only exported aliases are passed to a shell that runs a shell script. Several aliases are built into the shell. Some of them are: alias alias alias alias alias alias alias alias alias 12 autoload="typeset –fu" functions="typeset –f" hash="alias –t" history="fc –l" integer="typeset –i" nohup="nohup " r="fc –s" stop="kill –STOP" suspend="stop \$\$" z/OS V1R12.0 UNIX System Services Command Reference alias You can change or remove any of these aliases, and the changes will remain in effect for the current shell and any shell scripts or child shells invoked implicitly from the command. These aliases are reset to their default built-in values each time a new shell is invoked from the command line. Example The command: alias ls="ls –C" defines ls as an alias. From this point on, when you issue an ls command, it produces multicolumn output by default. alias in the tcsh shell examples To alias the !! history command, use \!-1 instead of \!\!. For example: alias mf ’more \!-1$’ creates an alias for looking at the file named by the final argument of the previously entered command. Example output would be the following: alias mf ’more \!-1$’ echo "We love tcsh." > file1 mf We love tcsh. "file1" (EOF) where mf pulls the last argument of the previous command (file1), and then displays that file using the more command. Localization alias uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Usage notes 1. alias is a built-in shell command. 2. Because exported aliases are only available in the current shell environment and to the child processes of this environment, they are not available to any new shell environments that are started (via the exec sh command, for example). To make an alias available to all shell environments, define it as a nonexported alias in the ENV file, which is executed whenever a new shell is run. Exit values 0 1 2 Successful completion Failure because an alias could not be set Failure because of an incorrect command-line option Chapter 2. Shell command descriptions 13 alias If you define alias to determine the values of a set of names, the exit value is the number of those names that are not currently defined as aliases. Portability – – This is a test. POSIX.2 User Portability Extension, UNIX KornShell. The –t and –x options are extensions to the POSIX standard. Related information fc, hash, nohup, set, sh, typeset, unalias, tcsh amblist — Display formatted information from object and executable files for diagnostic purposes Format amblist file... Description The amblist utility provides a UNIX interface to the AMBLIST program. With AMBLIST, you can obtain information about object modules and executable modules, and diagnose problems with them. Output is written to stdout and errors to stderr. amblist reads control statements from standard input (stdin). One or more control statements that identify the processing to be performed must be specified. Each control statement line must begin with one or more blanks. Keywords are case-sensitive and must be uppercase. Each control statement line can be up to 80 bytes long, but only the first 70 bytes can contain control information. Control statement lines longer than 70 bytes might be ignored or might cause an error to be reported. Options file The file argument can be either a path name or a data set name. You cannot specify both a path name and a data set name at the same time. If you do, amblist ends with an error message and a nonzero return code. v If a path name is specified, it can be either a UNIX file or a UNIX directory. You can use only one path name at a time. If a UNIX directory is used for the path name, MEMBER must be specified on the amblist control statement to specify the file name. v If a data set name is specified, or more data sets can be listed to indicate a concatenation of data sets to be searched. If a member name cannot be specified on the data set name (such as for LISTLOAD), it can either be specified on a control statement or omitted completely. If the member name is omitted, then all members are processed. Examples 1. Control statement from a pipe, output redirected to a file: echo “ LISTLOAD” | amblist a.out > a.amblist 2. Control statement read interactively, output sent to terminal: 14 z/OS V1R12.0 UNIX System Services Command Reference amblist amblist hello.o The user must then type " LISTOBJ" (leading blank, no quotes), then press CTRL-D to end the amblist processing. 3. Control statement from a file, with output sent to terminal: amblist hello.o < hello.ambctl where the file hello.ambctl contains a single line " LISTOBJ" (leading blank, no quotes). 4. Control statement from pipe, process an object data set, output redirected to a file: contains the single line " LISTOBJ" (leading blank, no quotes). echo “ LISTOBJ” | amblist “//binder.obj(hello)” > hello.amblist For examples of output created when running amblist, see z/OS MVS Diagnosis: Tools and Service Aids. Localization amblist uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion. 1 No operands were specified, or -? was used as an option 2 An incorrect option was specified. 3 The AMBLIST program ended with a nonzero return code. The return code is in message AMBU2003. Some output might have been written to stdout. 4 UNIX path names and MVS data set names cannot be mixed. 9 A file could not be opened. The error number is in message AMBU2010. 10 Dynamic allocation failure. Message AMBU2010 indicates the return code, error code, and the information code from dynamic allocation (SVC 99). Additional messages describing the error might have been written to stderr. Usage notes 1. You cannot use the DNN= control statement keyword except when specifying the default value of SYSLIB because amblist does not provide a facility for the use of any other data definition name. 2. You must specify at least one library when invoking amblist. Do not use LISTLPA because it is obsolete. Related information z/OS MVS Diagnosis: Tools and Service Aids contains detailed reference information about the AMBLIST program. z/OS MVS Program Management: User's Guide and Reference also has information about AMBLIST. Chapter 2. Shell command descriptions 15 ar ar — Create or maintain library archives Format ar ar ar ar ar ar ar ar –d[–Ilv] archive member... –m[–abIilsv] [posname] archive member ... –p[–Ilsv] archive member... –q[–clsv] [–F format] archive member ... –r[abcIilsuv] [–F format] [posname] archive member ... –t[Ilsv] archive[member...] –u[–abcIiklsv] [–F format] [posname] archive member ... –x[–CIlsTv] archive [member...] ... Description ar maintains archive libraries. The archive library is a collection of files, typically object files. Using ar, you can create a new library, add members to an existing library, delete members from a library, extract members from a library, and print a table of contents for a library. A library member is an arbitrary file. Typically, these files are object files or side files, suitable for use by a linkage editor. If any members of a library are object files, ar creates and maintains an external symbol index for link-editing. Member names in an archive are only the final component of any path name. When creating a new library member (member) as given on the command line, ar uses the full path name given. When storing the member name in the library, or comparing a member name, ar uses only the final component. Options The format shows the main functions of ar, which are defined as follows: 16 –d Deletes each named member from the archive and regenerates the symbol table. –m Moves the named archive member in the archive. The new position is specified by –a, –b, i, or posname. If a location is not specified, the member is moved to the end of the archive. –p Displays each member specified to the standard output (stdout). If you did not specify any members, ar displays all members. –q Quickly appends the specified file to the archive. With this option, ar does not check to see if file is already a member of the archive. –r Replaces or adds file to archive. If archive does not exist, ar creates it and prints a message. When ar replaces an existing member, the archive order is not changed. If file is not replacing a member, it is added to the end of the archive unless –a, –b, or –i is used. This option regenerates the symbol table. –t Displays a table of contents that lists members, or every member if member is not specified. ar prints a message for each member it doesn't find. By default, ar prints the member name for all selected members. With the verbose (–v) option, ar prints more information for all selected members. –x Extracts each specified member from the archive and copies it to a file. If z/OS V1R12.0 UNIX System Services Command Reference ar member is specified as a full path name, it is copied to that path name. If no member is specified, all members are extracted. The archive remains unchanged. The following options change the behavior of the main functions: –a Places file in the archive after the member specified by posname. If no member is named, file is added to the end of the archive. –b Places file in the archive before the member specified by posname. If no member is named, file is placed at the beginning of the archive. –C Prevents ar from overwriting existing files with extracted files. This option is used only with extraction (–x). –c Suppresses the message normally printed when ar creates a new archive file. You can use this only in conjunction with the –r and –q options. –F format Specifies the archive format to be used by a new archive. You can use this option only when creating a new archive with the –r and –q options. –I Ignores the case of letters when searching the archive for specified member names. Normally, the case is significant. –i Inserts file into the archive before the member specified by posname. If posname isn't specified, ar inserts file at the beginning of the archive. This option is the same as –b. –l This option is ignored. It requests that temporary files generated by ar be put in the directory rather than in the default temporary file directory. It is provided for backward compatibility with other versions of ar –s Regenerates the external symbol table regardless of whether the command modifies the archive. –T When used with –x, allows extraction of members with names longer than the file system supports. Normally this is an error, and ar does not extract the file. Most file systems truncate the filename to the appropriate length. –u Replaces the archive member only if the member file's modification time is more recent than the archive member time. –u implies –r, so it isn't necessary to specify –r also. –v Gives verbose output. With –d, –q, –r, and –x, this option prints the command letter and the member name affected before performing each operation. With –t, ar prints more information about archive members using a format similar to ls –l. With –p, ar writes the name of the member to stdout, before displaying the contents of the file. Operands archive Specifies the path name of the archive file. member Specifies the path name of the file that is to be acted upon (placed, deleted, searched for, and so on) in the archive library. Examples 1. To add a member fioacc.o to the archive file /u/turner/bin/cliserpgm.a, specify: ar –rc /u/turner/bin/cliserpgm.a fioacc.o 2. To display the members of the archive file /u/turner/bin/cliserpgm.a, specify: Chapter 2. Shell command descriptions 17 ar ar –tv /u/turner/bin/cliserpgm.a 3. To delete the member repgen.o from the archive file /u/turner/bin/cliserpgm.a and regenerate the external symbol table for the archive, specify: ar –ds /u/turner/bin/cliserpgm.a repgen.o Environment variables ar uses the following environment variable: TMPDIR The path name of the directory being used for temporary files. If it is not set, z/OS UNIX uses /tmp. Localization ar uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_TIME v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Files ar creates temporary files in the archive file's directory and in the directory named by the TMPDIR environment variable. These files are intermediate versions of the archive file being created or updated. Consequently, they require approximately the same file size as the archive file being manipulated. Usage notes ar may be used to store multiple versions of the same object file within one archive library. This is useful if you are providing an archive library which may be used to resolve references from code compiled with various compiler options. These options cause differences in the object files which must be matched with the archive library member attributes. Attributes for ar are: AMODE, XPLINK, and IPA. ar will store the attribute information for every entry in the symbol table. The linkage editor will use the attribute information to resolve external references with the appropriate archive library member. Because archive library member names are only the final component of the pathname, these member names must be unique for the different object file versions. Side files (normally those created when link-editing a DLL) can be made members of an archive file. When the linkage editor processes such an archive file, it will normally read in all such side-files so that archives can be used for resolving symbol references in DLLs. For more information about resolving external references, see z/OS MVS Program Management: User's Guide and Reference. You will want to establish a naming convention for the object files, and change your build procedures to generate the correct names. For example, if your archive contains 3 versions of myfuncs.o, you could generate names myfuncs.o AMODE(31), non-XPLINK myfuncsX.o AMODE(31), XPLINK myfuncs64.o AMODE(64) (AMODE(64) always forces XPLINK) 18 z/OS V1R12.0 UNIX System Services Command Reference ar Your make file might generate commands such as these: c89 c89 c89 ar -c myfuncs.c -Wc,xplink -o myfuncsX.o -c myfuncs.c -Wc,LP64 -o myfuncs64.o -c myfuncs.c -ruv libmyfuncs.a myfuncs.o myfuncsX.o myfuncs64.o To display the attributes of the symbols within an object file or an archive library of object files, use nm — Display symbol table of object, library, or executable files. Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to create the extracted file v An error writing to the extracted file v The requested module not found on appending v An error opening the module on appending v An incorrect module on appending v Inability to access the module on appending v A module not found on table or extraction 2 Incorrect command-line arguments or options Portability POSIX.2, X/Open Portability Guide, UNIX systems. For backward compatibility, you can omit the dash (–) preceding the options if the options appear only as the first argument after the command name. The following options are XPG extensions to the POSIX standard: –a, –b, –C, –i, –l, –m, –q, –s, and –T. The –F and the –I options are extensions to the POSIX and XPG standards. Related information c89, make, nm as — Use the HLASM assembler to produce object files Format as [--option[, option] ...] ... [-a[egimrsx][=file]] ... [-g] [--[no]gadata[=file]] [--[no]gdwarf3[=file]] [-moption] [-I name] [-o objectfile] [-v] [--[no]help] [--[no]verbose] file Chapter 2. Shell command descriptions 19 as Description The as command processes assembler source files and invokes the HLASM assembler to produce object files. Options -- Accepts all options that are accepted by HLASM. Multiple options can be specified by separating them with a comma. This style of option specification is designed to provide smooth migration for users accustomed to specifying options in JCL. For example: --"FLAG(ALIGN),RENT" -a[egimrsx][=file] Instructs the assembler to produce a listing. -ae Instructs the assembler to produce the External Symbol Dictionary section of the assembler listing. This is equivalent to specifying: --ESD. -ag Instructs the assembler to produce the General Purpose Register Cross Reference section of the assembler listing. This is equivalent to specifying: --RXREF. -ai Instructs the assembler to copy all product information to the list data set. This is equivalent to specifying: --INFO. -am Instructs the assembler to produce the Macro and Copy Code Source Summary section of the assembler listing. This is equivalent to specifying: --MXREF. -ar Instructs the assembler to produce the Relocation Dictionary (RLD) section of the assembler listing. This is equivalent to specifying: --RLD. -as Instructs the assembler to produce the Ordinary Symbol and Literal Cross Reference section of the assembler listing. It also instructs the assembler to produce the un-referenced symbols defined in the CSECTs section of the assembler listing. This is equivalent to specifying: --XREF(SHORT,UNREFS). -ax Instructs the assembler to produce the DSECT Cross Reference section of the assembler listing. This is equivalent to specifying: --DXREF. =file Specifies the file name of the listing output. If you do not specify a file name, the output goes to stdout. You may combine these options; for example, use -ams for an assembly listing with expanded macro and symbol output. The =file option, if used, must be specified last. -g Instructs the assembler to collect debug information. By default, the debug information is produced in DWARF Version 3 format (or --gdwarf3). --[no]gadata[=file] Instructs the assembler to collect associated data and write it to the associated data file. You can optionally specify the name of the output debug file. The specified name cannot be a PDS or z/OS UNIX file system directory name. If you do not specify a file name, the default name is created as follows: 20 z/OS V1R12.0 UNIX System Services Command Reference as v If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the user ID under which the as command is running, and .ADATA is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src) with this option, the produced debug file name will be TS12345.MYSOURCE.ADATA(src). v If you are compiling a z/OS UNIX file, the as command stores the debug information in a file that has the name of the source file with an .ad extension. For example, if you are compiling src.a with this option, the compiler will create a debug file named src.ad. --[no]gdwarf3[=file] Instructs the assembler to generate debug information conforming to the DWARF Version 3 format. Debugging tools (for example, dbx) can take advantage of this debug information. You can optionally specify the name of the output debug file. The file name of the output debug file must be a PDS member, a sequential data set or z/OS UNIX System Services file; it cannot be a PDS directory or z/OS UNIX System Services file system directory name. If you do not specify a file name, the default name is created as follows: v If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the userid under which the as command is running, and .DBG is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src) with the -g option, the produced debug file name will be TS12345.MYSOURCE.DBG(src). If TS12345 is compiling TSMYID.SEQSRC with the -g option, the produced debug file name will be TS12345.SEQSRC.DBG. v If you are compiling a z/OS UNIX System Services file, the as command stores the debug information in a file that has the name of the source file with a .dbg extension. For example, if you are compiling src.a with the -g option, the produced debug file name will be src.dbg. -moption HLASM keyword options are specified using the following syntax: -m<option>[=<parm>[=<value>][:<parm>[=<value>]]...] where <option> is an option name, <parm> is a suboption name, and <value> is the suboption value. Keyword options with no parameters represent switches that may be either on or off. The keyword by itself turns the switch on, and the keyword preceded by the letters NO turns the switch off. For example, -mLIST tells the HLASM assembler to produce a listing and -mNOLIST tells the HLASM assembler not to produce a listing. If an option that represents a switch is set more than once, the HLASM assembler uses the last setting. Keyword option and parameter names may appear in mixed case letters in the invocation command. -I name Instructs HLASM to look for assembler macro invocation in the specified location. The name can be either a PDS name or z/OS UNIX file system directory name. If a PDS data set is specified, it must be fully qualified. The specified locations are then prepended to a default set of macro libraries. The as command assumes a default set of macro libraries that is compatible with the defaults for the C/C++ compilers. The default data Chapter 2. Shell command descriptions 21 as sets used are: -I CEE.SCEEMAC, -I SYS1.MACLIB, and -I SYS1.MODGEN. The default data sets can be changed via the environment variable _AS_MACLIB, for example: export _AS_MACLIB="FIRST.PDS:SECOND.PDS" -o objectfile Specifies the name of the object file. If the name specified is a PDS or z/OS UNIX System Services directory name, a default file name is created in the PDS or z/OS UNIX directory specified as follows: v If the source file is a sequential data set, the second last part of the data set name will be used. If the data set name only contains one part after the high-level qualifier, then the last part will be used. v If the source file is a PDS member, the member name will be used. v If the source file is a z/OS UNIX file, the suffix will be removed if applicable. v If the object file is going into a PDS, the first eight characters of the name will be used. If there is a dot, anything after the first dot will be removed. v If the object file is going into a z/OS UNIX directory, .o will be appended to the name. For example: Source file: //’abc.hello.source’ Ouput file in PDS: HELLO Output file in UNIX directory: hello.o Source file: //’ABC.HELLO’ Ouput file in PDS: HELLO Output file in UNIX directory: HELLO.o Source file: //SOURCE(hello) Ouput file in PDS: HELLO Output file in UNIX directory: hello.o Source file: /abc/hello.s Ouput file in PDS: HELLO Output file in UNIX directory: hello.o Source file: /abc/hellothere.s Ouput file in PDS: HELLOTHE Output file in UNIX directory: hellothere.o -v Writes the version of the as command to stderr. --[no]help Help menu. Displays the syntax of the as command. --[no]verbose Specifies verbose mode, which writes additional information messages to stdout. file may be: v An MVS™ data set (for example, //somename) v An absolute z/OS UNIX file (for example, /somename) v A relative z/OS UNIX file (for example, ./somename or somename) The output of the as command is an object file. If you do not specify a file name via the -o option, the default name is created as follows: 22 z/OS V1R12.0 UNIX System Services Command Reference as v If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the user ID under which the as command is running, and .OBJ is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src), the compiler will create an object file named TS12345.MYSOURCE.OBJ(src). v If you are compiling a z/OS UNIX file, the as command names the object file with the name of the source file with an .o extension. For example, if you are compiling src.a, the object file name will be src.o. Notes: 1. The as command does not accept standard input as a file. 2. The as command invokes the HLASM assembler to produce the object file. The HLASM assembler is invoked with the default options ASA and TERM. The ASA option instructs HLASM to use American National Standard printer control characters in records written to the listing file, thus making the listing file more readable in the z/OS UNIX System Services environment. The TERM option instructs HLASM to write error messages to stderr. These defaults can be changed by using the -m option or -- option. 3. HLASM messages and as error messages are directed to stderr. Verbose option output is directed to stdout. 4. When invoking as from the shell, any option arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, source files specified as PDS member names contain parentheses; if they are specified as fully qualified names, they contain single quotes. To escape these special characters, either enclose the option argument or operand in double quotes, or precede each character with a backslash. asa — Interpret ASA/FORTRAN carriage control Format asa [file ...] Description Historically, printouts created by programs use the first character of each line to control the spacing between that line and the previous one. For example, if the first character is a space, the rest of that line immediately follows the previous line; if it is a 1, that line should begin on a new page, and so on. asa reads input in this format and writes it out in a normal text format, using newlines, formfeeds, and carriage returns to achieve the same effects as the carriage control characters. If you specify files on the command line, asa reads input from these files; otherwise, it reads the standard input (stdin). asa writes output to the standard output (stdout). It does not copy newline characters in the input to the output. Instead, it uses the first character of each line to determine how to print the rest of the line. asa interprets the first character as follows: Space Outputs the rest of the line without change. 0 Outputs a newline character before printing line. Chapter 2. Shell command descriptions 23 asa 1 Outputs a formfeed (start a new page) sequence before printing line. + Outputs a carriage return sequence so that line is output over the previous line. If + starts the first line, it's treated as a space. Localization asa uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Write error on stdout v Inability to open the input file 2 Unknown command-line option Portability POSIX.2, X/Open Portability Guide, UNIX System V. at — Run a command at a specified time Format at at at at [–m] [–f file] [–q queue] –t time [–m] [–f file] [–q queue] timespec –r [–q queue] at_job ... –l [–q queue] [at_job ...] Description at lets you set up a series of commands to be run later. It reads the commands from the standard input (stdin) or from a file specified with the –f option. When the commands run, they have the same environment variables, working directory, file creation mask, and so on that are set up when you run the at command; however, at does not typically preserve open file descriptors, traps, or priority inherited from the working environment. Typically, you redirect the standard output (stdout) from these commands to files so you can read the files after the system runs the commands. at mails the standard output (stdout) and standard error output (stderr) to you if you do not redirect them. The at command displays an at-job identifier when you submit commands, along with the time that the system is to run the commands. at, batch, and crontab submit jobs to cron; the data in these jobs may contain double-byte characters. When the jobs are run, the data in the jobs are interpreted in the locale that cron is using. Since it is strongly recommended that cron be 24 z/OS V1R12.0 UNIX System Services Command Reference at started in the POSIX locale, double-byte characters in the job may not be interpreted correctly. You can get around this by calling setlocale() in the job itself. Options –f file Reads commands from file rather than from standard input (stdin). –l Reports on standard output (stdout) all jobs you have scheduled and when the system is to run them if you do not specify at_job. Specifying at_job reports information about those jobs only. –m Sends you mail after your job has finished running. If you did not redirect the stdout and stderr, at also mails these to you. If stdout or stderr is non-null, at mails this output to you even if you do not specify –m. –q queue Specifies the queue your at job is to be recorded in or removed from. queue can be any single-byte character except a space, a tab, a null character, or a number sign (#). By default, at stores all its jobs in a queue called a, and batch stores all its jobs in a queue called b. If used with this option, –l only reports information about at jobs in queue. –r at_job Removes previously scheduled at jobs. The at_job arguments must be the identifiers assigned to the jobs when you set them up with at. –t time Specifies the time for the system to run the job. You specify time in the same format as the time argument for touch. When you do not use the –t option, you can use a timespec argument to specify the time. A timespec argument consists of three parts: a time, a date, and an increment (in that order). You must always specify the time, but you can omit the date, the increment, or both. Following are possible time formats: Format Meaning hhmm hh hours, mm minutes, 24-hour clock hh:mm hh hours, mm minutes, 24-hour clock h:mm h hours, mm minutes, 24-hour clock h:m h hours, m minutes, 24-hour clock hh:mm zone zone is time zone hh:mmam Morning, 12-hour clock hh:mmam zone Morning, 12-hour clock in given time zone hh:mmpm Afternoon, 12-hour clock hh:mmpm zone Afternoon, 12-hour clock in given time zone noon Noon midnight Midnight next The current time, next day that meets date and increment now The current time today All minute specifications are optional. For example, to specify an at job to run at 1:00 p.m., you can enter Chapter 2. Shell command descriptions 25 at at 1pm Currently, the z/OS shell only supports the time zones GMT, CUT, UTC, and ZULU, all of which stand for Coordinated Universal Time (often called Greenwich Mean Time). If you do not specify a zone, at interprets times with respect to the TZ environment variable. Appendix I, “Format of the TZ environment variable,” on page 961 explains how to set the local time zone with the TZ environment variable. Possible date formats are shown in the following list: Format month day Meaning month is the full name, or the three-letter abbreviation (as in January or Jan) month day, year day and year given as appropriate numbers weekday is the full name or the three-letter abbreviation (as in Monday or Mon) The current day Next day weekday today tomorrow The increment is added to the time and date you specify with the preceding parts of timespec. It has the format + n units where n is a number and units is one of the following: minute day month minutes days months hour week year hours weeks years Here are some sample time specifications: 0655 1855 18:55 6:55pm 6:55 pm Jan 10 now + 3 hours noon tomorrow midnight Friday Environment variables at uses the following environment variables: SHELL Contains the name of the shell used to invoke the at job. TZ Specifies the default time zone for all times given on the command line. If you include a time zone as part of time or timespec, it overrides the value of TZ. Appendix I, “Format of the TZ environment variable,” on page 961 explains how to set the local time zone with the TZ environment variable. Usage note at jobs that contain a line consisting of just the string "!!!ATEOF!!!" fail with unexpected results. Localization at uses the following localization variables: v LANG 26 z/OS V1R12.0 UNIX System Services Command Reference at v v v v v LC_ALL LC_CTYPE LC_MESSAGES LC_TIME NLSPATH The keywords midnight, noon, today, and tomorrow are valid only in the POSIX locale. See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion >0 Returned if the command fails for any reason If an error occurs, at does not schedule, remove, or list the job. Portability POSIX.2 User Portability Extension, UNIX systems. Related information batch, bg, cron, crontab, touch, tcsh autoload — Indicate function name not defined Format autoload name ... Description autoload is an alias for typeset –fu. Like typeset –fu, autoload indicates that the functions named in the command line are not yet defined. See “typeset — Assign attributes and values to variables” on page 742 and “Command execution” on page 576 for more information. Related information typeset, functions, sh automount — Configure the automount facility Format automount [–e] [–a|q] [–s] [Master filename] Description automount is used to configure the automount facility. This facility can automatically mount file systems at the time they are accessed, and also unmount them later. You can use a single automount policy to manage both HFS and zFS file systems. For information about setting up the automount facility, see z/OS UNIX System Services Planning. Chapter 2. Shell command descriptions 27 automount Requirement: automount requires superuser authority. Run automount from the /etc/rc script with no arguments. This action processes the installation's default automount configuration file. When run with no arguments, automount reads the /etc/auto.master file to determine all directories that are to be configured for the automount and the file names that contain their configuration specifications. Note: The /etc/auto.master file contains the directory or directories that the automount facility will monitor. It also contains an associated MapName file that contains the mount parameters. The name of the map file can be specified as an MVS data set name. The data set name must be specified as a fully qualified name and can be uppercase or lowercase. Single quotation marks are not needed. | | | | | | If the automount policy is loaded, you will get a return code of 0. A nonzero return code indicates that the policy was not loaded. The automount file system is mounted with an automove attribute of either AUTOMOVE or UNMOUNT. The automove attribute is set to UNMOUNT only when its parent file system has its automove attribute set to UNMOUNT. If you run automount with the [master filename] argument, that file name is used instead of /etc/auto.master. Guideline: zFS is the preferred file system and continued use of HFS is discouraged. New file systems should be created as zFS file systems. Options Indicates that the policy being loaded is to be appended to the existing policy rather than replace the existing policy. For example: –a /usr/sbin/automount -a –a is mutually exclusive with –q. –e Displays recent error information from automount attempting to create a new zFS or HFS file system. Typically, one allocation error value and reason code is displayed for the last allocation error, if there was one. If a zFS file system could not be created, you will see message text or error and reason codes (or both) for each automount-managed directory where the zFS file system was to be created. –q Displays the current automount policy. –q is mutually exclusive with –a. –s Checks the syntax of the configuration file. No automount is performed. Examples 1. The following example shows how automatic unmount can be avoided for a directory: name duration wjs nolimit Keywords that are not specified on a specific entry are inherited from the generic entry, if present. If the generic entry is not present, or if keys are not specified, the defaults are used. If the filesystem key cannot be resolved, the entry is considered invalid. 28 z/OS V1R12.0 UNIX System Services Command Reference automount 2. The following is an example of a /etc/auto.master file that is used to specify /u as automount-managed and the specifications for that directory in /etc/u.map: /u /etc/u.map Files automount uses these files: /etc/auto.master Specifies a list of directories to be configured, along with their MapName files. Each line in this file contains two path names separated by at least one space: the directory name to be managed and the path name of the MapName file. Both of these path names should be absolute. The path name of the managed directory is used as a file system name prefixed with *AMD. This restricts the length of the path name of a managed directory to 40 characters. If path names need to be longer, you can use symbolic links to resolve all or part of the path name. Blank lines and lines beginning with the characters /* are considered comments and are ignored. Line comments are not tolerated MapName The MapName file contains the mapping between a subdirectory of a directory managed by automount and the mount parameters. The file is organized as a set of specifications. Each specification contains one or more lines. Each line is of the form keyword argument. Each specification must begin with the keyword name. Blank lines and lines beginning with the characters /* are considered comments and are ignored. Line comments are not tolerated A generic entry can be specified as the first specification by using the name of *. The generic specification provides defaults for subsequent specific specifications. When the automounter tries to resolve a lookup request, it attempts to find a specific entry. If a specific entry does not exist for the name being looked up, it attempts to use the generic entry. The following is an example of a generic entry: name type filesystem mode duration delay parm tag * HFS OMVS.HFS.USER.<uc_name> rdwr 30 10 SYNC(60) text,819 Four special symbols are supported to provide name substitution: v <asis_name> used to represent the name exactly, as is. v <uc_name> used to represent the name in uppercase characters. v <sysname> or &SYSNAME. used to substitute the system name. Guideline: Use &SYSNAME. because <sysname> is only temporarily supported for compatibility. You can use these symbols when specifying a file system name or file system parameter that has a specific form with the name inserted as a qualifier. Chapter 2. Shell command descriptions 29 automount Following is a list of supported keywords. You can enter keywords using mixed case letters. Some arguments require mixed case. The allocany, allocuser, and lowercase keywords are valid on any specification, but are meaningful only on the generic entry. allocany allocation-spec Specifies the allocation parameters when using automount to allocate HFS or zFS file systems, keeping in mind that zFS is the preferred file system. allocany will cause an allocation if the data set does not exist for any name looked up in the automount-managed directory. The automount facility creates a new zFS file system as an HFS-compatible file system if the file system that was specified in the automount policy does not already exist. Do not use this option with HFS-compatible zFS file systems if file system aggregates are mounted with the same automount policy because unused data sets is likely to be created. Space for zFS file systems is always assumed to be in units of cylinders regardless of other specifications. All other allocation keywords that can be used for HFS can be specified but will be ignored. However, the syntax must be correct. These restrictions are in place so that migration to zFS or back to HFS will require minimal changes to the automount policy. See usage note 6 on page 34. allocation–spec A string that specifies allocation keywords. The following keywords can be specified in the string: space(primary–alloc[,secondary alloc]) cyl | tracks | block(block size) vol(volser[,volser]...) maxvol(num–volumes) unit(unit–name) storclas(storage–class) mgmtclas(management–class) dataclas(data–class) The next four keywords are added as appropriate: dsn(filesystem) dsntype(hfs) dir(1) new allocuser allocation–spec Specifies the allocation parameters when using automount to allocate HFS or zFS file systems, keeping in mind that zFS is the preferred file system. allocuser will cause an allocation to occur only if the name looked up matches the user ID of the current user. The automount facility creates a new zFS file system as an HFS-compatible file system if the file system that was specified in the automount policy does not already exist. Do not use this option with HFS-compatible zFS file systems if file system aggregates are mounted with the same automount policy because unused data sets is likely to be created. Space for zFS file systems is always assumed to be in units of cylinders regardless of other 30 z/OS V1R12.0 UNIX System Services Command Reference automount specifications. All other allocation keywords that can be used for HFS can be specified but will be ignored. However, the syntax must be correct. These restrictions are in place so that migration to zFS or back to HFS will require minimal changes to the automount policy. See usage note 6 on page 34. allocation–spec A string that specifies allocation keywords. The following keywords can be specified in the string: space(primary–alloc[,secondary alloc]) cyl | tracks | block(block size) vol(volser[,volser]...) maxvol(num–volumes) unit(unit–name) storclas(storage–class) mgmtclas(management–class) dataclas(data–class) The next four keywords are automatically added: dsn(filesystem) dsntype(hfs) dir(1) new delay The minimum amount of time in minutes to leave the file system mounted after the duration has expired and the file system is no longer in use. The default is 10. Rule: In a shared file system environment, specify a delay time of at least 10. duration The minimum amount of time in minutes to leave the file system mounted. The default is nolimit. filesystem The name of the file system to mount. This argument is case-sensitive. For the HFS file system, this argument must be specified in uppercase. Restriction: Symbol symbolics used by the file system name template cannot be more than 44 characters long. Symbolics used for the automount (<sysname>, <asis_name>, <us_name>) are resolved within automount as part of checking the length of the file system name template. lowercase [Yes|No] Indicates the case for names that can match the * specification. This keyword is valid on any specification, but is only meaningful on the generic entry. Yes Only names composed of lowercase characters can match the * specification (numbers and special characters may also be used). When this is specified, uppercase characters are not allowed. No Any names can match the * specification. This is the default. Chapter 2. Shell command descriptions 31 automount mode The mount mode for the file system (rdwr or read). The default is rdwr. name The name of the directory to be mounted. This key is required and must be the first key specified for the entry. If the first entry specifies name *, it is treated as the generic entry for the automount-managed directory. parm The file system-specific parameter. This argument is case-sensitive. For example, the following parameters can be specified for an HFS file system: parm SYNC(t),NOWRITEPROTECT security [Yes|No] Specifies security checking which should be done for files in the file system. You can specify these values: Yes Normal security checking will be done. This is the default. No Specifies that security checks will not be enforced for files in this file system. Any user may access or change any file or directory in any way. Security auditing will still be performed if the installation is auditing successes. The SETUID, SETGID, APF, and Program Control mode bits may be turned on in files from this file system, but will not be honored while it is mounted with NOSECURITY. When a file system is mounted with the NOSECURITY option enabled, any new files or directories that are created will be assigned an owner of UID 0, no matter what UID issued the request. Rule: The installation should normally take the default (Yes). For more information about mounting with no security and on the MOUNT statement in BPXPRMxx, see z/OS UNIX System Services Planning. Security keywords on the TSO MOUNT command are also discussed in “mount — Logically mount a file system” on page 450. setuid [Yes|No] Specifies whether the setuid and setgid mode bits are to be respected for executables run from this file system. You can specify these values: Yes The setuid and setgid modes are respected. This is the default. No The setuid and setgid modes are ignored. tag (text|notext,ccsid) Specifies whether file tags for untagged files in the mounted file system are implicitly set. Either text or notext, and CCSID (coded character set identifier) must be specified when tag is specified: text Specifies that each untagged file is implicitly marked as containing pure text data that can be converted. notext Specifies that none of the untagged files in the file system are automatically converted during file reading and writing. 32 z/OS V1R12.0 UNIX System Services Command Reference automount ccsid Identifies the coded character set identifier to be implicitly set for the untagged file. ccsid is specified as a decimal value from 0 to 65535. However, when text is specified, the value must be between 0 and 65535. Other than this, the value is not checked as being valid and the corresponding code page is not checked as being installed. For more information about file tagging, see z/OS UNIX System Services Planning. Additional information about the TAG parameter can be found in mount — Logically mount a file system. type The type of the file system (such as HFS, zFS, and NFS). The default is HFS. Usage notes 1. When a new file system of the type HFS is created and allocated to a new user, the owner UID and GID are based on that user. The setting of the permission bits is 700. Note that automount uses the UID and GID of the user ID owning the process, not the thread level UID and GID. 2. When a new file system of the type zFS is created and allocated to a new user, the owner UID and GID are based on that user. The setting of the permission bits is 750. Note that automount uses the UID and GID of the userid owning the process, not the thread level UID and GID. 3. The syntax of the automount master file is extended to optionally include the name of the filter utility. Each line contains: v The path name of the directory that is to be managed. v The path name of the map file. v An optional path name of the conversion utility. If a conversion utility is specified, automount will run that utility and provide the specified map file as the standard input for the utility. It will process the standard output from the utility as the automount map file and list it on its standard output. Errors detected by automount will be flagged the same as before, but line numbers will refer to the line as output from the conversion utility rather than the original map file that the utility processes. 4. Although automount ensures that loading a new policy is an atomic operation, it does not serialize multiple simultaneous instances of running the automount utility. This remains the case when using the -a option. This should not be used in an automated script such as /etc/rc that can be run at the same time from multiple systems. This may result in changes to the automount policy not being done with no indication of this. When automount is run this way without the -a option and the same policy is loaded from all systems, it is irrelevant that the policy load from one or more systems is overlaid. 5. automount recognizes the type specification in the automount map files of HFS and zFS as potentially interchangeable file system types. At the time automount applies the specification for the mount, it will determine if the file system is the name of either an zFS or HFS file system and alters the type as appropriate. If the data set does not exist and if allocany or allocuser is not specified, a new file system is allocated as the file system type as specified in type. Allocation is only done if allocany or allocuser is specified. If it is preferred to have new file systems allocated as zFS file systems, the automount policy should be changed to specify type zFS. This allows automount-managed file systems to be changed from HFS to zFS without changing the file system name and without changing the automount Chapter 2. Shell command descriptions 33 automount policy. If the file system name must be changed, it will be necessary to add a specific entry in the automount policy for this file system or manage it on another managed directory. 6. When the allocation-spec keyword TRACKS or BLOCK is specified in either the allocany or allocuser option for zFS file systems, the specified SPACE( ) units are converted to approximate CYL equivalent units before the zFS file system is allocated. The following formulas are used to do the conversion into CYL units: 1 TRACKS Unit = 1/15 CYL Unit 1 BLOCK Unit = 1/180 CYL Unit The conversion used does not consider the device type. 7. The /// placeholder is supported when used with the allocany or allocuser keywords in automount policy files to create new file systems. 8. The steps for preparing RACF in z/OS UNIX System Services Planning include a suggestion to make the kernel address space trusted. If you did not make the local address space trusted, you must give the kernel access to the local data sets as described in Step 3 on page 33. | | Related information chmount, mount, unmount awk — Process programs written in the awk language Format awk [–F ere] [–v var=value ...] [program] [var=value ...] [file ...] awk [–F ere] [–f prog] [–v var=value ...] [var=value ...] [file ...] Description awk is a file-processing language that is well suited to data manipulation and retrieval of information from text files. If you are unfamiliar with the language, you might find it helpful to read the awk information in z/OS UNIX System Services User's Guide first. An awk program consists of any number of user-defined functions and rules of the form: pattern {action} There are two ways to specify the awk program: v Directly on the command line. In this case, program is a single command-line argument, usually enclosed in single quotes (') to prevent the shell from attempting to expand it. v By using the –f prog option. You can specify program directly on the command line only if you do not use any –f prog arguments. For a summary of the UNIX03 changes to this command, see Appendix N, “Shell commands changed for UNIX03.” 34 z/OS V1R12.0 UNIX System Services Command Reference awk Options awk recognizes the following options: –F ere Is an extended regular expression to use as the field separator. –f prog Runs the awk program contained in the file prog. When more than one –f option appears on the command line, the resulting program is a concatenation of all programs you specify. –v var=value Assigns value to var before running the program. Files that you specify on the command line with the file argument provide the input data for awk to manipulate. If you specify no files or you specify a dash (–) as a file, awk reads data from standard input (stdin). You can initialize variables on the command line using: var=value You can intersperse such initializations with the names of input files on the command line. awk processes initializations and input files in the order they appear on the command line. For example, the command: awk -f progfile a=1 f1 f2 a=2 f3 sets a to 1 before reading input from f1 and sets a to 2 before reading input from f3. Variable initializations that appear before the first file on the command line are performed immediately after the BEGIN action. Initializations appearing after the last file are performed immediately before the END action. For more information about BEGIN and END, see Patterns. The –v option lets you assign a value to a variable before the awk program begins execution (that is, before the BEGIN action). For example, in: awk -v v1=10 -f prog datafile awk assigns the variable v1 its value before the BEGIN action of the program (but after default assignments made to such built-in variables as FS and OFMT; these built-in variables have special meaning to awk, as described later). awk divides input into records. By default, newline characters separate records; however, you can specify a different record separator if you want. One at a time, and in order, awk compares each input record with the pattern of every rule in the program. When a pattern matches, awk performs the action part of the rule on that input record. Patterns and actions often refer to separate fields within a record. By default, white space (usually blanks, newlines, or horizontal tab characters) separates fields; however, you can specify a different field separator string using the –F ere option). You can omit the pattern or action part of an awk rule (but not both). If you omit pattern, awk performs the action on every input record (that is, every record matches). If you omit action, awk's default action is equivalent to: {print}. awk considers everything after a # in a program line to be a comment. For example: Chapter 2. Shell command descriptions 35 awk # This is a comment To continue program lines on the next line, add a backslash (\) to the end of the line. Statement lines ending with a comma (,), double or-bars (||), or double ampersands (&&) continue automatically on the next line. Variables and expressions There are three types of variables in awk: identifiers, fields, and array elements. An identifier is a sequence of letters, digits, and underscores beginning with a letter or an underscore. These characters must be from the POSIX portable character set. (Data can come from other character sets.) For a description of fields, see Input. Arrays are associative collections of values called the elements of the array. Constructs of the form: identifier[subscript] where subscript has the form expr or expr,expr,..., refer to array elements. Each such expr can have any string value. For multiple expr subscripts, awk concatenates the string values of all expr arguments with a separate character SUBSEP between each. The initial value of SUBSEP is set to \042 (code page 01047 field separator). We sometimes refer to fields and identifiers as scalar variables to distinguish them from arrays. You do not declare awk variables, and you do not need to initialize them. The value of an uninitialized variable is the empty string in a string context and the number 0 in a numeric context. Expressions consist of constants, variables, functions, regular expressions, and subscript-in-array conditions combined with operators. (Subscript-in-array conditions are described in Subscript in array.) Each variable and expression has a string value and a corresponding numeric value; awk uses the value appropriate to the context. When converting a numeric value to its corresponding string value, awk performs the equivalent of a call to the sprintf() function where the one and only expr argument is the numeric value and the fmt argument is either %d (if the numeric value is an integer) or the value of the variable CONVFMT (if the numeric value is not an integer). The default value of CONVFMT is %.6g. If you use a string in a numeric context, and awk cannot interpret the contents of the string as a number, it treats the value of the string as zero. Numeric constants are sequences of decimal digits. String constants are quoted, as in "a literal string". Literal strings can contain the following escape sequences: Escape Character \a \b \f \n \r 36 z/OS V1R12.0 UNIX System Services Command Reference Sequence Audible bell Backspace Form feed Newline Carriage return awk Horizontal tab Vertical tab Octal value ooo Hexadecimal value dd Slash Quote Any other character c \t \v \ooo \xdd \/ \" \c awk supports full regular expressions. (See Appendix C, “Regular expressions (regexp),” on page 915 for more information.) When awk reads a program, it compiles characters enclosed in slash characters (/) as regular expressions. In addition, when literal strings and variables appear on the right side of a ~ or!~ operator, or as certain arguments to built-in matching and substitution functions, awk interprets them as dynamic regular expressions. Note: When you use literal strings as regular expressions, you need extra backslashes to escape regular expression metacharacters, because the backslash is also the literal string escape character. For example, the regular expression: /e\.g\./ should be written as: "e\\.g\\." Subscript in array awk defines the subscript-in-array condition as: index in array where index looks like expr or (expr,...,expr). This condition evaluates to 1 if the string value of index is a subscript of array, and to 0 otherwise. This is a way to determine if an array element exists. When the element does not exist, the subscript-in-array condition does not create it. Symbol table You can access the symbol table through the built-in array SYMTAB. SYMTAB[expr] is equivalent to the variable named by the evaluation of expr. For example, SYMTAB["var"] is a synonym for the variable var. Environment An awk program can determine its initial environment by examining the ENVIRON array. If the environment consists of entries of the form name=value, then ENVIRON[name] has string value "value". For example, the following program is equivalent to the default output of env: BEGIN { for (i in ENVIRON) printf("%s=%s\n", i, ENVIRON[i]) exit } Operators awk follows the usual precedence order of arithmetic operations, unless overridden with parentheses; a table giving the order of operations appears later in this topic. Chapter 2. Shell command descriptions 37 awk The unary operators are +, −, ++, and − −, where you can use the ++ and − − operators as either postfix or prefix operators, as in C. The binary arithmetic operators are +, −, *, /, %, and ^. The conditional operator expr ? expr1 : expr2 evaluates to expr1 if the value of expr is nonzero, and to expr2 otherwise. If two expressions are not separated by an operator, awk concatenates their string values. The tilde operator ~ yields 1 (true) if the regular expression on the right side matches the string on the left side. The operator !~ yields 1 when the right side has no match on the left. To illustrate: $2 ~ /[0-9]/ selects any line where the second field contains at least one digit. awk interprets any string or variable on the right side of ~ or !~ as a dynamic regular expression. The relational operators are <, <=, >, >=, ==, and !=. When both operands in a comparison are numeric, or if one is numeric and the other is not initialized, awk compares their values numerically; otherwise, it compares them as strings. An operator is considered to be numeric if it consists of any of the following: v An integer or floating-point number v A field, FILENAME, ARGV array element, or ENVIRON array element that looks like a number v A variable created by a command-line assignment that looks like a number v Input from a getline() function that looks like a number v An array element created by the split() function that looks like a number v A variable assignment from another number variable that looks like a number The Boolean operators are || (or), && (and), and ! (not). awk uses short-circuit evaluation when evaluating expressions. With an && expression, if the first operator is false, the entire expression is false and it is not necessary to evaluate the second operator. With an || expression, a similar situation exists if the first operator is true. You can assign values to a variable with: var = expr If op is a binary arithmetic operator, var op= expr is equivalent to var = var op expr, except that var is evaluated only once. See Table 2 for the precedence rules of the operators. Table 2. The order of operations for awk 38 Operators Order of operations (A) Grouping $i V[a] Field, array element V++ V-- ++V --V Increment, decrement A^B Exponentiation z/OS V1R12.0 UNIX System Services Command Reference awk Table 2. The order of operations for awk (continued) Operators Order of operations +A Unary plus, unary minus, logical NOT -A !A A*B A/B A+B A-B A%B Multiplication, division, remainder Addition, subtraction A B String concatenation A<B A>B A<=B A>=B A!=B A==B Comparisons A~B A!~B Regular expression matching A in V Array membership A && B Logical AND A || B Logical OR A ? B : C Conditional expression V=B V+=B V-=B V*=B V/=B V%=B V^=B Assignment Notes: 1. A, B, C are any expression. 2. i is any expression yielding an integer. 3. V is any variable. Command-line arguments awk sets the built-in variable ARGC to the number of command-line arguments. The built-in array ARGV has elements subscripted with digits from zero to ARGC−1, giving command-line arguments in the order they appeared on the command line. The ARGC count and the ARGV vector do not include command-line options (beginning with -) or the program file (following –f). They do include the name of the command itself, initialization statements of the form var=value, and the names of input data files. awk actually creates ARGC and ARGV before doing anything else. It then “walks through” ARGV, processing the arguments. If an element of ARGV is an empty string, awk skips it. If it contains an equals sign (=), awk interprets it as a variable assignment. If it is a minus sign (−), awk immediately reads input from stdin until it encounters the end of the file. Otherwise, awk treats the argument as a file name and reads input from that file until it reaches the end of the file. Note: awk runs the program by “walking through” ARGV in this way; thus, if the program changes ARGV, awk can read different files and make different assignments. Input awk divides input into records. A record separator character separates each record from the next. The value of the built-in variable RS gives the current record separator character; by default, it begins as the newline (\n). If you assign a different character to RS, awk uses that as the record separator character from that point on. awk divides records into fields. A field separator string, given by the value of the built-in variable FS, separates each field from the next. You can set a specific Chapter 2. Shell command descriptions 39 awk separator string by assigning a value to FS, or by specifying the –F ere option on the command line. You can assign a regular expression to FS. For example: FS = "[,:$]" says that commas, colons, or dollar signs can separate fields. As a special case, assigning FS a string containing only a blank character sets the field separator to white space. In this case, awk considers any sequence of contiguous space or tab characters a single field separator. This is the default for FS. However, if you assign FS a string containing any other character, that character designates the start of a new field. For example, if we set FS=\t (the tab character), texta \t textb \t \t \t textc contains five fields, two of which contain only blanks. With the default setting, this record only contains three fields, since awk considers the sequence of multiple blanks and tabs a single separator. The following list of built-in variables provides various pieces of information about input: NF Number of fields in the current record NR Number of records read so far FILENAME Name of file containing current record FNR Number of records read from current file Field specifiers have the form $n, where n runs from 1 through NF. Such a field specifier refers to the nth field of the current input record. $0 (zero) refers to the entire current input record. The getline function can read a value for a variable or $0 from the current input, from a file, or from a pipe. The result of getline is an integer indicating whether the read operation was successful. A value of 1 indicates success; 0 indicates that the end of the file was encountered; and −1 indicates that an error occurred. Possible forms for getline are: getline Reads next input record into $0 and splits the record into fields. NF, NR, and FNR are set appropriately. getline var Reads the next input record into the variable var. awk does not split the record into fields (which means that the current $n values do not change), but sets NR and FNR appropriately. getline <expr Interprets the string value of expr to be a file name. awk reads the next record from that file into $0, splits it into fields, and sets NF appropriately. If the file is not open, awk opens it. The file remains open until you close it with a close function. getline var <expr Interprets the string value of expr to be a file name, and reads the next record from that file into the variable var, but does not split it into fields. expr | getline Interprets the string value of expr as a command line to be run. awk pipes 40 z/OS V1R12.0 UNIX System Services Command Reference awk output from this command into getline, and reads it into $0, splits it into fields, and sets NF appropriately. See System function for additional details. expr | getline var Runs the string value of expr as a command and pipes the output of the command into getline. The result is similar to getline var <expr. You can have only a limited number of files and pipes open at one time. You can close files and pipes during execution using the close(expr) function. The expr argument must be one that came before | or after < in getline, or after > or >> in print or printf. If the function successfully closes the pipe, it returns zero. By closing files and pipes that you no longer need, you can use any number of files and pipes in the course of running an awk program. Built-in arithmetic functions atan2(expr1, expr2) Returns the arctangent of expr1/expr2 in the range of −π through π. exp(expr), log(expr), sqrt(expr) Returns the exponential, natural logarithm, and square root of the numeric value of expr. If you omit (expr), these functions use $0 instead. int(expr) Returns the integer part of the numeric value of expr. If you omit (expr), the function returns the integer part of $0. rand() Returns a random floating-point number in the range 0 through 1. sin(expr), cos(expr) Returns the sine and cosine of the numeric value of expr (interpreted as an angle in radians). srand(expr) Sets the seed of the rand function to the integer value of expr. If you omit (expr), awk uses the time of day as a default seed. Built-in string functions len = length (expr) Returns the number of characters in the string value of expr. If you omit (expr), the function uses $0 instead. The parentheses around expr are optional. n = split(string, array, regexp) Splits the string into fields. regexp is a regular expression giving the field separator string for the purposes of this operation. This function assigns the separate fields, in order, to the elements of array; subscripts for array begin at 1. awk discards all other elements of array. split returns the number of fields into which it divided string (which is also the maximum subscript for array). regexp divides the record in the same way that the FS field separator string does. If you omit regexp in the call to split, it uses the current value of FS. str = substr(string, offset, len) Returns the substring of string that begins in position offset and is at most Chapter 2. Shell command descriptions 41 awk len characters long. The first character of the string has an offset of 1. If you omit len, or if len specifies more characters than are left in the string, substr returns the rest of string. pos = index(string, str) Returns the position of the first occurrence of str in string. The count is in characters. If index does not find str in string, it returns 0. pos = match(string, regexp) Searches string for the first substring matching the regular expression regexp, and returns an integer giving the position of this substring counting from 1. If it finds no such substring, match returns zero. This function also sets the built-in variable RSTART to pos and the built-in variable RLENGTH to the length of the matched string. If it does not find a match, match sets RESTART to 0, and RLENGTH to −1. You can enclose regexp in slashes or specify it as a string. n = sub(regexp, repl, string) Searches string for the first substring matching the regular expression regexp, and replaces the substring with the string repl. awk replaces any ampersand (&) in repl with the substring of string which matches regexp. An ampersand preceded with a backslash ('\') is interpreted as the literal ampersand character. An occurrence of two consecutive backslashes is interpreted as just a single literal backslash character. Any other occurrence of a backslash (for example, preceding any other character) is treated as a literal backslash character. If repl is a string literal, the handling of the ampersand character occurs after any lexical processing, including any lexical backslash escape sequence. If you omit string, sub uses the current record instead. sub returns the number of substrings replaced (which is 1 if it found a match, and 0 otherwise). n = gsub(regexp, repl, string) Works the same way as sub, except that gsub replaces all matching substrings (global substitution). The return value is the number of substitutions performed. str = sprintf(fmt, expr, expr...) Formats the expression list expr, expr, ... using specifications from the string fmt, and then returns the formatted string. The fmt string consists of conversion specifications that convert and add the next expr to the string, and ordinary characters that sprintf simply adds to the string. These conversion specifications are similar to those used by the ANSI C standard. Conversion specifications have the form %[-][0][x][.y]c where - Left-justifies the field; default is right justification. 0 (Leading zero) prints numbers with leading zero. x Is the minimum field width. y Is the precision. c Is the conversion character. In a string, the precision is the maximum number of characters to be printed from the string; in a number, the precision is the number of digits to be printed to the 42 z/OS V1R12.0 UNIX System Services Command Reference awk right of the decimal point in a floating-point value. If x or y is * (asterisk), the minimum field width or precision is the value of the next expr in the call to sprintf. The conversion character c is one of following: d Decimal integer i Decimal integer o Unsigned octal integer x,X Unsigned hexadecimal integer u Unsigned decimal integer f,F Floating point e,E Floating point (scientific notation) g,G The shorter of e and f (suppresses nonsignificant zeros) c Single character of an integer value; first character of string s String The lowercase x specifies alphabetic hexadecimal digits in lowercase, whereas the uppercase X specifies alphabetic hexadecimal digits in uppercase. The other uppercase-lowercase pairs work similarly. n = ord(expr) Returns the integer value of first character in the string value of expr. This is useful in conjunction with %c in sprintf. str = tolower(expr) Converts all letters in the string value of expr into lowercase, and returns the result. If you omit expr, tolower uses $0 instead. This function uses the value of the locale or the LC_CTYPE environment variable. str = toupper(expr) Converts all letters in the string value of expr into uppercase, and returns the result. If you omit expr, toupper uses $0 instead. This function uses the value of the locale or the LC_CTYPE environment variable. System function status = system(expr) Runs the string value of expr as a command. For example, system("tail " $1) calls the tail command, using the string value of $1 as the file that tail examines. The standard command interpreter runs the command, as discussed in the Portability section, and the exit status returned depends on that command interpreter. User-defined functions You can define your own functions using the form: function name(parameter-list) { statements } A function definition can appear in the place of a pattern {action} rule. The parameter-list argument contains any number of normal (scalar) and array variables separated by commas. When you call a function, awk passes scalar arguments by value, and array arguments by reference. The names specified in parameter-list are Chapter 2. Shell command descriptions 43 awk local to the function; all other names used in the function are global. You can define local variables by adding them to the end of the parameter list as long as no call to the function uses these extra parameters. A function returns to its caller either when it runs the final statement in the function, or when it reaches an explicit return statement. The return value, if any, is specified in the return statement (see Actions). Patterns A pattern is a regular expression, a special pattern, a pattern range, or any arithmetic expression. BEGIN is a special pattern used to label actions that awk performs before reading any input records. END is a special pattern used to label actions that awk performs after reading all input records. You can give a pattern range as: pattern1,pattern2 This matches all lines from one that matches pattern1 to one that matches pattern2, inclusive. If you omit a pattern, or if the numeric value of the pattern is nonzero (true), awk runs the resulting action for the line. Actions An action is a series of statements ended by semicolons, newlines, or closing braces. A condition is any expression; awk considers a nonzero value true, and a zero value false. A statement is one of the following or any series of statements enclosed in braces: # expression statement, e.g. assignment expression # if statement if (condition) statement [else statement] # while loop while (condition) statement # do-while loop do statement while (condition) # for loop for (expression1; condition; expression2) statement The for statement is equivalent to: expression1 while (condition) { statement expression2 } The for statement can also have the form: for (i in array) statement 44 z/OS V1R12.0 UNIX System Services Command Reference awk awk runs the statement (specified with the statement argument) once for each element in array; on each repetition, the variable i contains the name of a subscript of array, running through all the subscripts in an arbitrary order. If array is multidimensional (has multiple subscripts), i is expressed as a single string with the SUBSEP character separating the subscripts. v The statement break exits a for or a while loop immediately. continue stops the current iteration of a for or while loop and begins the next iteration (if there is one). v next ends any processing for the current input record and immediately starts processing the next input record. Processing for the next record begins with the first appropriate rule. If a next statement appears or is invoked in a BEGIN or END action, awk will cause all further BEGIN or END action processing to be abandoned. v exit[(expr)] immediately goes to the END action if it exists; if there is no END action, or if awk is already running the END action, the awk program ends. awk sets the exit status of the program to the numeric value of expr. If you omit (expr), the exit status is 0. return [expr] returns from the execution of a function. If you specify an expr, the function returns the value of the expression as its result; otherwise, the function result is undefined. delete array[i] deletes element i from the given array. print expr, expr, ... is described in Output. printf fmt, expr, expr, ... is also described in Output. Output The print statement prints its arguments with only simple formatting. If it has no arguments, it prints the entire current input record. awk adds the output record separator ORS to the end of the output that each print statement produces; when commas separate arguments in the print statement, the output field separator OFS separates the corresponding output values. ORS and OFS are built-in variables, whose values you can change by assigning them strings. The default output record separator is a newline, and the default output field separator is a space. The variable OFMT gives the format of floating-point numbers output by print. By default, the value is %.6g; you can change this by assigning OFMT a different string value. OFMT applies only to floating-point numbers (ones with fractional parts). The printf statement formats its arguments using the fmt argument. Formatting is the same as for the built-in function sprintf. Unlike print, printf does not add output separators automatically. This gives the program more precise control of the output. The print and printf statements write to stdout. You can redirect output to a file or pipe. If you add >expr to a print or printf statement, awk treats the string value of expr as a file name, and writes output to that file. Similarly, if you add >>expr, awk sends output to the current contents of the file. The distinction between > and >> is important only for the first print to the file expr. Subsequent outputs to an already open file append to what is there already. You cannot use such ambiguous statements as: print a > b c Use parentheses to resolve the ambiguity. Chapter 2. Shell command descriptions 45 awk If you add |expr to a print or printf statement, awk treats the string value of expr as an executable command and runs it with the output from the statement piped as input into the command. As mentioned earlier, you can have only a limited number of files and pipes open at any time. To avoid going over the limit, use the close function to close files and pipes when you no longer need them. print and printf are also available as functions with the same calling sequence, but no redirection. Examples 1. The following example: awk ’{print NR ":" $0}’ input1 outputs the contents of the file input1 with line numbers prepended to each line. 2. The following is an example using var=value on the command line: awk ’{print NR SEP $0}’ SEP=":" input1 awk can also read the program script from a file as in the command line: awk –f addline.awk input1 which produces the same output when the file addline.awk contains: {print NR ":" $0} 3. The following program appends all input lines starting with January to the file jan (which may or may not exist already), and all lines starting with February or March to the file febmar: /^January/ {print >> "jan"} /^February|^March/ {print >> "febmar"} 4. This program prints the total and average for the last column of each input line: END {s += $NF} {print "sum is", s, "average is", s/NR} 5. The next program interchanges the first and second fields of input lines: { tmp = $1 $1 = $2 $2 = tmp print } 6. The following inserts line numbers so that output lines are left-aligned: {printf "%–6d: %s\n", NR, $0} 7. The following prints input records in reverse order (assuming sufficient memory): { a[NR] = $0 # index using record number } END { for (i = NR; i>0; --i) print a[i] } 8. The following program determines the number of lines starting with the same first field: 46 z/OS V1R12.0 UNIX System Services Command Reference awk { ++a[$1] # array indexed using the first field } END { # note output will be in undefined order for (i in a) print a[i], "lines start with", i } You can use the following program to determine the number of lines in each input file: { ++a[FILENAME] } END { for (file in a) if (a[file] == 1) print file, "has 1 line" else print file, "has", a[file], "lines" } 9. The following program illustrates how you can use a two-dimensional array in awk. Assume the first field of each input record contains a product number, the second field contains a month number, and the third field contains a quantity (bought, sold, or whatever). The program generates a table of products versus month. BEGIN { {NUMPROD = 5} array[$1,$2] += $3 } END { print "\t Jan\t Feb\tMarch\tApril\t May\t" \ "June\tJuly\t Aug\tSept\t Oct\t Nov\t Dec" for (prod = 1; prod <= NUMPROD; prod++) { printf "%-7s", "prod#" prod for (month = 1; month <= 12; month++){ printf "\t%5d", array[prod,month] } printf "\n" } } 10. As the following program reads in each line of input, it reports whether the line matches a predetermined value: function randint() { return (int((rand()+1)*10)) } BEGIN { prize[randint(),randint()] = "$100"; prize[randint(),randint()] = "$10"; prize[1,1] = "the booby prize" } { if (($1,$2) in prize) printf "You have won %s!\n", prize[$1,$2] } 11. The following example prints lines, the first and last fields of which are the same, reversing the order of the fields: $1==$NF { for (i = NF; i > 0; --i) printf "%s", $i (i>1 ? OFS : ORS) } Chapter 2. Shell command descriptions 47 awk 12. The following program prints the input files from the command line. The infiles function first empties the passed array, and then fills the array. The extra parameter i of infiles is a local variable. function infiles(f,i) { for (i in f) delete f[i] for (i = 1; i < ARGC; i++) if (index(ARGV[i],"=") == 0) f[i] = ARGV[i] } BEGIN { infiles(a) for (i in a) print a[i] exit } 13. Here is the standard recursive factorial function: function fact(num) { if (num <= 1) return 1 else return num * fact(num - 1) } { print $0 " factorial is " fact($0) } 14. The following program illustrates the use of getline with a pipe. Here, getline sets the current record from the output of the wc command. The program prints the number of words in each input file. function words(file, string) { string = "wc " fn string | getline close(string) return ($2) } BEGIN { for (i=1; i<ARGC; i++) { fn = ARGV[i] printf "There are %d words in %s.", words(fn), fn } } Environment variables awk uses the following environment variables: PATH Contains a list of directories that awk searches when looking for commands run by system(expr), or input and output pipes. _UNIX03 For more information about the effect of _UNIX03 on the awk command, see Appendix N, “Shell commands changed for UNIX03,” on page 975. Any other environment variable can be accessed by the awk program itself. Localization awk uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES 48 z/OS V1R12.0 UNIX System Services Command Reference awk v LC_NUMERIC v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion v If the awk program contains no actions and no patterns, but is otherwise a valid awk program, standard input and any file operands are not read and awk exits with an exit status of zero. 1 Any of the following errors: v Parser internal stack overflow v Syntax error v Function redefined v Internal execution tree error v Insufficient memory for string storage v Unbalanced parenthesis or brace v Missing script file v Missing field separator v Missing variable assignment v Unknown option v Incorrect character in input v Newline in regular expression v Newline in string v EOF in regular expression v EOF in string v Cannot open script file v Inadmissible use of reserved keyword v Attempt to redefine built-in function v Cannot open input file v Error on print v Error on printf v Getline in END action was not redirected v Too many open I/O streams v Error on I/O stream v Insufficient arguments to printf or sprintf() v Array cannot be used as a scalar v Variable cannot be used as a function v Too many fields v Record too long v Division (/ or %) by zero v Syntax error v Cannot assign to a function v Value required in assignment v Return outside of a function v Can delete only array element or array v Scalar cannot be used as array v SYMTAB must have exactly one index v Impossible function call v Function call nesting level exceeded v Wrong number of arguments to function v Regular expression error v Second parameter to “split” must be an array v sprintf string longer than allowed number of characters Chapter 2. Shell command descriptions 49 awk v v v v v v v v v v v v v v v v v v No open file name Function requires an array Is not a function Failed to match Incorrect collation element Trailing \ in pattern Newline found before end of pattern More than 9 \( \) pairs Number in [0–9] incorrect [ ] imbalance or syntax error ( ) or \( \) imbalance { } or \{ \} imbalance Incorrect endpoint in range Out of memory Incorrect repetition Incorrect character class type Internal error Unknown regex error When an awk program ends because of a call to exit(), the exit status is the value passed to exit(). Limits Most constructions in this implementation of awk are dynamic, limited only by memory restrictions of the system. The maximum record size is guaranteed to be at least LINE_MAX as returned by getconf. The maximum field size is guaranteed to be LINE_MAX, also. The parser stack depth is limited to 150 levels. Attempting to process extremely complicated programs may result in an overflow of this stack, causing an error. Input must be text files. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The ord function is an extension to traditional implementations of awk. The toupper and tolower functions and the ENVIRON array are in POSIX and the UNIX System V Release 4 version of awk. This version is a superset of New awk, as described in The AWK Programming Language by Aho, Weinberger, and Kernighan. The standard command interpreter that the system function uses and that awk uses to run pipelines for getline, print, and printf is system-dependent. On z/OS UNIX, this interpreter is always /bin/sh. Related information ed, egrep, sed, vi For more information about regexp, see Appendix C, “Regular expressions (regexp),” on page 915. 50 z/OS V1R12.0 UNIX System Services Command Reference basename basename — Return the nondirectory components of a path name Format basename name [suffix] Description basename strips off the leading part of a path name, leaving only the final component of the name, which is assumed to be the file name. To accomplish this, basename first checks to see if name consists of nothing but slash (/) characters. If so, basename replaces name with a single slash and the process is complete. If not, basename removes trailing slashes. If slashes still remain, basename strips off all leading characters up to and including the final slash. Finally, if you specify suffix and the remaining portion of name contains a suffix that matches suffix, basename removes that suffix. Examples The command: basename src/dos/printf.c produces: printf.c Localization basename uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Unknown command-line option v Incorrect number of arguments Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information dirname batch — Run commands when the system is not busy Format batch Chapter 2. Shell command descriptions 51 batch Description batch lets you run commands in batch mode. It reads the commands from the standard input (stdin). The system records the commands and runs them at a time when the system load is relatively low (that is, when the system is not busy). The batch command is equivalent to at –q b –m now For more details, see at. at, batch, and crontab submit jobs to cron; the data in those jobs may contain double-byte characters. When the jobs are run, the data in the jobs are interpreted in the locale that cron is using. Since it is strongly recommended that cron be started in the POSIX locale, double-byte characters in the job may not be interpreted correctly. You may be able to get around this by calling setlocale() in the job itself. Environment variables batch uses the following environment variable: SHELL Contains the name of the shell command interpreter used to invoke the batch job. Localization batch uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion >0 Returned if the command fails for any reason If an error occurs, batch does not schedule the job. Portability POSIX.2 User Portability Extension Related information at, bg, crontab bc — Use the arbitrary-precision arithmetic calculation language Format bc [–i] [–l] [file] 52 z/OS V1R12.0 UNIX System Services Command Reference bc Description bc is a programming language that can perform arithmetic calculations to arbitrary precision. You can use it interactively, by entering instructions from the terminal. It can also run programs taken from files. The file arguments you specify on the command line should be text files containing bc instructions. bc runs the instructions from those files, in the order that they appear on the command line, and then runs instructions from the standard input (stdin). bc ends when it runs a quit instruction or reaches the end of the file on stdin. bc is a simple but complete programming language with a syntax reminiscent of the C programming language. This version of bc is a superset of the standard language available on most systems. It has a number of additional features intended to make the language more flexible and useful. Features unique to this implementation are noted. Input consists of a series of instructions that assign values to variables or make calculations. It is also possible to define subprograms called functions, which perform a sequence of instructions to calculate a single value. bc displays the result of any line that calculates a value, but does not assign it to a variable. For example, the instruction: 2+2 displays: 4 By default, bc displays the result of any evaluated instruction followed by a newline. bc also saves the last value displayed in a special variable . (dot), so that you can use it in subsequent calculations. For a summary of the UNIX03 changes to this command, see Appendix N, “Shell commands changed for UNIX03.” Options bc supports the following options. –i Puts bc into interactive mode with a displayed prompt. In this mode, bc displays a prompt, which is “:”—waiting for input. In addition, it handles errors somewhat differently. Normally, when bc encounters an error while processing a file, the interpreter displays the error message and exits. In interactive mode, the interpreter displays the message and returns to the prompt mode to allow debugging. –l Loads a library of standard mathematical functions before processing any other input. This library also sets the scale to 20. For a description of the functions in the –l library, see Built-in functions. Numbers Numbers consist of an optional minus (−) sign or an optional plus (+) sign followed by a sequence of zero or more digits, followed by an optional decimal point (.), followed by a sequence of zero or more digits. Valid digits are 0 through 9, and the hexadecimal digits A through F. The uppercase letters represent the Chapter 2. Shell command descriptions 53 bc values from 10 through 15. There must be at least one digit, either before or after the decimal point. If not, bc interprets the decimal point as the special variable .. A number can be arbitrarily long and can contain spaces. Here are some valid numbers with an input base of 10: 0 0. .0 -3.14159 +09. -12 1 000 000 Here are some valid numbers with an input base of 16 (ibase=16): 0 FF FF.3 -10.444 A1 See Bases for more information. Restriction: You cannot break up numbers with commas; you can write 1000000 or 1 000 000, but 1,000,000 results in an error message. Identifiers Identifiers can include sequences containing any number of letters, digits, or the underscore (_) character but must start with a lowercase letter. Spaces are not allowed in identifiers. In the POSIX locale, valid identifiers can include sequences containing any number of letters, digits, or the underscore (_) character but must start with a lowercase letter, as defined by the current locale. For other locales, the character map for that locale determines which characters are valid in an identifier. If you want identifiers to be portable between locales, use characters from the POSIX character set. The use of identifiers longer than one character is an extension of this implementation. Identifiers are used as names for variables, functions, or arrays: v A variable holds a single numeric value. You can declare variables that are local to a function using the auto statement. (See Functions). All other variables are global and you can use them inside any function or outside all functions. You do not need to declare global variables. bc creates variables as it requires them, with an initial value of zero. (Remember that there is also the special variable . [dot], which contains the result of the last calculation.) v A function is a sequence of instructions that calculates a single value. A list of zero or more values enclosed in parentheses always follow a function name, as in my_func(3.14159). See Functions. v An array is a list of values. Values in the list are called elements of the array. These elements are numbered, beginning at zero. We call such a number a subscript, or index, of the array. Subscripts always appear in square brackets after the array. For example, a[0] refers to element zero in the array a. The first element of the array always has the subscript 0. If a subscript value is a floating-point number, the fractional part is discarded to make the subscript into an integer. For example, the following expressions all refer to the same element: a[3] a[3.2] a[3.999] The maximum number of elements in a bc array is in the range from 0 to {BC_DIM_MAX}−1 inclusive. Unlike with many languages, you don't need to declare the size of an array. Elements are created dynamically as required, with an initial value of zero. Since parentheses always follow function names and square brackets always follow array names, bc can distinguish between all three types of names—variable names, 54 z/OS V1R12.0 UNIX System Services Command Reference bc function names, and array names. Therefore, you can have variables, functions, and arrays with the same name. For example, foo may be a variable whereas foo() is a function and foo[ ] is an array. Built-in variables bc has a number of built-in variables that are used to control various aspects of the interpreter. These are described in the following topics. Scale The scale value is the number of digits to be retained after the decimal point in arithmetic operations. For example, if the scale is 3, each calculation retains at least three digits after the decimal point. This means that: 5 / 3 has the value: 1.666 If –l is specified, the scale is set to 20; otherwise, the default scale is zero. The variable scale holds the current scale value. To change scales, assign a new value to scale, as in: scale = 5 Since scale is just a regular bc variable, it can be used in the full range of bc expressions. The number of decimal places in the result of a calculation is affected not only by the scale, but also by the number of decimal places in the operands of the calculation. discusses this. Arithmetic operations discusses this. There is also a function scale, which can determine the scale of any expression. For example, scale(1.1234) returns the result 4, which is the scale of the number 1.1234. The result of the scale function is always an integer (that is, it has the scale of 0). The maximum value for scale is given by the configuration variable {BC_SCALE_MAX} and the minimum value is 0. Bases bc lets you specify numbers in different bases—for example, octal (base 8) or hexadecimal (base 16). You can input numbers in one base and output them in a different base, simplifying the job of converting from one base to another. bc does this using the built-in variables ibase and obase. ibase is the base for input numbers. It has an initial value of 10 (normal decimal numbers). To use a different base for inputting numbers, assign an integer to ibase, as in: ibase = 8 This means that all future input numbers are to be in base 8 (octal). The largest valid input base is 16, and the smallest valid input base is 2. There is no mechanism provided to represent digits larger than 15, so bases larger than 16 are essentially useless. When the base is greater than 10, use the uppercase letters as digits. For example, base 16 uses the digits 0 through 9, and A through F. The digits are allowed in any number, regardless of the setting of ibase but are largely Chapter 2. Shell command descriptions 55 bc meaningless if the base is smaller than the digit. The one case where this is useful is in resetting the input base to 10. The constant A always has the value 10 no matter what ibase is set to, so to reset the input base to 10, type: ibase = A obase is the base in which numbers are output. It has an initial value of 10 (normal decimal numbers). To change output bases, assign an appropriate integer to obase. If the output base is 16 or less, bc displays numbers with normal digits and hexadecimal digits (if needed). The output base can also be greater than 16, in which case each digit is printed as a decimal value and digits are separated by a single space. For example, if obase is 1000, the decimal number 123 456 789 is printed as: 123 456 789 Here, the digits are decimal values from 0 through 999. As a result, all output values are broken up into one or more chunks with three digits per chunk. Using output bases that are large powers of 10, you can arrange your output in columns; for example, many users find that 100 000 makes a good output base, because numbers are grouped into chunks of five digits each. Long numbers are output with a maximum of 70 characters per line. If a number is longer than this, bc puts a backslash (\) at the end of the line indicating that the number is continued on the next line. The backslash (\) and newline characters are counted as part of the 70 character length. Internal calculations are performed in decimal, regardless of the input and output bases. Therefore the number of places after the decimal point are dictated by the scale when numbers are expressed in decimal form. The maximum value for obase is given by the configuration variable {BC_BASE_MAX}. Arithmetic operations bc provides a large number of arithmetic operations. Following standard arithmetic conventions, some operations are calculated before others. For example, multiplications take place before additions unless you use parentheses to group operations. Operations that take place first are said to have a higher precedence than operations that take place later. Operations also have an associativity. The associativity dictates the order of evaluation when you have a sequence of operations with equal precedence. Some operations are evaluated left to right, whereas others are evaluated right to left. The following list shows the operators of bc from highest precedence to lowest. 56 bc Operator Associativity () Left to right Unary ++ −− Not applicable Unary − ! Not applicable ^ Right to left */% Left to right +− Left to right z/OS V1R12.0 UNIX System Services Command Reference bc = ^= *= /= %= += Right to left == <= >= != < > None && Left to right || Left to right bc’s order of precedence is not the same as C’s. In C, the assignment operators have the lowest precedence. The following list describes what each operation does. In the descriptions, A and B can be numbers, variables, array elements, or other expressions. V must be either a variable or an array element. (A) Indicates that this expression—A—should be evaluated before any other operations are performed on it. -A Is the negation of the expression. !A Is the logical complement of the expression. If A evaluates to zero, !A evaluates to 1. If A is not zero, !A evaluates to zero. This operator is unique to this version of bc. ++V Adds 1 to the value of V. The result of the expression is the new value of V. − −V Subtracts 1 from the value of V. The result of the expression is the new value of V. V++ Adds 1 to the value of V, but the result of the expression is the old value of V. V− − Subtracts 1 from the value of V, but the result of the expression is the old value of V. A ^ B Calculates A to the power B. B must be an integer. The scale of the result of A^B is: min(scale(A) * abs(B), max(scale, scale(A))) where min calculates the minimum of a set of numbers and max calculates the maximum. A*B Calculates A multiplied by B. The scale of the result is: min(scale(A) + scale(B), max(scale, scale(A), scale(B))) A/B Calculates A divided by B. The scale of the result is the value of scale. A % B Calculates the remainder from the division of A by B. This is calculated in two steps. First, bc calculates A/B to the current scale. It then obtains the remainder through the formula: A - (A / B) * B calculated to the scale: max(scale + scale(B), scale(A)) A + B Adds A plus B. The scale of the result is the maximum of the two scales of the operands. A−B Calculates A minus B. The scale of the result is the maximum of the two scales of the operands. Chapter 2. Shell command descriptions 57 bc The next group of operators are all assignment operators. They assign values to objects. An assignment operation has a value: the value that is being assigned. Therefore, you can write such operations as a=1+(b=2). In this operation, the value of the assignment in parentheses is 2 because that is the value assigned to b. Therefore, the value 3 is assigned to a. The possible assignment operators are: V=B Assigns the value of B to V. V ^= B Is equivalent to V=V^B. V *= B Is equivalent to V=V*B. V /= B Is equivalent to V=V/B. V %= B Is equivalent to V=V%B. V += B Is equivalent to V=V+B. V −= B Is equivalent to V=V-B. The following expressions are called relations, and their values can be either true (1) or false (0). This version of bc lets you use the relational operators in any expression, not just in the conditional parts of if, while, or for statements. These operators work exactly like their equivalents in the C language. The result of a relation is 0 if the relation is false and 1 if the relation is true. A == B Is true if and only if A equals B. A <= B Is true if and only if A is less than or equal to B. A >= B Is true if and only if A is greater than or equal to B. A != B Is true if and only if A is not equal to B. A<B Is true if and only if A is less than B. A>B Is true if and only if A is greater than B. A && B Is true if and only if A is true (nonzero) and B is true. If A is not true, the expression B is never evaluated. A || B Is true if A is true or B is true. If A is true, the expression B is never evaluated. Comments and white space A comment has the form: /* Any string */ Comments can extend over more than one line of text. When bc sees /* at the start of a comment, it discards everything up to the next */. The only effect a comment has is to indicate the end of a token. As an extension, this version of bc also provides an additional comment convention using the # character. All text from the # to the end of the line is treated as a single blank, as in: 2+2 # this is a comment bc is free format. You can freely insert blanks or horizontal tab characters to improve the readability of the code. Instructions are assumed to end at the end of the line. If you have an instruction that is so long you need to continue it on a new line, put a backslash (\) as the very last character of the first line and continue on the second, as in: a = 2\ + 3 58 z/OS V1R12.0 UNIX System Services Command Reference bc The \ indicates that the instruction continues on the next line, so this is equivalent to: a = 2 + 3 Instructions A bc instruction can be an expression that performs a calculation, an assignment, a function definition, or a statement. If an instruction is not an assignment, bc displays the result of the instruction when it has completed the calculation. For example, if you enter: 3.14 * 23 bc displays the result of the calculation. However, with: a = 3.14 * 23 bc does not display anything, because the expression is an assignment. If you do want to display the value of an assignment expression, simply place the expression in parentheses. The following list shows the instruction forms recognized by bc: expression Calculates the value of the expression. “string” Is a string constant. When bc sees a statement of this form, it displays the contents of the string. For example: "Hello world!" tells bc to display Hello world! A newline character is not output after the string. This makes it possible to do things like: foo = 15 "The value of foo is "; foo With these instructions, bc displays The value of foo is 15 statement ; statement ... Is a sequence of statements on the same line. In bc, a semicolon (;) and a newline are equivalent. They both indicate the end of a statement. bc runs these statements in order from left to right. {statement} Is a brace-bracketed statement. Brace brackets are used to group sequences of statements together, as in: { statement statement ... } Brace brackets can group a series of statements that are split over several lines. Braces are typically used with control statements like if and while. break Can be used only inside a while or for loop. break ends the loop. for (initexp ; relation ; endexp) statement Is equivalent to: Chapter 2. Shell command descriptions 59 bc initexp while (relation) { statement endexp } where initexp and endexp are expressions and relation is a relation. For example: a = 0 for (i = 1; i <= 10; ++i) a += i is equivalent to the while example given earlier. Rule: All three items inside the parentheses must be specified. Unlike C, bc does not let you omit any of these expressions. if (relation)statement Tests whether the given relation is true. If so, bc runs the statement; otherwise, bc skips over the statement and goes to the next instruction. For example: if ((a%2) == 0) "a is even" displays a is even if a has an even value. if (relation) statement1 elsestatement2 Is similar to the simple if statement. It runs statement1 if relation is true and otherwise runs statement2. It may be used as follows: if ((a%2) == 0) "a is even" else "a is odd" There is no statement separator between “a is even” and the else keyword. This differs from the C language Here is another example: if (a<10) { "a " "is "; "less than 10 " a } else { "a is" " greater than 10 " a } Rule: The braces must be on the same line as the if and the else keywords. This is because a new line or a semicolon right after (relation) indicates that the body of the statement is null. One common source of errors in bc programs is typing the statement body portion of an if statement on a separate line. If –i is used, the interpreter displays a warning when if statements with null bodies are encountered. while (relation)statement Repeatedly runs the given statement while relation is true. For example: i = 1 a = 0 while (i <= 10) { a += i ++i } adds the integers from 1 through 10 and stores the result in a. 60 z/OS V1R12.0 UNIX System Services Command Reference bc If relation is not true when bc encounters the while loop, bc does not run statement at all. print expression , expression ... Displays the results of the argument expressions. Normally, bc displays the value of each expression or string it encounters. This makes it difficult to format your output in programs. For this reason, the z/OS shell version of bc has a print statement to give you more control over how things are displayed. print lets you display several numbers on the same line with strings. This statement displays all its arguments on a single line. A single space is displayed between adjacent numbers (but not between numbers and strings). A print statement with no arguments displays a newline. If the last argument is null, subsequent output continues on the same line. Here are some examples of how to use print: /* basic print statement */ print "The square of ", 2, "is ", 2*2 The square of 2 is 4 /* inserts a space between adjacent numbers */ print 1,2,3 1 2 3 /* note - no spaces */ print 1,"",2,"",3 123 /* just print a blank line */ print /* two statements with output on same line */ print 1,2,3, ; print 4, 5, 6 1 2 3 4 5 6 quit Ends bc. In other implementations of bc, the interpreter exits as soon as it reads this token. This version of bc treats quit as a real statement, so you can use it in loops, functions, and so on. sh ... Lets you send a line to the system command interpreter for execution, as in: sh more <foo This command passes everything from the first nonblank character until the end of the line to the command interpreter for execution. void expression Throws away, or “voids,” the result of the evaluation of expression instead of displaying it. This instruction is useful when using ++ and -- operators, or when you want to use a function but don't want to use the return value for anything. For example: void foo++ increments foo but does not display the result. The void statement is unique to this version of bc. Several other types of statements are relevant only in function definitions. These are described in the next topic. Functions A function is a subprogram to calculate a result based on argument values. For example, the following function converts a temperature given in Fahrenheit into the equivalent temperature in Celsius: Chapter 2. Shell command descriptions 61 bc define f_to_c(f) { return ((f-32) * 5 / 9) } This defines a function named f_to_c() that takes a single argument called f. The body of the function is enclosed in brace brackets. The opening brace must be on the same line as the define keyword. The function body consists of a sequence of statements to calculate the result of the function. An expression of the form: return (expression) returns the value of expression as the result of the function. The parentheses around the expression are optional. To activate the subprogram you use a function call. This has the form: name(expression,expression,...) where name is the name of the function, and the expressions are argument values for the function. You can use function call anywhere you might use any other expression. The value of the function call is the value that the function returns. For example, with the function f_to_c(), described earlier, f_to_c(41) has the value 5 (since 41 Fahrenheit is equivalent to 5 Celsius). The general form of a function definition is: define name(parameter,parameter,...) { auto local, local, ... statement statement ... } Each parameter on the first line can be a variable name or an array name. Array names are indicated by putting square brackets after them. For example, if cmpvec is a function that compares two vectors, the function definition might start with: define cmpvec(a[],b[]) { Parameters do not conflict with arrays or variables of the same name. For example, you can have a parameter named a inside a function, and a variable named a outside, and the two are considered entirely separate entities. Assigning a value to the variable does not change the parameter and vice versa. All parameters are passed by value. This means that a copy is made of the argument value and is assigned to the formal parameter. This also applies to arrays. If you pass an array to a function, a copy is made of the whole array, so any changes made to the array parameter do not affect the original array. A function may not need any arguments. In this case, the define line does not have any parameters inside the parentheses, as in: define f() { The auto statement declares a sequence of local variables. When a variable or array name appears in an auto statement, the current values of those items are saved and the items are initialized to zero. For the duration of the function, the items have their new values. When the function ends, the old values of the items are restored. However, bc uses dynamic scoping rules, unlike C which uses lexical scoping rules. 62 z/OS V1R12.0 UNIX System Services Command Reference bc See Usage notes for more details. For example: define addarr(a[],l) { auto i, s for (i=0; i < l; ++i) s += a[i] return (s) } is a function that adds the elements in an array. The argument l stands for the number of elements in the array. The function uses two local names: a variable named i and a variable named s. These variables are “local” to the function addarr and are unrelated to objects of the same name outside the function (or in other functions). Objects that are named in an auto statement are called autos. Autos are initialized to 0 each time the function is called. Thus, the sum s is set to zero each time this function is called. You can also have local arrays, which are specified by placing square brackets after the array name in the auto statement. define func_with_local_array() { auto local_array[]; for(i=0; i<100; i++) local_array[i] = i*2 } This example defines a local array called local_array. Local arrays start out with no elements in them. If a function refers to an object that is not a parameter and not declared auto, the object is assumed to be external. External objects may be referred to by other functions or by statements that are outside of functions. For example: define sum_c(a[ ],b[ ],l) { auto i for (i=0; i < l; ++i) c[i] = a[i] + b[i] } refers to an external array named c, which is the element-by-element sum of two other arrays. If c did not exist prior to calling sum_c, it is created dynamically. After the program has called sum_c, statements in the program or in functions can refer to array c. Functions typically require a return statement. This has the form: return (expression) The argument expression is evaluated and used as the result of the function. The expression must have a single numeric value; it cannot be an array. A return statement ends a function, even if there are more statements left in the function. For example: define abs(i) { if (i < 0) return (-i) return (i) } is a function that returns the absolute value of its argument. If i is less than zero, the function takes the first return; otherwise, it takes the second. A function can also end by running the last statement in the function. If so, the result of the function is zero. The function sum_c is an example of a function that does not have a return statement. The function does not need a return statement, Chapter 2. Shell command descriptions 63 bc because its work is to calculate the external array c, not to calculate a single value. Finally, if you want to return from a function, but not return a value you can use return() or simply return. If there are no parameters to the return statement, a default value of zero is returned. Built-in functions bc has a number of built-in functions that perform various operations. These functions are similar to user-defined functions. You do not have to define them yourself, however; they are already set up for you. These functions are: length(expression) Calculates the total number of decimal digits in expression. This includes digits both before and after the decimal point. The result of length() is an integer. For example, length(123.456) returns 6. scale(expression) Returns the scale of expression. For example, scale(123.456) returns 3. The result of scale() is always an integer. Subtracting the scale of a number from the length of a number lets you determine the number of digits before the decimal point. sqrt(expression) Calculates the square root of the value of expression. The result is truncated in the least significant decimal place (not rounded). The scale of the result is the scale of expression, or the value of scale(), whichever is larger. You can use the following functions if –l is specified on the command line. If it is not, the function names are not recognized. There are two names for each function: a full name, and a single character name for compatibility with POSIX.2. The full names are the same as the equivalent functions in the standard C math library. arctan(expression) or a(expression) Calculates the arctangent of expression, returning an angle in radians. This function can also be called as atan(expression). bessel(integer,expression) or j(integer,expression) Calculates the Bessel function of expression, with order integer. This function can also be called as jn(integer,expression). cos(expression) or c(expression) Calculates the cosine of expression, where expression is an angle in radians. exp(expression) or e(expression) Calculates the exponential of expression (that is, the value e to the power of expression). ln(expression) or l(expression) Calculates the natural logarithm of expression. This function can also be called as log(expression). sin(expression) or s(expression) Calculates the sine of expression, where expression is an angle in radians. The scale value of the result returned by these functions will be the value of the scale variable at the time the function is invoked. The value of the scale variable after these functions have completed their execution will be the same value it had upon invocation. 64 z/OS V1R12.0 UNIX System Services Command Reference bc Examples 1. Here is a simple function to calculate the sales tax on a purchase. The amount of the purchase is given by purchase, and the amount of the sales tax (in per cent) is given by tax. define sales_tax(purchase,tax) { auto old_scale scale = 2 tax = purchase*(tax/100) scale = old_scale return (tax) } For example: sales_tax(23.99,6) calculates 6% tax on a purchase of $23.99. The function temporarily sets the scale value to 2 so that the monetary figures have two figures after the decimal point. Remember that bc truncates calculations instead of rounding, so some accuracy may be lost. It is better to use one more digit than needed and perform the rounding at the end. The round2 function, shown later in this topic, rounds a number to two decimal places. 2. Division resets the scale of a number to the value of scale. You can use this to extract the integer portion of a number, as follows: define integer_part(x) { # a local to save the value of scale auto old_scale # save the old scale, and set scale to 0 old_scale = scale; scale=0 # divide by 1 to truncate the number x /= 1 # restore the old scale scale=old_scale return (x) } 3. Here is a function you can define to return the fractional part of a number: define fractional_part(x) {return (x - integer_part(x))} 4. The following function lets you set the scale of number to a given number of decimal places: define set_scale(x, s) { auto os os = scale scale = s x /= 1 scale = os return (x) } You can now use set_scale() in a function that rounds a number to two decimal places: define round2(num) { auto temp; if(scale(num) < 2) return (set_scale(num, 2)) temp = (num - set_scale(num, 2)) * 1000 if(temp > 5) num += 0.01 return (set_scale(num,2)) } This is a very useful function if you want to work with monetary values. For example, you can now rewrite sales_tax() to use round2(): define sales_tax(purchase,tax) { auto old_scale scale = 2 Chapter 2. Shell command descriptions 65 bc tax = round2(purchase*(tax/100)) scale = old_scale return (tax) } 5. Here is a function that recursively calculates the factorial of its argument: define fact (x) { if(x < 1) return 1 return (x*fact(x-1)) } You can also write the factorial function iteratively: define fact (x) { auto result result = 1 while(x>1) result *= x-return (result) } With either version, fact(6) returns 720. 6. Here is another recursive function, that calculates the nth element of the Fibonacci sequence: define fib(n) { if(n < 3) { return (1) } else { return (fib(n-1)+fib(n-2)) } } Usage notes 1. Unlike the C language, which uses lexical scoping rules, bc uses dynamic scoping, which is most easily explained with an example: a=10 define f1() { auto a; a = 13; return (f2()) } define f2() { return (a) } f1() 13 f2() 10 If f1() is called, bc prints the number 13, instead of the number 10. This is because f1() hides away the old (global) value of a and then sets it to 13. When f2() refers to a, it sees the variable dynamically created by f1() and so prints 13. When f1() returns, it restores the old value of a. When f2() is called directly, instead of through f1(), it sees the global value for a and prints 10. The corresponding C code prints 10 in both cases. 2. Numbers are stored as strings in the program and converted into numbers each time they are used. This is important because the value of a “constant” number may change depending on the setting of the ibase variable. For example, suppose the following instructions are given to bc: define ten() { return (10) } ten() 66 z/OS V1R12.0 UNIX System Services Command Reference bc 10 ibase=16 ten() 16 In this example, when the base is set to 10, ten() returns the decimal value 10. However, when the input base is changed to 16, the function returns the decimal value 16. This can be a source of confusing errors in bc programs. 3. The library of functions loaded using the –l option is stored in the file /usr/lib/lib.b under your root directory. This is a simple text file that you can examine and change to add new functions as desired. 4. In a noninteractive invocation, bc will exit on any invalid input and the rest of the input will be skipped. Files bc uses the following file: /usr/lib/lib.b File containing the library of functions loaded with –l Localization bc uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following errors: v Break statement found outside loop v Parser stack overflow v Syntax error v End of file in comment v End of file in string v Numerical constant is too long v String is too long v Empty evaluation stack v Cannot pass scalar to array v Cannot pass array to scalar v Incorrect array index v Built-in variable cannot be used as a parameter or auto variable v name is not a function v Incorrect value for built-in variable v Shell command failed to run v Division by 0 v Incorrect value for exponentiation operator v Attempt to take square root of negative number v Out of memory 2 Unknown command-line option Chapter 2. Shell command descriptions 67 bc Limits The parser stack depth is limited to 150 levels. Attempting to process extremely complicated programs may result in an overflow of this stack, causing an error. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The following are extensions to the POSIX standard: The –i option The &&and || operators The if ... else ... statement Identifiers of more than one character or containing characters outside the POSIX character set v The print statement v The sh statement v The optional parentheses in the return statement v v v v In a double-byte environment, remember that only numbers and operators from the POSIX character set can be used. Identifiers can use characters from the current locale; if you want scripts to be portable, use only characters from the POSIX character set. bg — Move a job to the background Format bg [job...] tcsh shell: bg [%job ...] Description bg runs one or more jobs in the background. The job IDs given on the command line identify these jobs, which should all be ones that are currently stopped. If you do not specify any job IDs, bg uses the most recently stopped job. bg works only if job control is enabled; see the –m option of set for more information. Job control is enabled by default in the z/OS shell. bg in the tcsh shell In the tcsh shell, bg puts the specified jobs (or, without arguments, the current job) into the background, continuing each if it is stopped. job may be a number, a string, ", %, + or - . In the tcsh shell, %job & is a synonym of the bg command. Localization bg uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH 68 z/OS V1R12.0 UNIX System Services Command Reference bg See Appendix F, “Localization,” on page 937 for more information. Usage note bg is a built-in shell command. Exit values 0 >0 Successful completion Failure because a job argument is incorrect or there is no current job If an error occurs, bg exits and does not place the job in the background. Portability POSIX.2 User Portability Extension, UNIX systems. Related information at, batch, fg, jobs, set, tcsh bpxmtext — Display reason code text Format bpxmtext reason_code Description bpxmtext displays the description and action text for a reason code returned from the kernel and errnojr values returned from the C/C++ run-time library. bpxmtext supports reason codes from z/OS UNIX System Services and TCP/IP. This command is intended as an aid for problem determination. Reason codes such as those returned by HFS or NFS are not supported by this command. It also displays the text and action of zFS reason codes (EFxxnnnn) returned from the kernel. zFS does not use the xx part of the reason code to display a module name. It always displays zFS. If you only know the nnnn part of the zFS reason code, you can use EF00nnnn as the reason code. Restriction: The bpxmtext command is not valid for zFS abend reason codes (EAxxnnnn). reason_code is specified as 8 hexadecimal characters. Leading zeros can be omitted. Usage notes 1. If no text is available for the reason code, a blank line is displayed. 2. An argument that is not 1–8 hexadecimal digits in length results in a usage message. The message is not translated. Examples The command: bpxmtext 058800B0 produces data displayed in the following format: Chapter 2. Shell command descriptions 69 bpxmtext BPXFSUMT 08/18/98 JRUserNotPrivileged: The requester of the service is not privileged Action: The service requested required a privileged user. Check the documentation for the service to understand what privilege is required. Exit values 0 2 Successful completion Failure due to an argument that is not 1-8 hexadecimal digits bpxtrace — Activate or deactivate traces for processes Format bpxtrace –a [-B debug] [-p pid] [-u userid] bpxtrace –c [–f format|full|short|counts] [–o outputpath] [–T tempdir] [–v volser] [–B debug] [–h columns] [–x] [command] bpxtrace –e [-p pid] [-u userid] [–f format|full|short|counts] [–o outputpath] [–T tempdir] [–v volser] [-B debug] [–h columns] [–x] bpxtrace –i [-p pid] [-u userid] [–f format|full|short|counts] [–o outputpath] [–T tempdir] [–v volser] [-B debug] [–h columns] [–x] bpxtrace –s [-B debug] [-p pid] [-u userid] bpxtrace –S [–o outputpath] [–T tempdir] [–B debug] [–v volser] bpxtrace –t <seconds> [-p pid] [-u userid] [–f format|full|short|counts] [–o outputpath] [–T tempdir] [–v volser] [-B debug] [–h columns] [–x] Description bpxtrace activates and deactivates tracing for one or more processes. It can be run from the z/OS UNIX shell or the TSO environment. The captured syscall trace output is dependent on the system-wide setting for SYSOMVS CTRACE options and the amount of z/OS UNIX activity on the system when the bpxtrace command is issued. Guideline: When using SYSOMVS CTRACE, always specify the minimal setting. Otherwise, when you run bpxtrace to capture syscall data, the amount of the output might be reduced. Restriction: A single user can run bpxtrace only once at any given time. Running multiple occurrences might result in allocation errors, dump failures, inconsistent process tracing, or other unexpected behaviors. The bpxtrace command might allocate the following temporary data sets: v userid.BPXGDCORE.DUMPDS 70 z/OS V1R12.0 UNIX System Services Command Reference bpxtrace v userid.BPXGDCORE.LOG v userid.BPXGDCORE.BPXEXEC v userid.BPXGDCORE.DDIR The userid prefix is the MVS user name of the user running the command and is not affected by the current TSO prefix setting. The caller must have authority to create these data sets or the bpxtrace command will fail. The data set names must be eligible for allocation on the specified or default volumes, or the bpxtrace command will fail. For example, any ACS routines that determine the SMS classes and storage groups for these data sets and objects might need to be modified to allow allocation on these volumes. Options While all options and parameters are accepted for each function, some might be ignored for a particular function. See the function descriptions in “Format” on page 70 for options that are applicable to that particular function. -a Stops tracing without producing trace output. -B debug Used when diagnosing problems running bpxtrace. Restriction: This option is intended for use by service personnel only. The debug level is specified as one of the following numbers: 1 Verbose mode 2 Verbose mode and traps REXX signals 3 Verbose mode, traps REXX signals, and retains the temporary files and data sets 4 Verbose mode, traps REXX signals, retains the temporary files and data sets, and does not disable tracing for the bpxtrace command itself -c command Traces the shell command or script that is specified by the command string invoked by the /bin/sh -c command. -e Ends the tracing of user processes and produces trace output. –f format|full|short|counts Specifies how the trace records (syscall entry and syscall exit records) should be displayed. The values full, short, and counts show the trace records as formatted by the IPCS CTRACE command with the corresponding IPCS format request for COMP(SYSOMVS). v format processes the trace records and displays one line per trace record formatted with relevant information from the trace record. The format value is also filtered based on the user ID or process ID value that was specified. The following screen shows an example of output from bpxtrace -f format: PID ASID TCB Local time System call 7 0025 8FF1D8 09:43:04.070651 Call open 7 0025 8FF1D8 09:43:04.070668 Exit open 7 0025 8FF1D8 09:43:04.070675 Call read 7 0025 8FF1D8 09:43:04.091468 Exit read Additional trace data pgm=/bin/bpxtrace parms: 0000000D /bin/bpxwrtso 00800002 00000000 00000000 00000000 00000000 rv=00000007 pgm=/bin/bpxtrace pgm=/bin/bpxtrace parms: 00000007 25D00000 00000000 00001000 00000000 00000000 00000000 rv=00001000 pgm=/bin/bpxtrace</xmp></entry> Chapter 2. Shell command descriptions 71 bpxtrace The first word of the "System Call" column identifies whether the trace entry corresponds to a syscall entry (CALL) or syscall exit (EXIT). The second word identifies the syscall. For "CALL" type entries, parameters shown in the "Additional Trace Data" column must be matched with the input and output parameters for the specified syscall. Note that the output parameters might contain residual data upon entry to a syscall. The pgm=field displays information about the process being traced only if it remains active after bpxtrace has ended. For "EXIT" type entries, the return value (RV) returned from the syscall is displayed in the "Additional Trace Data" column. Both the input parameter mapping and the return value meaning can be found in z/OS UNIX System Services Programming: Assembler Callable Services Reference. v full corresponds to the full format option of the IPCS CTRACE command when specified with the KERNINFO option. Restriction: This option is intended for use by service personnel only. CTRACE COMP(SYSOMVS) FULL OPTIONS((KERNINFO)) The following screen shows an example of output from bpxtrace -f full: FCN...open SY1 SYSCALL ASID..0025 TCB...008FF1D8 +0000 00000026 +0010 8000000C +0020 00000002 +0030 C0000007 +0040 A699A3A2 +0050 00000000 +0060 00000000 +0070 00000000 +0080 00000000 FCN...open SY1 SYSCALL ASID..0025 TCB...008FF1D8 +0000 00000026 +0010 8000000A +0020 00000001 FCN...read SY1 SYSCALL ASID..0025 TCB...008FF1D8 +0000 0000002B +0010 8000000C +0020 00000000 +0030 40000007 +0040 00001000 FCN...read SY1 SYSCALL ASID..0025 TCB...008FF1D8 +0000 0000002B +0010 8000000A +0020 00000000 SYSCALL...BPX1OPN PID...00000007 MODULE...BPXJCPC 0F080001 09:43:04.070651 STANDARD SYSCALL ENTRY TRACE USERID....MEGA [email protected] EUID......00000000 PID.......00000007 00000000 D1C3E2C5 8C000004 | ........JCSE.... | 00000000 8288B768 FFFFFFFF | ........bh...... | 26D9E8B4 00000000 7F6DCBBC | .....RY....."_.. | 0000000D 61828995 618297A7 | {......./bin/bpx | 96000000 00800002 00000000 | wrtso........... | 00000000 0BBD0000 00000000 | ................ | 00000000 00000000 00000000 | ................ | 00000000 00000000 00000000 | ................ | 00000000 00000000 | ............ | SYSCALL...BPX1OPN PID...00000007 MODULE...BPXJCPC 0F080002 09:43:04.070668 STANDARD SYSCALL EXIT TRACE USERID....MEGA [email protected] EUID......00000000 PID.......00000007 00000000 D1C3E2C5 8C008000 | ........JCSE.... | 00000000 00000007 00000002 | ................ | | .... | SYSCALL...BPX1RED PID...00000007 MODULE...BPXJCPC 0F080001 09:43:04.070675 STANDARD SYSCALL ENTRY TRACE USERID....MEGA [email protected] EUID......00000000 PID.......00000007 00000000 D1C3E2C5 8C000004 | ........JCSE.... | 00000000 82885438 00000000 | ........bh...... | 618297A7 00000000 7F6DCBBC | ..../bpx...."_.. | 00000007 25D00000 00000000 | ........}...... | 00000007 00000000 0BBD0000 | ................ | SYSCALL...BPX1RED PID...00000007 MODULE...BPXJCPC 0F080002 09:43:04.091468 STANDARD SYSCALL EXIT TRACE USERID....MEGA [email protected] EUID......00000000 PID.......00000007 00000000 D1C3E2C5 8C008000 | ........JCSE.... | 00000000 00001000 26D9D0BA | .............R}. | | .... | v short corresponds to the IPCS CTRACE command short format option: CTRACE COMP(SYSOMVS) SHORT For an example of the SYSOMVS trace record when the short format option is specified, see z/OS MVS Diagnosis: Tools and Service Aids. v counts corresponds to the IPCS CTRACE command SYSOMVS sccounts option CTRACE COMP(SYSOMVS) OPTIONS((SCCOUNTS)) 72 z/OS V1R12.0 UNIX System Services Command Reference bpxtrace For an example of the SYSOMVS trace record when the sccounts format option is specified, see z/OS MVS Diagnosis: Tools and Service Aids. The default is –f format. –h columns Selects the columns for trace output when –f format is used. columns is specified as a string of characters where each character represents a column. p PID column a ASID column t TCB column l Local time column s System call column d Additional trace data The characters can be specified in any order but the column order in the output is not affected. An incorrect specification for the columns will cause the default to be used. The default is -h patlsd. -i Produces trace output, leaving trace enabled. –o outputpath Specifies the path name of the z/OS UNIX file to contain the trace output. The default is to write the trace records to the standard output stream, which might cause a significant amount of trace output. When running in a shell environment, stdout can be redirected to a file; otherwise you can use the -o option to avoid having the output written to your session. If the specified file already exists, the contents are replaced. If redirection is used, the results depend on the redirection operator. –p pid,... Specifies the process ID of the process to have trace started, stopped or formatted. When formatting a trace, the default formatting shows only the records for the processes that are identified by the list of specified PIDs. To have a list of multiple processes traced, specify multiple -p pids instances on the command. By default, tracing is started for all processes for the user. -s Starts tracing user processes. -S Produces trace output for unusual or unexpected conditions reported by the System Authorization Facility (SAF). To avoid flooding its trace with SAF results, z/OS UNIX traces only those conditions where the callable service documentation and return values do not provide enough information to determine the cause of the problem. Users with an effective UID of 0 will see the trace records for all UIDs while non-effective UID 0 users will see only those trace records with a matching UID. The first 40 (decimal) bytes of these trace records are mapped by the ThliSecErrCT section of the BPXYTHLI macro, which is documented in z/OS UNIX System Services Programming: Assembler Callable Services Reference. The portion of the records beyond the first 40 bytes are for use by IBM service. The trace facilities utilized by the -S option do not require the prior activation of tracing for the system or for a given process. The trace facilities that are used for the -S option are always active and do not need to be activated or deactivated. Chapter 2. Shell command descriptions 73 bpxtrace The following z/OS UNIX services create trace records for unusual or unexpected conditions reported by SAF: v BPX1PWD (__passwd) v BPX1SUI (setuid) v BPX1SEU (seteuid) v BPX1SRU (setreuid) v BPX1TLS (pthread_security) v BPX1GGN (getgrnam) v BPX1GGR (getgroups) v BPX1SEC (__login) -t seconds Traces for a specified period of time and then produces output. At the end of the time period, the traced processes will no longer have tracing on. -T tempdir Specifies the path name of the directory to be used for temporary files. By default, if bpxtrace is running in a shell environment, it uses the TMPDIR environment variable if available. Otherwise, /tmp is used. –u userid Specifies the user ID that is used in processing the trace. If the user ID is not the same as that of the invoking user, bpxtrace attempts to switch to UID(0) before determining which processes are to be traced. If the invoking user does not have permission to switch to UID(0), the bpxtrace command will fail. If both -p and -u are specified, -u is ignored. –v volser Specifies the volume to use for allocating temporary data sets. If -v is not specified, unit(sysallda) is used. Specifies that the output will contain only exit trace lines. -f format must also be specified. -x Examples 1. To trace the calls made by the df utility and capture the output in a file: bpxtrace -c -o trace.output df Usage note If the user's effective UID is changed after BPXTRACE tracing has started, CTRACE records might be missing from the BPXTRACE output. Due to limitations in DUMP processing, only CTRACE records matching the user's EUID at the time of the dump are captured and made available for display. | | | | Exit values 74 0 Successful completion 1 The trace was successful but a listing was not generated 3 Command-line syntax error 4 Data set or file allocation error 5 The seteuid failed 8 z/OS UNIX callable service BPXGMCDE (MVS IPCS dump open/close service) open failure. This error indicates that the dump data set could not be opened. Try the command again. If the error persists, contact IBM Service. z/OS V1R12.0 UNIX System Services Command Reference bpxtrace 9 z/OS UNIX callable service BPXGMPTR (Ptrace IPCS dump access service) command failure. This error indicates a resource constraint was encountered while attempting to process the dump. Try the command again. If the error persists, contact IBM Service. 12 Review the error log to determine the problem. break — Exit from a loop in a shell script Format break [number] tcsh shell: break Description break exits from a for, select, while, or until loop in a shell script. If number is given, break exits from the given number of enclosing loops. The default value of number is 1. break is a special built-in shell command. break in the tcsh shell In the tcsh shell, break causes execution to resume after the end of the nearest enclosing foreach or while. The remaining commands on the current line are executed. Multilevel breaks are thus possible by writing them all on one line. Localization break uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit value break always exits with an exit status of 0. Portability POSIX.2, X/Open Portability Guide. Related information continue, sh, tcsh c++ — Compile C and C++ source code, link-edit and create an executable file See c89/xlc or man xlc. Note: When working in the shell, to view man page information about c++, type: man c89 or man xlc. Chapter 2. Shell command descriptions 75 c89, cc, and c++ c89 — Compiler invocation using host environment variables Format c89 | cc | c++ | cxx [–+CcEFfgOpqrsVv0123] [-D name[=value]]... [-U name]... [-e function] [-u function]... [-W phase,option[,option]...]... [-o outfile] [-I directory]... [-L directory]... [file.C]... [file.i]... [file.c]... [file.s]... [file.o]... [file.x]... [file.p]... [file.I]... [file.a]... [-l libname]... Notes: 1. The c99 command is only supported by the xlc utility. See “xlc — Compiler invocation using a customizable configuration file” on page 824 for more information. 2. In this information, -l signifies -l (a lowercase L) and not an uppercase I. Description c89 and cc compile, assemble, and link-edit C programs; cxx/c++ does the same for C++ programs. v c89 should be used when compiling C programs that are written according to Standard C. v cc should be used when compiling C programs that are written according to Common Usage C. v cxx/c++ must be used when compiling C++ programs. Prior to z/OS V1R2, the C++ compiler supported the Draft Proposal International Standard for Information Systems — Programming Language C++ (X3J16). As of z/OS V1R7, the C++ compiler supports the Programming languages - C++ (ISO/IEC 14882:2003(E)) standard, as well as the Programming languages - C++ (ISO/IEC 14882:1998) standard. c++ can compile both C++ and C programs, and can also be invoked by the name cxx (all references to c++ throughout this document apply to both names). c89, cc, and c++ call other programs for each step of the compilation, assemble and link-editing phases. The list below contains the following: the step name, the name of the document that describes the program you use for that step and the document that describes any messages issued by that program, and prefixes to those messages: Table 3. Reference documentation for programs invoked by c89, cc, and c++ commands 76 Step Name Document Describing Options and How to Call Program Document Containing Messages Issued by Program Prefix of Messages Issued by Program ASSEMBLE HLASM Programmer's Guide HLASM Programmer's Guide ASMA z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ Table 3. Reference documentation for programs invoked by c89, cc, and c++ commands (continued) Step Name Document Describing Options and How to Call Program Document Containing Messages Issued by Program Prefix of Messages Issued by Program COMPILE, IPACOMP, TEMPINC, IPATEMP, IPALINK z/OS C/C++ User's Guide for releases prior to z/OS V1R7 and z/OS XL C/C++ User's Guide for z/OS V1R7 and later releases z/OS C/C++ Messages for z/OS V1R5 and z/OS V1R6 releases and z/OS XL C/C++ Messages for z/OS V1R7 and later releases CCN for z/OS V1R2 and later releases PRELINK z/OS Language Environment Programming Guide and z/OS XL C/C++ User's Guide z/OS Language Environment Debugging Guide EDC LINKEDIT (Program Management Binder) z/OS MVS Program Management: User's Guide and Reference z/OS MVS System Messages, Vol 8 (IEF-IGD) IEW Execution of any Language Environment® program (including c89 and the z/OS XL C/C++ compiler) can result in run-time messages. These messages are described in z/OS Language Environment Run-Time Messages and have an EDC prefix. In some cases, c89 issues messages with Language Environment messages appended to them. Messages issued by c89 have an FSUM3 prefix. In order for c89, cc, and c++ to perform C and C++ compiles, the z/OS C/C++ Optional Feature must be installed on the system. The z/OS C/C++ Optional Feature provides a C compiler, a C++ compiler, C++ Class Libraries, and some utilities. See z/OS Introduction and Release Guide for further details. Also see prefix_CLIB_PREFIX and prefix_PLIB_PREFIX in “Environment variables” on page 93 for information about the names of the z/OS XL C/C++ Optional Feature data sets that must be made available to c89/cc/c++. Note: The term prefix is defined in “Environment variables” on page 93. First, c89, cc, and c++ perform the compilation phase (including preprocessing) by compiling all source file operands (file.C, file.i, and file.c, as appropriate). For c++, if automatic template generation is being used (which is the default), then z/OS XL C++ source files may be created or updated in the tempinc subdirectory of the working directory during the compilation phase (the tempinc subdirectory will be created if it does not already exist). Then, c89, cc, and c++ perform the assemble phase by assembling all operands of the file.s form. The result of each compile step and each assemble step is a file.o file. If all compilations and assemblies are successful, or if only file.o and/or file.a files are specified, c89, cc, and c++ proceed to the link-editing phase. For c++, the link-editing phase begins with an automatic template generation step when applicable. For IPA (Interprocedural Analysis) optimization an additional IPA Link step comes next. The link-edit step is last. See Chapter 2. Shell command descriptions 77 c89, cc, and c++ the environment variable prefix_STEPS under “Environment variables” on page 93 for more information about the link-editing phase steps. In the link-editing phase, c89, cc, and c++ combine all file.o files from the compilation phase along with any file.o files that were specified on the command line. For c++, this is preceded by compiling all C++ source files in the tempinc subdirectory of the working directory (possibly creating and updating additional C++ source files during the automatic template generation step). After compiling all the C++ source files, the resulting object files are combined along with the file.o files from the compilation phase and the command line. Any file.a files, file.x files and -l libname operands that were specified are also used. The usual output of the link-editing phase is an executable file. For c89, cc, and c++ to produce an executable file, you must specify at least one operand which is of other than -l libname form. If -r is used, the output file is not executable. For more information about automatic template generation, see z/OS XL C/C++ User's Guide and the information on "Using TEMPINC or NOTEMPINC" in z/OS XL C/C++ Programming Guide. Note that the c++ command only supports using the tempinc subdirectory of the working directory for automatic template generation. For more information on IPA, see “Options.” Options –+ Specifies that all source files are to be recognized as C++ source files. All file.s, file.o, and file.a files will continue to be recognized as assembler source, object, and archive files respectively. However, any C file.c or file.i files will be processed as corresponding C++ file.C or file.i files, and any other file suffix which would otherwise be unrecognized will be processed as a file.C file. This option effectively overrides the environment variable prefix_EXTRA_ARGS. This option is only supported by the c++ command. -C Specifies that C and C++ source comments should be retained by the preprocessor. By default, all comments are removed by the preprocessor. This option is ignored except when used with the -E option. -c Specifies that only compilations and assemblies be done. Link-edit is not done. -D name[=value] Defines a C or C++ macro for use in compilation. If only name is provided, a value of 1 is used for the macro it specifies. For information about macros that c89/cc/c++ automatically define, see Usage Note 5 on page 108. Also see Usage Note 13 on page 110. Notes: v The xlc utility has slightly different semantics for processing -D options. v As of z/OS V1R12, to define a macro name that contains an escape character (that is, the back slash) using an option such as -D or -Wc,DEFINE, you must specify the option in a way that can preserve the back slash character when the macro reaches the compiler parser. Because an option passes through the UNIX shell and the compiler options processor, both of which are sensitive to back slash characters, the rules for such characters 78 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ must be followed to ensure that the compiler parser receives a macro with the back slash character. The UNIX shell and the compiler options parser both interpret and consume back slash characters that are unquoted or quoted by double quotation marks. On the other hand, the UNIX shell does not interpret back slash characters that are quoted by single quotation marks, while the compiler options parser is not sensitive to single quotation marks. For example, for the compiler parser to receive \u0024 as the macro symbol, the compiler options processor must receive \\u0024, so you must specify -D'\\u0024' or -D"\\\u0024" on the command line. This also applies to the -Wc,DEFINE option, which is an alternative method of defining macros (for example, -Wc,'DEFINE(\\u0024)' or -Wc,"DEFINE(\\\u0024)"). The same is true for any compiler option which requires the use of a back slash to suppress special meaning of a particular character. -E Specifies that output of the compiler preprocessor phase be copied to stdout. Object files are not created, and no link-editing is performed. -e function Specifies the name of the function to be used as the entry point of the program. This can be useful when creating a fetchable program, or a non–C or non–C++ main, such as a COBOL program. Non–C++ linkage symbols of up to 1024 characters in length may be specified. You can specify an S-name by preceding the function name with double slash (//). (For more information about S-names, see Usage Note 23 on page 113.) Specify a null S-name ("-e //") so that no function name is identified by c89/cc/c++ as the entry point of the program. In that case, the Program Management Binder (link editor) default rules will determine the entry point of the program. For more information about the Program Management Binder and the ENTRY control statement, see z/OS MVS Program Management: User's Guide and Reference. The function //ceestart is the default. When the default function entry point is used, a binder ORDER control statement is generated by c89/cc/c++ to cause the CEESTART code section to be ordered to the beginning of the program. Specify the name with a trailing blank to disable this behavior, as in "//ceestart ". For more information about the Program Management Binder and the ORDER control statement, see z/OS MVS Program Management: User's Guide and Reference. This option may be required when building products which are intended to be installed using the IBM SMP/E product. When installing ++MOD elements with SMP/E, binder control statements should be provided in the JCLIN created to install the product instead of being embedded in the elements themselves. -F Ignored by cc. Provided for compatibility with historical implementations of cc. Flagged as an error by c89 and c++. -f Ignored by cc. Provided for compatibility with historical implementations of cc. Flagged as an error by c89 and c++. Historical implementations of C/C++ used this option to enable floating-point support. Floating-point is automatically included in z/OS XL C/C++. However, in z/OS XL C/C++, two types of floating-point support are available: Chapter 2. Shell command descriptions 79 c89, cc, and c++ HEXADECIMAL Base 16 IBM System z9® hexadecimal format. The IBM System z9 hexadecimal format is referred to as the hexadecimal floating-point format, and is unique to IBM System z9 hardware. This is the default. IEEE754 Base 2 IEEE-754 binary format. The IEEE-754 binary format is referred to as binary floating-point format. The IEEE-754 binary format is the more common floating point format used on other platforms. If you are porting an application from another platform, transmitting floating-point numbers between other platforms or workstations, or your application requires the larger exponent range provided by IEEE-754 binary format, then you should consider using IEEE floating-point. The z/OS XL C/C++ User's Guide contains more information on the FLOAT compiler option. Example: The following is an example of compiling with IEEE-754 binary floating point format: c89 -o outfile -Wc,’float(ieee)’ file.c -g Specifies that a side file that contains symbolic information is emitted and the executable is to be loaded into read/write storage, which is required for source-level debugging with dbx, and other debuggers. For 32-bit compiles, if the _DEBUG_FORMAT=ISD environment variable is exported, then -g specifies that the output file (executable) is to contain symbolic information and is to be loaded into read/write storage, which is required for source-level debugging with dbx, and other debuggers. When specified for the compilation phase, the compiler produces symbolic information for source-level debugging. When specified for the link-editing phase, the executable file is marked as being serially reusable and will always be loaded into read/write storage. dbx requires that all the executables comprising the process be loaded into read/write storage so that it can set break points in these executables. When dbx is attached to a running process, this cannot be guaranteed because the process was already running and some executables were already loaded. There are two techniques that will cause all the executables comprising the process to be loaded into read-write storage: 1. Specify the -g option for the link-editing phase of each executable. After this is done, the executable is always loaded into read/write storage. Because the executable is marked as being serially reusable, this technique works except in cases where the executable must be marked as being reentrant. For example: v If the executable is to be used by multiple processes in the same user space. v If the executable is a DLL that is used on more than one thread in a multithreaded program. In these cases, use the following technique instead: 2. Do not specify the -g option during the link-editing phase so that the executable will be marked as being reentrant. Before invoking the program, export the environment variable _BPX_PTRACE_ATTACH 80 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ with a value of YES. After you do this, then executables will be loaded into read/write storage regardless of their reusability attribute. If you compile an MVS data set source using the -g option, you can use dbx to perform source-level debugging for the executable file. You must first issue the dbx use subcommand to specify a path of double slash (//), causing dbx to recognize that the symbolic name of the primary source file is an MVS data set. For information on the dbx command and its use subcommand, see “use subcommand for dbx: Set the list of directories to be searched” on page 240. For more information on using dbx, see z/OS UNIX System Services Programming Tools. The z/OS UNIX System Services web page also has more information about dbx. Go to http://www.ibm.com/systems/z/os/zos/features/ unix/. For more information on the _BPX_PTRACE_ATTACH environment variable, see z/OS UNIX System Services Programming: Assembler Callable Services Reference. The GONUMBER option is automatically turned on by the -g option, but can also be turned on independently. There is no execution path overhead incurred for turning on this option, only some additional space for the saved line number tables. For 31-bit compiles and In Storage Debug (ISD) information, the GONUMBER option generates tables that correspond to the input source file line numbers. These tables make it possible for Debug Tools and for error trace back information in CEE dumps to display the source line numbers. Having source line numbers in CEE dumps improves serviceability costs of applications in production. The z/OS XL C/C++ User's Guide contains more information on the GONUMBER compiler option. Example: The following is an example of compiling with the GONUMBER compiler option: c89 -o outfile -Wc,’GONUM’ file.c Note: -g forces the NOOPTIMIZE compiler option regardless of its position in the command line. -I directory Note: The I option signifies an uppercase i, not a lowercase L. -I specifies the directories to be used during compilation in searching for include files (also called header files). Absolute pathnames specified on #include directives are searched exactly as specified. The directories specified using the -I option or from the usual places are not searched. If absolute pathnames are not specified on #include directives, then the search order is as follows: 1. Include files enclosed in double quotation marks (") are first searched for in the directory of the file containing the #include directive. Include files enclosed in angle-brackets (< >) skip this initial search. 2. The include files are then searched for in all directories specified by the -I option, in the order specified. Chapter 2. Shell command descriptions 81 c89, cc, and c++ 3. Finally, the include files are searched for in the usual places. (See Usage Note 4 on page 107 for a description of the usual places.) You can specify an MVS data set name as an include file search directory. Also, MVS data set names can explicitly be specified on #include directives. You can indicate both by specifying a leading double slash (//). Example: To include the include file DEF that is a member of the MVS PDS ABC.HDRS, code your C or C++ source as follows: #include <//’abc.hdrs(def)’> MVS data set include files are handled according to z/OS XL C/C++ compiler conversion rules (see Usage Note 4 on page 107). When specifying an #include directive with a leading double slash (in a format other than #include<//’dsname’> and #include<//dd:ddname>), the specified name is paired only with MVS data set names specified on the -I option. That is, when you explicitly specify an MVS data set name, any z/OS UNIX file system directory names specified on the -I option are ignored. Note: As of z/OS V1R12, a directory name that contains a comma must be quoted by double quotation marks, and the comma must be escaped by the back slash character. For example, -Imy,directory can result in two directories "my" and "directory". If the intended name is a single directory name that contains a comma, the option must be specified as -I"my\,directory" to suppress the special meaning of the comma as suboption separator. -L directory Specifies the directories to be used to search for archive libraries specified by the -l operand. The directories are searched in the order specified, followed by the usual places. You cannot specify an MVS data set as an archive library directory. For information on specifying C370LIB libraries, see the description of the -l libname operand. Also see Usage Note 7 on page 109 for a description of the usual places. -0, -O (-1), -2, -3 Specifies the level of compiler optimization (including inlining) to be used. The level -1 (number one) is equivalent to -O (capital letter O). The level -3 gives the highest level of optimization. The default is -0 (level zero), no optimization and no inlining, when not using IPA (Interprocedural Analysis). When optimization is specified, the default is ANSIALIAS. The ANSIALIAS default specifies whether type-based aliasing is to be used during optimization. That is, the optimizer assumes that pointers can only be used to access objects of the same type. Type-based aliasing improves optimization. Applications that use pointers that point to objects of a different type will need to specify NOANSIALIAS when the optimization compiler option is specified. If your application works when compiled with no optimization and fails when compiled with optimization, then try compiling your application with both optimization and NOANSIALIAS compiler options. The z/OS XL C/C++ User's Guide contains more information on ANSIALIAS. 82 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ Notes: 1. Options can also be specified as -O1 (using capital letter O), -O2, and -O3. For further information, see Usage Note 12 on page 109. 2. These options cannot be overridden by specifying optimization options using the -Wc syntax. This behavior differs from the behavior of the xlc utility, which allows the use of -q and -Wc syntax to override the flag optimization options. Example: The following is an example of a compile with the highest level of optimization and no type-based aliasing: c89 -o outfile -O3 -Wc,NOANSIALIAS file.c When optimization is specified, you may want to obtain a report on the amount of inlining performed and increase or decrease the level of inlining. More inlining will improve application performance and increase application memory usage. The z/OS XL C/C++ User's Guide contains more information on the INLINE compiler option. Example: The following is an example of a compile with optimization with no report generated, a threshold of 500 abstract code units, and a limit of 2500 abstract code units: c89 -o outfile -O2 -Wc,’inline(auto,noreport,500,2500)’ file.c When using IPA, the default is -O (level 1) optimization and inlining. IPA optimization is independent from and can be specified in addition to this optimization level. IPA is further described in this topic. If compiling with PDF, the same optimization level must be used in the PDF1 and PDF2 steps. If you compile your program to take advantage of dbx source-level debugging and specify -g (see the -g option description in this topic), you will always get -0 (level zero) optimization regardless of which of these compiler optimization levels you specify. In addition to using optimization techniques, you may want to control writable strings by using the #pragma strings(readonly) directive or the ROSTRING compiler option. As of z/OS Version 1 Release 2, ROSTRING is the default. For more information on this topic, refer to the section on reentrancy in z/OS XL C/C++ in z/OS XL C/C++ Programming Guide or the description of the ROSTRING option in the z/OS XL C/C++ User's Guide. -o outfile Specifies the name of the c89/cc/c++ output file. If the -o option is specified in addition to the –c option, and only one source file is specified, then this option specifies the name of the output file associated with the one source file. See file.o under “Operands” on page 90 for information on the default name of the output file. Otherwise the -o option specifies the name of the executable file produced during the link-editing phase. The default output file is a.out. -p Ignored by cc. Provided for compatibility with historical implementations of cc. Flagged as an error by c89 and c++. -q Ignored by cc. Provided for compatibility with historical implementations of cc. Flagged as an error by c89 and c++. Chapter 2. Shell command descriptions 83 c89, cc, and c++ -r Specifies that c89/cc/c++ is to save relocation information about the object files which are processed. When the output file (as specified on –o) is created, it is not made an executable file. Instead, this output file can later be used as input to c89/cc/c++. This can be used as an alternative to an archive library. IPA usage note: When using -r and link-editing IPA compiled object files, you must link-edit with IPA (see the description of IPA under the -W option). However, the -r option is typically not useful when you create an IPA optimized program. This is because link-editing with IPA requires that all of the program information is available to the link editor. It is not acceptable to have unresolved symbols, especially the program entry point symbol, which is usually main. The -r option is normally used when you want to combine object files incrementally. Specify object files during the initial link-edit that uses -r. Later, specify the output of the initial link-edit, along with the remaining object files in a final link-edit that is done without using -r. When you want to combine IPA compiled object files, use the alternative that does not involve the link editor, that is, concatenating the object files into one larger file by using the cp or cat utilities. You can use this larger file later in a final link-edit when the remainder of the object files are also made available. | | | | | | | | | | | | | | | -S | | | | | | Specifies that the output file produced by the compiler is in assembler source code format. The absence of the -S flag indicates that the output file produced is in object code format. The -S flag is supported only with the -qmetal compiler option. The compiler does not produce an object file when the -S flag is used. | | | | | | | | | | | | | | | By default, the assembler source file name is based on the C source file name specified on the command line. However, the assembler source file can be affected by the use of the -o option: v If -c is specified, the names of all intermediate files including assembler source names, are based on the name specified in the -o option. For instance, when you specify -S -qmetal -c -o foo.x hello.c, the assembler source name is foo.s, which is generated based on foo.x by replacing the suffix with .s. v If -c is not specified, default naming conventions are used for files produced in the compile step because the -o option controls the link step. For instance, when you specify -S -qmetal -o foo.x hello.c, the assembler source name is hello.s, which is generated based on hello.c by replacing the suffix with .s. The names of all intermediate files in the link step, including the output of the IPA link step, however, are based on the name specified in the -o option. | | | | | | | | | Naming of intermediate files that are based on the -o flag follows these rules: v If a suffix exists for the name specified in the -o option, the intermediate file names are generated by replacing the suffix. v If a suffix does not exist for the name specified in the -o option, the intermediate file names are generated by adding a suffix. v The suffix is determined based on the appropriate c89 utility environment variable or xlc configuration file attribute, depending on which utility is used on the command line. | The following specifications have the same result: 84 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ | | | | xlc xlc xlc xlc -s -S -S -S -S -qmetal -qmetal -qmetal -qmetal hello.c -o hello.s hello.c -c hello.c -c -o hello.s hello.c Specifies that the compilation phase is to produce a file.o file that does not include symbolic information, and that the link-editing phase produce an executable that is marked reentrant. This is the default behavior for c89/cc/c++. -U name Undefines a C or C++ macro specified with name. This option affects only macros defined by the -D option, including those automatically specified by c89/cc/c++. For information about macros that c89/cc/c++ automatically define, see Usage Note 5 on page 108. Also see Usage Note 13 on page 110. Note: The xlc utility uses different semantics for handling the -U option. See “xlc — Compiler invocation using a customizable configuration file” on page 824 for more information. -u function Specifies the name of the function to be added to the list of symbols which are not yet defined. This can be useful if the only input to c89/cc/c++ is archive libraries. Non–C++ linkage symbols of up to 255 characters in length may be specified. You can specify an S-name by preceding the function name with double slash (//). (For more information about S-names, see Usage Note 23 on page 113.) The function //ceemain is the default for non-IPA Link-editing, and the function main is the default for IPA Link-editing. However, if this -u option is used, or the DLL link editor option is used, then the default function is not added to the list. -V This verbose option produces and directs output to stdout as compiler, assembler, IPA linker, prelinker, and link editor listings. If the -O, -2, or -3 options are specified and cause c89/cc/c++ to use the compiler INLINE option, then the inline report is also produced with the compiler listing. Error output continues to be directed to stderr. Because this option causes c89/cc/c++ to change the options passed to the steps producing these listings so that they produce more information, it may also result in additional messages being directed to stderr. In the case of the compile step, it may also result in the return code of the compiler changing from 0 to 4. Note: This option has a different meaning when using the xlc utility. See “xlc — Compiler invocation using a customizable configuration file” on page 824 for more information. -v This verbose option causes pseudo-JCL to be written to stdout before the compiler, assembler, IPA linker, prelinker, and link editor programs are run. Example: It also causes phaseid information to be emitted in stderr: FSUM0000I Utility(c89) Level(UQ99999) It provides information about exactly which compiler, prelinker, and link editor options are being passed, and also which data sets are being used. If you want to obtain this information without actually invoking the underlying programs, specify the -v option more than once on the c89/cc/c++ command string. For more information about the programs which are executed, see Usage Note 14 on page 110. Chapter 2. Shell command descriptions 85 c89, cc, and c++ -W phase, option[,option]... Specifies options to be passed to the steps associated with the compile, assemble, or link-editing phases of c89/cc/c++. The valid phase codes are: 0 Specifies the compile phase (used for both non-IPA and IPA compilation). a Specifies the assemble phase. c Same as phase code 0. I Enables IPA (Interprocedural Analysis) optimization. Unlike other phase codes, the IPA phase code I does not require that any additional options be specified, but it does allow them. In order to pass IPA suboptions, specify those suboptions using the IPA phase code. Example: To specify that an IPA Compile should save source line number information, without writing a listing file, specify: c89 -c -W I,list file.c Example: To specify that an IPA Link-edit should write the map file to stdout, specify: c89 -W I,map file.o l Specifies the link-editing phase. v To pass options to the prelinker, the first link-editing phase option must be p or P. All the following options are then prelink options. Example: To write the prelink map to stdout, specify: c89 –W l,p,map file.c Note: The prelinker is no longer used in the link-editing phase in most circumstances. If it is not used, any options passed are accepted but ignored. See the environment variable prefix_STEPS under “Environment variables” on page 93 for more information about the link-editing phase prelink step. v To pass options to the IPA linker, the first link-editing phase option must be i or I. All the following options are then IPA Link options. Example: To specify the size of the SPILL area to be used during an IPA Link-edit, you could specify: c89 –W l,I,"spill(256)" file.o v To link-edit a DLL (Dynamic Link Library) and produce a side deck, the link-editing phase option DLL must be specified. Example: To accomplish this task, you could specify: c89 –o outdll –W l,dll file.o Most z/OS XL C/C++ extensions can be enabled by using this option. Those which do not directly pass options through to the underlying steps, or involve files which are extensions to the compile and link-edit model, are described here: DLL (Dynamic Link Library) A DLL is a part of a program that is not statically bound to the program. Instead, linkage to symbols (variables and functions) is completed dynamically at execution time. DLLs can improve storage utilization, because the program can be broken into smaller 86 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ parts, and some parts may not always need to be loaded. DLLs can improve maintainability, because the individual parts can be managed and serviced separately. In order to create a DLL, some symbols must be identified as being exported for use by other parts of the program. This can be done with the z/OS XL C/C++ #pragma export compiler directive, or by using the z/OS XL C/C++ EXPORTALL compiler option. If during the link-editing phase some of the parts have exported symbols, the executable which is created is a DLL. In addition to the DLL, a definition side-deck is created, containing link-editing phase IMPORT control statements which name those symbols which were exported by the DLL. In order for the definition side-deck to be created, the DLL link editor option must be specified. This definition side-deck is subsequently used during the link-editing phase of a program which is to use the DLL. See the file.x operand description in the “Operands” on page 90 topic for information on where the definition side-deck is written. In order for the program to refer to symbols exported by the DLL, it must be compiled with the DLL compiler option. Example: To compile and link a program into a DLL, you could specify: c89 -o outdll -W c,exportall -W l,dll file.c To subsequently use file.x definition side-decks, specify them along with any other file.o object files specified for c89/cc/c++ link-editing phase. Example: To accomplish this task, you could specify: c89 –o myappl –W c,dll myappl.c outdll.x In order to run an application which is link-edited with a definition side-deck, the DLL must be made available (the definition side-deck created along with the DLL is not needed at execution time). When the DLL resides in the z/OS UNIX file system, it must be in either the working directory or in a directory named on the LIBPATH environment variable. Otherwise it must be a member of a data set in the search order used for MVS programs. Note: For non-DLL C++ compiles, a dummy definition side file will be allocated to prevent the binder from issuing a warning message. If you do want the binder to issue a warning message when an exported symbol is encountered, specify the DLL=NO option for the link-editing phase; for example: c++ -o outfile -W l,dll=no file.C IPA (interprocedural analysis) IPA optimization is independent from and can be used in addition to the c89/cc/c++ optimization level options (such as –O). IPA optimization can also improve the execution time of your application. IPA is a mechanism for performing optimizations across function boundaries, even across compilation units. It also performs optimizations not otherwise available with the z/OS XL C/C++ compiler. Chapter 2. Shell command descriptions 87 c89, cc, and c++ When phase code I (capital letter I) is specified for the compilation phase, then IPA compilation steps are performed. When phase code I is specified for the link-editing phase, or when the first link-editing phase (code l) option is i or I, then an additional IPA Link step is performed prior to the prelink and link-edit steps. With conventional compilation and link-editing, the object code generation takes place during the compilation phase. With IPA compilation and link-editing, the object code generation takes place during the link-editing phase. Therefore, you might need to request listing information about the program (such as with the -V option) during the link-editing phase. Unlike the other phase codes, phase code I does not require that any additional options be specified. If they are, they should be specified for both the compilation and link-editing phases. No additional preparation needs to be done in order to use IPA. Example: To create the executable myIPApgm using c89 with some existing source program mypgm.c, you could specify: c89 –W I –o myIPApgm mypgm.c When IPA is used with c++, and automatic template generation is being used, phase code I will control whether the automatic template generation compiles are done using IPA. If you do not specify phase code I, then regular compiles will be done. Specifying I as the first option of the link-editing phase option (that is, -W l,I), will cause the IPA linker to be used, but will not cause the IPA compiler to be used for automatic template generation unless phase code I (that is, -W I) is also specified. The IPA Profile-Directed Feedback (PDF) option tunes optimizations, where results from sample program execution are used to improve optimization near conditional branches and in frequently executed code sections. The profiling information is placed in the file specified by the PDFNAME(filename) suboption. If PDFNAME(filename) is not specified, the default name of the file containing profile information is PDF. Note: When using the c89 utility to invoke the compiler for IPA Compile and IPA Link processing using a single command line, some compiler options are not passed to both the IPA Compile and IPA Link steps; for example, the LIST compiler option is not passed. If you want to pass it to both steps, you must use -Wl,I,list syntax so that it is also passed to the IPA Link step. The xlc utility passes all compiler options to both the IPA Compile and IPA Link step. LP64 The LP64 option instructs the compiler to generate AMODE 64 code utilizing the z/Architecture® 64-bit instructions. To compile 64-bit code, specify the z/OS XL C/C++ LP64 compiler option. Example: The following example shows how to compile and bind using the LP64 option: c89 -o -W c,LP64 -Wl,LP64 file.c XPLINK (Extra Performance Linkage) z/OS XPLINK provides improved performance for many C/C++ 88 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ programs. The XPLINK compiler option instructs the z/OS XL C/C++ compiler to generate high performance linkage for subroutine calls. It does so primarily by making subroutine calls as fast and efficient as possible, by reducing linkage overhead, and by passing function call parameters in registers. Furthermore, it reduces the data size by eliminating unused information from function control blocks. An XPLINK-compiled program is implicitly a DLL-compiled program (the C/C++ DLL compiler option need not be specified along with the XPLINK option). XPLINK improves performance when crossing function boundaries, even across compilation units, since XPLINK uses a more efficient linkage mechanism. For more information about the z/OS XL C/C++/C++ XPLINK compiler option, refer to z/OS XL C/C++ User's Guide. For more information about Extra Performance Linkage, refer to z/OS Language Environment Programming Guide. To use XPLINK, you must both compile and link-edit the program for XPLINK. All C and C++ source files must be compiled XPLINK, as you cannot statically link together XPLINK and non-XPLINK C and C++ object files (with the exception of non-XPLINK "OS" linkage). You can however mix XPLINK and non-XPLINK executables across DLL and fetch() boundaries. To compile a program as XPLINK, specify the z/OS XL C/C++ XPLINK compiler option. If there are any exported symbols in the executable and you want to produce a definition side-deck, specify the DLL link editor option. When XPLINK is specified in the link-editing step, different link-edit libraries will be used. Example: Here is an example of compiling and link-editing an XPLINK application in one command: c89 -o outxpl -W c,XPLINK -W l,XPLINK,dll file.c In order to execute an XPLINK program, the SCEERUN2 as well as the SCEERUN data set must be in the MVS program search order (see the prefix_PLIB_PREFIX environment variable). You cannot use -W to override the compiler options that correspond to c89 utility flag options, with the following exceptions: v Listing options (corresponding to -V) v Inlining options (corresponding to -O, -2, and -3) v Symbolic options (corresponding to -s and -g); symbolic options can be overridden only when neither -s nor -g is specified. Notes: 1. Most compiler, prelinker, and IPA linker options have a positive and negative form. The negative form is the positive with a prepended NO (as in XREF and NOXREF). 2. The compiler #pragma options directives as well as any other #pragma directives which are overridden by compiler options, will have no effect in source code compiled by c89/cc/c++. 3. Link editor options must be specified in the name=value format. Both the option name and value must be spelled out in full. If you do not Chapter 2. Shell command descriptions 89 c89, cc, and c++ specify a value, a default value of YES is used, except for the following options, which if specified without a value, have the default values shown here: ALIASES ALIASES=ALL DYNAM DYNAM=DLL LET LET=8 LIST LIST=NOIMPORT Notes: a. The binder default is COMPAT=MIN. For downward compatibility (when - Wc,’target(release)’ is used), COMPAT should also be used (for example, -Wl,compat=min, or the specific program object format level supported by the target deployment system, if it is known). For more information, see the Downward Compatibility section of z/OS XL C/C++ User's Guide. b. As of z/OS V1R8, the default for the COMPAT option is no longer emitted by the c89 utility. In prior releases, the default was COMPAT=CURRENT. c. References throughout this document to the link editor are generic references. c89/cc/c++ specifically uses the Program Management binder for this function. 4. The z/OS XL C/C++ compiler is described in z/OS XL C/C++ User's Guide. Related information about the z/OS XL C/C++ run-time library, including information about DLL and IPA support, is described in z/OS XL C/C++ Programming Guide. Related information about the C and C++ languages, including information about compiler directives, is described in z/OS XL C/C++ Language Reference. 5. Since some compiler options are only used by z/OS XL C and some compiler options are only used by z/OS XL C++, you may get warning messages and a compiler return code of 4, if you use this option and compile both C and C++ source programs in the same c++ command invocation. 6. The prelinker is described in z/OS XL C/C++ User's Guide. 7. The z/OS XL C/C++ User's Guide also describes z/OS XL C/C++ compiler options.Any messages produced by it (CCN messages) are documented in z/OS XL C/C++ Messages. 8. You may see run-time messages (CEE or EDC) in executing your applications. These messages are described in z/OS Language Environment Debugging Guide. 9. The link editor (the Program Management binder) is described in z/OS MVS Program Management: User's Guide and Reference. The Program Management binder messages are described in z/OS MVS System Messages, Vol 8 (IEF-IGD). Operands c89/cc/c++ generally recognize their file operand types by file suffixes. The suffixes shown here represent the default values used by c89/cc/c++. See “Environment variables” on page 93 for information on changing the suffixes to be used. 90 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ Unlike c89 and c++, which report an error if given an operand with an unrecognized suffix, cc determines that it is either an object file or a library based on the file itself. This behavior is in accordance with the environment variable prefix_EXTRA_ARGS. file.a Specifies the name of an archive file, as produced by the ar command, to be used during the link-editing phase. You can specify an MVS data set name, by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be LIB. The data set specified must be a C370LIB object library or a load library. See the description of the -l name operand for more information about using data sets as libraries. file.C Specifies the name of a C++ source file to be compiled. You can specify an MVS data set name by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be CXX. This operand is only supported by the c++ command. file.c Specifies the name of a C source file to be compiled. You can specify an MVS data set name by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be C. (The conventions formerly used by c89 for specifying data set names are still supported. See the environment variables prefix_OSUFFIX_HOSTRULE and prefix_OSUFFIX_HOSTQUAL for more information.) file.I Specifies the name of a IPA linker output file produced during the c89/cc/c++ link-editing phase, when the -W option is specified with phase code I. IPA is further described in the “Options” on page 78 topic. By default the IPA linker output file is written to a temporary file. To have the IPA linker output file written to a permanent file, see the environment variable prefix_TMPS under Environment variables. When an IPA linker output file is produced by c89/cc/c++, the default name is based upon the output file name. See the -o option description in the Options topic, for information on the name of the output file. If the output file is named a.out, then the IPA linker output file is named a.I, and is always in the working directory. If the output file is named //a.load, then the IPA linker output file is named //a.IPA. If the output file specified already has a suffix, that suffix is replaced. Otherwise the suffix is appended. This file may also be specified on the command line, in which case it is used as a file to be link-edited. file.i Specifies the name of a preprocessed C or C++ source file to be compiled. You can specify an MVS data set name, by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be CEX. When using the c++ command, this source file is recognized as a C++ source file, otherwise it is recognized as a C source file. c++ can be made to distinguish between the two. For more information see the environment variables prefix_IXXSUFFIX and prefix_IXXSUFFIX_HOST. file.o Specifies the name of a C, C++, or assembler object file, produced by c89/cc/c++, to be link-edited. When an object file is produced by c89/cc/c++, the default name is based upon the source file. If the source file is named file.c, then the object file is named file.o, and is always in the working directory. If the source file were a data set named //file.C, then the object file is named //file.OBJ. Chapter 2. Shell command descriptions 91 c89, cc, and c++ If the data set specified as an object file has undefined (U) record format, then it is assumed to be a load module. Load modules are not processed by the prelinker. You can specify an MVS data set name to be link-edited, by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be OBJ. Example: If a partitioned data set is specified, more than one member name may be specified by separating each with a comma (,): c89 //file.OBJ(mem1,mem2,mem3) file.p Specifies the name of a prelinker composite object file produced during the c89/cc/c++ link-editing phase. By default, the composite object file is written to a temporary file. To have the composite object file written to a permanent file, see the environment variable prefix_TMPS under Environment variables. When a composite object file is produced by c89/cc/c++, the default name is based upon the output file name. See the -o option description in the Options topic, for information on the name of the output file. If the output file is named a.out, then the composite object file is named a.p, and is always in the working directory. If the output file is named //a.load, then the composite object file is named //a.CPOBJ. If the output file specified already has a suffix, that suffix is replaced. Otherwise the suffix is appended. This file may also be specified on the command line, in which case it is used as a file to be link-edited. file.s Specifies the name of an assembler source file to be assembled. You can specify an MVS data set name, by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be ASM. file.x Specifies the name of a definition side-deck produced during the c89/cc/c++ link-editing phase when creating a DLL (Dynamic Link Library), and used during the link-editing phase of an application using the DLL. DLLs are further described under the -W option. When a definition side-deck is produced by c89/cc/c++, the default name is based upon the output file name. See the -o option description in the Options topic, for information on the name of the output file. If the output file is named a.dll, then the definition side-deck is named a.x, and is always in the working directory. If the output file is named //a.DLL, then the definition side-deck is named //a.EXP. If the output file specified already has a suffix, that suffix is replaced. Otherwise the suffix is appended. You can specify an MVS data set name to be link-edited, by preceding the file name with double slash (//), in which case the last qualifier of the data set name must be EXP. Example: If a partitioned data set is specified, more than one member name may be specified by separating each with a comma (,): c89 //file.EXP(mem1,mem2,mem3) –l name Specifies the name of an archive library. c89/cc/c++ searches for the file lib libname.a in the directories specified on the -L option and then in the usual places. The first occurrence of the archive library is used. For a description of the usual places, see Usage Note 7 on page 109. 92 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ You can also specify an MVS data set; you must specify the full data set name, because there are no rules for searching library directories. The data set specified must be a C370LIB object library or a load library. If a data set specified as a library has undefined (U) record format, then it is assumed to be a load library. For more information about how load libraries are searched, see Usage Note 7 on page 109. Environment variables You can use environment variables to specify necessary system and operational information to c89/cc/c++. When a particular environment variable is not set, c89/cc/c++ uses the default shown. For information about the JCL parameters used in these environment variables, see z/OS MVS JCL User's Guide. Each environment variable has a prefix (shown in italics) that should be replaced by one of the following, depending on the command name used: v _CC v _CXX v _C89 This means that to specify cc environment variables, the name shown must be prefixed with _CC (for example, _CC_ACCEPTABLE_RC). To specify c89 environment variables, the name shown must be prefixed with _C89 (for example, _C89_ACCEPTABLE_RC). To specify c++/cxx environment variables, the name shown must be prefixed with _CXX (for example, _CXX_ACCEPTABLE_RC). The following examples show how to code one or more MVS data sets: v export _CXX_LSYSLIB=CEE.SCEELKED v export _CXX_LSYSLIB=CEE.SCEELKED:CEE.SCEELKEX Notes: 1. For most environment variables, you can use all three prefixes (_CC, _CXX, _C89). In the list of environment variables that follows, you should assume that all three prefixes can be used unless otherwise indicated. 2. c89/cc/c++ can accept parameters only in the syntax indicated here. A null value indicates that c89/cc/c++ should omit the corresponding parameters during dynamic allocation. Numbers in parentheses following the environment variable name correspond to usage notes, which indicate specific usage information for the environment variable. 3. The _CCN_IPA_WORK_SPACE environment variable does not include a prefix. _CCN_32_RUNOPTS Specifies Language Environment run-time options that apply to the environment in which the 32-bit compiler components are running. _CCN_64_RUNOPTS Specifies Language Environment run-time options that apply to the environment in which the 64-bit compiler components are running. _CCN_IPA_WORK_SPACE The SPACE parameter used by the z/OS XL C/C++ compiler for the unnamed temporary work data set related to IPALINK. When _CCN_IPA_WORK_SPACE is not specified, the default is to use the settings from prefix_WORK_SPACE. In this case, prefix_WORK_SPACE must be set large enough for the potentially large work files that can be Chapter 2. Shell command descriptions 93 c89, cc, and c++ generated by IPALINK. If _CCN_IPA_WORK_SPACE is used, prefix_WORK_SPACE can be tuned for the typically smaller work files generated by the rest of the compiler. prefix_ACCEPTABLE_RC The maximum allowed return code (result) of any step (compile, assemble, IPA Link, prelink, or link-edit). If the result is between zero and this value (inclusive), then it is treated internally by c89/cc/c++ exactly as if it were a zero result, except that message FSUM3065 is also issued. The default value is 4. When used under c89/cc/c++, the prelinker by default returns at least a 4 when there are duplicate symbols or unresolved writable static symbols (but not for other unresolved references). The link editor returns at least a 4 when there are duplicate symbols, and at least an 8 when there are unresolved references and automatic library call was used. prefix_ASUFFIX (15) The suffix by which c89/cc/c++ recognizes an archive file. This environment variable does not affect the treatment of archive libraries specified as -l operands, which are always prefixed with lib and suffixed with .a. The default value is a. prefix_ASUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes a library data set. This environment variable does not affect the treatment of data set libraries specified as -l operands, which are always used exactly as specified. The default value is LIB. prefix_CCMODE Controls how c89/cc/c++ does parsing. The default behavior of c89/cc/c++ is to expect all options to precede all operands. Setting this variable allows compatibility with historical implementations (other cc commands). When set to 1, c89/cc/c++ operates as follows: v Options and operands can be interspersed. v The double dash (––) is ignored. Setting this variable to 0 results in the default behavior. The default value is 0. prefix_CLASSLIB_PREFIX (17) The prefix for the following named data sets used during the compilation phase and execution of your C++ application. To be used, the following data sets must be cataloged: v The data sets ${prefix_CLASSLIB_PREFIX}.SCLBH.+ contain the z/OS XL C++ Class Library include (header) files. v The data set ${prefix_CLASSLIB_PREFIX}.SCLBSID contains the z/OS XL C++ Class Library definition side-decks. The following data sets are also used: The data sets ${prefix_CLASSLIB_PREFIX}.SCLBDLL and ${prefix_CLASSLIB_PREFIX}.SCLBDLL2 contain the z/OS XL C++ Class Library DLLs and messages. The preceding data sets contain MVS programs that are invoked during the execution of a C++ application built by c++. To be executed correctly, these data sets must be made part of the MVS search order. Regardless of the setting of this or any other c++ environment variable, c++ does not 94 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ affect the MVS search order. These data sets are listed here for information only, to assist in identifying the correct data sets to be added to the MVS program search order. The default value is the value of the environment variable: _CXX_CLIB_PREFIXThe prefix_CLASSLIB_PREFIX environment variable applies only to c++ and cxx command names. _CXX is the only valid prefix. prefix_CLASSVERSION The version of the C++ Class Library to be invoked by c++. The setting of this variable allows c++ to control which C++ Class Library named data sets are used during the c++ processing phases. It also sets default values for other environment variables. The format of this variable is the same as the result of the Language Environment C/C++ run-time library function _librel(). See z/OS XL C/C++ Run-Time Library Reference for a description of the _librel() function. The default value is the same as the value for the _CVERSION environment variable. If _CVERSION is not set, then the default value will be the result of the C/C++ Run-Time library _librel() function. The prefix_CLASSVERSION environment variable applies only to the c++ and cxx command names. _CXX is the only valid prefix. prefix_CLIB_PREFIX (17) The prefix for the following named data set used during the compilation phase. The data set ${prefix_CLIB_PREFIX}.SCCNCMP contains the compiler programs called by c89/cc/c++. The preceding data set contains MVS programs that are invoked during the execution of c89/cc/c++ and during the execution of a C/C++ application built by c89/cc/c++. To be executed correctly, the data set must be made part of the MVS search order. Regardless of the setting of this or any other c89/cc/c++ environment variable, c89/cc/c++ does not affect the MVS search order. The data set is listed here for information only, to assist in identifying the correct data set to be added to the MVS program search order. The following data set is also used: The data set ${prefix_CLIB_PREFIX}.SCCNOBJ contains object files required to instrument the code for profile-driven feedback optimization. The default value is CBC. prefix_CMEMORY A suggestion as to the use of compiler C/C++ Runtime Library memory files. When set to 0, c89/cc/c++ will prefer to use the compiler NOMEMORY option. When set to 1, c89/cc/c++ will prefer to use the compiler MEMORY option. When set to 1, and if the compiler MEMORY option can be used, c89/cc/c++ need not allocate data sets for the corresponding work files. In this case it is the responsibility of the user to not override the compiler options (using the -W option) with the NOMEMORY option or any other compiler option which implies the NOMEMORY option. The default value is 1. Chapter 2. Shell command descriptions 95 c89, cc, and c++ prefix_CMSGS (14) The Language Environment national language name used by the compiler program. A null value will cause the default Language Environment NATLANG run-time name to be used, and a non-null value must be a valid Language Environment NATLANG run-time option name (Language Environment run-time options are described in z/OS Language Environment Programming Guide . The default value is "" (null). prefix_CNAME (14) The name of the compiler program called by c89/cc/c++. It must be a member of a data set in the search order used for MVS programs. The default value is CCNDRVR. If c89/cc/c++ is being used with prefix_CVERSION set to a release prior to z/OS V1R2, the default value will be CBCDRVR. prefix_CSUFFIX (15) The suffix by which c89/cc/c++ recognizes a C source file. The default value is c. prefix_CSUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes a C source data set. The default value is C. prefix_CSYSLIB (4, 16) The system library data set concatenation to be used to resolve #include directives during compilation. Normally #include directives are resolved using all the information specified including the directory name. When c89/cc/c++ can determine that the directory information can be used, such as when the Language Environment include (header) files are installed in the default location (in accordance with prefix_INCDIRS), then the default concatenation is "" (null). When c89/cc/c++ cannot determine that the directory information can be used, then the default concatenation is: "${prefix_PLIB_PREFIX}.SCEEH.H" "${prefix_PLIB_PREFIX}.SCEEH.SYS.H" "${prefix_PLIB_PREFIX}.SCEEH.ARPA.H" "${prefix_PLIB_PREFIX}.SCEEH.NET.H" "${prefix_PLIB_PREFIX}.SCEEH.NETINET.H" When this variable is a null value, then no allocation is done for compiler system library data sets. In this case, the use of //DD:SYSLIB on the -I option and the #include directive will be unsuccessful. Unless there is a dependency on the use of //DD:SYSLIB, it is recommended that for improved performance this variable be allowed to default to a null value. prefix_CVERSION The version of the z/OS XL C/C++ compiler to be invoked by c89/cc/c++. The setting of this variable allows c89/cc/c++ to control which z/OS XL C/C++ compiler program is invoked. It also sets default values for other environment variables. The format of this variable is the same as the result of the Language Environment C/C++ run-time library function _librel(). See z/OS XL C/C++ Run-Time Library Reference for a description of the _librel() function. The default value is the result of the C/C++ Run-Time library _librel() function. 96 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ prefix_CXXSUFFIX (15) The suffix by which c++ recognizes a C++ source file. The default value is C. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix. prefix_CXXSUFFIX_HOST (15) The suffix by which c++ recognizes a C++ source data set. The default value is CXX. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix. prefix_DAMPLEVEL The minimum severity level of dynamic allocation messages returned by dynamic allocation message processing. Messages with severity greater than or equal to this number are written to stderr. However, if the number is out of the range shown here (that is, less than 0 or greater than 8), then c89/cc/c++ dynamic allocation message processing is disabled. The default value is 4. Following are the values: 0 Informational 1–4 Warning 5–8 Severe prefix_DAMPNAME (14) The name of the dynamic allocation message processing program called by c89/cc/c++. It must be a member of a data set in the search order used for MVS programs. The default dynamic allocation message processing program is described in z/OS MVS Programming: Authorized Assembler Services Guide. The default value is IEFDB476. prefix_DCBF2008 (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format fixed unblocked and minimum block size of 2008. The block size must be in multiples of 8, and the maximum depends on the phase in which it is used but can be at least 5100. The default value is (RECFM=F,LRECL=4088,BLKSIZE=4088). prefix_DCBU (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format undefined and data set organization partitioned. This DCB is used by c89/cc/c++ for the output file when it is to be written to a data set. The default value is (RECFM=U,LRECL=0,BLKSIZE=6144,DSORG=PO). prefix_DCB121M (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format fixed blocked and logical record length 121, for data sets whose records may contain machine control characters. The default value is (RECFM=FBM,LRECL=121,BLKSIZE=3630). prefix_DCB133M (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format fixed blocked and logical record length 133, for data sets whose records may contain machine control characters. The default value is (RECFM=FBM,LRECL=133,BLKSIZE=3990). prefix_DCB137 (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format variable blocked and logical record length 137. The default value is (RECFM=VB,LRECL=137,BLKSIZE=882). prefix_DCB137A (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of Chapter 2. Shell command descriptions 97 c89, cc, and c++ record format variable blocked and logical record length 137, for data sets whose records may contain ISO/ANSI control characters. The default value is (RECFM=VB,LRECL=137,BLKSIZE=882). prefix_DCB3200 (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format fixed blocked and logical record length 3200. The default value is (RECFM=FB,LRECL=3200,BLKSIZE=12800). prefix_DCB80 (21) The DCB parameters used by c89/cc/c++ for data sets with the attributes of record format fixed blocked and logical record length 80. This value is also used when c89/cc/c++ allocates a new data set for an object file. The default value is (RECFM=FB,LRECL=80,BLKSIZE=3200). prefix_DEBUG_FORMAT (21) This variable is used to determine to which debug format (DWARF or ISD) the -g flag is translated. If _DEBUG_FORMAT is set to DWARF, then -g is translated to DEBUG(FORMAT(DWARF)). If _DEBUG_FORMAT is set to ISD, then -g is translated to TEST. The default value is DWARF. Note: This environment variable only applies to 31-bit compiles. prefix_ELINES This variable controls whether the output of the -E option will include #line directives. #line directives provide information about the source file names and line numbers from which the preprocessed source came. The preprocessor only inserts #line directives where it is necessary. When set to 1, the output of the c89/cc/c++ -E option will include #line directives where necessary. When set to 0, the output will not include any #line directives. The default value is 0. prefix_EXTRA_ARGS The setting of this variable controls whether c89/cc/c++ treats a file operand with an unrecognized suffix as an error, or attempts to process it. When the c++ command -+ option is specified, all suffixes which otherwise would be unrecognized are instead recognized as C++ source, effectively disabling this environment variable. See “Options” on page 78 for information on the -+ option. When set to 0, c89/cc/c++ treats such a file as an error and the command will be unsuccessful, because the suffix will not be recognized. When set to 1, c89/cc/c++ treats such a file as either an object file or a library, depending on the file itself. If it is neither an object file nor a library then the command will be unsuccessful, because the link-editing phase will be unable to process it. The default value for c89 and c++ is 0. The default value for cc is 1. prefix_IL6SYSIX (7, 16) The system definition side-deck list that is used to resolve symbols during the IPA Link step of the link-editing phase when using LP64 (see the description of LP64 in “Options” on page 78). The default value is whatever prefix_L6SYSIX is set to or defaults to. prefix_IL6SYSLIB (7, 16) The system library data set list that is used to resolve symbols during the IPA Link step of the link-editing phase when using LP64 (see the description of LP64 in “Options” on page 78). The default value is whatever prefix_L6SYSLIB is set to or defaults to. 98 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ prefix_ILCTL (14) The name of the control file used by the IPA linker program. By default the control file is not used, so the -W option must be specified to enable its use, as in: c89 -WI,control ... The default value is ipa.ctl. prefix_ILMSGS (14) The name of the message data set member, or the Language Environment national language name, used by the IPA linker program. The default value is whatever prefix_CMSGS is. So if prefix_CMSGS is set or defaults to "" (null), the default value is "" (null). prefix_ILNAME (14) The name of the IPA linker program called by c89/cc. It must be a member of a data set in the search order used for MVS programs. The default value is whatever prefix_CNAME is. So if prefix_CNAME is set or defaults to CCNDRVR the default value is CCNDRVR. prefix_ILSUFFIX (15) The suffix c89/cc uses when creating an IPA linker output file. The default value is I. prefix_ILSUFFIX_HOST (15) The suffix c89/cc uses when creating an IPA linker output data set. The default value is IPA. prefix_ILSYSLIB (7, 16) The system library data set list to be used to resolve symbols during the IPA Link step of the link-editing phase of non-XPLINK programs. The default value is whatever prefix_PSYSLIB is set or defaults to, followed by whatever prefix_LSYSLIB is set or defaults to. prefix_ILSYSIX (7, 16) The system definition side-deck list to be used to resolve symbols during the IPA Link step of the link-editing phase in non-XPLINK programs. The default value is whatever prefix_PSYSIX is set or defaults to. prefix_ILXSYSLIB (7, 16) The system library data set list to be used to resolve symbols during the IPA Link step of the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in “Options” on page 78). The default value is whatever prefix_LXSYSLIB is set or defaults to. prefix_ILXSYSIX (7, 16) The system definition side-deck list to be used to resolve symbols during the IPA Link step of the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in “Options” on page 78). The default value is whatever prefix_LXSYSIX is set or defaults to. prefix_INCDIRS (22) The directories used by c89/cc/c++ as a default place to search for include files during compilation (before searching prefix_INCLIBS and prefix_CSYSLIB). If c++ is not being used the default value is /usr/include. If c++ is being used the default value is /usr/include /usr/lpp/cbclib/ include. prefix_INCLIBS (22) The directories used by c89/cc/c++ as a default place to search for include files during compilation (after searching prefix_INCDIRS and before Chapter 2. Shell command descriptions 99 c89, cc, and c++ searching prefix_CSYSLIB). The default value depends on whether or not c++ is being used. If c++ is not being used the default value is //'${prefix_PLIB_PREFIX}.SCEEH.+' If c++ is being used, the default value is //'${prefix_PLIB_PREFIX}.SCEEH.+' //'${prefix_CLIB_PREFIX}.SCLBH.+' prefix_ISUFFIX (15) The suffix by which c89/cc/c++ recognizes a preprocessed C source file. The default value is i. prefix_ISUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes a preprocessed (expanded) C source data set. The default value is CEX. prefix_IXXSUFFIX (15) The suffix by which c++ recognizes a preprocessed C++ source file. The default value is i. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix. prefix_IXXSUFFIX_HOST (15) The suffix by which c++ recognizes a preprocessed (expanded) C++ source data set. The default value is CEX. This environment variable is only supported by the c++ and cxx command names. _CXX is the valid prefix. prefix_L6SYSIX (7, 16) The system definition side-deck list that resolves symbols during the link-editing phase when using LP64 (see the description of LP64 in “Options” on page 78). A definition side-deck contains link-editing phase IMPORT control statements, which name symbols that are exported by a DLL. The default value depends on whether or not c++ is used. If c++ is not used, the default value is: ${prefix_PLIB_PREFIX}.SCEELLIB(CELQS003). If c++ is used, the default value is the list concatenation: "${prefix_PLIB_PREFIX}.SCEELIB(CELQS003,CELQSCPP,C64)" "${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSX64)" prefix_L6SYSLIB (7, 16) The system library data set concatenation that is used to resolve symbols during the link-editing step when using LP64 (see the description of LP64 in “Options” on page 78). The default value is the concatenation: "${prefix_PLIB_PREFIX}.SCEEBND2" "${prefix_SLIB_PREFIX}.CSSLIB" prefix_LIBDIRS (22) The directories used by c89/cc/c++ as the default place to search for archive libraries which are specified using the -l operand. The default value is /lib /usr/lib. prefix_LSYSLIB (7, 16) The system library data set concatenation to be used to resolve symbols during the IPA Link step and the link-edit step of the non-XPLINK link-editing phase. The prefix_PSYSLIB libraries always precede the prefix_LSYSLIB libraries when resolving symbols in the link-editing phase. The default value is the concatenation: "${prefix_PLIB_PREFIX}.SCEELKEX" "${prefix_PLIB_PREFIX}.SCEELKED" "${prefix_SLIB_PREFIX}.CSSLIB" prefix_LXSYSLIB (7, 16) The system library data set concatenation to be used to resolve symbols 100 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ during the IPA Link step and the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in “Options” on page 78). The default value is the concatenation: "${prefix_PLIB_PREFIX}.SCEEBND2" "${prefix_SLIB_PREFIX}.CSSLIB" prefix_LXSYSIX (7, 16) The system definition side-deck list to be used to resolve symbols during the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in “Options” on page 78). A definition side-deck contains link-editing phase IMPORT control statements naming symbols which are exported by a DLL. The default value depends on whether or not c++ is being used. For 32-bit objects, if c++ is not being used, the default value is the list ${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001). For 32-bit objects, if c++ is being used with prefix_PVERSION and prefix_CLASSVERSION defaulted to the current z/OS release, the default value is the list concatenation: "${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001,CELHSCPP,C128)" "${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSTREAM,COMPLEX)" For 32-bit objects, if c++ is being used with prefix_PVERSION and prefix_CLASSVERSION set to a release prior to z/OS V1R2 for a 32-bit program, the default value is the list concatenation: "${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001,CELHSCPP)" "${prefix_CLASSLIB_PREFIX}.SCLBSID(ASCCOLL,COMPLEX,IOSTREAM)" Note: For 64–bit objects, see prefix_L6SYSIX. prefix_MEMORY A suggestion as to the use of XL C/C++ run-time library memory files by c89/cc/c++. When set to 0, c89/cc/c++ uses temporary data sets for all work files. When set to 1, c89/cc/c++ uses memory files for all work files that it can. The default value is 1. prefix_NEW_DATACLAS (18) The DATACLAS parameter used by c89/cc/c++ for any new data sets it creates. The default value is "" (null). prefix_NEW_DSNTYPE (18, 20) The DSNTYPE parameter used by c89/cc/c++ for any new data sets it creates. The default value is "" (null). prefix_NEW_MGMTCLAS (18) The MGMTCLAS parameter used by c89/cc/c++ for any new data sets it creates. The default value is "" (null). prefix_NEW_SPACE (18, 19) The SPACE parameters used by c89/cc/c++for any new data sets it creates. A value for the number of directory blocks should always be specified. When allocating a sequential data set, c89/cc/c++ automatically ignores the specification. The default value is (,(10,10,10)). prefix_NEW_STORCLAS (18) The STORCLAS parameter used by c89/cc/c++ for any new data sets it creates. The default value is "" (null). prefix_NEW_UNIT (18) The UNIT parameter used by c89/cc/c++ for any new data sets it creates. The default value is "" (null). Chapter 2. Shell command descriptions 101 c89, cc, and c++ prefix_NOCMDOPTS (27) Controls how the compiler processes the default options set by c89. Setting this variable to 1, reverts the compiler to the behavior that was available prior to z/OS V1R5, when the compiler was unable to distinguish between the c89 defaults and the user-specified options. Setting this variable to 0, results in the default behavior where the compiler is now able to recognize c89 defaults. The default value is 0. prefix_OPERANDS (22) These operands are parsed as if they were specified after all other operands on the c89/cc/c++ command line. The default value is "" (null). prefix_OPTIONS (22) These options are parsed as if they were specified before all other options on the c89/cc/c++ command line. The default value is "" (null). prefix_OSUFFIX (15) The suffix by which c89/cc/c++ recognizes an object file. The default value is o. prefix_OSUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes an object data set. The default value is OBJ. prefix_OSUFFIX_HOSTQUAL The data set name of an object data set is determined by the setting of this option. If it is set to 0, then the suffix prefix_OSUFFIX_HOST is appended to the source data set name to produce the object data set name. If it is set to 1, then the suffix prefix_OSUFFIX_HOST replaces the last qualifier of the source data set name to produce the object data set name (unless there is only a single qualifier, in which case the suffix is appended). The default value is 1. Note: Earlier versions of c89 always appended the suffix, which was inconsistent with the treatment of files in the hierarchical file system. It is recommended that any existing data sets be converted to use the new convention. prefix_OSUFFIX_HOSTRULE The way in which suffixes are used for host data sets is determined by the setting of this option. If it is set to 0, then data set types are determined by the rule described in the note which follows. If it is set to 1, then the data set types are determined by last qualifier of the data set (just as a suffix is used to determine the type of hierarchical file system file). Each host file type has an environment variable by which the default suffix can be modified. The default value is 1. Notes: 1. Earlier versions of c89 scanned the data set name to determine if it was an object data set. It searched for the string OBJ in the data set name, exclusive of the first qualifier and the member name. If it was found, the data set was determined to be an object data set, and otherwise it was determined to be a C source data set. It is recommended that any existing data sets be converted to use the new convention. Also, because the earlier convention only provided for recognition of C source files, assembler source cannot be processed if it is used. 102 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ 2. The c++ command does not support this environment variable, as the earlier convention would not provide for recognition of both C++ and C source files. Therefore regardless of its setting, c++ always behaves as if it is set to 1. prefix_PLIB_PREFIX (17) The prefix for the following named data sets used during the compilation, assemble, and link-editing phases, and during the execution of your application. To be used, the following data sets must be cataloged: v The data sets ${prefix_PLIB_PREFIX}.SCEEH.+ contain the include (header) files for use with the run-time library functions (where + can be any of H, SYS.H, ARPA.H, NET.H, and NETINET.H). v The data set ${prefix_PLIB_PREFIX}.SCEEMAC contains COPY and MACRO files to be used during assembly. v The data sets ${prefix_PLIB_PREFIX}.SCEEOBJ and ${prefix_PLIB_PREFIX}.SCEECPP contain run-time library bindings which exploit constructed reentrancy, used during the link-editing phase of non-XPLINK programs. v The data set ${prefix_PLIB_PREFIX}.SCEELKEX contains C run-time library bindings which exploit L-names used during the link-editing phase of non-XPLINK programs. For more information about L-names, see usage note 23 on page 113. v The data set ${prefix_PLIB_PREFIX}.SCEELKED contains all other Language Environment run-time library bindings, used during the link-editing phase of non-XPLINK programs. v The data set ${prefix_PLIB_PREFIX}.SCEEBND2 contains all static Language Environment run-time library bindings, used during the link-editing phase of XPLINK programs. v The data set ${prefix_PLIB_PREFIX}.SCEELIB contains the definition side-decks for the run-time library bindings, used during the link-editing phase of XPLINK programs. The following data sets are also used: v The data sets ${prefix_PLIB_PREFIX}.SCEERUN and ${prefix_PLIB_PREFIX}.SCEERUN2 contains the run-time library programs. These data sets contain MVS programs that are invoked during the execution of c89/cc/c++ and during the execution of a C/C++ application built by c89/cc/c++. To be executed correctly, these data sets must be made part of the MVS search order. Regardless of the setting of this or any other c89/cc/c++ environment variable, c89/cc/c++ does not affect the MVS program search order. These data sets are listed here for information only, to assist in identifying the correct data sets to be added to the MVS program search order. The default value is CEE. prefix_PMEMORY A suggestion as to the use of prelinker C/C++ Runtime Library memory files. When set to 0, c89/cc/c++ uses the prelinker NOMEMORY option. When set to 1, c89/cc/c++ uses the prelinker MEMORY option. The default value is 1. Chapter 2. Shell command descriptions 103 c89, cc, and c++ prefix_PMSGS (14) The name of the message data set used by the prelinker program. It must be a member of the cataloged data set ${prefix_PLIB_PREFIX}.SCEEMSGP. The default value is EDCPMSGE. prefix_PNAME (14) The name of the prelinker program called by c89/cc/c++. It must be a member of a data set in the search order used for MVS programs. The prelinker program is shipped as a member of the ${prefix_PLIB_PREFIX}.SCEERUN data set. The default value is EDCPRLK. prefix_PSUFFIX (15) The suffix c89/cc/c++ uses when creating a prelinker (composite object) output file. The default value is p. prefix_PSUFFIX_HOST (15) The suffix c89/cc/c++ uses when creating a prelinker (composite object) output data set. The default value is CPOBJ. prefix_PSYSIX (16) The system definition side-deck list to be used to resolve symbols during the non-XPLINK link-editing phase. A definition side-deck contains link-editing phase IMPORT control statements naming symbols which are exported by a DLL. The default value when c++ is not being used is null. If c++ is being used with prefix_PVERSION and prefix_CLASSVERSION set or defaulted to the current z/OS release, the default value is the list concatenation: "${prefix_PLIB_PREFIX}.SCEELIB(C128)" "${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSTREAM,COMPLEX)" If c++ is being used with prefix_PVERSION and prefix_CLASSVERSION set to a release prior to z/OS V1R2, the default value is the list ${prefix_CLASSLIB_PREFIX}.SCLBSID(ASCCOLL,COMPLEX,IOSTREAM) prefix_PSYSLIB (16) The system library data set list to be used to resolve symbols during the non-XPLINK link-editing phase. The prefix_PSYSLIB libraries always precede the prefix_LSYSLIB libraries when resolving symbols in the link-editing phase. The default value depends on whether or not c++ is being used. If c++ is not being used, the default value is the list containing the single entry: "${prefix_PLIB_PREFIX}.SCEEOBJ" If c++ is being used, the default value is the list: "${prefix_PLIB_PREFIX}.SCEEOBJ:${prefix_PLIB_PREFIX}.SCEECPP" prefix_PVERSION (26) The version of the Language Environment run-time library to be used with c89/cc/c++. The setting of this variable allows c89/cc/c++ to control which Language Environment named data sets are used during the c89/cc/c++ processing phases. These named data sets include those required for use of the C/C++ run-time library as well as the ISO C++ Library. It also sets default values for other environment variables. The format of this variable is the same as the result of the Language Environment C/C++ run-time library function _librel(). See z/OS XL C/C++ Run-Time Library Reference for a description of the _librel() function. The default value is the result of the C/C++ Run-Time library _librel() function. 104 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ prefix_SLIB_PREFIX (17) The prefix for the named data sets used by the link editor (CSSLIB) and the assembler system library data sets (MACLIB and MODGEN). The data set ${prefix_SLIB_PREFIX}.CSSLIB contains the z/OS UNIX assembler callable services bindings. The data sets ${prefix_SLIB_PREFIX}.MACLIB and ${prefix_SLIB_PREFIX}.MODGEN contain COPY and MACRO files to be used during assembly. These data sets must be cataloged to be used. The default value is SYS1. prefix_SNAME (14) The name of the assembler program called by c89/cc/c++. It must be a member of a data set in the search order used for MVS programs. The default value is ASMA90. prefix_SSUFFIX (15) The suffix by which c89/cc/c++ recognizes an assembler source file. The default value is s. prefix_SSUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes an assembler source data set. The default value is ASM. prefix_SSYSLIB (16) The system library data set concatenation to be used to find COPY and MACRO files during assembly. The default concatenation is: "${prefix_PLIB_PREFIX}.SCEEMAC" "${prefix_SLIB_PREFIX}.MACLIB" "${prefix_SLIB_PREFIX}.MODGEN" prefix_STEPS The steps that are executed for the link-editing phase can be controlled with this variable. For example, the prelinker step can be enabled, so that the inputs normally destined for the link editor instead go into the prelinker, and then the output of the prelinker becomes the input to the link editor. This variable allows the prelinker to be used in order to produce output which is compatible with previous releases of c89/cc/c++. The prelinker is normally used by c89/cc/c++ when the output file is a data set which is not a PDSE ( partitioned data set extended). Note: The prelinker and XPLINK are incompatible. When using the link editor XPLINK option, the prelinker cannot be used. Thus, specifying the prelinker on this variable will have no effect. The format of this variable is a set of binary switches which either enable (when turned on) or disable (when turned off) the corresponding step. Turning a switch on will not cause a step to be enabled if it was not already determined by c89/cc/c++ that any other conditions necessary for its use are satisfied. For example, the IPA Link step will not be executed unless the -W option is specified to enable the IPA linker. Enabling the IPA linker is described in “Options” on page 78. Considering this variable to be a set of 32 switches, numbered left-to-right from 0 to 31, the steps corresponding to each of the switches are as follows: 0-27 Reserved 28 TEMPINC/IPATEMP 29 IPALINK 30 PRELINK Chapter 2. Shell command descriptions 105 c89, cc, and c++ 31 LINKEDIT Example: To override the default behavior of c89/cc/c++ and cause the prelinker step to be run (this is also the default when the output file is a data set which is not a PDSE), set this variable to: 0xffffffff or the equivalent, -1. The default value when the output file is a z/OS UNIX file or a PDSE data set is 0xfffffffd or the equivalent, -3. Note: The IPATEMP step is the IPA equivalent of the TEMPINC (automatic template generation) step, just as the IPACOMP step is the IPA equivalent of the COMPILE step. See the description of IPA under the -W option for more information. prefix_SUSRLIB (16) The user library data set concatenation to be used to find COPY and MACRO files during assembly (before searching prefix_SSYSLIB). The default value is "" (null). prefix_TMPS The use of temporary files by c89/cc/c++ can be controlled with this variable. The format of this variable is a set of binary switches which either cause a temporary file to be used (when turned on) or a permanent file to be used (when turned off) in the corresponding step. The correspondence of these switches to steps is the same as for the variable prefix_STEPS. Only the prelinker and IPA linker output can be captured using this variable. Example: To capture the prelinker output, set this variable to: 0xfffffffD or the equivalent, -3. The default value is 0xffffffff or the equivalent, -1. prefix_WORK_DATACLAS (18) The DATACLAS parameter used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is "" (null). prefix_WORK_DSNTYPE (18, 20) The DSNTYPE parameter used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is "" (null). prefix_WORK_MGMTCLAS (18) The MGMTCLAS parameter used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is "" (null). prefix_WORK_SPACE (18, 19) The SPACE parameters used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is (32000,(30,30)). See also _CCN_IPA_WORK_SPACE. prefix_WORK_STORCLAS (18) The STORCLAS parameter used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is "" (null). prefix_WORK_UNIT (18) The UNIT parameter used by c89/cc/c++ for unnamed temporary (work) data sets. The default value is SYSDA. prefix_XSUFFIX (15) The suffix by which c89/cc/c++ recognizes a definition side-deck file of exported symbols. The default value is x. 106 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ prefix_XSUFFIX_HOST (15) The suffix by which c89/cc/c++ recognizes a definition side-deck data set of exported symbols. The default value is EXP. Files libc.a z/OS XL C/C++ run-time library function library (see Usage Note 7 on page 109). libm.a C/C++ Runtime Library math function library (see Usage Note 7 on page 109) libl.a lex function library liby.a yacc function library /dev/fd0, /dev/fd1, ... Character special files required by c89/cc/c++. For installation information, see z/OS UNIX System Services Planning. /usr/include The usual place to search for include files (see Usage Note 4 on page 107). The usual place to search for run-time library bindings (see Usage Note 7 on page 109). /lib /usr/lib The usual place to search for run-time library bindings (see Usage Note 7 on page 109). Usage notes 1. To be able to specify an operand that begins with a dash (–), before specifying any other operands that do not, you must use the double dash (––) end-of-options delimiter. This also applies to the specification of the –l operand. (See the description of environment variable prefix_CCMODE for an alternate style of argument parsing.) 2. When invoking c89/cc/c++ from the shell, any option-arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, some -W option-arguments contain parentheses. Source files specified as PDS member names contain parentheses; if they are specified as fully qualified names, they contain single quotation marks. To escape these special characters, either enclose the option-argument or operand in double quotation marks, or precede each character with a backslash. 3. Some c89/cc/c++ behavior applies only to hierarchical files (and not to data sets). v If the compile or assemble is not successful, the corresponding object file (file.o) is always removed. v If the DLL option is passed to the link-editing phase, and afterwards the file.x file exists but has a size of zero, then that file is removed. 4. MVS data sets may be used as the usual place to resolve C and C++ #include directives during compilation. Such data sets are installed with the Language Environment run-time library. When it is allocated, searching for these include files can be specified on the -I option as //DD:SYSLIB. (See the description of environment variable prefix_CSYSLIB for information. Chapter 2. Shell command descriptions 107 c89, cc, and c++ When include files are MVS PDS members, z/OS XL C/C++ uses conversion rules to transform the include (header) file name on a #include preprocessor directive into a member name. If the "//'dataset_prefix.+'" syntax is not used for the MVS data set which is being searched for the include file, then this transformation strips any directory name on the #include directive, and then takes the first 8 or fewer characters up to the first dot (.). If the "//'dataset_prefix.+'" syntax is used for the MVS data set which is being searched for the include file, then this transformation uses any directory name on the #include directive, and the characters following the first dot (.), and substitutes the "+" of the data set being searched with these qualifiers. In both cases the data set name and member name are converted to uppercase and underscores (_) are changed to at signs (@). If the include (header) files provided by the Language Environment run-time library are installed into the hierarchical file system in the default location (in accordance with the prefix_INCDIRS environment variable), then the compiler will use those files to resolve #include directives during compilation. c89/cc/c++ by default searches the directory /usr/include as the usual place, just before searching the data sets just described. See the description of environment variables prefix_CSYSLIB, prefix_INCDIRS, and prefix_INCLIBS for information on customizing the default directories to search. 5. Feature test macros control which symbols are made visible in a source file (typically a header file). c89/cc/c++ automatically defines the following feature test macros along with the errno macro, according to whether or not cc was invoked. v Other than cc –D "errno=(*__errno())" –D _OPEN_DEFAULT=1 v cc –D "errno=(*__errno())" –D _OPEN_DEFAULT=0 –D _NO_PROTO=1 c89/cc/c++ add these macro definitions only after processing the command string. Therefore, you can override these macros by specifying -D or -U options for them on the command string. 6. The default LANGLVL and related compiler options are set according to whether cc, c89, or c++ (cxx) was invoked. These options affect various aspects of the compilation, such as z/OS XL C/C++ predefined macros, which are used like feature test macros to control which symbols are made visible in a source file (typically a header file), but are normally not defined or undefined except by this compiler option. They can also affect the language rules used by the compiler. For more information about the compiler options listed here, see z/OS XL C/C++ User's Guide . For more information about z/OS XL C/C++ predefined macros, see z/OS XL C/C++ Language Reference. The options are shown here in a syntax that the user can specify on the c89/cc/c++ command line to override them: v c89 (also c++ (cxx) when using a C++ compiler older than z/OS v1r2) -W "c,langlvl(ansi),noupconv" v c++ (cxx) -W "c,langlvl(extended,nolibext,nolonglong) v cc -W "c,langlvl(commonc),upconv" 108 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ 7. By default the usual place for the -L option search is the /lib directory followed by the /usr/lib directory. See the description of environment variable prefix_LIBDIRS for information on customizing the default directories to search. The archive libraries libc.a and libm.a exist as files in the usual place for consistency with other implementations. However, the run-time library bindings are not contained in them. Instead, MVS data sets installed with the Language Environment run-time library are used as the usual place to resolve run-time library bindings. In the final step of the link-editing phase, any MVS load libraries specified on the -l operand are searched in the order specified, followed by searching these data sets. See the prefix_PLIB_PREFIX description, as well as descriptions of the environment variables featured in the following list. prefix_ILSYSLIB prefix_ILSYSIX prefix_LSYSLIB prefix_PSYSIX prefix_PSYSLIB This list of environment variables affects the link-editing phase of c89, but only for non-XPLINK link-editing. See XPLINK (Extra Performance Linkage) in “Options” on page 78. The following list of environment variables affects the link-editing phase of c89, but only for ILP32 XPLINK link-editing. See XPLINK (Extra Performance Linkage) in “Options” on page 78. prefix_ILXSYSLIB prefix_ILXSYSIX prefix_LXSYSLIB prefix_LXSYSIX The following list of environment variables affects the link-editing phase of c89, but only for LP64 link-editing. See the description of LP64 in “Options” on page 78. prefix_IL6SYSLIB prefix_IL6SYSIX prefix_L6SYSLIB prefix_L6SYSIX 8. Because archive library files are searched when their names are encountered, the placement of -l operands and file.a operands is significant. You may have to specify a library multiple times on the command string, if subsequent specification of file.o files requires that additional symbols be resolved from that library. 9. When the prelinker is used during the link-editing phase, you cannot use as input to c89/cc/c++ an executable file produced as output from a previous use of c89/cc/c++. The output of c89/cc/c++ when the -r option is specified (which is not an executable file) may be used as input. 10. All MVS data sets used by c89/cc/c++ must be cataloged (including the system data sets installed with the z/OS XL C/C++ compiler and the Language Environment run-time library). 11. c89/cc/c++ operation depends on the correct setting of their installation and configuration environment variables (see “Environment variables” on page 93). Also, they require that certain character special files are in the /dev directory. For additional installation and configuration information, see z/OS UNIX System Services Planning. 12. Normally, options and operands are processed in the order read (from left to right). Where there are conflicts, the last specification is used (such as with -g Chapter 2. Shell command descriptions 109 c89, cc, and c++ and -s). However, some c89 utility flag options will override others, regardless of the order in which they are specified. The option priorities, in order of highest to lowest, are as follows: -v specified twice The pseudo-JCL is printed only, but the effect of all the other options and operands as specified is reflected in the pseudo-JCL. -E Overrides -0, -O, -1, -2, -3, -V, -c, -g and -s (also ignores any file.s files). -g Overrides -0, -O, -1, -2, -3, and -s. -s Overrides -g (the last one specified is honored). -0 (zero), -O (capital letter O), -1, -2, -3, -V, -c All are honored if not overridden. -0, -O, -1, -2, -3 override each other (the last one specified is honored). Note: The preferred way for specifying optimization options, is -O (capital letter O) followed by a number; for example, -O2. 13. For options that have option-arguments, the meaning of multiple specifications of the options is as follows: -D All specifications are used. If the same name is specified on more than one -D option, only the first definition is used. -e The entry function used will be the one specified on the last -e option. -I All specifications are used. If the same directory is specified on more than one -I option, the directory is searched only the first time. -L All specifications are used. If the same directory is specified on more than one -L option, the directory is searched only the first time. -o The output file used will be the one specified on the last -o option. -U All specifications are used. The name is not defined, regardless of the position of this option relative to any -D option specifying the same name. -u All specifications are used. If a definition cannot be found for any of the functions specified, the link-editing phase will be unsuccessful. All specifications are used. All options specified for a phase are passed to it, as if they were concatenated together in the order specified. 14. The following environment variables can be at most eight characters in length. For those whose values specify the names of MVS programs to be executed, you can dynamically alter the search order used to find those programs by using the STEPLIB environment variable. c89/cc/c++ environment variables do not affect the MVS program search order. Also, for c89/cc/c++ to work correctly, the setting of the STEPLIB environment variable should reflect the Language Environment library in use at the time that c89/cc/c++ is invoked. For more information on the STEPLIB environment variable, see z/OS UNIX System Services Planning. It is also described under the sh command. Note that the STEPLIB allocation in the pseudo-JCL produced by the -v verbose option is shown as a comment, and has no effect on the MVS program search order. Its appearance in the pseudo-JCL is strictly informational. prefix_CMSGS prefix_CNAME -W 110 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ 15. 16. 17. 18. prefix_DAMPNAME prefix_ILCTL prefix_ILNAME prefix_ILMSGS prefix_PMSGS prefix_PNAME prefix_SNAME The following environment variables can be at most 15 characters in length. You should not specify any dots (.) when setting these environment variables since they would then never match their corresponding operands: prefix_ASUFFIX prefix_ASUFFIX_HOST prefix_CSUFFIX prefix_CSUFFIX_HOST prefix_CXXSUFFIX prefix_CXXSUFFIX_HOST prefix_ISUFFIX prefix_ISUFFIX_HOST prefix_ILSUFFIX prefix_ILSUFFIX_HOST prefix_IXXSUFFIX prefix_IXXSUFFIX_HOST prefix_OSUFFIX prefix_OSUFFIX_HOST prefix_PSUFFIX prefix_PSUFFIX_HOST prefix_SSUFFIX prefix_SSUFFIX_HOST prefix_XSUFFIX prefix_XSUFFIX_HOST The following environment variables are parsed as colon-delimited data set names, and represent a data set concatenation or a data set list. The maximum length of each specification is 1024 characters: prefix_CSYSLIB prefix_IL6SYSIX prefix_IL6SYSLIB prefix_ILSYSIX prefix_ILSYSLIB prefix_ILXSYSIX prefix_ILXSYSLIB prefix_L6SYSIX prefix_L6SYSLIB prefix_LSYSLIB prefix_LXSYSIX prefix_LXSYSLIB prefix_PSYSIX prefix_PSYSLIB prefix_SSYSLIB prefix_SUSRLIB The following environment variables can be at most 44 characters in length: prefix_CLASSLIB_PREFIX prefix_CLIB_PREFIX prefix_PLIB_PREFIX prefix_SLIB_PREFIX The following environment variables can be at most 63 characters in length: Chapter 2. Shell command descriptions 111 c89, cc, and c++ prefix_NEW_DATACLAS prefix_NEW_DSNTYPE prefix_NEW_MGMTCLAS prefix_NEW_SPACE prefix_NEW_STORCLAS prefix_NEW_UNIT prefix_WORK_DATACLAS prefix_WORK_DSNTYPE prefix_WORK_MGMTCLAS prefix_WORK_SPACE prefix_WORK_STORCLAS prefix_WORK_UNIT 19. The following environment variables are for specification of the SPACE parameter, and support only the syntax as shown with their default values (including all commas and parentheses). Also as shown with their default values, individual subparameters can be omitted, in which case the system defaults are used. _CCN_IPA_WORK_SPACE prefix_NEW_SPACE prefix_WORK_SPACE 20. The following environment variables are for specification of the DSNTYPE parameter, and support only the subparameters LIBRARY or PDS (or null for no DSNTYPE): prefix_NEW_DSNTYPE prefix_WORK_DSNTYPE 21. The following environment variables can be at most 127 characters in length: prefix_DCBF2008 prefix_DCBU prefix_DCB121M prefix_DCB133M prefix_DCB137 prefix_DCB137A prefix_DCB3200 prefix_DCB80 prefix_DEBUG_FORMAT These environment variables are for specification of DCB information, and support only the following DCB subparameters, with the noted restrictions: RECFM Incorrect values are ignored. LRECL None BLKSIZE None DSORG Incorrect values are treated as if no value had been specified. 22. The following environment variables are parsed as blank-delimited words, and therefore no embedded blanks or other white-space is allowed in the value specified. The maximum length of each word is 1024 characters: prefix_INCDIRS prefix_INCLIBS prefix_LIBDIRS prefix_OPTIONS prefix_OPERANDS 112 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ 23. An S-name is a short external symbol name, such as produced by the z/OS XL C/C++ compiler when compiling C programs with the NOLONGNAME option. An L-name is a long external symbol name, such as produced by the z/OS XL C/C++ compiler when compiling C programs with the LONGNAME option. 24. The z/OS XL C/C++ run-time library supports a file naming convention of // (the filename can begin with exactly two slashes). c89/cc/c++ indicate that the file naming convention of // can be used. However, the Shell and Utilities feature does not support this convention. Do not use this convention (//) unless it is specifically indicated (as here in c89/cc/c++). The z/OS Shell and Utilities feature does support the POSIX file naming convention where the filename can be selected from the set of character values excluding the slash and the null character. 25. When coding in C and C++, c89, cc, and c++, by default, produce reentrant executables. For more information on reentrancy, see z/OS XL C/C++ Programming Guide. When coding in assembly language, the code must not violate reentrancy. If it does, the resulting executable may not be reentrant. 26. The prefix_CVERSION, prefix_PVERSION and prefix_CLASSVERSION environment variables are set to a hex string in the format 0xPVVRRMMM where P is product, VV is version, RR is release and MMM is modification level. For example, the prefix_CVERSION and prefix_CLASSVERSION for the z/OS V1R2 compiler is 0x41020000. 27. c89 passes some options to the compiler so that expected behavior is achieved; for example, POSIX behavior. These options are passed onto the compiler as defaults that the user can overwrite. When default options passed by c89 are in conflict with options or pragmas that the user specified, the compiler issues diagnostic messages and may terminate processing. Since the user did not specify options that c89 passed as defaults, these messages may confuse the user. Prior to the z/OS V1R5 release, the compiler was unable to differentiate between the options that c89 passed as defaults and the user-specified options so it was unable to correctly resolve conflicting pragma/option combinations. In some cases, the compiler would overwrite pragmas with the options that c89 passed as defaults thus limiting a user's ability to use pragmas. As of z/OS V1R5, the compiler is now able to recognize c89 defaults and avoid confusion from messages for options, which were not explicitly specified by the user, and overriding pragmas, when the user did not explicitly request it. It is believed that most users will benefit from this feature so it is the default behavior. To enable the old behavior, environment variable prefix_NOCMDOPTS must have a nonzero value. Example: The following sequence will preserve the old behavior: export _C89_NOCMDOPTS=1 c89 -o hello hello.c 28. The following example shows the concatenation of data sets in environment variables. It shows how to use an environment variable to setup the SYSLIB DD when using the c89 command name: export _C89_LSYSLIB="CEE.SCEELKEX:CEE.SCEELKED:CBC.SCCNOBJ:SYS1.CSSLIB" This environment variable will produce the following SYSLIB concatenation: //SYSLIB // // // DD DSN=CEE.SCEELKEX,DISP=SHR DD DSN=CEE.SCEELKED,DISP=SHR DD DSN=CBC.SCCNOBJ,DISP=SHR DD DSN=SYS1.CSSLIB,DISP=SHR Chapter 2. Shell command descriptions 113 c89, cc, and c++ Localization c89/cc/c++ use the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES Exit values 0 Successful completion. 1 Failure due to incorrect specification of the arguments. 2 Failure processing archive libraries: v Archive library was not in any of the library directories specified. v Archive library was incorrectly specified, or was not specified, following the -l operand. 3 Step of compilation, assemble, or link-editing phase was unsuccessful. 4 Dynamic allocation error, when preparing to call the compiler, assembler, IPA linker, prelinker, or link editor, for one of the following reasons: v The file or data set name specified is incorrect. v The file or data set name cannot be opened. 5 Dynamic allocation error, when preparing to call the compiler, assembler, prelinker, IPA linker, or link editor, due to an error being detected in the allocation information. 6 Error copying the file between a temporary data set and a hierarchical file system file (applies to the -2 option, when processing assembler source files, and -r option processing). 7 Error creating a temporary control input data set for the link-editing phase. 8 Error creating a temporary system input data set for the compile or link-editing phase. Portability For c89, X/Open Portability Guide, POSIX.2 C-Language Development Utilities Option. For cc, POSIX.2 C-Language Development Utilities Option, UNIX systems. The following are extensions to the POSIX standard: v The -v, -V, -0, -1, -2 and -3 options v DLL support v IPA optimization support v The behavior of the -o option in combination with the -c option and a single source file. Note: -Ox (where x is 0, 1, 2, or 3) is equivalent to -x because -x overrides -O. This happens to match the standard compliant syntax of optimization level x (-Ox), but Ox is not treated as a single entity. It may appear redundant to use -Ox but it is recommended because it improves portability. In order to avoid creating non-portable legacy, the xlc utility does not support -x extension syntax. For example, the following are equivalent but the first syntax is recommended: 114 z/OS V1R12.0 UNIX System Services Command Reference c89, cc, and c++ c89 -O2 hello.c c89 -2 hello.c Features have been added to z/OS releases, which have made it easier to port applications from other platforms to z/OS and improve performance. For compatibility reasons, these portability and performance enhancements could not be made the default. If you are porting an application from another platform to z/OS, you may want to start by specifying the following options: c89 -o HelloWorld -2 -Wc,NOANSIALIAS -Wc,XPLINK\ -Wl,XPLINK -Wc,’FLOAT(IEEE)’ -Wc,’GONUM’ HelloWorld.c Note: The string shown in this example is one line (it had to be split to fit the page). A space exists between -Wc,XPLINK and -Wl,XPLINK. Related information ar, dbx, file, lex, makedepend, nm, strings, strip, yacc c99 — Compile C source code, link-edit and create an executable file See xlc. Note: When working in the shell, to view man page information about c99, type: man xlc. cal — Display a calendar for a month or year Format cal [month ] [year] Description cal displays a calendar on standard output (stdout). v With no arguments, cal displays a calendar for the current month of the current year. v If one argument is given and it is numeric, cal interprets it as a year (for example, 1991); if a single argument is not numeric, cal interprets it as the name of a month, possibly abbreviated (for example, apr). v If two arguments are given, cal assumes that the first argument is the month (either a number from 1 to 12 or a month name) and the second is the year. Localization cal uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Usage note Year numbers less than 100 refer to the early Christian era, not the current century. This command prints the Gregorian calendar, handling September 1752 correctly. Many cultures observe other calendars. Chapter 2. Shell command descriptions 115 cal Exit values 0 Successful completion. 1 Failure due to any of the following: v An incorrect command-line argument v An incorrect date v A year outside the range 1 to 9999 A.D. Portability X/Open Portability Guide, UNIX systems. calendar — Display all current appointments Format calendar [–] The calendar utility is fully supported for compatibility with older UNIX systems. However, because it is no longer supported by POSIX.2 IEEE standard 1003.2-1992, this utility should be avoided for applications intended to be portable to other UNIX-branded systems. Description If you do not specify any options, calendar displays all current appointments on standard output (stdout). It searches the file calendar in the current directory, looking for lines that match either today's date or tomorrow's date. On Friday, Saturday, or Sunday, tomorrow extends through to Monday. Each appointment must fit on a single line, with the date formatted as one of: January 27 1/27 jan 27 The name of the month can be abbreviated to three letters. Also, the case is not significant and the month can be given numerically. Options – Searches the RACF data base to find user IDs. calendar uses the mailx command (or, alternatively, the command named in the MAILER environment variable) to send mail to the corresponding user for any appointments that are found to be current. Because calendar cannot determine each user's locale, it runs in the POSIX locale when this option is used; otherwise it runs in the user's locale, processing data in single-byte mode. Examples If today is Friday April 7th and the following calendar file is found in the current directory: tue mar 7 1:00 pm dentist Sat April 8 Trip to the zoo mon april 10 3:30 pm job interview 4/11 vacation starts calendar prints the following: 116 z/OS V1R12.0 UNIX System Services Command Reference calendar Sat April 8 Trip to the zoo mon april 10 3:30 pm job interview Environment variable calendar uses the following environment variable: MAILER Contains the name of the command that calendar uses to send mail. If this variable is not set, calendar uses /bin/mail as the default mail command. Files calendar uses the following file: calendar File used in the current directory, or user's home directory. Localization calendar uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values Successful completion Failure due to any of the following: v An incorrect command-line argument v An inability to open the calendar file 0 1 Portability X/Open Portability Guide, UNIX systems The MAILER environment variable is an extension to traditional implementations of calendar. Related information mailx cancel — Cancel print queue requests (stub command) Format cancel [print_ID ...] printer ... cancel print_ID ... [printer ...] The cancel utility is fully supported for compatibility with older UNIX systems. However, because it is no longer supported by POSIX.2 IEEE standard 1003.2-1992, this utility should be avoided for applications intended to be portable to other UNIX-branded systems. Chapter 2. Shell command descriptions 117 cancel Description cancel cancels print queue requests. print_ID specifies the particular job (or jobs) to be canceled; the print_ID number is reported by lp when the job is submitted, or by lpstat. cancel is recognized, but its functions are not supported. If you are using the z/OS Infoprint Server feature, your system automatically uses that version of the cancel command. For more information about the print server commands, see z/OS Infoprint Server User's Guide. captoinfo — Print the terminal entries in the terminfo database Format captoinfo [–1vV] [–w width] [file ...] Description captoinfo prints all of the terminal entries in the terminfo database to standard output (stdout) in terminfo format. You can either look at the output or send it to a file that can be processed by tic. The Curses application uses the terminfo database, which contains a list of terminal descriptions. This enables you to manipulate a terminal's display regardless of the terminal type. To create the terminfo database, use tic. See the section on customizing the terminfo database in z/OS UNIX System Services Planning for information about defining the terminfo database. For more information about curses, see z/OS C Curses. Options 1 Single-column output V Print the program version v Print debugging information (verbose) to standard error (stderr) w Specifies the width of the output filename Specifies the termcap entries to be processed Examples 1. This example shows how to print all the terminal entries in the file /etc/termcap.src in terminfo format. The entry for a vt52 is shown. Issue: captoinfo /etc/termcap.src You get the following display: captoinfo: obsolete 2 character name ’dv’ removed. synonyms are: ’vt52|dec vt52’ # vt52|dec vt52, xon, cols#80, lines#24, bel=^¬, clear=-E-310-E-321, cub1=^½, cud1=^-, cuf1=-E-303, 118 z/OS V1R12.0 UNIX System Services Command Reference captoinfo cup=-E-350%-227-361%’-s’%+%-203%-227-362%’-s’%+%-203, cuu1=-E-301, ed=-E-321, el=-E-322, ind=^-, kbs=^½, kcub1=-E-304, kcud1=-E-302, kcuf1=-E-303, kcuu1=-E-301, ri=-E-311, # END OF TERMCAP # ------------------------ 2. To print all the terminal entries in the file /etc/termcap.src in terminfo format with each entry on a separate line, issue: captoinfo –1 /etc/termcap.src You get the following display: captoinfo: obsolete 2 character name ’dv’ removed. synonyms are: ’vt52|dec vt52’ # vt52|dec vt52, xon, cols#80, lines#24, clear=-E-310-E-321, cub1=^½, cud1=^-, cuf1=-E-303, cup=-E-350%-227-361%’-s’%+%-203%-227-362%’-s’%+%-203, cuu1=-E-301, ed=-E-321, el=-E-322, ind=^-, kbs=^½, kcub1=-E-304, kcud1=-E-302, kcuf1=-E-303, kcuu1=-E-301, ri=-E-311, # END OF TERMCAP # ------------------------ 3. This example shows how to write all the terminal entries in the file /etc/termcap.src to the file /test/terminfo.ti. The resulting file can be processed by tic. Notice that the error messages are written to stderr. captoinfo /etc/termcap.src 1> /test/terminfo.ti You get the following: captoinfo: obsolete 2 character name ’dv’ removed. synonyms are: ’vt52|dec vt52’ # Related information infocmp, tic cat — Concatenate or display text files Format cat [–su] [–v [et]] [file ...] Description cat displays and concatenates files. It copies each file argument to the standard output (stdout). If you specify no files or specify a dash (–) as a file name, cat reads the standard input (stdin). Chapter 2. Shell command descriptions 119 cat You can use cat in conjunction with the scrolling facility of the OMVS TSO/E command to browse data files. Options –e Displays a $ character at the end of each line. This option works only if you also specify –v. –s Does not produce an error message if cat cannot find or read a specified file. –t Displays tabs as ^I. This option works only if you also specify –v. –u Does not buffer output. –v Displays all characters including those that are unprintable characters. With a double-byte character set, an unprintable wide character is converted back to its double-byte representation. Each byte is then checked as if it were a single-byte character. If the character is unprintable, one of the following three representations is used: v M–X is used for character X if the significant bit is set. v ^X is used for the control character X (for example, ^A for CTRL-A). v \xxx represents a character with the octal value xxx. The \xxx form is used if neither of the other representations can be used. Localization cat uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v An incorrect command-line argument v Inability to open the input file v End of the file detected on stdout v The input file is the same as the output file 2 An incorrect command-line argument Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –e, –s, –t, and –v options are extensions of the POSIX standard. Related information cp, more, mv 120 z/OS V1R12.0 UNIX System Services Command Reference cc cc — Compile C source code, link-edit and create an executable file See c89/xlc or man xlc. Notes: 1. The cc command is fully supported for compatibility with older UNIX systems. However, it is recommended that the c89 command be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. 2. When working in the shell, to view man page information about cc, type: man c89 or man xlc. cd — Change the working directory Format cd [directory] cd old new cd – tcsh shell: cd [-p] [-l] [-n|-v] [name] Description The command cd directory changes the working directory of the current shell execution environment (see sh) to directory. If you specify directory as an absolute path name, beginning with /, this is the target directory. cd assumes the target directory to be the name just as you specified it. If you specify directory as a relative path name, cd assumes it to be relative to the current working directory. If the variable CDPATH is defined in the shell, the built-in cd command searches for a relative path name in each of the directories defined in CDPATH. If cd finds the directory outside the working directory, it displays the new working directory. Use colons to separate directories in CDPATH. In CDPATH, a null string represents the working directory. For example, if the value of CDPATH begins with a separator character, cd searches the working directory first; if it ends with a separator character, cd searches the working directory last. In the shell, the command cd - is a special case that changes the current working directory to the previous working directory by exchanging the values of the variables PWD and OLDPWD. Note: Repeating this command toggles the current working directory between the current and the previous working directory. Calling cd without arguments sets the working directory to the value of the HOME environment variable, if the variable exists. If there is no HOME variable, cd does not change the working directory. The form cd old new is an extension to the POSIX standard and optionally to the Korn shell. The shell keeps the name of the working directory in the variable PWD. The cd command scans the current value of PWD and replaces the first occurrence of the string old with the string new. The shell displays the resulting value of PWD, and it becomes the new working directory. Chapter 2. Shell command descriptions 121 cd If either directory is a symbolic link to another directory, the behavior depends on the setting of the shell's –o logical option. See the set command for more information. cd in the tcsh shell If a directory name is given, cd changes the tcsh shell's working directory to name. If not, it changes the directory to home. If name is '-' it is interpreted as the previous working directory. If name is not a subdirectory of the current directory (and does not begin with /, ./ or ../), each component of the tcsh variable cdpath is checked to see if it has a subdirectory name. Finally, if all else fails but name is a tcsh shell variable whose value begins with /, then this is tried to see if it is a directory (see also the implicitcd tcsh shell variable). Options for the cd tcsh built-in command are: -l Output is expanded explicitly to home or the path name of the home directory for the user. -n Entries are wrapped before they reach the edge of the screen. -p Prints the final directory stack. -v Entries are printed one per line, preceded by their stack positions. If more than one of -n or -v is given, -v takes precedence. -p is accepted but does nothing. Environment variables cd uses the following environment variables: CDPATH Contains a list of directories for cd to search in when directory is a relative path name. HOME Contains the name of your home directory. This is used when you do not specify directory on the command line. OLDPWD Contains the path name of the previous working directory. This is used by cd –. PWD Contains the path name of the current working directory. This is set by cd after changing to that directory. Localization cd uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Usage note cd is a built-in shell command. 122 z/OS V1R12.0 UNIX System Services Command Reference cd Exit values 0 Successful completion 1 Failure due to any of the following: v No HOME directory v No previous directory v A search for directory failed v An old-to-new substitution failed 2 An incorrect command-line option Messages Possible error messages include: dir bad directory cd could not locate the target directory. This does not change the working directory. Restricted You are using the restricted version of the shell (for example, by specifying the –r option for sh). The restricted shell does not allow the cd command. No HOME directory You have not assigned a value to the HOME environment variable. Thus, when you run cd in order to return to your home directory, cd cannot determine what your home directory is. No previous directory You tried the command cd – to return to your previous directory; but there is no record of your previous directory. Pattern old not found in dir You tried a command of the form cd old new. However, the name of the working directory dir does not contain any string matching the regular expression old. Portability POSIX.2, X/Open Portability Guide. All UNIX systems feature the first form of the command. The cd old new form of the command is an extension of the POSIX standard. Related information dirs, popd, pushd, set, sh, tcsh ceebldtx — Transform message source files into assembler source files Format ceebldtx [-C csect_name][-I secondary_file_name] [-P] [-S] [-c class] [-d APOST | ' | QUOTE | "] [-l BAL | C | COBOL | FORTRAN | PLI] [-s id] in_file out_file Chapter 2. Shell command descriptions 123 ceebldtx Restriction: The ceebldtx utility only works with z/OS UNIX files; MVS data sets are not applicable. Description The ceebldtx utility creates several files from the message source file. It creates an assembler source file, which can be assembled into an object (text) file and link-edited into a module in an MVS load library. When the name of the module is placed in a message module table, the Language Environment message services can dynamically access the messages. See Creating a Message Module Table in the Language Environment Programming Guide for more information about creating a message module table. The ceebldtx utility optionally creates secondary input files (COPY or INCLUDE), which contain declarations for the condition tokens associated with each message in the message source file. When a program uses the secondary input file, the condition tokens can then be used to reference the messages from the message table. The :msgname. tag indicates the symbolic name of the condition token. See the topic on Using and Handling Messages in z/OS Language Environment Programming Guide for a description of creating message source files and other corresponding information. Operands in_file The name of the file containing the message source. out_file The name of the resulting assembler source file containing the messages, inserts, and others items, suitable for input into the High Level Assembler. An extension of ".s" is assumed if none is present. Options -C csect_name This option is used to explicitly specify the CSECT name. An uppercase version of the CSECT name will be used. By default, the CSECT name is the output file base name. -I secondary_file_name The -I (uppercase i) option provides the name of the secondary input file generated for the language specified with the -l (lowercase L) option. If no suffix is present in the secondary_file_name specified, the extension will be ".h" for C, ".fortran" for FORTRAN, and ".copy" for all others. -P This option is used to save previous prologs, if files being generated already exist in the directory and contain prologs. By default, previous prologs are not reused. -S This option is used to indicate sequence numbers should be generated in the files produced. By default, no sequence numbers are generated. -c class This option is used to specify the default value for :msgclass. in cases where the tag is not coded. -d APOST | ' | QUOTE | " This option is used to specify which COBOL delimiter to use and is used in combination with the -l (lowercase L) COBOL option. By default, APOST is used as the delimiter. 124 z/OS V1R12.0 UNIX System Services Command Reference ceebldtx Tip: Quotation marks should be escaped in order to prevent them from being treated as shell metacharacters, for example: ceebldtx -l COBOL -I secondary_file_name -d \’ in_file out_file ceebldtx -l COBOL -I secondary_file_name -d \" in_file out_file ceebldtx -l COBOL -I secondary_file_name -d QUOTE in_file out_file -l BAL | C | COBOL | FORTRAN | PLI The -l (lowercase L) option is used to specify the language to be used in generating a secondary input file and is used in combination with the I secondary_file_name option. The file will contain declarations for the condition tokens associated with each message in the message source file. The language is accepted in lowercase and uppercase. C370 is also supported. This option is used to specify the default value for :msgsubid. in cases where the tag is not coded. -s id Examples ceebldtx -l PLI -I exmplcop example exmplasm Where the in_file is example, the out_file is exmplasm.s, and the PL/I secondary_file_name is exmplcop.copy. After the out_file is generated, the High Level Assembler can be used to assemble the out_file into an object file as exmplasm.s and the binder can be used to link-edit it into an MVS load library: ld -o "//mylib(exmplasm)" -e// -u//exmplasm exmplasm.o Rule: A CSECT name greater than 8 characters requires the use of the High Level Assemble GOFF option for assembling the primary output file. Exit values -1 Rexx terminated execution due to lack of storage. (See IRX0005I in the z/OS TSO/E Messages.) Attempt one of the following options: 1. Increase the virtual storage space available on the system. 2. Split up the script in_file, into two or more files, and adjust the Message Module Table for the corresponding split. 0 Successful completion. 5 Error reading file ssssssss. 6 Error erasing file ssssssss. 7 Error writing file ssssssss. 8 Bad filename ssssssss: forward slash not allowed at the end of a filename. 9 Option x requires an argument. 10 Invalid option = x. Valid options are: CIPScdls. 11 Bad data set name ssssssss. 20 CSECT name ssssssss is greater than 63 characters. Chapter 2. Shell command descriptions 125 ceebldtx 21 CSECT name ssssssss does not begin with a letter, $, #, @ or underscore (_). 28 ssssssss SCRIPT not found on any accessed disk. 40 Error on line nnn in message nnnn. Insert number greater than mmmm. 44 Error on line nnn. Duplicate :FACID. tags found with the given script file. 48 No :FACID. tag found within the given script file. 52 Error on line nnn. Message number nnnn found out of range mmmm to mmmm. 56 Number of hexadecimal digits not divisible by 2 on line nnn in message nnnn. 60 Invalid hexadecimal digits on line nnn in message nnnn. 64 Number of DBCS bytes not divisible by 2 on line nnn in message nnnn. 68 PLAS out_file name must be longer than the message facility ID pppp. 72 Message facility ID pppp on line nnn was longer than 4 characters. 76 Message class on line nnn was not a valid message class type: IWESCFA. 80 Tag not recognized on line nnn. 84 The first tag was not a :FACID. tag on line nnn. 88 Unexpected tag found on line nnn. 92 Duplicate tags ttt found on line nnn. 96 No :MSGNO. tags found within the given SCRIPT file. 98 No :MSGCLASS. (or :MSGCL.) tag found for message nnnn. 100 Insert number was not provided or was less than 1 on line nnn. 104 Message subid was out of the range mmmm to mmmm on line nnn. 108 Existing secondary file, ssssssss, found, but not on A-disk. 112 The current ADDRESS environment not CMS, TSO/E, or z/OS UNIX. nnn Undefined error number nnn issued. Contact your service representative. chaudit — Change audit flags for a file Format chaudit [–Fdai] attr pathname ... Description chaudit changes the audit attributes of the specified files or directories. Audit attributes determine whether or not accesses to a file are audited by the system authorization facility (SAF) interface. Restriction: The chaudit command can be used only by the file owner or a superuser for non-auditor-requested audit attributes. Only a user with auditor authority can change the auditor-requested audit attributes. 126 z/OS V1R12.0 UNIX System Services Command Reference chaudit Options –F If you specify a directory as a path name on the command, chaudit changes the audit characteristics of all files in that directory. Subdirectory audit characteristics are not changed. –d If you specify a directory as a path name on the command, chaudit changes the audit characteristics of all the subdirectories in that directory. File audit characteristics are not changed. –a Auditor-requested audit attributes are to be changed for the files or directories specified. If –a is not specified, user-requested audit attributes are changed. –i Does not issue error messages concerning file access authority, even if chaudit encounters such errors. The symbolic form of the attr argument has the form: [operation] op auditcondition[op auditcondition ...] The r w x operation value is any combination of the following: Sets the file to audit read attempts. Sets the file to audit write attempts. Sets the file to audit execute attempts. The default is rwx. The op part of a symbolic mode is an operator telling whether chaudit should turn file auditing on or off. The possible values are: + Turns on specified audit conditions. - Turns off specified audit conditions. = Turns on the specified audit conditions and turns off all others. The auditcondition part of a symbolic mode is any combination of the following: s Audit on successful access if the audit attribute is on. f Audit on failed access if the audit attribute is on. You can specify multiple symbolic attr values if you separate them with commas. Examples 1. The command: chaudit –s file changes the file file so that successful file accesses are not audited. 2. The command: chaudit rwx=sf file1 changes the file file1 so that all successful and unsuccessful file accesses are audited. 3. The command: chaudit r=f file2 changes the file file2 so that unsuccessful file read accesses are audited. 4. The command: chaudit r-f,w+s file3 Chapter 2. Shell command descriptions 127 chaudit changes the file file3 to not audit unsuccessful file read accesses and to audit successful write accesses. Localization chaudit uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to access a specified file v Inability to change the audit attributes for a specified file v Inability to not read the directory containing item to change v Irrecoverable error when using the –F or –d option 2 Failure due to any of the following: v Missing or incorrect attr argument v Too few arguments Messages Possible error messages include: fatal error during -F or -d option You specified the –F or –d option, but some file or directory in the directory structure was inaccessible. This may happen because of permissions or because you have removed a removable unit. read directory name You do not have read permissions on the specified directory. Portability None. This is a security extension that comes with z/OS UNIX services. Related information chmod, chown, ls chcp — Set or query ASCII/EBCDIC code pages for the terminal Format chcp [–r | –q] chcp [–s] [–a ASCII_cp] [–e EBCDIC_cp] Description chcp sets, resets, or queries the current ASCII/EBCDIC code conversion in effect for the controlling terminal. Use it when the terminal requires ASCII data and the shell application uses EBCDIC. Do not use chcp if you are logged on through the TSO/E OMVS command. The _BPX_TERMPATH environment variable enables shell scripts to tell if the user logged on from TSO, rather from rlogin or telnet. 128 z/OS V1R12.0 UNIX System Services Command Reference chcp Options –a ASCII_cp The name of the ASCII code page used by the terminal. EBCDIC data from the shell application is converted to this ASCII code page before it is sent out to the terminal. Data from the terminal is converted from this ASCII code page to EBCDIC before the application receives it. The name of the ASCII code page is case-sensitive. For a list of code pages supported by the shell, see z/OS XL C/C++ Programming Guide. –e EBCDIC_cp The name of the EBCDIC code page used for this session. EBCDIC data from the shell application is converted from this EBCDIC code page to ASCII before it is sent out to the terminal. ASCII data from the terminal is converted to this EBCDIC code page before the application receives it. The name of the EBCDIC code page is case-sensitive. For a list of code pages supported by the z/OS shell, see z/OS XL C/C++ Programming Guide. –q Queries the current ASCII and EBCDIC code pages for this terminal. The results are written to standard output. You cannot use any other options if you use the –q option. –r Resets the ASCII/EBCDIC conversion for the terminal to the default code pages. The default ASCII code page is ISO8859-1, and the default EBCDIC code page is IBM-1047. You cannot use –r with any other options. Specifies that the ASCII/EBCDIC conversion for the terminal is to use the code pages specified by the –a and –e options. You cannot use –s with any other options other than –a or –e. Either –a or e (or both) must also be specified if –s is used. –s The chcp query output is written to standard output. For example, if you enter chcp –q You get the following output: Current ASCII code page = ISO8859-1 Current EBCDIC code page = IBM-1047 Examples 1. To set the ASCII and EBCDIC code pages to IBM-eucJP and IBM-939, enter: chcp –a IBM-eucJP –e IBM-939 2. To change just the EBCDIC code page to IBM-277, enter: chcp –seIBM-277 3. To change just the ASCII code page to IBM-850, enter: chcp –a IBM-850 4. To reset ASCII/EBCDIC code page conversion to the default code pages for this terminal, enter: chcp –r 5. To query the current ASCII and EBCDIC code pages for this terminal, enter: chcp –q Chapter 2. Shell command descriptions 129 chcp Usage notes 1. Do not use chcp when you are logged on from the TSO/E OMVS command because the OMVS command does not do any ASCII/EBCDIC code page conversion. Shell scripts can test the _BPX_TERMPATH environment variable and bypass chcp when the user is logged on through OMVS. (The _BPX_TERMPATH environment variable enables shell scripts to tell if the user logged on from TSO/E rather than from rlogin or telnet.) Before starting the session, the TSO/E OMVS command sets _BPX_TERMPATH to “OMVS”. Sample shell script code: # # # ----------------------------------------------Issue chcp only if not using TSO/E OMVS command ----------------------------------------------- if test "$_BPX_TERMPATH" != "OMVS" then chcp –a IBM-850 –e IBM-1047 fi 2. After running chcp –s to change the EBCDIC code page for the session, you may also need to alter or set the following environment variables to match the new code page: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH 3. The code page names supplied with the –a and –e options are passed to iconv_open() without any uppercase or lowercase conversion. Code page converters that convert between the specified ASCII and EBCDIC code pages must be available for iconv(). 4. If ASCII/EBCDIC conversion is not active for this terminal, both the ASCII and EBCDIC code pages must be specified on the chcp –s command. At other times, omit –a when just the EBCDIC code page needs to be changed. Omit –e when just the ASCII code page needs to be changed. 5. All code pages with names not known to chcp are considered to be single-byte (SBCS) user-defined code pages. User-defined multibyte code pages are not supported. 6. chcp cannot check user-defined code page names to make sure that –a really specifies an ASCII code page and –e specifies an EBCDIC code page. In this case, specifying the wrong code pages may cause terminal input and output to be completely unreadable. It may also be impossible to enter any more shell commands. 7. chcp operates on the controlling terminal. 8. chcp should not be run as a background job. 9. The –d option specifies that special debugging information be printed. Specify this option only when requested by IBM. 130 z/OS V1R12.0 UNIX System Services Command Reference chcp Localization chcp uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 1 2 Successful completion Incorrect command-line arguments or options Any of the following errors: v There is no controlling terminal. v The controlling terminal does not support ASCII/EBCDIC code page conversion (the TSO/E OMVS command, for example). v iconv_() fails when passed the code page names specified on the command line. v chcp cannot build SBCS conversion tables using iconv() when required. v An I/O error occurred on the controlling terminal. v Either the –a or –e was omitted and the chcp –s command was run while the terminal code page conversion is in binary mode. Portability None. chcp is not described in any standard. Related information lm, rlogin chgrp — Change the group owner of a file or directory Format chgrp [–fhR] group pathname ... Description chgrp sets the group ID to group for the files and directories named by the pathname arguments. group can be a group name from a group database, or it can be a numeric group ID (GID). Rule: chgrp can be used only by the file owner or a superuser. The file owner must have the new group as his or her group or one of the supplementary groups. chgrp also turns off the set-user-ID bit and set-group-ID bit of the named files and directories. Options –f Does not issue an error message if chgrp cannot change the group ID. In this case, chgrp always returns a status of 0. –h Does not attempt to follow the symbolic link (or external link), but instead makes changes to the symbolic link (or external link) itself. Chapter 2. Shell command descriptions 131 chgrp If a pathname on the command line is the name of a directory, chgrp changes the group ID of all files and subdirectories in that directory. If chgrp cannot change some file or subdirectory in the directory, it continues to try to change the other files and subdirectories in the directory, but exits with a nonzero status. –R Localization chgrp uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 1 2 You specified –f, or chgrp successfully changed the group ownership of all the specified files and directories. Failure due to any of the following: v Inability to access a specified file v Inability to change the group of a specified file v An unrecoverable error was encountered when you specified the –R option Failure due to any of the following: v The command line contained an unknown option or too few arguments v chgrp did not recognize the specified group Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –f and –h options are an extension of the POSIX standard. Related information chmod, chown chlabel — Set the security label of files and directories Format chlabel [–cqR] [–h|–L] seclabel pathname ... Description chlabel sets the security label of the files and directories specified by pathname. Setting the security label is only allowed if the user has RACF SPECIAL authority, and no security label currently exists on the resource. Once a security label is set, it cannot be changed. seclabel is a 1-8 character security label that corresponds to a RACF security level with a set of zero or more security categories. See z/OS Planning for Multilevel Security and the Common Criteria for restrictions on security label. If chlabel could not set the security label for a file or object, it continues to try to change the other files but exits with a nonzero status. 132 z/OS V1R12.0 UNIX System Services Command Reference chlabel When –R is specified, chlabel will not cross device boundaries from the directory specified by pathname. unless the –c option is used. Options –c cross device boundaries. –h Does not follow the symbolic link (or external link), but instead makes changes to the symbolic link (or external link) itself. Cannot be used with –L. –L Follow symbolic links. Cannot be used with –h. –q Quiet mode. chlabel will suppress all warning messages. The condition that caused the warning will not affect the exit value. –R chlabel sets the security label on all the file objects and subdirectories under the directory specified by pathname. Usage notes 1. See z/OS Planning for Multilevel Security and the Common Criteria for more information about multilevel security, and seclabels. 2. chlabel will not set the security label for a symbolic link, or for the file to which it points, unless either the –h or –L option is specified. If neither option is specified, chlabel prints a warning, continues to the next file and exits with a nonzero status. 3. chlabel is typically run to set up security labels on file systems before multilevel security is activated. 4. Only the zFS file system supports the setting of security labels. 5. The SECLABEL class must be active before the chlabel command will set a security label. If the SECLABEL class is not active, security labels will not be set. Exit values 0 Successful completion 1 Failure due to any of the following: v The user does not have RACF SPECIAL authority v The user specified a security label with more than 8 characters v The file system does not support setting security labels v The RACF SECLABEL class is not active 2 Command syntax error 3 One or more warnings occurred, due to any of the following: v The path name already has a security label assigned v A symbolic link was encountered, but neither –h nor –L was specified v Device boundary not crossed Examples 1. To set the security label TOPSEC for file "secret_file": chlabel TOPSEC secret_file 2. To set the security label SYSLOW for a symbolic link "mylink": chlabel -h SYSLOW mylink Chapter 2. Shell command descriptions 133 chlabel 3. To set the security label l SYSLOW for the file to which the symbolic link "mylink" points: chlabel -L SYSLOW mylink 4. To recursively set the security label SYSHIGH for all files, symbolic links, and subdirectories under the directory "Team": chlabel -Rh SYSHIGH Team chmod — Change the mode of a file or directory Format chmod [–fhR] mode pathname Description chmod changes the access permissions, or modes, of the specified file or directory. (Modes determine who can read, write, or search a directory or file.) Users with read access to SUPERUSER.FILESYS.CHANGEPERMS (a UNIXPRIV class profile), can use the chmod command to change the permission bits of any file. Rule: chmod can be used only by the file owner or a superuser. Options –f Does not issue error messages concerning file access permissions, even if chmod encounters such errors. –h Suppresses a mode change for the file or directory pointed to by the encountered symbolic link (or external link). Symbolic link (or external link) permissions cannot be changed on a z/OS system. –R Recursively change file mode bits. For each path name operand that names a directory, chmod will change the file mode bits of the directory and all files in the file hierarchy below it. chmod never changes the permissions of symbolic links (or external links), because, on a z/OS system, the permissions on symbolic links (and external links) are never used. When -h is not specified, and symbolic links (or external links) are specified or encountered during the file hierarchy traversal, the links are followed, and the resolved directory (and files and subdirectories) are changed. You can specify the mode value on the command line in either symbolic form or as an octal value. The symbolic form of the mode argument has the form: [who] op permission[op permission ...] The who value is any combination of the following: 134 u Sets owner (user or individual) permissions. g Sets group permissions. o Sets other permissions. a Sets all permissions; this is the default. If a who value is not specified, the default is a, modified by umask. z/OS V1R12.0 UNIX System Services Command Reference chmod The op part of a symbolic mode is an operator that tells chmod to turn the permissions on or off. The possible values are: + Turns on a permission. − Turns off a permission. = Turns on the specified permissions and turns off all others. The permission part of a symbolic mode is any combination of the following: r Read permission. If this is off, you cannot read the file. x Execute permission. If this is off, you cannot run the file. X Execute or search permission for a directory; or execute permission for a file only when the current mode has at least one of the execute bits set. w Write permission. If this is off, you cannot write to the file. s If in owner permissions section, the set-user-ID bit is on; if in group permissions section, the set-group-ID bit is on. A superuser or the file owner can use a chmod command or chmod() function to change two options for an executable file. The options are set in two file mode bits: v Set-user-ID (S_ISUID) with the setuid option v Set-group-ID (S_ISGID) with the setgid option If one or both of these bits are on, the effective UID, effective GID, or both, plus the saved UID, saved GID, or both, for the process running the program are changed to the owning UID, GID, or both, for the file. This change temporarily gives the process running the program access to data the file owner or group can access. In a new file, both bits are set off. Also, if the owning UID or GID of a file is changed or if the file is written in, the bits are turned off. In shell scripts, these bits are ignored. If the RACF profile named FILE.GROUPOWNER.SETGID exists in the UNIXPRIV class, then the set-group-ID bit for a directory determines how the group owner is initialized for new objects created within the directory: v If the set-gid bit is on, then the owning GID is set to that of the directory. v If the set-gid bit is off, then the owning GID is set to the effective GID of the process. t This represents the sticky bit. For a file, the sticky bit causes a search for the program in the user's STEPLIB, the link pack area, or link list concatenation. For a directory, the sticky bit allows files in a directory or subdirectories to be deleted or renamed only by the owner of the file, by the owner of the directory, or by a superuser. You can specify multiple symbolic names if you separate them with commas. Absolute modes are octal numbers specifying the complete list of attributes for the files; you specify attributes by ORing together these bits. 4000 2000 1000 0400 0200 0100 0040 Set-user-ID bit Set-group-ID bit Sticky bit User read User write User execute (or list directory) Group read Chapter 2. Shell command descriptions 135 chmod 0020 0010 0004 0002 0001 Group Group Other Other Other write execute read write execute Examples 1. To remove write permission from orgcht: chmod –w orgcht 2. To turn on read, write, and execute permissions, and turn off the set-user-ID bit, set-group-ID bit, and sticky bit attributes. This is equivalent to chmod 0777 aprsal: chmod a=rwx aprsal 3. To set all permission bits on (anyone can read/write/execute): chmod 777 scratch 4. To set user (owner) executable permission bit on: chmod u+x file 5. To set group read / write permission bits: chmod g+rw file 6. To set other write permission off on 2 files: chmod o-w file1 file2 7. To set group read/write/execute permissions on the directory /public/teamdir and all its files and subdirectories: chmod -R g+rwx /public/teamdir 8. To set group read/execute on, group write off on /u/ateam/pgm: chmod g=rx /u/ateam/pgm Localization chmod uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to access a specified file v Inability to change the modes on a specified file v Inability to read the directory containing the item to change v An unrecoverable error was encountered when using the –R option 2 Failure due to any of the following: v Missing or incorrect mode argument v Too few arguments Messages Possible error messages include: 136 z/OS V1R12.0 UNIX System Services Command Reference chmod function not implemented This error may occur if the directory is under automount control. irrecoverable error during –R option The –R option was specified, but some file or directory in the directory structure was inaccessible. This may happen because of permissions. read directory name Read permissions are not on the specified directory. Portability POSIX.2, X/Open Portability Guide. The –f and –h options and the t permission are extensions of the POSIX standard. Related information ls, setfacl, umask chmount — Change the mount attributes of a file system Format chmount [–DRrsw] [-dsysname] [ –d destsys] [–a yes|no|unmount|include,sysname1,...,sysnameN|exclude,sysname1,...,sysnameN] pathname... Description The chmount shell command, located in /usr/sbin, changes the mount attributes of a specified file system. Rule: A chmount user must have UID(0) or at least have READ access to the SUPERUSER.FILESYS.MOUNT resource found in the UNIXPRIV class. Options –a yes|no|unmount|include,sysname1,...,sysnameN|exclude,sysname1,...,sysnameN The -a option specifies the AUTOMOVE attribute of the file system in a sysplex environment where systems are exploiting the shared file system capability. –a yes allows the system to automatically move logical ownership for a specified file system as needed. This is the default. –a no prevents ownership movement in some situations. –a umount unmounts the file system in some situations. –a include,sysname1,...,sysnameN specifies a list of systems, in priority order, to which the file system's ownership can be moved. include can be abbreviated to i. –a exclude,sysname1,...,sysnameN specifies a list of systems, in priority order, to which the file system's ownership cannot be moved. exclude can be abbreviated to e. See the data movement section in z/OS UNIX System Services Planning for details about the behavior of the AUTOMOVE options. –D Reassigns logical ownership of a file system to any available file system participating in shared file system. Chapter 2. Shell command descriptions 137 chmount –d destsys To designate a specific reassignment, use –d destsys, where destsys becomes the logical owner of a file system in a shared file system environment. –R Changes the attributes of a specified file system and all file systems mounted below it in the file system hierarchy. –r Switches the specified file system to read-only mode. –s Remounts the specified file system but does not change the current mode. –w Switches the specified file system to read-write mode. pathname... specifies the path names to use for locating the file systems that need attributes changed. Example To move ownership of the file system that contains /u/wjs to SY1: chmount -d SY1 /u/wjs Usage note Because the path name for chmount and unmount is a node, symbolic links cannot be followed unless a trailing slash is added to the symbolic link name. For example, if /etc has been converted into a symbolic link, /etc -> $SYSNAME/etc, issuing chmount -w /etc without the trailing slash will result in trying to chmount -w /etc -> $SYSNAME/etc. Depending on the security access for the symbolic link, RACF errors might occur. However if you specify chmount -w /etc/ with the trailing slash, the symbolic link will be followed and RACF will determine the access from the file being linked to. Exit values 0 Successful completion Related information mount, unmount chown — Change the owner or group of a file or directory Format chown [–fhR] owner[:group] pathname ... Description chown sets the user ID (UID) to owner for the files and directories named by pathname arguments. owner can be a user name from the user data base, or it can be a numeric user ID. (If a numeric owner exists as a user name in the user data base, the user ID number associated with that user name is used.) If there is no change to the UID, then specify – – –1. If you include a group name (that is, if you specify owner followed immediately by a colon (:) and then group with no intervening spaces, such as owner:group) chown also sets the group ID (GID) to group for the files and directories named. group can be a group name from the security facility group data base, or it can be a numeric group ID. If a numeric group exists as a group name in the group data base, the 138 z/OS V1R12.0 UNIX System Services Command Reference chown group ID number associated with that group is used. If there is no change to the GID, then specify –1 (or do not specify the :group). Restriction: Only a superuser can change the UID. To change the GID, you must either be a superuser, or the effective user ID of the process must be equal to the user ID of the file owner, and the owner argument is also equal to the user ID of the file owner or –1, and the group argument is the calling process's effective group ID or one of its supplementary group IDs. chown also turns off the set-user-ID bit and set-group-ID bit of the named files and directories. For additional information related to chown usage, see the description of the UNIXPRIV class profiles CHOWN.UNRESTRICTED and SUPERUSER.FILESYS.CHOWN in z/OS UNIX System Services Planning. Options –f Does not issue an error message if chown cannot change the owner. In this case, chown always returns a status of zero. Other errors may cause a nonzero return status. –h Does not attempt to follow the symbolic link (or external link), but instead makes the changes on the symbolic link (or external link) itself. –R If pathname on the command line is the name of a directory, chown changes all the files and subdirectories in that directory to belong to the specified owner (and group, if :group is specified). If a symbolic link is specified or encountered during the traversal of a file hierarchy, chown changes the directory referenced by the symbolic link and all files in the file hierarchy below it. If chown cannot change some file or subdirectory in the directory, it continues to try to change the other files and subdirectories in the directory, but exits with a nonzero status. Localization chown uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 You specified –f, or chown successfully changed the ownership of all the specified files and directories. 1 Failure due to any of the following: v Inability to access a specified file. v Inability to change the owner of a specified file. v Inability to read the directory containing the directory entry of the file. v An irrecoverable error was encountered when using the –R option. 2 Failure due to any of the following: Chapter 2. Shell command descriptions 139 chown v The command line contained an incorrect option. v The command line had too few arguments. v An owner was specified with a user ID that the system did not recognize. Message function not implemented This error may occur if the directory is under automount control. Portability POSIX.2, UNIX systems. The –f and –h options are an extension of the POSIX standard. Related Information chgrp, chmod chroot — Change the root directory for the execution of a command Format chroot directory command Description If you have appropriate privileges, the chroot command changes the root directory to the directory specified by the directory parameter of a specific command. The new root directory will also contain its children. Rule: In order to use chroot, you must either be a superuser (UID=0), or have READ permission to the BPX.SUPERUSER resource profile in the FACILITY class. The directory path name is always relative to the current root. If a nested chroot command is in effect, the directory path name is still relative to the current (new) root of the running process. In order for your process to operate properly after the chroot is issued, you need to have in your new root all the files that your program depends on. For example, if your new root is /tmp and you issue an ls, you will get a not found error. To use ls with /tmp as your new root, you will need a /tmp/bin with ls in it before you issue the chroot command. In addition, utilities that depend on locale-sensitive files (/usr/lib/nis/*) may be unsuccessful if these files are not in the new root file system. After chroot is issued, your current working directory is the new root (directory), chroot does not change environment variables. directory Specifies the new root directory command Specifies a command to run with the chroot command Examples 1. To run the ls command with the /tmp directory as the root file system, enter: 140 z/OS V1R12.0 UNIX System Services Command Reference chroot mkdir /tmp/bin cp /bin/ls /tmp/bin chroot /tmp ls 2. To run a child shell with another file system as the root file system (assuming that /tmp is the mount point of a file system), enter: mkdir /tmp/bin cp /bin/sh /tmp/bin chroot /tmp sh or chroot /tmp /bin/sh This makes the directory name / (slash) refer to the /tmp for the duration of the /bin/sh command. It also makes the original root file system inaccessible. The file system on the /tmp file must contain the standard directories of a root file system. Running the sh command creates a child shell that runs as a separate process from your original shell. Press the END OF FILE (Crtl-D) key sequence or type exit to end the child shell and go back to where you were in the original shell. This restores the environment of the original shell, including the meanings of the . (current directory) and the / (root directory). 3. To create a file relative to the original root, not the new one, enter: chroot Directory Command > file For example, chroot /tmp ls > /bin/file will create the file in /bin/file. Note: Redirection is handled by the current shell before chroot is executed. 4. To create a file relative to the new root, enter: chroot Directory ’Command > file’ For example, chroot /tmp ’ls > /bin/file’ will create the file in /tmp/bin/file. 5. Examples of how the current root changes: Given the standard directories of the file system plus: # echo $PATH /bin # ls /tmp/bin bin file2 sh # ls /tmp/bin/bin file1 sh # whence file2 # # whence file1 # # chroot /tmp ’whence file1’ # # chroot /tmp ’type file2’ /bin/file2 # chroot /tmp/bin ’type file1’ /bin/file1 Exit values 0 The command completed successfully 1 Failure due to any of the following: v chroot seteuid failed v User not authorized to issue chroot Chapter 2. Shell command descriptions 141 chroot 2 Failure due to any of the following: v Cannot chdir to directory specified v chroot cannot change root v Unable to execute the shell v Incorrect command syntax If the SHELL environment variable is set, chroot uses its value to invoke the shell. chtag — Change file tag information Format chtag chtag chtag chtag –b | –r [–hqRv] pathname... –c codeset [–hqRv] pathname... –m | –t [–c codeset] [–hqRv]pathname... –p [–hqRv ]pathname... Rule: You must have write permission to the file or be a superuser in order to use chtag. Description chtag allows you to set, modify, remove, or display information in a file tag. A file tag is composed of a text flag (txtflag) and a code set: codeset Represents the coded character set in which text data is encoded. The code set can be used for uniformly encoded text files or files that contain mixed text/binary data. txtflag Indicates whether or not a file contains uniformly encoded or non-uniformly encoded text data. txtflag = ON indicates the file has uniformly encoded text data txtflag = OFF indicates the file has non-uniformly encoded text data Only files with txtflag = ON and a valid code set are candidates for automatic conversion. If txtflag = OFF and a code set is associated with it, automatic conversion will not take effect. However, user applications can take advantage of the associated code set information and perform code set conversion by themselves. For information about enabling automatic conversion, see the section on using enhanced ASCII functionality in z/OS UNIX System Services Planning. Options –b Indicates that the file contains only binary (non-uniformly encoded) data. Automatic conversion is disabled with this option. –b is mutually exclusive with the –c, –m, –t, or –r options. –c codeset Allows the user to modify the code set associated with the file. codeset can be a character code set name known to the system, or the numeric coded character set identifier (CCSID); if a numeric code set name exists, the CCSID associated with that name is used. –c is mutually exclusive with the –r and –b options. Modifying the code set associated with an untagged file without specifying -t will cause the file to be marked as "mixed". 142 z/OS V1R12.0 UNIX System Services Command Reference chtag –h Does not change file tag information if the file is a symbolic link or an external link. –m Indicates that the file contains mixed text and binary data. The data is not uniformly encoded, but to identify the encoding of portions of the file that are text, this option allows the specifications of a code set with the –c option. This option sets txtflag = OFF. When used without –c, the existing character code set associated with the file is retained. Automatic conversion is disabled with this option. However, user applications can independently convert any text data residing in the file by knowing the code set associated with it. –m is mutually exclusive with the –b, –t and –r options. Specifying -m without -c on an untagged file will not have any effect on the tagging of the file. –p Prints file tag information associated with a file. If no code set name is associated with the CCSID in the file tag, the numeric CCSID will be presented instead. Sample output looks like: t b m b IBM-1047 untagged binary ISO-8859-1 untagged binary T=on T=on T=off T=off T=off T=on file1 file2 file3 file4 file5 file6 Where: t = text b = binary m = mixed – = untagged Note: Code sets that aliases of each other exist, which might cause the test to fail because the file inquiry operator might return an alias of the code set you are testing. –q Suppresses warning messages. –r Removes any tagging information associated with the file and sets the status of the file to "untagged". This option disables automatic conversion for the files. –r is mutually exclusive with the –b, –c, –m, and –t options. –R Recursively changes the file tag information. For each pathname operand that names a directory, chtag changes the file tag information about all of the files in the file hierarchy below it. When –h is not specified, and symbolic links (or external links) are specified or encountered during the file hierarchy traversal, the links are followed, and the resolved file (or files in the directory) are changed. –t Indicates that the specified file contains pure (uniformly encoded) text data. Used alone, this option sets txtflag = ON and retains the existing character code set associated with the file. To set or change the code set, use the –c option. Files that are tagged with this option and contain a valid code set are candidates for automatic conversion. –t is mutually exclusive with the –b, –m, and –r options. –v Gives verbose output. Displays what state the file tag is currently in, and Chapter 2. Shell command descriptions 143 chtag what state the user is trying to change it to. This option is only useful for the –t, –b, –m, –r and –c options. Output will be displayed in the following format: txtflag Char Set Char Set ---> txtflag Name Type Char Set Name Char Set Type Filename If the character set name is unknown, the CCSID will be used. Sample output will look like the following: chtag -mvc IBM-1047 file3.c t ISO-8859 A ---> m IBM-1047 E file3.c Where: A = ASCII E = EBCDIC ? = unknown Examples 1. To specify a text file with IBM-1047 code set, issue: chtag -tc IBM-1047 filename 2. To specify a binary file, issue: chtag -b filename 3. To specify a file of mixed binary and text data, with a new code set of ISO8859-1, issue: chtag -mc ISO8859-1 filename 4. To remove the tag from a file issue: chtag -r filename Usage notes Table 4 illustrates how the different combinations of txtflag and Character Code Set / CCSID affect a file's candidacy for automatic conversion. txtflag indicates whether this field is turned ON, OFF, binary or untagged. Character Code Set / CCSID indicates whether the stored code set is valid, invalid, or does not exist. Candidate for Automatic Conversion indicates whether this file is a candidate for automatic conversion. Table 4. Possible txtflag / CCSID combinations txtflag Character code set / CCSID Candidate for automatic conversion t (on) Defined Yes (text file) t (on) Defined No b (off) –– No m (off) Defined No (mixed data) –– (off) –– No Exit values 144 0 Successful completion 1 chtag failed to change the tag of a specified file for the following reasons: z/OS V1R12.0 UNIX System Services Command Reference chtag v Calling process does not have appropriate privileges to change file attributes v Invalid txtflag / character code set combination was issued 2 Incorrect command line syntax Related information iconv, ls cksum — Calculate and display checksums and byte counts Format cksum [–ciprtT] [file ...] Description cksum calculates and displays a checksum for each input file. A checksum is an error-checking technique used by many programs as a quick way to compare files that have been moved from one location to another to ensure that no data has been lost. It also displays the number of 8-bit bytes in each file. If you do not specify any files on the command line, or if you specify – as the file name, cksum reads the standard input (stdin). When _UNIX03 is YES, the cksum output has the space-separated form: checksum bytecount filename When _UNIX03 is unset or not YES, the cksum output has the tab-separated form: checksum bytecount filename If the file operand is not specified, the path name and its leading white space is omitted. Read error messages are controlled by the _UNIX03 variable. v If cksum fails with a read error and _UNIX03 is YES, it sends a diagnostic message to standard error, and does not show a checksum for that file. v If _UNIX03 is unset or not YES, cksum displays the checksum up to that point and marks the output line with FSUM6199 [read error]. cksum continues processing files in either case. All other error messages are sent to standard error (stderr). Options cksum can calculate checksums in a variety of ways. The default is compatible with the POSIX.2 standard. You can specify other algorithms with the following options. The POSIX standard does not recognize these algorithms; they are provided for compatibility with the UNIX sum command. –c Uses a standard 16-bit cyclic redundancy check (CRC-16). –i Uses the CCITT standard cyclic redundancy check (CRC-CCITT). Data communication network protocols often use a cyclic redundancy check to ensure proper transmission. This algorithm is more likely to produce a different sum for inputs—the only difference is byte order. Chapter 2. Shell command descriptions 145 cksum –p Uses the POSIX.2 checksum algorithm. This is the default. –r Enables the use of an alternate checksum algorithm that has the advantage of being sensitive to byte order. –t Produces a line containing the total number of bytes of data read as well as the checksum of the concatenation of the input files. –T Enables the autoconversion of tagged files. Localization cksum uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_TYPE v NLSPATH See Appendix F, “Localization” for more information. Environment variable v _UNIX03 For more information about the effect of _UNIX03 on the cksum command, see Appendix N, “Shell commands changed for UNIX03.” Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to open input file v An error reading the input file v Error turning off the autoconversion of the input file 2 Unknown command-line option Portability POSIX.2, X/Open Portability Guide. All the listed options are extensions of the POSIX standard. Related information cmp, diff, ls, sum, wc clear — Clear the screen of all previous output Format clear Description The clear command clears the screen of all output and places the cursor at the top of the screen. 146 z/OS V1R12.0 UNIX System Services Command Reference clear Localization clear uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Environment variables clear uses the following environment variables: TERM Contains the current terminal type. TERMINFO Contains the terminal information database, if different than the default. Exit values 0 1 2 3 4 Successfully cleared the screen according to the current terminal's characteristics. The terminal definition does not define a "clear" capability. Syntax error. The terminal definition specified by TERM is invalid. Invalid terminfo capability. Related information tput cmp — Compare two files Format cmp [–blsxB] file1 file2 [seek1[seek2]] Description cmp compares two files. If either file name is –, cmp reads the standard input (stdin) for that file. By default, cmp begins the comparison with the first byte of each file. If you specify seek1 and/or seek2, cmp uses it as a byte offset into file1 or file2 (respectively), and comparison begins at that offset instead of at the beginning of the files. The comparison continues (1 byte at a time) until a difference is found, at which point the comparison ends and cmp displays the byte and line number where the difference occurred. cmp numbers bytes and lines beginning with 1. Options –b Compares single blocks at a time. Normally, cmp reads large buffers of data into memory for comparison. –l Causes the comparison and display to continue to the end; however, cmp attempts no resynchronization. cmp displays the byte number (in decimal) and the differing bytes (in octal format) for each difference found. –s Suppresses output and returns a nonzero status if the files are not identical. Chapter 2. Shell command descriptions 147 cmp –x Displays the differing bytes shown by the –l option in hexadecimal format. Typically, cmp displays them in octal format. File tag specific option -B Disables autoconversion of tagged files. Localization cmp uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 The files were identical The files were not identical Failure because of an error opening or reading an input file Messages Possible error messages include: EOF on filename cmp reached the end of the file on the specified file before reaching the end of the file on the other file. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –b and –x options and the seek pointers are extensions of the POSIX standard. Related information comm, diff, uniq col — Remove reverse line feeds Format col [–bfpx] [file ...] The col utility is fully supported for compatibility with older UNIX systems. However, because it is no longer supported by POSIX.2 IEEE standard 1003.2-1992, this utility should be avoided for applications intended to be portable to other UNIX-branded systems. Description col processes control characters for vertical line feeds and writes the processed text to the standard output. If you do not specify any files, col reads from the standard input (stdin). Otherwise, col will read and process each specified file in sequence. It is intended to be used as a filter between a program such as nroff and an output device that cannot handle reverse line feeds. | | | 148 z/OS V1R12.0 UNIX System Services Command Reference col Where possible, blank characters (spaces) are converted to tabs; tab stops are assumed to be every eight characters. col also removes all escape sequences except for those shown in the following list. ESC is the ASCII escape character, octal code 033. Character Backspace Carriage-return Newline Vertical Tab SO SI Space Tab Reverse line feed Reverse half-line feed Forward half-line feed ASCII control character 010 015 012 013 016 017 040 011 ESC-7 ESC-8 ESC-9 The ASCII control characters SO and SI denote the beginning and end of text in an alternative character set. The set of each input character is remembered. col generates SO and SI characters as needed to output each character in the correct character set. Options –b Ignores backspace (CRTL-H) characters. If two characters are supposed to appear in the same space, the first character is ignored and the second is output. –f Allows forward half-line motions. Typically, y these are changed to forward full-line motions. –x Prevents conversion of spaces to tab characters. Localization col uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Usage notes 1. Because col ignores vertical motions that back up over the first line, you might get unexpected results if the first line contains superscripts. 2. Because –f allows escape sequences, it might cause unexpected results on terminals. Exit values 0 Successful completion 1 Failure due to any of the following: v Incorrect command-line option Chapter 2. Shell command descriptions 149 col v Insufficient memory Portability UNIX systems. This implementation does not handle double-byte characters. : (colon) — Do nothing, successfully Format : [argument ...] tcsh shell: : Description The : (colon) command is used when a command is needed, as in the then condition of an if command, but nothing is to be done by the command. This command simply yields an exit status of zero (success). This can be useful, for example, when you are evaluating shell expressions for their side effects. : (colon) in the tcsh shell Performs as indicated for the z/OS version of : (colon). Example : ${VAR:="default value"} sets VAR to a default value if and only if it is not already set. Usage notes colon is a special built-in shell command. Localization colon uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values Because this command always succeeds, the only possible exit status is: 0 Successful completion Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information sh, tcsh, true 150 z/OS V1R12.0 UNIX System Services Command Reference comm comm — Show and select or reject lines common to two files Format comm [–123] file1 file2 Description | | | comm locates identical lines within files sorted in the same collating sequence, and produces three columns; the first contains lines found only in the first file, the second lines only in the second file, and the third lines that are in both files. If you specify - in place of either file1 or file2, comm reads from the standard input (stdin). Options –1 –2 –3 Suppresses lines that appear only in file1 Suppresses lines that appear only in file2 Suppresses lines that appear both in file1 and file2 The options suppress individual columns. Thus, to list only the lines common to both files, use: comm -12 To find lines unique to one file or the other, use: comm -3 Observe that comm -123 displays nothing. Localization comm uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion Failure because of an error opening or reading an input file Failure that generated a usage message, such as naming only one input file Incorrect command-line options are reported but do not affect the exit status value. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information cmp, diff, sort, uniq Chapter 2. Shell command descriptions 151 command command — Run a simple command Format command [–p] command-name [argument...] command [–V|–v] command-name Description command causes the shell to suppress its function lookup and execute the given command-name and arguments as though they made up a standard command line. In most cases, if command-name is not the name of a function, the results are the same as omitting command. If, however, command-name is a special built-in command, (see sh), some unique properties of special built-in commands do not apply: v A syntax error in the command does not cause the shell running the command to stop. v Variable assignments specified with the special built-in command do not remain in effect after the shell has run the command. Options –p Searches for command-name using the system default PATH variable. –v Writes a string indicating the path name or command that the shell uses to invoke command-name. –V Writes a string indicating how the shell interprets command-name. If command-name is a command, a regular built-in command, or an implementation-provided function found using the PATH variable, the string identifies it as such and includes the absolute path name. If command-name is an alias, function, special built-in command, or reserved word, the string identifies it as such and includes its definition if it is an alias. If the command is a tracked alias, the string identifies it as cached. Example Typically, you use command when you have a command that may have the same name as a function. For example, here's a definition of a cd function that not only switches to a new directory but also uses lc to list the contents of that directory: function cd { command cd $1 lc } Inside the function, we use command to get at the real cd. If we didn't do this, the cd function would call itself in an infinite recursion. Localization command uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. 152 z/OS V1R12.0 UNIX System Services Command Reference command Usage note command is a built-in shell command. Exit values If you specified –v, possible exit status values are: 0 Successful completion 1 command could not find command-name, or an error occurred 2 Failure due to incorrect command-line argument If you did not specify –v, possible exit status values are: 126 command found command-name, but failed to invoke it. 127 An error occurred in the command or it could not find command-name. Otherwise, the exit status of command is the exit status of command-name. Portability POSIX.2. Related Information sh compress — Lempel-Ziv file compression Format compress [–cDdfVv] [–b bits] [file ...] Description compress compresses each input file using Lempel-Ziv compression techniques. If you do not specify any input files, compress reads data from standard input (stdin) and writes the compressed result to standard output (stdout). The output files have the same names as the input files but with a .Z suffix. For example, abc is compressed into abc.Z. If the .Z file already exists and you did not specify the –f option, compress gives an error and asks whether it should overwrite the existing file. compress uses the modified Lempel-Ziv algorithm described in A Technique for High Performance Data Compression, Terry A. Welch, IEEE Computer, vol. 17, no. 6 (June 1984), pp.8-19. compress first replaces common substrings in the file by 9-bit codes starting at 257. After it reaches code 512, compress begins with 10-bit codes and continues to use more bits until it reaches the limit set by the –b option. After attaining the bits limit, compress periodically checks the compression ratio. If it is increasing, compress continues to use the existing code dictionary. However, if the compression ratio decreases, compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to compensate for files, such as archives, where individual components have different information content profiles. Options –b bits Limits the maximum number of bits of compression to bits. The value bits can be an integer from 9 to 16. The default is 16. Chapter 2. Shell command descriptions 153 compress –c Writes the output to stdout. When you use this option, you can only specify one file on the command line. –D Allows an extra degree of compression to be done for files such as sorted dictionaries where subsequent lines normally have many characters in common with the preceding line. –d Decompresses argument files instead of compressing them. This works by overlaying the compress program with the uncompress program. For this to work, uncompress must be available somewhere in your search path (given by the PATH environment variable). Decompressing files this way is slower than calling uncompress directly. –f Forces compression even if the resulting file is larger or the output file already exists. When you do not specify this option, files which are larger after compression are not compressed. compress does not print an error message if this happens. –V Prints the version number of compress. –v Prints statistics giving the amount of compression achieved. Statistics give the name of each file compressed and the compression ratio, expressed as a percentage. If the file resulting from compression is larger than the original, the compression ratio is negative. Localization compress uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to one of the following: v Missing number of bits after the –b option v Incorrect number of bits specified v Failed to execute uncompress v Unknown option v Dictionary option —same count of string exceeded v Output path or file name too long v Cannot stat file v Argument file not a regular file: unchanged v Argument file has other links: unchanged v No space for compression tables 2 One or more files were not compressed because the compressed version was larger than the original Limits This implementation of compress is limited to a maximum of 16-bit compression. 154 z/OS V1R12.0 UNIX System Services Command Reference compress Portability A binary-compatible version of compress with more options is often found on UNIX systems. The –D option is an extension to traditional implementations of compress. The –D, –d and –V options are extensions of the POSIX standard. For portability, you should restrict the number of bits in the code (–b option) to a value between 9 and 14. Related information cpio, pack, pax, tar, uncompress, unpack, zcat confighfs — Invoke the vfs_pfsctl function for HFS file systems Format confighfs [–l] [–v n] [–f n] [–q] [pathname] [–x[n] size pathname] Note: The l option signifies a lowercase L, not an uppercase i. Description confighfs gives interactive shell users the ability to invoke the vfs_pfsctl function. The vfs_pfsctl function is used to pass control information to the PFS (physical file system). For more information about vfs_pfsctl, see the z/OS UNIX System Services File System Interface Reference. Detailed information about its use can be found in z/OS DFSMS Using Data Sets. confighfs resides in the following directory: /usr/lpp/dfsms/bin/. This directory is not part of the default search path definition. Therefore, the directory must be included in the command specification when invoking the command. Restriction: You can only use the confighfs command when working with the DFSMS file system (HFS). For the zFS file system, use the zfsadmn command. For more information about the zFS file system, see z/OS Distributed File Service zSeries File System Administration. Options –l Query HFS limits. Note: l signifies a lowercase L, not an uppercase i. –v n Set virtual storage max to n (where n is in MB). Requires superuser authority. –f n Set fixed storage min to n (where n is in MB). Requires superuser authority. –q Query your global statistics. pathname Query file system statistics for the file system containing each of the path names specified. Chapter 2. Shell command descriptions 155 confighfs –x size pathname Extend the specified file system, where size is the amount to be extended suffixed by the extend unit of M, T, or C (for megabytes, tracks, or cylinders), and the path name is a full or simple path name to a file or directory in the file system to extend. Requires superuser authority. –xn size pathname Extend the specified file system to a new volume using the -x rules. Requires superuser authority. The following are internal debug options: –dn Prints incoming and outgoing pfsctl buffers (where n is 0, 1, or 2). –t Skips issuing the pfsctl. Examples Restriction: On systems running shared file systems, this command should only be issued on the server system (file system owner) for the file system pointed to by the path name. Issuing it on client systems results in fields of zeros. 1. To set virtual and fixed buffer limits for the HFS file system: > confighfs –v 128 –f 32 2. To extend the file system for your current directory 100 cylinders: > confighfs –x 100c . 3. If you need to get statistics for the root file system and the file system mounted over /tmp, you would do the following: > confighfs / /tmp . Note: The . (period) in examples two and three indicates the current directory. Usage notes 1. If the HFS file system encounters an out of space condition during SYNC processing producing message IGW022S, then the following can result: a. If confighfs is used to successfully extend the file system (by specifying confighfs -x size pathname, for example) and the extent was large enough to accommodate the pages required to complete the SYNC processing, confighfs invokes the SYNC function again to complete its update and then resets the Out of Space error flag. It will no longer be necessary to unmount and remount the file system to use it further. After the error flag is reset, all file system functions will work properly again. b. If the extend size is not large enough to provide the amount of space required to complete the SYNC process, confighfs issues the following response: Inadequate space added to HFS. At least another nn tracks required. These results only apply when the IGW022S message indicates an Error Loc: EXTEND value. If it indicates an Error Loc: ARPN value, it goes into the out of space error state and require an unmount followed by a mount to reset the error condition and make it reusable. The updates applied to the HFS since the last successful SYNC will also be lost. 2. Unlike most z/OS UNIX commands, which are located in /bin, confighfs is found in the /usr/lpp/dfsms/bin directory. You can symbolically link to the actual location of confighfs. The symbolic link is found in /usr/sbin: /usr/sbin/confighfs -> /usr/lpp/dfsms/bin/confighfs 156 z/OS V1R12.0 UNIX System Services Command Reference configstk configstk — Configure the AF_UEINT stack Format configstk {–s} Configuration_file_name Description configstk is used to configure the AF_UEINT stack. This command should initially be run from the /etc/rc script, which is run when z/OS UNIX System Services is initialized. It should also be run each time the AF_UEINT network topology changes after z/OS UNIX services have been initialized. This command requires superuser authority. Options –s Does syntax checking only. Files configstk uses the following file: Configuration_file_name Specifies the configuration for the AF_UEINT stack. As with any system-wide configuration file, it should have the appropriate permissions set. This file has two types of specifications, HOME and GATEWAY. Be careful when modifying the configuration file to insure that the F_UEINT environment is not corrupted due to user error. HOME ip_address BUFFERS(number) blocking This statement is required but you can only specify it once. The entire statement must be on a single line. ip_address Defines the single virtual IP address to be used by all RS/6K clients when accessing the z/OS host, independent of how many RS/6K gateways are connected to a given z/OS image. This implementation differs from the standard IP model which defines an IP address per physical adapter. number Defines the maximum number of 32K page-fixed buffers (in OMVS private memory) that are to be used by the protocol stack. The number specified is be distributed equally among the read and write flows. As new ESCON® fibers are added to the configuration, additional IO buffers are required. Thruput decreases and overhead increases if the number specified is too restrictive. You should initially specify a value of 10 times the number of defined gateways for low-to-average use and increase it proportionally as the number of users increase). The maximum number of buffers allocated is the larger of six times the number of active gateways, or the number specified. A decrease in the number is not honored until the next IPL. blocking Indicates whether the internal blocking algorithm should be Chapter 2. Shell command descriptions 157 configstk activated for outgoing packets. The default is BLOCKING. Specifying NOBLOCKING causes the internal optimization routines, which attempt to group multiple packets into a single blocked I/O, to be bypassed (such as single packet per block written on demand). Specifying BLOCKING minimizes the z/OS overhead and maximizes the ESCON channel bandwidth, but can delay the packet delivery slightly. GATEWAY device_number checksum At least one of these statements is required and up to 32 can be specified. The entire statement must be on a single line. This statement maps the target RS/6K IP addresses to the gateway that will process the request. The device number to define the gateway must be the first of an even-odd pair of subchannels (both configured thru a single ESCON fiber) between the z/OS image and the RS/6K gateway. Multiple target IP addresses can be mapped to a given gateway. A given target IP address can be mapped to at most one gateway. device_number Specifies the hexadecimal address of device to be configured. This number must be four hexadecimal digits and must be an even number. checksum Indicates whether a reliable communications path exists between the communicating applications. Specify CHECKSUM if any portion of the path between the communicating applications is unreliable (such as a LAN). Specify NOCHECKSUM if the entire path is reliable (such as a SP2 fast switch or ESCON). A list of IP addresses immediately follows this statement, one IP address per line. At least one IP address must be specified for each gateway device. Up to 256 IP addresses can be specified in the configuration file. Blank lines are permitted and lines beginning with /* are treated as comments. Examples /* configure AF_UEINT sockets /* name the ip address for this node, default to blocking enabled home 10.32.166.20 buffers(20) /* configure device 324 gateway 0324 nochecksum 10.34.166.20 10.34.166.24 10.34.166.26 /* configure device b28 gateway 0b28 checksum 10.36.166.20 10.36.166.22 10.36.166.24 10.36.166.26 158 z/OS V1R12.0 UNIX System Services Command Reference configstrm configstrm — Set and query the STREAMS physical file system configuration Format configstrm [–bimv] [–h high_mem | ?] [–l loadmod ]... [–t trace_opt | ?]... [–u loadmod] Note: The l option signifies a lowercase L, not an uppercase i. Description configstrm sets and queries the STREAMS physical file system configuration. It can be used to view statistics and change configuration options for the STREAMS physical file system without changing your BPXPRMxx member and re-IPLing. Options –b Print current buffer pool utilization. –h high_mem Set and query the maximum allowed storage utilization and query the current utilization. high_mem is specified in kilobytes. –i Print internal diagnostic information. –l loadmod Load a new device driver set. Note: l signifies a lowercase L, not an uppercase i. –m Print device major information. –t trace_opt Set and query trace options. The valid trace options are: all | none Enables or disables all trace points. proc | noproc Enables or disables procedure entry and exit trace points. data | nodata Enables or disables data trace points. nw | nonw Enables or disables Netware trace points. code | nocode Enables or disables code trace points. diag | nodiag Enables or disables diagnostic trace points. –u loadmod Unload a device driver. –v Avoid output truncation when information is excessive. Usage notes 1. Must be a superuser to use the configstrm command. Chapter 2. Shell command descriptions 159 configstrm 2. configstrm can be used to dynamically configure the physical file system for Netware. Example To display device information for the configured STREAMS device drivers, issue: configstrm -m continue — Skip to the next iteration of a loop in a shell script Format continue [n] Description continue skips to the next iteration of an enclosing for, select, until, or while loop in a shell script. If a number n is given, execution continues at the loop control of the nth enclosing loop. The default value of n is 1. Usage notes continue is a special built-in shell command. Localization continue uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 The value of n given was not an unsigned decimal greater than 0. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information break, sh, tcsh copytree — Make a copy of a file hierarchy while preserving all file attributes Format /samples/copytree [–afos] sourcedir [targetdir] 160 z/OS V1R12.0 UNIX System Services Command Reference copytree Description copytree is a REXX sample that enables you to use a number of z/OS UNIX capabilities. Included is a recursive routine to descend a hierarchical directory. You can also use it to accomplish the following tasks: v Retrieve and set attributes for files v Read and write files v Read and set access control lists (ACLs) copytree replicates a source tree starting under the source directory within a file system to a target directory. It: v Tolerates errors when setting target attributes with messages. v Tolerates errors in the source tree, skipping those files. v Copies sparse files as sparse files. v Handles both symbolic links and external links v Does not cross mount points v Preserves file links copytree is installed in the z/OS UNIX file system. Run it as /samples/copytree. To run it under TSO, copy /samples/copytree to a PDS where REXX execs can be run, or in a PDS to run under TSO. Restriction: copytree cannot handle files greater than 1 GB in TSO/E. Guideline: Every attribute that can be set should be copied if you have sufficient authorization. Options Any combination of the option flags can be used, with no spaces between flags. -a Specifies that the 30,000 node limit warning is not to be issued. -f Specifies that full file reads are to be done when copytree is run in check mode. -o Specifies that file ownership is not to be preserved. -s Specifies that the effective UID is to be set to 0 before copytree is started. <sourcedir> The path name for the source directory where the copy begins. The path name must be used, not the file system name. <targetdir> The path name for the target directory. This directory must exist and must be empty. The permissions and other attributes of the target directory are not modified to be the same as the source directory. If <targetdir> is not specified, copytree runs in a mode to check the source file tree. Exit values 0 Successful completion >0 An error occurred Any other value means that there were errors. Chapter 2. Shell command descriptions 161 copytree Related information pax cp — Copy a file Format If the variable _UNIX03=YES is set: cp [–cfimMUv] [–p|F format|B|T|X] [-W seqparms=params] [–Z] [–O u | c=codeset] file1 file2 cp [–ACcfimMUv] [–p|F format|B|T|X] [–S suffix] [–Z] [–O u | c=codeset] file ... directory cp –R [-H|L|P] [–cfimp] [–Z] [–O u | c=codeset] source... directory cp –r [-H|L|P] [–cfimp] [–Z] [–O u | c=codeset] source... directory If the variable _UNIX03 is unset or not "YES": cp [–cfimMUv] [–p|F format|B|T|X] [–P params] [-W seqparms=params] [–Z] [–O u | c=codeset] file1 file2 cp [–ACcfimMUv] [–p|F format|B|T|X] [–S suffix] [–Z] [–O u | c=codeset] file ... directory cp –R [-H|L] [–cfimp] [–Z] [–O u | c=codeset] source... directory cp –r [-H|L] [–cfimp] [–Z] [–O u | c=codeset] source... directory Description cp copies files to a target named by the last argument on its command line. If the target is an existing file, cp overwrites it; if it does not exist, cp creates it. If the target file already exists and does not have write permission, cp denies access and continues with the next copy. If you specify more than two path names, the last path name (that is, the target) must be a directory. If the target is a directory, cp copies the sources into that directory with names given by the final component of the source path name. You can also use cp to copy files to and from MVS data sets. If you specify more than one file to be copied, the target (last path name on command line) must be either a directory or a partitioned data set. If the target is an MVS partitioned data set, the source cannot be a UNIX directory. cp does not support the copying to or from generation data groups (GDGs). To use those MVS data sets, the user must specify the real data set name. cp also does not support copying to a temporary PDSE. | | When copying records, the string " \n" is copied the same way as the string "\n": both are read back as "\n", where "\n" indicates that z/OS XL C++ will write a record containing a single blank to the file (the default behavior of z/OS XL C/C++). All other blanks in your output are read back as blanks, and any empty (zero-length) records are ignored on input. However, if the environment variable _EDC_ZERO_RECLEN is set to Y before calling cp, an empty record is treated as a single newline character and is not ignored. Also, if _EDC_ZERO_RECLEN is set to Y, a single newline character is written to the file as an empty record, and a single blank will be represented by " \n". You can copy: 162 z/OS V1R12.0 UNIX System Services Command Reference cp v v v v v v One file to another file in the working directory One file to a new file on another directory A set of directories and files to another place in your file system A UNIX file to an MVS data set An MVS data set to a file system An MVS data set to an MVS data set Options –A Specifies that all suffixes (from the first period till the end of the target) be truncated. –A has precedence over –M and –C options. –S will be turned off if –A is the last option specified. –B Specifies that the data to be copied contains binary data. When you specify –B, cp operates without any consideration for <newline> characters or special characteristics of DBCS data. (This type of behavior is typical when copying across a UNIX system.) Because –B is mutually exclusive with –F, –X, and –T, you will get an error if you specify more than one of these options. –C Specifies truncating the file name to 8 characters to meet the restriction in the MVS data set member. –c (UNIX to UNIX only) Prompts you to change the diskette if there is not enough room to complete a copy operation. This option has no effect on systems without floppy drives. Rule: The parent directories must already exist on the new target diskette. –F format Specifies whether the file is to be treated as binary, text, or record file format when copied; for text files, specifies the end-of-line delimiter. Also sets the file format to format if the target is a UNIX file. For text files, when copying from UNIX to MVS, the end-of-line delimiter is stripped. When copying from MVS to UNIX, the end-of-line delimiter is added. (Code page IBM-1047 is used to check for end-of-line delimiters.) Record file format files are treated as if they were binary files. If -F is used when copying from UNIX to UNIX, cp sets only the target file format and does not replace the end-of-line delimiters. If setting format fails, a warning is displayed but cp will continue to copy any remaining files that were specified to be copied. –F is mutually exclusive with –B, –X, –p, and –T. If you specify one of these options with –F, you will get an error. If –F is specified more than once, the last –F specified will be used. For format, you can specify: not Not specified bin Binary data rec Record. (File data consists of records with prefixes. The record prefix contains the length of the record that follows. From the shell command perspective, files with this format will be treated as if they were binary files.) Or the following text data delimiters: nl Newline character cr Carriage return Chapter 2. Shell command descriptions 163 cp lf crlf lfcr crnl Line feed Carriage return followed by line feed Line feed followed by carriage return Carriage return followed by new line –f Attempts to remove and replace a UNIX destination file that cannot be opened. -H Follows symbolic links specified as source operand on the command line. Symbolic links encountered in the tree traversal are not followed. This is the default behavior when the -R or -r option is specified but none of the -H, -L or -P options are specified. Restriction: This option can only be used with the -R or the -r option. –i When copying to a UNIX target, –i asks you if you want to overwrite an existing file, whether or not the file is read-only. -L Follows symbolic links specified as source operand on the command line and those encountered in the tree traverse. Restriction: This option can only be used with the -R or the -r option. –M Specifies that some characters of the file name are translated when copying between a UNIX file and an MVS data set member. Characters are translated as follows: v _ (underscore) in UNIX is translated to @ in MVS data set members and vice versa. v . (period) in UNIX is translated to # in MVS data set members and vice versa. v – (dash) in UNIX is translated to $ in MVS data set members and vice versa. –m (UNIX to UNIX only) Sets the modification and access time of each destination file to that of the corresponding source file. Typically, cp sets the modification time of the destination file to the present. -P If _UNIX03 is YES, does not follow any symbolic links, neither those specified as source operand on the command line not those encountered in the tree traverse. Restriction: This option can only be used with the -R or the -r option. –P params If _UNIX03 is unset or not YES, then the -P option will be treated as specifying parameters needed to create a new sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format the CRTL fopen() function uses. SPACE=(units,(primary,secondary) where the following values are supported for units: v Any positive integer indicating BLKSIZE v CYL (mixed case) v TRK (mixed case) For example: SPACE=(500,(100,500)) units, primary, secondary SPACE=(500,100) units and primary only For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide. 164 z/OS V1R12.0 UNIX System Services Command Reference cp Note: CRTL fopen() arguments: LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets. –p (UNIX to UNIX only) Preserves the modification and access times (as the –m option does). In addition, it preserves the file mode, file format, owner, and group owner, if authorized. It also preserves extended attributes. It preserves the ACLs of files and directories, if possible. The ACLs are not preserved if a file system does not support ACLs. –p is mutually exclusive with –F. If you specify both, you will get an error message. –R (UNIX to UNIX only) “Clones” the source trees. cp copies all the files and subdirectories specified by source... into directory, making careful arrangements to duplicate special files (FIFO, character special). cp only follows symbolic link specified as source operand on the command line. –r (UNIX to UNIX only) “Clones” the source trees, but makes no allowances for special files (FIFO, character special). Consequently, cp attempts to read from a device rather than duplicate the special file. This is similar to, but less useful than, the preferred –R. –S d=suffix|a=suffix v d=suffix Removes the specified suffix from a file. v a=suffix Appends the specified suffix to a file. –S has precedence over –M and –C. It also turns off the –A option (if –S is the last specified option). –T Specifies that the data to be copied contains text data. See “Usage notes” on page 172 for details on how to treat text data. This option looks for IBM-1047 end-of-line delimiters, and is mutually exclusive with –F, –X, and –B. That is, you will get an error if you specify more than one of these options. Note: –T is ignored when copying across UNIX file systems. –U Keeps file names in uppercase when copying from MVS data set members to UNIX files. The default is to make file names lowercase. –v Verbose -W seqparms=params Specifies the parameters needed to create a sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format the CRTL fopen() function uses. SPACE=(units,(primary,secondary) where the following values are supported for units: v Any positive integer indicating BLKSIZE v CYL (mixed case) v TRK (mixed case) Chapter 2. Shell command descriptions 165 cp For example: SPACE=(500,(100,500)) units, primary, secondary SPACE=(500,100) units and primary only For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide. Note: CRTL fopen() arguments: LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets. This option is the same as -P params with _UNIX03 unset or not YES. If multiple -P params and -W are specified, the value of the last one specified on the command will be used. –X Specifies that the data to be copied is an executable. Cannot be used in conjunction with –F, –T, or –B. -Z Specifies that error messages are not to be displayed when setting ACLs on the target. The return code will be zero. If you do not specify either –F|B|T or X, cp will first check the format of the MVS data set indicated and then try to determine the type of file. Automatic conversion and file tag specific options –Z Suppresses failure when default behavior is used to set file tag. For a description of the default behavior, see “Automatic conversion and file tagging behavior for cp” on page 167. –O u | c=codeset Allow automatic conversion on source and target files. –O u If the target exists and is not empty nor already tagged, cp will not change the target's tag in order for the target to be a candidate for automatic conversion. For new targets and existing, untagged, empty files, this option has no effect and cp behaves the same as the default. For a description of the default behavior, see “Automatic conversion and file tagging behavior for cp” on page 167. When using cp to copy from a UNIX file to a MVS data set, if the source is a tagged text file, then it might be a candidate for automatic conversion. When copying executables from or to MVS, the automatic conversion is disabled for both source and target. –O c=codeset For a detailed description of the behavior of this option on cp, see “Automatic conversion and file tagging behavior for cp” on page 167. To prevent corruption of text files, cp will fail if it cannot set the tag to text or code set. 166 z/OS V1R12.0 UNIX System Services Command Reference cp Attention: If automatic conversion is not set properly or if the source is not tagged properly, the target might end up with a tag code set that does not match the file content. Automatic conversion and file tagging behavior for cp The following tables describe the behavior of file tagging and automatic conversion for various source and target scenarios depending on whether the -O option is specified on the cp command. Table 5. Automatic conversion and file tagging behavior: Copying UNIX files to UNIX files Default (without -O option) If the target file system supports setting file tags... File tagging Target file is tagged the same as the source file. If the target file system does not support setting file tags (For example, NFS)... With -O c=codeset With -O u option option Target's tag is unchanged. An existing target's tag is unchanged. A new target is created with a tag according to the file system's attributes (MOUNT parameter can specify TAG). Automatic Disabled for conversion source and target files (The source or target file is a candidate for automatic conversion when its TXTFLAG is tagged TEXT.) Target's TXTFLAG is set to TEXT and its codeset is set to codeset. Allowed for source and target files Table 6. Automatic conversion and file tagging behavior: Copying MVS data sets to UNIX files Default (without -O option) If the target file system supports setting file tags... If the target file system does not support setting file tags (For example, NFS)... With -O c=codeset With -O u option option If the SOURCE is text: File tagging Target is set to UNTAG Target's tag is unchanged An existing target's tag is unchanged. A new target is created with a tag according to the file system's attributes (MOUNT parameter can specify TAG). Target's TXTFLAG is set to TEXT and its code set is set to codeset. Chapter 2. Shell command descriptions 167 cp Table 6. Automatic conversion and file tagging behavior: Copying MVS data sets to UNIX files (continued) Default (without -O option) If the target file system supports setting file tags... Automatic Disabled for conversion target file If the target file system does not support setting file tags (For example, NFS)... With -O c=codeset With -O u option option Allowed for target file (The target file is a candidate for automatic conversion when its TXTFLAG is tagged TEXT.) If the SOURCE is binary or executable: File tagging Target is set to UNTAG Target's tag is unchanged Target's TXTFLAG is set to BINARY and its code set is set to codeset. Disabled for target file Automatic conversion Table 7. Automatic conversion and file tagging behavior: Copying UNIX files to MVS data sets Default (without -O option) With -O u option With -O c=codeset option If the SOURCE is text or binary: File tagging Not applicable for target data set Automatic Disabled for source file conversion Allowed for source file Disabled for source file (The source file is a candidate for automatic conversion when its TXTFLAG is tagged TEXT.) If the SOURCE is executable: File tagging Not applicable for target data set Automatic conversion Disabled for source file The –p option on cp does not affect file tagging. Limits and requirements In general: 1. To specify an MVS data set name, precede the name with double slashes (//). For example, to specify the fully qualified data set names 'turbo.gammalib' and 'turbo.gammalib(pgm1)', you write: "//’turbo.gammalib’" "//’turbo.gammalib(pgm1)’" The same goes for data set names that are not fully qualified: //turbo 168 z/OS V1R12.0 UNIX System Services Command Reference cp 2. For PDS (partitioned data set) or PDSE (partitioned data set extended), to avoid parsing by the shell, the name should be quoted or minimally, the parenthesis should be escaped. For example, to specify 'turbo(pgm1)', you can use quotes: "//turbo(pgm1)" or escape the parenthesis: //turbo\(pgm1\) 3. 4. 5. 6. As indicated, a fully qualified name must be single-quoted (as is done within TSO). To prevent the single quotes from being interpreted by the shell, they must be escaped or the name must be placed within regular quotation marks. See the 'turbo.gammalib' examples. If you specify a UNIX file as source and the MVS data set (target) does not exist, a sequential data set will be created. If the partitioned data set exists, the UNIX file will be copied to the partitioned data set member. If source is an MVS data set and target is a UNIX directory, the UNIX directory must exist. You cannot have a UNIX directory, partitioned data set, or sequential data set as source if the target is a partitioned data set. To copy all members from a partitioned data set, you can specify the partitioned data set as source and a UNIX directory as target. MVS data set naming limitations. The naming of MVS data sets has some limitations. v Data set names can only contain uppercase alphabetic characters (A-Z). Lowercase characters will be converted to uppercase during any copies to MVS data sets. v Data set names can contain numeric characters 0–9 and special characters @, #, and $. v Data set names cannot begin with a numeric character. v A data set member name cannot be more than 8 characters. If a file name is longer than 8 characters or uses characters that are not allowed in an MVS data set name, the file is not copied. You can use the –C option to truncate names to 8 characters. Limitations: UNIX to MVS data set. The limitations are as follows: 1. If you specify a sequential MVS data set that is in undefined record format, the file is copied as binary. 2. If you specify a PDSE that is in undefined record format, the first file successfully copied determines in what format files will be copied. Note that PDSE does not allow a mixture of formats. If the first successfully copied file is an executable, the PDSE will have program objects only and all other files will fail. On the other hand, if the first file is data, then all files are copied as binary. 3. If you specify a PDS that is in undefined record format, UNIX executables are saved as PDS load modules. All other files are copied as binary. 4. If you specify an MVS data set that is either in variable length or fixed record length and you have not set the file format, text files are copied as text, binaries as binary, and executables as binary. (IBM-1047 end-of-line delimiters are detected in the data) 5. If you set the file format, the set value is used to determine if data is binary, text, or record file format. Limitations: MVS data set to UNIX. The limitations are as follows: Chapter 2. Shell command descriptions 169 cp 1. If an UNIX file does not exist, one is created using 666 mode value, whether the data to be copied is binary or text: 666 mode value: owner(rw-) group(rw-) other(rw-) If the data to be copied is a shell script or executable residing in a PDS or PDSE with undefined record format, the UNIX file is created using 777 mode value: 777 mode value: owner(rwx) group(rwx) other(rwx) 2. If a UNIX file exists and the file format is set, cp copies the file as that format. Otherwise, v Load modules (PDS) are stored as UNIX executables and program objects (PDSE) are copied because they are the same as executables; v Data within data sets of undefined record format are copied as binary if the data is not a program object or load module; v Data found within data sets of fixed length or variable record length are copied as text. (IBM-1047 end-of-line delimiters are detected in the data) Limitations: MVS to MVS. The limitations are as follows: 1. Options –A, –C, –f, and –S are ignored. 2. If target and source are in undefined record format (and neither is a sequential data set), cp will attempt to copy the data as a load module. If that fails, then cp will copy the data as binary. 3. If target and source are in undefined record format and either is a sequential data set, cp copies the data as binary. 4. If the source has a fixed or variable record length and the target is in undefined record format, cp copies the data as binary. 5. If the source is in undefined record format and the target has a fixed or variable record length, cp copies the data as binary. 6. If both source and target are in fixed or variable record length, cp copies the data as text. Limitations: Copying executables into a PDS. The limitations are as follows: 1. A PDS cannot store load modules that incorporate program management features. 2. c89, by default, produces objects using the highest level of program management. 3. If you plan on copying a load module to a PDS, you can use a prelinker, which produces output compatible with linkage editor. Output generated by a linkage editor generated can be stored in a PDS. The following table is a quick reference for determining the correct use of options with cp. Table 8. cp Format: File to File and File ... (multiple files) to directory 170 Source/target Options allowed Options ignored UNIX file/UNIX file Ffip ABCMPSTUX UNIX file/sequential data set BFiPT ACfMpSU UNIX file/PDS or PDSE member BFiTX ACfMPpSU z/OS V1R12.0 UNIX System Services Command Reference Options failed X cp Table 8. cp Format: File to File and File ... (multiple files) to directory (continued) Source/target Options allowed Options ignored Options failed Sequential data set/UNIX file BFfiTU ACMPpS X Sequential data set/sequential data set BFiPT ACfMpSU X Sequential data set/PDS or BFiT PDSE member ACfMPpSU X PDS or PDSE member/UNIX file BFfiTUX ACMPpS PDS or PDSE member/sequential data set BFiPT ACfMpSU PDS or PDSE member/PDS or PDSE member BFiTX ACfMPpSU UNIX file/UNIX directory ACFipS BMPTUX PDSE or PDSE member/UNIX directory BFfiMSTUX ACMPp X UNIX file/partitioned data ABCFiMSTX set fPpU PDS or PDSE member/partitioned data set BFiTX ACfMPpSU Partitioned data set/UNIX directory ABCFfiMSTUX Pp The tables that follow indicate the kind of copies allowed using cp. Table 9. cp Format: File to File Source Target Allowed UNIX file, sequential data set, or partitioned data set member UNIX file, sequential data set, or partitioned data set member Yes UNIX directory UNIX directory No (unless cp is used with –R or –r) Partitioned data set UNIX directory (dir) NOTE: results in each member of data set are moved to dir. Yes UNIX directory Partitioned data set No Partitioned data set Partitioned data set No UNIX file or partitioned data UNIX directory (must exist) set member or partitioned data set Yes Partitioned data set member Yes Partitioned data set Chapter 2. Shell command descriptions 171 cp Table 10. cp Format: File... (multiple files) to Directory Source Target Allowed Any combination of UNIX file or partitioned data set member UNIX directory or Partitioned data set Yes Any combination of UNIX directory or sequential data set Partitioned data set or UNIX directory No Partitioned data set UNIX directory Yes Partitioned data set Partitioned data set No Usage notes For UNIX to MVS: 1. To copy from UNIX to a partitioned data set, you must allocate the data set before doing the cp. 2. If an MVS data set does not exist, cp will allocate a new sequential data set of variable record format. 3. For text files, all <newline> characters are stripped during the copy. Each line in the file ending with a <newline> character is copied into a record of the MVS data set. If text file format is specified or already exists for the source file, that file format will be used for end-of-line delimiter instead of <newline>. Note that cp looks for IBM-1047 end-of-line delimiters in data. You cannot copy a text file to an MVS data set that has an undefined record format: v For an MVS data set in fixed record format, any line copied longer than the record size will cause cp to fail with a displayed error message and error code. If the line is shorter than the record size, the record is padded with blanks. v For an MVS data set in variable record format: Any line copied longer than the largest record size will cause cp to fail with a displayed error message and error code. Record length is set to the length of the line. 4. For binary files, all copied data is preserved: v For an MVS data set in fixed record format, data is cut into chunks of size equal to the record length. Each chunk is put into one record. The last record is padded with blanks. v For an MVS data set in variable record format, data is cut into chunks of size equal to the largest record length. Each chunk is put into one record. The length of the last record is equal to length of the data left. v For an MVS data set in undefined record format, data is cut into chunks of size equal to the block size. Each chunk is put into one record. The length of the last record is equal to the length of the data left. 5. For load modules, the partitioned data set specified must be in undefined record format otherwise the executable will not be copied. 6. If more than one file name is the same, the file is overwritten on each subsequent copy. 7. If a UNIX file name contains characters that are not allowed in an MVS data set, it will not be copied. If the UNIX file name has more than 8 characters, it can not be copied to an MVS data set member. (See the –ACMS options for converting file names) 8. You are not allowed to copy files into data sets with spanned records. 172 z/OS V1R12.0 UNIX System Services Command Reference cp 9. PDSE cannot have a mixture of program objects and data members. PDS allows mixing, but it is not recommended. 10. Special files such as external links and FIFO will not be copied to MVS data sets. However, you can copy character special files to MVS data sets. 11. If a file is a symbolic link, cp copies the resolved file, not the link itself. 12. UNIX file attributes are lost when copying to MVS. If you want to preserve file attributes, you should use the pax utility. For MVS to UNIX: 1. If the target UNIX file exists, the new data overwrites the existing data. The mode of the file is unchanged (except the S_ISUID and S_ISGID bits are turned off). 2. If the specified UNIX file does not exist, it will be created using 666 mode value if binary or text (this is subject to umask). If the data to be copied is a shell script or executable, the UNIX file will be created with 777 mode value (also subject to umask). 3. For an MVS data set in variable record format RECFM(VB) or undefined record format RECFM(U), trailing blanks are preserved when copying from MVS to UNIX. For an MVS data set in fixed record format, trailing blanks are not preserved when copying from MVS to UNIX. 4. When you copy MVS data sets to text files in the z/OS UNIX file system, a <newline> character is appended to the end of each record. If trailing blanks exist in the record, the <newline> character is appended after the trailing blanks. If the file format option is specified or the target file has the file format set, that file format is used as the end-of-line delimiter instead of <newline>. 5. When you copy MVS data sets to UNIX binary files, the <newline> character is not appended to the record. 6. You cannot use cp to copy data sets with spanned record lengths. 7. Due to an XL C/C++ Run-Time restriction, when copying a file from a file system to an MVS sequential data set with the same name and case, you must prefix the file in the file system with "./". For example: cp ./SMPL.DATA "//’SMPL.DATA’" Examples 1. If _UNIX03 is unset or not 'YES', to specify –P params for a nonexisting sequential target: cp -P "RECFM=U,space=(500,100)" file "//’turbo.gammalib’" This cp command is equivalent to: cp -W "seqparms=’RECFM=U,space=(500,100)’" file "//’turbo.gammalib’" 2. To copy file f1 to a fully qualified sequential data set ’turbo.gammalib’ and treat it as a binary: cp -F bin f1 "//’turbo.gammalib’" 3. To copy all members from a fully qualified PDS ’turbo.gammalib’ to an existing UNIX directory dir: cp "//’turbo.gammalib’" dir 4. To drop .c suffixes before copying all files in UNIX directory dir to an existing PDS ’turbo.gammalib’: cp -S d=.c dir/* "//’turbo.gammalib’" Chapter 2. Shell command descriptions 173 cp Environment variables cp uses the following environment variable when copying records to or from MVS data sets: _EDC_ZERO_RECLEN If set to Y before calling cp, an empty record (zero-length) is treated as a single newline character and is not ignored. Also, a single newline character is written to the file as an empty record, and a single blank will be represented by “ \n”. If you do not set this environment variable when copying records, then the string “ \n” is copied the same way as the string “\n”: both are read and written as “\n”, where “\n” indicates that z/OS XL C/C++ will write a record containing a single blank to the file (the default behavior of z/OS XL C/C++). All other blanks in the output are read back as blanks, and any empty records are ignored. cp also uses the following environment variable: _UNIX03 For more information about the effect of _UNIX03 on this command, see Appendix N, “Shell commands changed for UNIX03,” on page 975. Localization cp uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 174 0 Successful completion 1 Failure due to any of the following: v An argument had a trailing slash (/) but was not a directory v Inability to find a file v Inability to open an input file for reading v Inability to create or open an output file v A read error occurred on an input file v A write error occurred on an output file v The input and output files were the same file v An unrecoverable error when using –r or –R. Possible unrecoverable –r or –R errors include: – Inability to access a file – Inability to change permissions on a target file – Inability to read a directory – Inability to create a directory – A target that is not a directory – Source and destination directories are the same 2 Failure due to any of the following: v An incorrect command-line option v Too few arguments on the command line z/OS V1R12.0 UNIX System Services Command Reference cp v v v v A target that should be a directory but isn't No space left on target device Insufficient memory to hold the data to be copied Inability to create a directory to hold a target file Messages Possible error messages include: cannot allocate target string cp has no space to hold the name of the target file. Try to release some memory to give cp more space. name is a directory (not copied) You did not specify –r or –R, but one of the names you asked to copy was the name of a directory. target name? You are attempting to copy a file with the –i option, but there is already a file with the target name. If you have specified –f, you can write over the existing file by typing y and pressing <Enter>. If you do not want to write over the existing file, type n and press <Enter>. If you did not specify –f and the file is read-only, you are not given the opportunity to overwrite it. source name and target name are identical The source and the target are actually the same file (for example, because of links). In this case, cp does nothing. unreadable directory name cp cannot read the specified directory—for example, because you do not have appropriate permission. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –f and –m options are extensions of the POSIX standard. Related information cat, cpio, ln, mv, rm cpio — Copy in/out file archives Format cpio –o [ –aBcvyz] [–C blocksize] [–O file] [–V volpat] cpio –i [–BbcdfmrsStuvqyz] [–C blocksize] [–I file] [–V volpat] [pattern ...] cpio –p [–aBdlmruv] directory The cpio utility is fully supported for compatibility with older UNIX systems. However, it is recommended that the pax utility be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Description cpio reads and writes files called cpio archives. A cpio archive is a concatenation of files and directories preceded by a header giving the filename and other file Chapter 2. Shell command descriptions 175 cpio system information. With cpio, you can create a new archive, extract contents of an existing archive, list archive contents, and copy files from one directory to another. Options Every call to cpio must specify one and only one of the following selector options: –i Reads an existing archive (created with the –o option) from the standard input (stdin). Unless you specify the –t option, cpio extracts all files matching one or more of the given pattern arguments from the archive. Patterns are the same as those used by filename generation (see sh). When you do not specify a pattern argument, the default pattern * is used; as a result, cpio extracts all files. –o Writes a new archive to the standard output (stdout), using the list of files read from stdin. Such a list might be produced by the ls or find commands. For example: ls . | cpio –o >arch uses ls to list the files of the working directory and then pipes this list as input to cpio. The resulting archive contains the contents of all the files, and is written to arch. –p Is shorthand for: cpio –o | (cd directory; cpio –i) where cpio –i is performed in the given directory. You can use this option to copy entire file trees. Consult the syntax lines to determine which of the following additional options can be applied with a particular selector option: –a Resets the access time (of each file accessed for copying to the archive) to what it was before the copy took place. –B Uses buffers of 5120 bytes for input and output rather than the default 512-byte buffers. –b Causes 16-bit words to be swapped within each longword and bytes to be swapped within each 16-bit word of each extracted file. This facilitates the transfer of information between different processor architectures. This is equivalent to specifying both the –s and –S options. –C blocksize Sets the buffer size to a specified block size, rather than the default 512-byte buffers. 176 –c Reads and writes header information in ASCII form. Normally, cpio writes the header information in a compact binary format. This option produces an archive more amenable to transfer through nonbinary streams (such as some data communication links) and is highly recommended for those moving data between different processors. –d Forces the creation of necessary intermediate directories when they do not already exist. –f Inverts the sense of pattern matching. More precisely, cpio extracts a file from the archive if and only if it does not match any of the pattern arguments. –I file Causes input to be read from the specified file, rather than from stdin. z/OS V1R12.0 UNIX System Services Command Reference cpio –l Gives permission to create a link to a file rather than making a separate copy. –m Resets the modification time of an output file to the modification time of the source file. Normally, when cpio copies data into a file, it sets the modification time of the file to the time at which the file is written. This option has no effect on directories. –O file Causes output to be written to the specified file, rather than to stdout. –q Assumes all created files are text. This means that any \r (carriage return) characters are stripped, and only the \n (newlines) are retained. Do not use the –q option for converting text to a system-independent format, because that would require all files to be read twice. –r Lets you rename files as cpio works. When extracting, cpio displays the name of the component it is about to extract and gives you the chance to specify a name for the extracted file. If you enter . as the name, cpio processes the file or directory with no modification to the name. If you just press Enter, cpio skips the file. –S For portability reasons, swaps pairs of 16-bit words within longwords (a 32-bit or 64-bit word) only when extracting files. This option does not affect the headers. –s For portability reasons, swaps pairs of bytes within each 16-bit word only when extracting files. –s does not affect the headers. –t Prevents files extraction, producing instead a table of filenames contained in the archive. See the description of the –v option. –u Copies an archive file to a target file even if the target is newer than the archive. Normally, cpio does not copy the file. –V volpat Provides automatic multivolume support. cpio writes output to files, the names of which are formatted using volpat. The current volume number replaces any occurrence of # in volpat. When you invoke cpio with this option, it asks for the first number in the archive set, and waits for you to type the number and a carriage return before its precedes with the operation. cpio issues the same sort of message when a write error or read error occurs on the archive; the reasoning is that this kind of error means that cpio has reached the end of the volume and should go on to a new one. –v Provides more verbose information than usual. cpio prints the names of files as it extracts them from or adds them to archives. When you specify both –v and –t, cpio prints a table of files in a format similar to that produced by the ls –l command. –y When used with –V, does not ask for a volume number to begin with, but does ask if it gets a read or write error. –z Performs Lempel-Ziv compression. Output is always a 16-bit compression. On input, any compression up to 16-bit is acceptable. Usage notes 1. Use the pax command if you need to use multibyte patterns when searching for filenames. Chapter 2. Shell command descriptions 177 cpio 2. The POSIX 1003.1 standard defines formats for cpio archives that limit the UIDs and GIDs that can be stored to the maximum value of 262143. Values larger than this will not be properly restored. 3. The byte and word swapping done by the –b, –S, and –s options is effective only for the file data written. With or without the –c option, header information is always written in a machine-invariant format. Localization cpio uses the following localization environment variable: v LANG v LC_ALL v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v An incorrect option v Incorrect command-line arguments v Out of memory v Compression error v Failure on extraction v Failure on creation Portability X/Open Portability Guide, non-Berkeley UNIX systems after Version 7. The –q, –V, –y, and –z options are specific to the z/OS shell. Related information compress, cp, dd, find, ls, mv, pax, tar, cpio, uncompress See the pax file format description in Appendix H, “File formats,” on page 943. cron daemon — Run commands at specified dates and times Format cron Description cron is a clock daemon that runs commands at specified dates and times. You can specify regularly scheduled commands as described in crontab. You can also submit jobs that are to be run only once using the at command. cron runs commands with priorities and limits set by the queuedefs file. cron uses the value from queuedefs to lower the priority for non-UID=0 users only. The priority is unchanged for UID=0 users. 178 z/OS V1R12.0 UNIX System Services Command Reference cron daemon cron only examines crontab files and at command files when initializing or when a file changes using crontab or at. This reduces the overhead of checking for new or changed files at regularly scheduled intervals. The setuid bit for cron should never be set; however, it must be started by a user with appropriate privileges to issue the setuid call for any UID. Because cron never exits, it should only be run once, normally during the system initialization process. cron automatically forks and runs itself in the background, in a new shell session. cron uses the pid file to prevent more than one cron running at the same time. When matching the date and time expressions given in crontab entries, cron uses the time zone in effect when the system started the daemon. As a result, you should ensure that the TZ environment variable is set at this time. For information about setting the TZ environment variable, see Appendix I, “Format of the TZ environment variable,” on page 961. For at jobs, cron uses the value of TZ in effect when you submitted the job. at, batch, and crontab submit jobs to cron; the data for those jobs can contain double-byte characters. When the jobs are executed, the data in the jobs are interpreted in the locale that cron is using. Because it is strongly recommended that cron be started in the POSIX locale, doublebyte characters in the jobs may not be interpreted correctly. You can get around this by calling the setlocale() system call in the job itself. The crontab, batch, and at job files store information about the MVS identity and the UNIX identity (the real UID) of the user who created the jobs. The cron daemon uses that information to set up the environment in which to run the jobs as follows: v The MVS identity is set to the user's MVS identity. v The UNIX real and effective UIDs are set to the user's real UID. cron handles the following externally generated signals in a special way: SIGTERM Causes cron to exit. You can cause cron to exit with the following command: kill –TERM pid where pid is the cron's PID number. To find the cron's PID number, you can use: ps -e | grep cron SIGUSR1 Is sent by either at or crontab to indicate a new at job or an updated crontab entry. cron does not delete at jobs until they finish running. If the cron daemon is terminated while at jobs are running, cron runs them again when the daemon is restarted. SIGUSR2 Writes internal cron queue information to the log file. The following is an example of output to a cron log from ’kill -USR2 5’. The output was written to the log on a test system when the queuedefs job limit of 5 was exceeded. The number of jobs that are running is 5 (the limit is 500): Queue `c’ 5j2n15w: queued 4, running 5, jobs 5 Next try for queued jobs 13 seconds Chapter 2. Shell command descriptions 179 cron daemon RUNNING: uid/gid: 0/512: pid 33554441: sleep 10000 RUNNING: uid/gid: 0/512: pid 385875972: echo start; sleep 10000; echo end RUNNING: uid/gid: 0/512: pid 67108876: echo start; sleep 10000; echo end RUNNING: uid/gid: 0/512: pid 33554445: echo start; sleep 10000; echo end RUNNING: uid/gid: 0/512: pid 67108879: echo start; sleep 10000; echo end QUEUED: uid/gid: 0/512: echo Hello! QUEUED: uid/gid: 0/512: echo start; sleep 10000; echo end QUEUED: uid/gid: 0/512: echo Hello! QUEUED: uid/gid: 0/512: echo start; sleep 10000; echo end cron uses a number of files in the /usr/lib/cron directory to determine which users may and may not use the at and crontab commands. v The file at.allow contains the list of users who have permission to use at. v The file at.deny contains the list of users who do not have permission to use at. If these files do not exist, only the superuser can use the at command. To allow all users access to at, there must be a null at.deny file and no at.allow file. cron uses the files cron.allow and cron.deny in a similar manner. v cron.allow contains the list of users who have permission to use crontab. v cron.deny contains the list of users who do not have permission to use crontab. If these files do not exist, only the superuser can use crontab. To allow all users access to crontab, there must be a null cron.deny file and no cron.allow file. Files cron uses the following files which reside in a system-defined directory: /etc/mailx.rc Although cron does not use this file directly, cron may call mailx which uses this file for configuration settings. Specifically, for cron to deliver messages properly, this file should contain a valid setting for the mailx sendmail variable. This file is generally copied from /samples/mailx.rc. /usr/spool/cron The main cron directory. /usr/spool/cron/atjobs A directory containing at files. /usr/spool/cron/crontabs A directory containing crontab files. /usr/spool/cron/log A file that maintains a history of the commands being run. The systems administrator should truncate this file periodically. /usr/spool/cron/pid A file that cron uses to ensure that only one version of cron is currently running on the system. This file must be unique per system which is particularly important when you are setting up a sysplex. See the section in z/OS UNIX System Services Planning about customizing cron for a read-only file system. /usr/lib/cron/at.allow Contains a list of the users who can use the at command (one per line). /usr/lib/cron/at.deny Contains a list of the users who cannot use the at command (one per line). 180 z/OS V1R12.0 UNIX System Services Command Reference cron daemon /usr/lib/cron/cron.allow Contains a list of the users who can use the crontab command (one per line). /usr/lib/cron/cron.deny Contains a list of the users who cannot use the crontab command (one per line). /usr/lib/cron/queuedefs The queue description file (see the description of queuedefs in “queuedefs — Queue description for at, batch, and cron” on page 951). Related information at, crontab, mailx Appendix I, “Format of the TZ environment variable,” on page 961 also explains how to set the local time zone with the TZ environment variable. For more information about customizing cron, see the section on customizing the cron, uucp, and mail utilities for a read-only root file system in z/OS UNIX System Services Planning. Also see the section about customizing the cron and uucp utilities in z/OS UNIX System Services Planning. crontab — Schedule regular background jobs Format crontab [–e|–l|–r] [–u user] [file] Description crontab creates or changes your crontab entry. The crontab is a system facility that automatically runs a set of commands for you on a regular schedule. For example, you might set up your crontab entry so it runs a job every night at midnight, or once a week during low-use hours. This job could perform regular maintenance chores, for example, backing up files or getting rid of unnecessary work files. To set up a crontab entry, use: crontab file If you omit the file argument, crontab takes input from standard input (stdin). Requirement: In this mode, you must provide your entire crontab file. This replaces any other existing crontab entries. If you issue crontab with no options, do not enter the end-of-file character or you will end up with an empty crontab file. Press INTERRUPT instead. Input consists of six fields, separated by blanks. All blank lines and any input that contains a # as the first non-blank character are ignored. The first five give a date and time in the following form: v A minute, expressed as a number from 0 through 59 v v v v An hour, expressed as a number from 0 through 23 A day of the month, expressed as a number from 1 through 31 A month of the year, expressed as a number from 1 through 12 A day of the week, expressed as a number from 0 through 6 (with 0 standing for Sunday) Chapter 2. Shell command descriptions 181 crontab Requirement: Always use a system default time zone. Your system administrator can tell you what it is. The cron daemon does not use the value of the TZ environment variable when crontab is invoked. Any of these fields may contain an asterisk (*) standing for all possible values. For example, if you have an * as the day of the month, the job runs every day of the month. A field can also contain a set of numbers separated by commas, or a range of numbers, with the first number followed by a minus sign – followed by the second number. If you give specific days for both day of the month and day of the week, the two are ORed together. Here are some examples: 0 0 0 0 0 0 0 0 * * * * * 1-5 1,15 * * 1 * 5 ----- Midnight Midnight Midnight Midnight every day every weekday on 1st and 15th of month on 1st of month and every Friday The sixth field of a crontab entry is a string that your shell executes at the specified time. When the shell executes this string, it sets the HOME, LOGNAME, PATH, and SHELL environment variables to default values for you. If the string in your crontab entry contains percent characters %, the shell interprets them as newline characters, splitting your string in several logical lines. The first logical line (up to the first %) is interpreted as the command you want to execute; subsequent logical lines are used as standard input to the command. If any real (not logical) line in the file is blank or begins with #, the shell ignores the line (treats it as a comment). To obtain the output of the command in your crontab entry, redirect the standard output (stdout) and the standard error (stderr) into a file. If you do not do this, the system mails you the output from the command. at, batch, and crontab submit jobs to cron; the data for those jobs may contain double-byte characters. When the jobs are run, the data in the jobs are interpreted in the locale that cron is using. Because it is strongly recommended that cron be started in the POSIX locale, double-byte characters in the jobs may not be interpreted correctly. You can get around this by calling setlocale() in the job itself. Options –e Lets you edit your crontab entry. crontab invokes an editor to edit the entry. if you have an editor environment variable defined, crontab assumes that the variable's value is the name of the editor you want to use. if you do not have editor defined, crontab uses vi. if you do not have a crontab entry, crontab sets up a blank entry for you. when you exit from the editor, crontab uses the edited entry as your new entry. –l Displays your current crontab entry on stdout. –r Removes (deletes) your current crontab entry. –u user Uses the crontab entry of user. the user specified has to be the same username that the crontab entry was created under in /usr/spool/cron/crontabs. this requires the appropriate privileges. You can specify only one of the –e, –l, or –r options. 182 z/OS V1R12.0 UNIX System Services Command Reference crontab Environment variables crontab uses the following environment variables: EDITOR Specifies the editor that the –e option invokes. The default editor is vi. HOME Is set to your user ID's home directory (not necessarily the current value of HOME when the commands in your crontab entry are run. LOGNAME Is set to your user ID when the commands in your crontab entry are run. PATH Is set to a system-wide default value when the commands in your crontab entry are run. Is not used in time calculations. The cron daemon does, however, use this variable when cron is first started, typically when the system is started. TZ Localization crontab uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Returned if the command fails for any reason. In this case, crontab does not change your crontab entry. Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. The –u option is an extension to the POSIX standard. Related information at, batch, bg, cron Also see the queuedef file format description in Appendix H, “File formats,” on page 943. csplit — Split text files Format csplit [–Aaks] [–f prefix] [–n number] file arg arg ... Description csplit takes a text file as input and breaks up its contents into pieces, based on criteria given by the arg value on the command line. For example, you can use Chapter 2. Shell command descriptions 183 csplit csplit to break up a text file into chunks of ten lines each, then save each of those chunks in a separate file. See “Splitting criteria” for more information. If you specify – as the file argument, csplit uses the standard input (stdin). The files created by csplit normally have names of the form xxnumber where number is a 2-digit decimal number that begins at zero and increments by one for each new file that csplit creates. csplit also displays the size, in bytes, of each file that it creates. Options –A Uses uppercase letters in place of numbers in the number portion of created file names. This generates names of the form xxAA, xxAB, and so on. –a Uses lowercase letters in place of numbers in the number portion of created file names. This generates names of the form xxaa, xxab, and so on. –f prefix Specifies a prefix to use in place of the default xx when naming files. If it causes a file name longer than NAME_MAX bytes, an error occurs and csplit exits without creating any files. –k Leaves all created files intact. Normally, when an error occurs, csplit removes files that it has created. –n number Specifies the number of digits in the number portion of created file names. –s Suppresses the display of file sizes. Splitting criteria csplit processes the args on the command line sequentially. The first argument breaks off the first chunk of the file, the second argument breaks off the next chunk (beginning at the first line remaining in the file), and so on. Thus each chunk of the file begins with the first line remaining in the file and goes to the line given by the next arg. arg values can take any of the following forms: /regexp/ Takes the chunk as all the lines from the current line up to but not including the next line that contains a string matching the regular expression regexp. After csplit obtains the chunk and writes it to an output file, it sets the current line to the line that matched regexp. /regexp/offset Is the same as the previous criterion, except that the chunk goes up to but not including the line that is a given offset from the first line containing a string that matches regexp. The offset can be a positive or negative integer. After csplit has obtained the chunk and written it to an output file, it sets the current line to the line that matched regexp. Note: This current line is the first one that was not part of the chunk just written out. 184 z/OS V1R12.0 UNIX System Services Command Reference csplit %regexp% Is the same as /regexp/, except that csplit does not write the chunk to an output file. It simply skips over the chunk. %regexp%offset Is the same as /regexp/offset, except csplit does not write the chunk to an output file. linenumber Obtains a chunk beginning at the current line and going up to but not including the linenumberth line. After split writes the chunk to an output file, it sets the current line to linenumber. {number} Repeats the previous criterion number times. If it follows a regular expression criterion, it repeats the regular expression process number more times. If it follows a linenumber criterion, csplit splits the file every linenumber lines, number times, beginning at the current line. For example, csplit file 10 {10} obtains a chunk from line 1 to line 9, then every 10 lines after that, up to line 109. Errors occur if any criterion tries to "grab" lines beyond the end of the file, if a regular expression does not match any line between the current line and the end of the file, or if an offset refers to a position before the current line or past the end of the file. Localization csplit uses the following localization variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v csplit could not open the input or output files v A write error on the output file 2 Failure due to any of the following: v Unknown command-line option v The prefix name was missing after –f v The number of digits was missing after –n v The input file was not specified v No arg values were specified v The command ran out of memory v An arg was incorrect v The command found end-of-file before it was expected Chapter 2. Shell command descriptions 185 csplit v v v v v A regular expression in an arg was badly formed A line offset/number in an arg was badly formed A {number} repetition count was misplaced or badly formed Too many file names were generated when using –n Generated file names would be too long Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. The –A and –a options are extensions to the POSIX standard. Related information awk, sed For more information about regexp, see Appendix C, “Regular expressions (regexp),” on page 915. ctags — Create tag files for ex, more, and vi Format ctags [–aBFwx] [–f tagfile] sourcefile ... Description ctags creates a file named tags in the current directory. It summarizes the locations of various objects in the C source files named on the command line. All files with a .c or .h suffix are treated as C source files. For C source code, ctags summarizes function, macro and typedef definitions. See “tags — Format of the tags file” on page 952 for a description of the format of the tags file. The tags file is used by ex, more, and vi to support the tag command. The tag command can be used to edit the file containing a name in the tags file. For ex and vi, the command is: : tag name For more, the command is: :tname After these commands are run, the tags file is searched for name. If it is found, the file associated in the tags file with that name is loaded and the line containing the name is made the current line. Options 186 –a Appends output to the existing tags file rather than overwriting the file. –B Produces a tags file that searches backward from the current position to find the pattern matching the tag. –F Searches for tag patterns in the forward direction. This is the default. –f Generates a file named tagfile rather than the default tags file. z/OS V1R12.0 UNIX System Services Command Reference ctags –w Suppresses warning messages. –x Produces a report on the standard output. The report gives the definition name, the line number of where it appears in the file, the name of the file in which it appears, and the text of that line. ctags arranges this output in columns and sorts it in order by tag name according to the current locale's collation sequence. This option does not produce a tags file. Localization ctags uses the following localization environment variables: v LANG v LC_ALL v LC_COLLECT v LC_CTYPE v LC_MESSAGES v LC_TIME See Appendix F, “Localization” for more information. Files ctags uses the following file: Output tags file tags Usage notes 1. It can be difficult to recognize a function definition in C source code. Because ctags does not know which C preprocessor symbols are defined, there may be some misplaced function definition information if sections of code within #if...#endif are not complete blocks. 2. ctags invokes the sort internally. 3. ctags makes special provision for the main() function, which may occur in several C source files. The tags file contains an entry for the first main() routine found. For all occurrences of main(), including the first, the tags file contains an entry for Mname, where name is the name of the input source file, with the .c suffix and any leading pathname components removed. For example, a tags file created for a C source code file named foo.c would contain an entry for Mfoo, which represents the main() routine in foo.c). 4. ctags uses sort to sort the file by tag name, according to the POSIX locale's collation sequence. Exit values 0 Successful completion 1 Failure due to any of the following: v Unknown command-line option v Cannot create the output file v Cannot open the output file v One of the input files was unrecognized Portability POSIX.2, X/Open Portability Guide, 4.2BSD and higher. This utility only understands characters from the POSIX locale. Chapter 2. Shell command descriptions 187 ctags The –B, –F, and –w options are extensions to the POSIX and XPG standards. Related information more, sort, vi See the tags file format description in “tags — Format of the tags file” on page 952. cu — Call up another system (stub only) Format cu [–dehot] [–l device_name] [–s speed] [system_name | phone_num] cu –n [–dehot] [–l device_name] [–s speed] Note: The cu utility is fully supported for compatibility with older UNIX systems. However, because it is no longer supported by POSIX.2 IEEE standard 1003.2-1992, this utility should be avoided for applications intended to be portable to other UNIX-branded systems. Description cu connects to remote systems specified in the UUCP configuration file. You can use it for simple terminal connections, or to do simple file transfer with no error checking. cu is recognized, but its functions are disabled. Traditionally, it is used for simple terminal connections to remote systems specified in the UUCP configuration file. cu requires a direct connection (such as with a modem) to the remote system, but this is not supported by z/OS. cut — Cut out selected fields from each line of a file Format v cut –b list [–n] [file...] v cut –c list [file...] v cut –f list [–d char] [–s] [file...] Description cut reads input from files, each specified with the file argument, and selectively copies sections of the input lines to the standard output (stdout). If you do not specify any file, or if you specify a file named –, cut reads from standard input (stdin). Options –b list Invokes byte position mode. After this comes a list of the byte positions you want to display. This list may contain multiple byte positions, separated by commas (,) or blanks or ranges of positions separated by dashes (–). Since the list must be a single argument, shell quoting is necessary if you use blanks. You can combine these to allow selection of any byte positions of the input. Guideline: When using the –b option with double-byte characters, you should also specify the –n option to ensure that entire characters are 188 z/OS V1R12.0 UNIX System Services Command Reference cut displayed. If you do not specify the –n option, cut assumes that the low byte of a range is the first byte of a character and that the high byte of a range is the last byte of a double-byte character, possibility resulting in the misinterpretation of the characters represented by those byte positions. –c list Invokes character-position mode. After this comes a list of character positions to retain in the output. This list can contain many character positions, separated by commas (,) or blanks or ranges of positions separated by a dash (–). Since the list must be a single argument, shell quoting is necessary if you use blanks. You can combine these to allow selection of any character positions of the input. –d char Specifies char as the character that separates fields in the input data; by default, this is the horizontal tab. –f list Invokes field delimiter mode. After this comes a list of the fields you want to display. You specify ranges of fields and multiple field numbers in the same way you specify ranges of character positions and multiple character positions in –c mode. –n Does not split characters. If the low byte in a selected range is not the first byte of a character, cut extends the range downward to include the entire character; if the high byte in a selected range is not the last byte of a character, cut limits the range to include only the last entire character before the high byte selected. If –n is selected, cut does not list ranges that do not encompass an entire character, and these ranges do not cause an error. –s Does not display lines that do not contain a field separator character. Normally, cut displays lines that do not contain a field separator character in their entirety. Example cd /bin ls –al | cut –c 42–48,54–66 prints a directory listing containing file creation dates and filenames of files in the working directory. Localization cut uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Cannot open the input file v Out of memory Chapter 2. Shell command descriptions 189 cut 2 Failure due to any of the following: v An incorrect command-line argument v You did not specify any of –b, –c, or –f v You omitted the list argument v Badly formed list argument Portability POSIX.2, X/Open Portability Guide, UNIX System V. Related information paste, uname cxx — Compile C and C++ source code, link-edit and create an executable file See c89/xlc or man xlc. Note: When working in the shell, to view man page information about cxx, type: man c89 or man xlc. date — Display the date and time Format date [–cu ] [+format] Description date displays the operating system's idea of the current date and time. The following example shows the default format of the date: Wed Feb 26 14:01:43 EST 1986 Options date accepts the following options: –c Displays the date and displays the time according to Greenwich Mean Time (Coordinated Universal Time) using CUT as the time zone name. –u Displays the date and displays the time according to Greenwich Mean Time (Coordinated Universal Time) using GMT as the time zone name. If the argument to date begins with a + character, date uses format to display the date. date writes all characters in format, with the exception of the % and the character that immediately follows it, directly to the standard output. After date exhausts the format string, it outputs a newline character. The % character introduces a special format field similar to the printf() function in the C library. date supports the following field descriptors: 190 %A The full weekday name (for example, Sunday). %a The three-letter abbreviation for the weekday (for example, Sun). %B The full month name (for example, February). %b The three-letter abbreviation for the month name (for example, Feb). z/OS V1R12.0 UNIX System Services Command Reference date %C The first two digits of the year (00 to 99). %c The local representation of the date and time (see %D and %T). %D The date in the form mm/dd/yy. %d The two-digit day of the month as a number (01 to 31). %e The day of the month in a two-character, right-aligned, blank-filled field. %H The two-digit hour (00 to 23). %h The three-letter abbreviation for the month (for example, June). %I The hour in the 12-hour clock representation (01 to 12). %j The numeric day of the year (001 to 366). %M The minute (00 to 59). %m The month number (01 to 12). %n The newline character. %p The local equivalent of a.m. or p.m. %r The time in a.m.–p.m. notation (11:53:29 a.m.). %S The seconds (00 to 61). There is an allowance for two leap seconds. %T The time (14:53:29). %t A tab character. %U The week number in the year, with Sunday being the first day of the week (00 to 53). %W The week number in the year, with Monday being the first day of the week (00 to 53). %w The weekday number, with Sunday being 0. %X The local time representation (see %T). %x The local date representation (see %D). %Y The year. %y The two-digit year. %Z The time zone name (for example, EDT). %% A percent-sign character. The date command also supports the following modified field descriptors to indicate a different format as specified by the locale indicated by LC_TIME. If the current locale does not support a modified descriptor, date uses the unmodified field descriptor value. %EC The name of the base year (period) in the current locale's alternate representation. %Ec The current locale's alternate date and time representation. %Ex The current locale's alternate date representation. %EY The full alternate year representation. %Ey The offset from %EC (year only) in the current locale's alternate representation. Chapter 2. Shell command descriptions 191 date %Od The day of the month using the current locale's alternate numeric symbols. %Oe The day of the month using the current locale's alternate numeric symbols. %OH The hour (24-hour clock) using the current locale's alternate numeric symbols. %OI The hour (12-hour clock) using the current locale's alternate numeric symbols. %OM The minutes using the current locale's alternate numeric symbols. %Om The month using the current locale's alternate numeric symbols. %OS The seconds using the current locale's alternate numeric symbols. %OU The week number of the year (0–53) (with Sunday as the first day of the week) using the current locale's alternate numeric symbols. %OW The week number of the year (0–53) (with Monday as the first day of the week) using the current locale's alternate numeric symbols. %Ow The weekday as a number using the current locale's alternate numeric symbols (Sunday=0). %Oy The year (offset from %C) using the current locale's alternate numeric symbols. Example The command: date ’+%a %b %e %T %Z %Y’ produces the date in the default format—as shown at the start of this command description. Environment variable date uses the following environment variables: Gives the time zone for date to use when displaying the time. This is ignored if you specify either the –c or the –u option. TZ For information about setting the local time zone with the TZ environment variable, see Appendix I, “Format of the TZ environment variable,” on page 961. Localization date uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_TIME v NLSPATH See Appendix F, “Localization” for more information. Exit values 192 0 Successful completion >0 Failure due to any of the following: z/OS V1R12.0 UNIX System Services Command Reference date An incorrect command-line option Too many arguments on the command line A bad date conversion A formatted date that was too long You do not have permission to set the date v v v v v Messages Possible error messages include: Bad format character x A character following “%” in the format string was not in the list of field descriptors. No permission to set date The system has denied you the right to set the date. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –c option is an extension of the POSIX standard. Related information touch Appendix I, “Format of the TZ environment variable,” on page 961 also explains how to set the local time zone with the TZ environment variable. dbgld — Create a module map for debugging Format dbgld [option] ... file Description The compiler creates a .dbg file for each compilation unit if the DEBUG compiler option is specified. The path names of all of the .dbg files are then stored in the module, which is an executable file or a DLL. The dbgld command opens all of the .dbg files associated with the module and stores all of the functions, global variables, external types, and source files in a single module map file with a .mdbg extension. In addition, the contents of all of the .dbg files are packaged together into this same .mdbg file. The dbgld command only needs to be executed once after binding. Debuggers that support demand load can use the .mdbg file for faster access to debug information. For more information on using the module map to improve debugger performance, see z/OS Common Debug Architecture User's Guide. If the original source files are not available at debugging time (for example, the source files are moved into a different directory or the compilation and debugging are performed on different machines), you can add the source file contents to the .mdbg file before the source files are relocated. Because the source file contents cannot be captured into the .mdbg file by the dbgld command by default, you can Chapter 2. Shell command descriptions 193 dbgld specify the -c option when invoking the dbgld command. A debugger that supports captured source can then retrieve the source file contents from the .mdbg file. Options option -c Adds captured source file to the module map, which consists of all files that contain executable lines of code. -v Writes the version information to stderr. file Is the module name, which can be: v The absolute path name of a z/OS UNIX System Services file v The relative path name of a z/OS UNIX System Services file v A fully qualified MVS data set (PDS member) The output of the dbgld command is a file with the name of the module followed by a .mdbg extension. The file will always be written in the current directory. For example, if the module name is /mypath/mymodule, a file called mymodule.mdbg will be created in the current directory. If the file already exists, it will be overwritten. Restrictions The following restrictions apply to the use of dbgld: v The source files must be compiled with the DEBUG compiler option. v The name of a valid module must be passed into the dbgld utility. The module must be bound with the EDIT=YES binder option, which is the default. An error message will be generated if EDIT=NO. v The .dbg files associated with the module must exist in the directories where they were during compilation. Otherwise, they will not be added to the module map and no debug information will be available to the compilation units via the module map during debugging. An error message will be generated for each .dbg file that is not found. v Because the dbgld command always creates the .mdbg file in the current directory, the command must be run from a directory that has write permission. Examples The following example shows how to compile hello1.c and hello2.c and create a module map in a file called hello.mdbg. xlc -g hello1.c hello2.c -o hello dbgld hello The following example shows how to compile hello1.c and hello2.c and create a module map in a file called hello.mdbg which contains captured source. xlc -g hello1.c hello2.c -o hello dbgld -c hello The following example shows how to display the version information for the dbgld utility and the Common Debug Architecture run times when creating the module map. dbgld -v hello The output is: 194 z/OS V1R12.0 UNIX System Services Command Reference dbgld CDA0000I CDA0000I CDA0000I CDA0000I Utility(dbgld ) Level(level name) Library(elf ) Level(level name) Library(dwarf ) Level(level name) Library(ddpi ) Level(level name) If the -g option is missing during compilation, hello.mdbg will not be generated and a warning message will be printed, as shown in the following example: xlc hello1.c hello2.c -o hello dbgld hello The output is a warning message stating that no debug information was found in hello. Exit values The exit values for dblgd are: 0 Successful completion 4 Warning 8 Error 12 Severe error dbx — Use the debugger Format dbx [options] [executable-file [program-arguments ...]] dbx [options] [attach-type] process-id dbx [options] -C core-file Description dbx is a source-level debugger for z/OS UNIX System Services. It provides an environment to debug and run C and C++ programs, as well as performing machine level debug. You can carry out operations such as the following: v Examine object files v Run a program in a controlled environment v Set breakpoints at selected statements or run the program one line at a time v Debug using symbolic variables and display them in their correct format v View an MVS dump v Attach to a running program, and perform debugging operations. The executable-file argument is an load module produced by a compiler. To perform source-level debugging, you need to compile your executable with symbolic information. This is accomplished by specifying the –g or –Wc,debug compiler flags on the compiler command line. Note: If the object file is not compiled with the –g or –Wc,debug option on the c89/cc/c++ command, or if the user compiles with optimization, the capabilities of the dbx command will be reduced. The core-file argument is an MVS dump that exists as a file in the z/OS UNIX file system or in an MVS data set. dbx allows the end user to customize its behavior via two files that are processed during initialization. These are .dbxsetup . Each file can contain a list of dbx Chapter 2. Shell command descriptions 195 dbx subcommands that will be run before the dbx prompt is displayed. During startup, dbx will first search for these files in the current working directory and then in the user's $HOME directory. If a file is found, it is parsed and the search for that specific file terminates. Use a text editor to create a .dbxsetup or .dbxinit file. and .dbxinit Any subcommands in the .dbxsetup file are executed before the debug target program is loaded. This allows the user to tailor dbx's operational behavior during this phase of the dbx startup process. Any subcommands in the .dbxinit file are executed just before the dbx prompt is displayed. You can use the man command to view descriptions of dbx subcommands. To do this, you must prefix all subcommands with dbx. For example, to view a description of the dbx alias subcommand, you would enter the following: man dbxalias Attach-types –a ProcessID Attaches the debug program to a running process. The debug program becomes active as soon as the process wakes up. To attach the debug program, you need authority to use the kill command on this process. –A ProcessID Reattaches the debug program to a running process that is already being debugged by dbx. Use this option to reattach a child process that was created when a debugged parent process did a fork while multiprocess debugging mode was active. To reattach to the debug program, you need authority to use the kill command on this process. Options -b Suppresses processing of .dbxsetup and .dbxinit files (bare startup). –c script Runs dbx subcommands from a specified script file before reading from standard input. –C dump–filename Puts dbx in dump reading (core file) processing mode. –d Deprecated. This option will be ignored and remains only for compatibility purposes. –f Deprecated. This option will be ignored and remains only for compatibility purposes. –F Starts debug target in a different address space than the one dbx currently resides in; or starts dbx in its own address space when attaching to a running target program. –h Prints the dbx command syntax. –I directory Appends the given directory to the list of directories searched for source and debug files. The default list contains the working directory and the directory containing the object files. The search path can also be set with the use subcommand. –m dbxmode Instructs dbx to start in a specific mode: 196 z/OS V1R12.0 UNIX System Services Command Reference dbx v Specifying –m4 forces dbx to run in 31-bit mode, even on a machine capable of running it in 64-bit mode. v Specifying –m8 forces dbx to run in 64-bit mode. If this is impossible, dbx will terminate. -p ipaddress | name[:port] Tells dbx to open a socket and connect to the ipAddress:port or machineName:port which is assumed to be a GUI that supports remote debugging. For example: dbx -p 9.123.456.78:8001 mypgm. In this mode the command line prompt will not be displayed nor will the user be able to enter dbx subcommands through the command line interface. In addition, the following dbx subcommands are not supported when entered via a GUI debug console (command line) interface: detach, edit, multproc, object, quit, rerun, run, sh. If :port is not specified, port 8001 will be used as the default. –q Suppresses some of the dbx startup messages. Specifically, this will only print the dbx version information before the prompt is displayed. All other messages will be suppressed. Note that this option does not affect the verbosity of normal dbx operation. –r Runs the object file immediately. If it ends successfully, the dbx debug program is exited. Otherwise, the debug program is entered and the reason for termination is reported. Note: Unless –r is specified, the dbx command prompts the user and waits for a command. However, you can specify program arguments on and .dbxinit even when –r is not used. For example: dbx myprog arg1 arg2 arg3 –u Deprecated. This option will be ignored and remains only for compatibility purposes. Expression handling Specify expressions in dbx with a subset of C and Pascal syntax. A prefix * (asterisk) or a postfix ^ (circumflex) denotes indirection. Specify portions of an array by separating the lower and upper bounds with .. (two periods). Use [ ] (square brackets) or ( ) (parentheses) to enclose array subscripts. Use the field reference operator . (period) with pointers and records. Note: The field reference operator . (period) makes the C operator → unnecessary (although it is supported). When displaying variables and expressions, the dbx command resolves names first using the static scope of the current function. The dynamic scope is used if the name is not defined in the first scope. If static and dynamic searches do not yield a result, an arbitrary symbol is chosen and the system prints the message (using Module.Variable). The Module.Variable construction is the name of an identifier qualified with a block name. Override the name resolution procedure by qualifying an identifier with a block name. Source files are treated as modules named by the filename without the language suffix (such as the .c suffix on a C language program). The dbx command debug program checks types of expressions. Override types of expressions by using TypeName (Expression). When there is no corresponding Chapter 2. Shell command descriptions 197 dbx named type, use the &TypeName special construct to represent a pointer to the named type. Represent a pointer to enum, struct, or union tag with the $$TagName construct. A condition can be any dbx expression that evaluates to a true or false value. This pertains to four dbx subcommands: stop, stopi, trace, and tracei. The following operators are valid in expressions: Expression Operators exp (exponentiation) Algebraic + (addition), - (subtraction), * (multiplication), / (floating point division), div (integral division), mod (modulo division), exp (exponentiation) Bitwise ? (unary minus), ? (bitwise or), & (bitwise and), ? (bitwise xor), ~ (one’s complement), << (bitwise left shift), >> (bitwise right shift), bitand (bitwise and), xor (bitwise xor) Logical ?? (logical or), && (logical and), ! (logical not), or, and, not Comparison < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal to), <> (not equal to), != (not equal to), = (equal to), == (equal to) Other sizeof Files a.out The object file a.out is the default name of an executable file produced by the compiler. If no executable is specified on the dbx command line, then dbx will look for an a.out file to debug. .dbxinit Contains initial commands. .dbxsetup Contains initial commands. .dbxhistory Contains a listing of recently used dbx commands. Used by the history dbx subcommand. Examples 1. This example shows you how to attach dbx to a running process. To do this, it is useful to insert a sleep(30) call into the program to be debugged. This will give you enough time to issue the ps -Aef shell command to find the process ID of the program. Once you have the process ID, issue the shell command: dbx -a process-id. Before starting the server, set the following four environment variables: export _BPX_PTRACE_ATTACH=yes (tells the kernel to always load DLLs and executables into read/write storage) export _CEE_RUNOPTS="test(all)" (tells Language Environment to load the CEEEVDBG debugger exit and send dbx debug events) 198 z/OS V1R12.0 UNIX System Services Command Reference dbx export _CEE_DEBUG_FILENAME31=/bin/dbx31vdbg (the path to the Language Environment debugger exit for 31-bit programs) export _CEE_DEBUG_FILENAME64=/bin/dbx64vdbg (the path to the Language Environment debugger exit for 64-bit programs) Use dbx commands to set breakpoints, step through program statements, print variables, work with threads, examine storage, and actions as needed. 2. Example of creating .dbxinit file in your home directory: alias nsf "use /sandbox3/UNIX_notes/CGOOD/notes/nsf/" alias asc "set $asciichars ; set $asciistrings" alias ebc "unset $asciichars ; unset $asciistrings" set $repeat set $history_unique set $hold_next set $showbases 3. Sample dbx commands issued after starting server and seeing "sleeping for 30 seconds" message for server process ID 50331876: /sandbox3/UNIX_notes/CGOOD/notes/os> dbx -a 50331876 FDBX0278: Waiting to attach to process 50331876 ... FDBX0089: dbx for MVS. FDBX0399: Compiled: Sep 28 2001 10:22:24 GMT as BFP FDBX0400: OS level: 12.00 03, LE level: 4.1.2 with CWIs. FDBX0100: Type ’help’ for help. FDBX0099: reading symbolic information ... FDBX0900: reading symbols for /sandbox3/UNIX_notes/CGOOD/usr/lpp/lotus/notes/latest/os390/server ... FDBX0037: XPLink module found FDBX0900: reading symbols for /sandbox3/UNIX_notes/CGOOD/usr/lpp/lotus/notes/latest/os390/libnotes ... attached in sleep at 0xebcd024 ($t1) sleep() at 0xebcd024 unnamed block $b64, line 873 in "meminit.c" MemoryInit1(), line 873 in "meminit.c" OSInitExt() at 0x1000cdc4 ServerMain() at 0xf80ac38 main() at 0xf80a12e .() at 0xeeb2f4a .() at 0x6f8e976 0x0ebcd024 (+0xff3c3024) 47060003 nop X’3’($r6,) (dbx) stop at "meminit.c":875 [1] stop at "meminit.c":875 (dbx) c [1] stopped in unnamed block $b64 at line 875 in file "meminit.c" ($t1) (dbx) where unnamed block $b64, line 875 in "meminit.c" MemoryInit1(), line 875 in "meminit.c" OSInitExt() at 0x1000cdc4 ServerMain() at 0xf80ac38 main() at 0xf80a12e .() at 0xeeb2f4a .() at 0x6f8e976 (dbx) list 872,875 872 __printf_a("sleeping for 30 seconds time to dbx\n"); 873 sleep(30); 874 __printf_a("Done sleeping \n"); 875 if (loc_num_of_segs > MAX_NUM_OF_SEGM) (dbx) print loc_num_of_segs 4 (dbx) &loc_num_of_segs/8x 0fc55af8: 0000 0004 0000 01b0 0400 0000 0f9d 57f8 (dbx) 0xfc55af8/8x 0fc55af8: 0000 0004 0000 01b0 0400 0000 0f9d 57f8 (dbx) n Chapter 2. Shell command descriptions 199 dbx stopped in unnamed block $b64 at line 971 in file "meminit.c" ($t1) 971 DoAgain2: (dbx) n stopped in unnamed block $b64 at line 972 in file "meminit.c" ($t1) 972 hMMShMemId = shmget(ShmemAccessKey, FirstSegSize, IPC_CREAT|IPC_EXCL|loc_shm390flags|perms); Related information c89/cc/c++ dbx subcommands The following list of dbx subcommands can have their output redirected to a file. v alias v args v condition v dump v examine v list v listfiles v listfuncs v listi v map v mutex v onload v readwritelock v rerun v registers v run v sh v status v thread v whatis v where v whereis v which The following dbx subcommands will return an error message in GUI mode (-p). v detach v edit v multproc v object v quit v rerun v run v sh . ? subcommand for dbx: Search backward for a pattern Format ? [RegularExpression] 200 z/OS V1R12.0 UNIX System Services Command Reference dbx: ? Description The ? subcommand searches backward in the current source file for the pattern specified by the RegularExpression argument. Entering the ? subcommand with no arguments causes dbx to search backward for the previous regular expression. Usage notes The ? subcommand can be run only while the dbx debug program is running. Examples 1. To search backward in the current source file for the letter z, enter: ?z 2. To repeat the previous search, enter: ? Related information The / (search) subcommand. / subcommand for dbx: Search forward for a pattern Format / [RegularExpression] Description The / subcommand searches forward in the current source file for the pattern specified by the RegularExpression argument. Entering the / subcommand with no arguments causes dbx to search forward for the previous regular expression. Usage notes The / subcommand can be run only while the dbx debug program is running. Examples 1. To search forward in the current source file for the number 12, enter: / 12 2. To repeat the previous search, enter: / Related information The ? (search) subcommand. alias subcommand for dbx: Display and assign subcommand aliases Format alias [name] [string] Description The alias subcommand creates aliases for dbx subcommands. The name argument is the alias being created. The string argument is a series of dbx subcommands that, after the execution of this subcommand, can be referred to by name. If the alias subcommand is used without aliases, it displays all current aliases. Usage notes The alias subcommand can be run only while the dbx debug program is running. Chapter 2. Shell command descriptions 201 dbx: alias Examples 1. To set tracef1 to be an alias for trace in f1, enter: alias tracef1 "trace in f1" 2. To define a stopf alias with file and line arguments to allow shorthand for setting a breakpoint within a file, enter: alias stopf(file, line) "stop at \"file\":line" args subcommand for dbx: Display program arguments Format args Description The args subcommand displays the argument count and a list of arguments that are passed to the user's program when dbx starts debugging the program. Usage notes The args subcommand can be run only while the dbx debug program is running. Examples To display the current arguments, enter: args Related information The rerun and run subcommands. assign subcommand for dbx: Assign a value to a variable Format assign [variable=expression] Description The assign subcommand assigns the value specified by the expression argument to the variable specified by the variable argument. Usage notes 1. The assign subcommand can be run only while the dbx debug program is running. 2. Functions cannot be specified with the expression argument. Examples 1. To assign the value 5 to a variable x, enter: assign x = 5 2. To assign the value of a variable y to a variable x, enter: assign x = y 3. To assign a value to a storage location, enter: assign 0x02e0f7f0 = 0xff 4. To assign a value to a register, enter: assign $r7 = 123 5. To change the exit_status of a specific thread, enter: assign $t1.exit_status=&$void(0x2d95840); 202 z/OS V1R12.0 UNIX System Services Command Reference dbx: case case subcommand for dbx: Change how dbx interprets symbols Format case [default | mixed | lower | upper] Description The case subcommand changes how the dbx debug program interprets symbols. Use case if a symbol needs to be interpreted in a way not consistent with the default behavior. Entering case with no parameters displays the current case mode. Options default Varies with the current language. mixed Causes symbols to be interpreted as they actually appear. lower Causes symbols to be interpreted as lowercase. upper Causes symbols to be interpreted as uppercase. Usage notes The case subcommand can be run only while the dbx debug program is running. Examples 1. To instruct dbx to interpret symbols as they actually appear, enter: case mixed 2. To instruct dbx to interpret symbols as uppercase, enter: case upper catch subcommand for dbx: Start trapping a signal Format catch [signalnumber | signalname] Description The catch subcommand starts the trapping of a specified signal before that signal is sent to the application program. This subcommand is useful when the application program being debugged handles such signals as interrupts. The signal to be trapped can be specified by number or by name using either the signalnumber or the signalname argument, respectively. Signal names are case-insensitive, and the SIG prefix is optional. All signals are caught by default except the SIGDUMP, SIGHUP, SIGCHLD, SIGALRM, and SIGKILL signals. If no arguments are specified, the current list of signals to be caught is displayed. Usage notes The catch subcommand can be run only while the dbx debug program is running. Examples 1. To display a current list of signals to be caught by dbx, enter: catch 2. To trap signal SIGALRM, enter: catch SIGALRM Chapter 2. Shell command descriptions 203 dbx: catch or: catch ALRM or: catch 14 Related information The ignore subcommand. clear subcommand for dbx: Remove all stops at a given source line Format clear sourceline Description The clear subcommand removes all stops at a given source line. The sourceline argument can be specified in two formats: v As an integer v As a filename string followed by a : (colon) and an integer Usage notes The clear subcommand can be run only while the dbx debug program is running. Example To remove breakpoints set at line 19, enter: clear 19 Related information The cleari and delete subcommands. cleari subcommand for dbx: Remove all breakpoints at an address Format cleari address Description The cleari subcommand clears all the breakpoints at the address specified by the address argument. Usage notes The cleari subcommand can be run only while the dbx debug program is running. Examples 1. To remove a breakpoint set at address 0X100001B4, enter: cleari 0x100001b4 2. To remove a breakpoint set at the address of the main() procedure, enter: cleari &main Related information The clear and delete subcommands. 204 z/OS V1R12.0 UNIX System Services Command Reference dbx: condition condition subcommand for dbx: Display a list of active condition variables Format condition [number ...] condition wait condition nowait Description The condition subcommand displays a list of active condition variables for the application program. All active condition variables are listed unless you use the number parameter to specify the condition variables you want listed. You can also select condition variables with or without waiters by using the wait or nowait options. In order to capture the condition variables, dbx must be debugging your program before the condition variable is created. You must have coded your application in one of the following ways: v Add the following line at the top of the C program: #pragma runopts(TEST(ALL)) Or: v Code an assembler program, CEEUOPT, to invoke the CEEXOPT macro, which specifies TEST(ALL). For examples of how to code this program, see z/OS XL C/C++ Programming Guide . Usage notes The condition subcommand can be run only while the dbx debug program is running. Examples 1. To display all condition variables, enter: condition 2. To display condition variables number 1 and number 4, enter: condition 1 4 3. To display all condition variables with waiters, enter: condition wait 4. To display all condition variables without waiters, enter: condition nowait cont subcommand for dbx: Continue program execution Format cont [signalnumber | signalname] Description The cont subcommand continues the execution of the program from the current stopping point until either the program finishes, another breakpoint is reached, a signal is received that is trapped by the dbx command, or an event occurs (such as a fork, an exec, or a program abend). If a signal is specified, either by the number specified in the signalnumber argument or by the name specified in the signalname argument, the program continues as if that signal had been received by the focus thread. Chapter 2. Shell command descriptions 205 dbx: cont If a signal is not specified, the dbx debug program variable $sigblock is set, and a signal caused the debugged program to stop, then the program resumes execution. If a signal is not specified, the dbx debug program variable $sigblock is not set, and a signal caused the debugged program to stop, then typing in the cont command with no signal causes the program to continue as if it had received the original signal. Signal names are not case-sensitive, and the SIG prefix is optional. If no signal is specified, the program continues as if it had not been stopped. Usage notes The cont subcommand can be run only while the dbx debug program is running. Examples 1. To continue program execution from the current stopping point, enter: cont 2. To continue program execution as though it had received the signal SIGQUIT, enter: cont SIGQUIT Related information The step, next, goto, and skip subcommands. delete subcommand for dbx: Remove traces and stops Format delete [all | number...] Description The delete subcommand removes traces and stops from the program. You can specify the traces and stops to be removed through the number arguments, or you can remove all traces and stops by using the all option. To display the numbers associated by the dbx debug program with a trace or stop, use the status subcommand. Options all Removes all traces and stops. Usage notes The delete subcommand can be run only while the dbx debug program is running. Examples 1. To remove all traces and stops from the program, enter: delete all 2. To remove traces and stops for event number 4, enter: delete 4 Related information The status, clear, and cleari subcommands. 206 z/OS V1R12.0 UNIX System Services Command Reference dbx: detach detach subcommand for dbx: Continue program execution without dbx control Format detach [signalnumber | signalname] Description The detach subcommand continues the execution of a program from the current stopping point without control of dbx. If a signal is specified, either by the number specified in the signalnumber argument or by the name specified in the signalname argument, the program continues without dbx control as if that signal had been received by the focus thread. If the signal is not specified, the program continues with no signal and without dbx control. Signal names are not case-sensitive, and the SIG prefix is optional. If no signal is specified, the program continues without dbx control as if it had not been stopped. Usage notes v The detach subcommand can be run only while the dbx debug program is running. v The detach subcommand is not supported in GUI (socket) mode (-p). Examples 1. To continue program execution from the current stopping point without dbx in control, enter: detach 2. To continue program execution without dbx control as though it had received the signal SIGQUIT, enter: detach SIGQUIT Related information The cont subcommand. display memory subcommand for dbx: Display the contents of memory Format address, address/[mode] address/[count][mode] [b| Bd | Bf | Bq | c | d | D | f | g | h | i | I | ld | lo | lx | o | O | q | s | S | o | W | X] [>file] Description The display memory subcommand displays the contents of memory. The display starts at the first address, and terminates at either the second address or until count items are printed. If the address is ".", the address following the one most recently printed is used. The mode specifies how memory is to be printed; if it is omitted the previous mode specified is used. The initial mode is "X". v The range of memory displayed is controlled by specifying: Chapter 2. Shell command descriptions 207 dbx: display memory 208 –- Two address arguments, in which case all lines between those two addresses are displayed (address/address), or –- One address argument, where the display starts, and count, which determines the number of lines displayed from address (address/count). . Used in place of the first address argument, this displays from the point where you left off (see example 3 on page 209). v Symbolic addresses are specified by preceding the name with an & (ampersand). v Registers are denoted by "$rN", "$frN" or "$drN", where N is the number of the register. v Addresses may be expressions made up of other addresses and the operators +, -, and * indirection. v Any expression enclosed in parentheses is interpreted as an address. v The format in which the memory is displayed is controlled by the mode argument. The default for the mode argument is the current mode. The initial value of mode is X. The possible modes include: b Print a byte in octal Bf Print single precision real number in BFP Bg Print a double precision real number in BFP Bq Print a long double precision real number in BFP c Print a byte as a character C Print a wchar_t character d Print a short word in decimal D Print a long word in decimal Df Print single precision real number in DFP Dg Print a double precision real number in DFP Dq Print a long double precision real number in DFP f Print a single precision real number in HFP g Print a double precision real number in HFP h Print a byte in hexadecimal ha Print a byte in hexadecimal and ASCII he Print a byte in hexadecimal and EBCDIC i Print the machine instruction I Print a wint_t character ld Print a long long in signed decimal lo Print a long long in octal lu Print a long long in unsigned decimal lx Print a long long in hexadecimal o Print a short word in octal z/OS V1R12.0 UNIX System Services Command Reference dbx: display memory O Print a long word in octal q Print a long double precision real number in HFP s Print a string (terminated by a null byte) S Print a wchar_t string W Print a wint_t string x Print a short word in hexadecimal X Print a long word in hexadecimal Options >file Redirects output to the specified file. Usage notes The display memory subcommand can be run only while the dbx debug program is running. Examples 1. To display one long word of memory content in hexadecimal starting at the address 0X3FFFE460, enter: 0x3fffe460 / x 2. To display 2 bytes of memory content as characters starting at the address of variable y, enter: &y/2c 3. To display from the point where you left off, when using . (period) in place of one of the addresses, enter: 0x100 / 2 which displays 2 words starting at x’100’ followed by: . / 3 which displays 3 words starting at x’108’ Related information See also: cleari, gotoi, registers, stepi, nexti, tracei, and stopi commands. down subcommand for dbx: Move the current function down the stack Format down [count] Description The down subcommand moves the current function down the stack count number of levels. The current function is used for resolving names. The default for the count argument is 1. Usage note The down subcommand can be run only while the dbx debug program is running. Examples 1. To move one level down the stack, enter: down 2. To move three levels down the stack, enter: down 3 Chapter 2. Shell command descriptions 209 dbx: down Related information The up and where subcommands. dump subcommand for dbx: Display the names and values of variables in a procedure Format dump [procedure] [>file] Description The dump subcommand displays the names and values of all variables in the specified procedure. If the procedure argument is . (dot), all active variables are displayed. If the procedure argument is not specified, the current procedure is used. If the >file option is used, the output is redirected to the specified file. Options >file dump output to the specified file. Usage notes The dump subcommand can be run only while the dbx debug program is running. dump redirects output to the specified file. Examples 1. To display names and values of variables in the current procedure, enter: dump 2. To display names and values of variables in the add_count procedure, enter: dump add_count 3. To redirect names and values of variables in the current procedure to the var.list file, enter: dump > var.list edit subcommand for dbx: Invoke an editor Format edit [procedure | file] Description The edit subcommand invokes an editor on the specified file. The file can be specified through the file argument or through the procedure argument (in which case the editor is invoked on the file containing that procedure). If no file is specified, the editor is invoked on the current source file. The default editor is the ed editor. Override the default by resetting the EDITOR environment variable to the name of the desired editor. Usage notes v The edit subcommand can be run only while the dbx debug program is running. v The edit subcommand is not supported in GUI (socket) mode (-p). Examples 1. To invoke an editor on the current source file, enter: edit 2. To invoke an editor on the main.c file, enter: edit main.c 210 z/OS V1R12.0 UNIX System Services Command Reference dbx: edit 3. To invoke an editor on the file containing the do_count procedure, enter: edit do_count Related information The ed editor. The list subcommand for the dbx command. file subcommand for dbx: Change the current source file Format file [file] Description The file subcommand changes the current source file to the file specified by the file argument; it does not write to that file. If the file argument is not specified, the file subcommand displays the name of the current source file. Usage notes The file subcommand can be run only while the dbx debug program is running. Examples 1. To change the current source file to the main.c file, enter: file main.c 2. To display the name of the current source file, enter: file func subcommand for dbx: Change the current function Format func [procedure] Description The func subcommand changes the current function to the procedure or function specified by the procedure argument. If the procedure argument is not specified, the default current function is displayed. Changing the current function implicitly changes the current source file to the file containing the new function; the current scope used for name resolution is also changed. Usage notes The func subcommand can be run only while the dbx debug program is running. Examples 1. To change the current function to the do_count procedure, enter: func do_count 2. To display the name of the current function, enter: func goto subcommand for dbx: Run a specified source line Format goto sourceline Chapter 2. Shell command descriptions 211 dbx: goto Description The goto subcommand causes the specified source line to be run next. Typically, the source line must be in the same function as the current source line. To override this restriction, use the set subcommand with the $unsafegoto variable. Usage notes v The goto subcommand can be run only while the dbx debug program is running. v While dbx allows the changing of the next instruction to be run, unpredictable results might occur in the program being debugged. Whether the unpredictable results occur depends on where the program is currently stopped, the current state of the program, and where the program is to resume running. Example To change the next line to be executed to line 6, enter: goto 6 Related information The cont, gotoi, and set subcommands. gotoi subcommand for dbx: Change the program counter address Format gotoi address Description The gotoi subcommand changes the program counter address to the address specified by the address argument. Usage notes v The gotoi subcommand can be run only while the dbx debug program is running. v While dbx allows the changing of the next instruction to be run, unpredictable results might occur in the program being debugged. Whether the unpredictable results occur depends on where the program is currently stopped, the current state of the program, and where the program is to resume running. Example To change the program counter address to address 0X100002B4, enter: gotoi 0x100002b4 Related information The goto subcommand. help subcommand for dbx: Display a subcommand synopsis Format help [subcommand] [topic] Description The help subcommand displays a synopsis of common dbx subcommands. Usage notes The help subcommand can be run only while the dbx debug program is running. 212 z/OS V1R12.0 UNIX System Services Command Reference dbx: help Examples To obtain a synopsis of common dbx subcommands, enter one of the following: help help subcommand help topic The help subcommand with no arguments lists available dbx subcommands and topics. help subcommand, where subcommand is one of the dbx subcommands, displays a synopsis and brief description of the subcommand. help topic—where topic is execution, expression, files, machine, scope, usage, or variables—displays a synopsis and brief description of the topic. history subcommand for dbx: Display commands in a history list Format history Usage notes The history subcommand displays the commands in the history list. As each command is entered, it is appended to the history list. A mechanism for history substitution is provided through the exclamation (!) operator. The allowable forms are !! for a previous command, !n for the nth command, and !string for the previous command that starts with string. The number of commands retained and displayed is controlled by the dbx internal variable $historywindow. ignore subcommand for dbx: Stop trapping a signal Format ignore [signalnumber | signalname] Description The ignore subcommand stops the trapping of a specified signal before that signal is sent to the program. This subcommand is useful when the program being debugged handles such signals as interrupts. The signal to be trapped can be specified by: v Number, with the signalnumber argument v Name, with the signalname argument Signal names are not case-sensitive. The SIG prefix is optional. If neither the signalnumber nor the signalname argument is specified, all signals except the SIGDUMP, SIGHUP, SIGCHLD, SIGALRM, and SIGKILL signals are ignored by default. The dbx debug program cannot catch SIGKILL or SIGDUMP. If no arguments are specified, the list of currently ignored signals is displayed. Usage notes The ignore subcommand can be run only while the dbx debug program is running. Chapter 2. Shell command descriptions 213 dbx: ignore Examples To cause dbx to ignore alarm clock timeout signals sent to the program, enter: ignore sigalrm or: ignore alrm or: ignore 14 Related information The catch subcommand. list subcommand for dbx: Display lines of the current source file Format list [procedure | SourcelineExpression] [,SourcelineExpression] Description The list subcommand displays a specified number of lines in the source file. The number of lines displayed are specified in one of two ways: v By specifying a procedure using the procedure argument. In this case, the list subcommand displays lines before the first executable line of source in the specified procedure and until the list window is filled. v By specifying a starting and ending source line number using the SourcelineExpression argument. Use the current filename or source filename if specified. The SourcelineExpression argument should consist of a valid line number followed by an optional + or − and an integer. In addition, a SourcelineExpression of $ can be used to denote the current line number, and a SourcelineExpression of @ can be used to denote the next line number to be listed. All lines from the first line number specified to the second line number specified, inclusive, are then displayed, provided these lines fit in the list window. If the second source line is omitted, ten lines are printed, beginning with the line number specified in the SourcelineExpression argument. If the list subcommand is used without arguments, the default number of lines are printed, beginning with the current source line. The default is 10. To change the number of lines to list by default, set the special debug program variable, $listwindow, to the number of lines you want. Initially, $listwindow is set to 10. Usage notes The list subcommand can be run only while the dbx debug program is running. Examples 1. To list the lines 1 through 10 in the current file, enter: list 1,10 2. To list 10, or $listwindow, lines around the first executable line in the main procedure, enter: 214 z/OS V1R12.0 UNIX System Services Command Reference dbx: list list main 3. To list 11 lines around the current line, enter: list $-5,$+5 Related information The edit, listi, move, and set subcommands. listfiles subcommand for dbx: Display the list of source files Format listfiles [loadmap-index] Description The listfiles subcommand displays the list of files associated with each module in the load map. If the listfiles subcommand is used without arguments, the files for every module in the load map will be listed. Usage notes The listfiles subcommand can be run only while the dbx debug program is running. Examples 1. To list all files in all modules, enter: listfiles 2. To list the files only for module with index 0 in the loadmap, enter: listfiles 0 Related information The listfuncs and map subcommands. listfuncs subcommand for dbx: Display the list of functions Format listfuncs [filename] Description The listfuncs subcommand displays a list of functions associated with each file in the program. If the listfuncs subcommand is used without arguments, the function for every file in the program will be listed. Usage notes The listfuncs subcommand can be run only while the dbx debug program is running. Examples 1. To list all functions in all files, enter: listfuncs 2. To list the function only for file mypgm.c, enter: listfuncs mypgm.c Chapter 2. Shell command descriptions 215 dbx: listfuncs Related information The func subcommand. listi subcommand for dbx: List instructions from the program Format listi [procedure | at | sourceline | address ] [,address] Description The listi subcommand displays a specified set of instructions from the source file. The instructions displayed are specified by: v Providing the procedure argument, in which case the listi subcommand lists instructions from the beginning of procedure until the list window is filled. v Using the atsourceline option, in which case the listi subcommand displays instructions beginning at the specified source line and continuing until the list window is filled. v Specifying a beginning and ending address using the address arguments, in which case all instructions between the two addresses, inclusive, are displayed. If the listi subcommand is used without options or arguments, the next $listwindow instructions are displayed. To change the current size of the list window, use the set $listwindow=value subcommand. Options at sourceline Specifies a starting source line for the listing. Usage notes The listi subcommand can be run only while the dbx debug program is running. Examples 1. To list the next 10, or $listwindow, instructions, enter: listi 2. To list the machine instructions beginning at source line 10, enter: listi at 10 3. To list the instructions between addresses 0X10000400 and 0X10000420, enter: listi 0x10000400, 0x10000420 Related information The list and set subcommands. map subcommand for dbx: Display load characteristics Format map [>file] Description The map subcommand displays characteristics for each loaded portion of the program. This information includes the name, text origin, text length, text end, text subpool, data origin, data length, data subpool, and file descriptor for each loaded module. The data origin, data length, data subpool, and file descriptor do not contain meaningful information. 216 z/OS V1R12.0 UNIX System Services Command Reference dbx: map Options >file Redirects output to the specified file. Usage notes The map subcommand can be run only while the dbx debug program is running. Example To examine the characteristics of the loaded portions of the application, enter: map move subcommand for dbx: Display or change the next line to be shown with the list command Format move move sourceline move function Description The move subcommand changes the next line to be displayed to the line specified by the sourceline argument. This subcommand changes the value of the @ variable. The sourceline argument can either be a line number in the current file, or a function name. Omitting the sourceline argument will display the current line number. Usage notes The move subcommand can be run only while the dbx debug program is running. Example To change the next line to be listed to line 12, enter: move 12 To change the next line to be listed to be the function main, enter: move main To display the current line number, enter : move Related information The list subcommand. multproc subcommand for dbx: Enable or disable multiprocess debugging Format multproc multproc multproc multproc multproc [on] [off] [parent] [child] Chapter 2. Shell command descriptions 217 dbx: multproc Description The multproc subcommand alters the way dbx behaves when the process that is being debugged issues a fork() runtime call. By default, multiprocess debugging is disabled when dbx is started. If no options are specified, the multproc subcommand returns the current status of multiprocess debugging. Options on dbx will notify the user that a fork has occurred, provide the PID of the new child process, and follow the parent process. off dbx will ignore any forks that occur. parent dbx will notify the user that a fork has occurred and follow the parent process. child dbx will notify the user that a fork has occurred and follow the child process. Usage notes v The multproc subcommand can be run only while the dbx debug program is running. v The multproc subcommand is not supported in GUI (socket) mode (-p). Examples 1. To check the current status of multiprocess debugging, enter: multproc 2. To have dbx notify the user that the process being debugged has forked, enter: multproc on 3. To have dbx ignore all forks by the process being debugged, enter: multproc off Related information The fork() function. mutex subcommand for dbx: Display a list of active mutex objects Format mutex mutex mutex mutex mutex [number ...] lock unlock wait nowait Description The mutex subcommand displays a list of active mutex objects for the application program. All active mutex objects are listed unless you use the number parameter to specify the mutex objects you want listed. You can also select only locked or unlocked mutexes, or mutexes with or without waiters, by using the lock, unlock, wait, or nowait options. In order to capture the mutex variables, dbx must be debugging your program before the mutex variable is created. You must have coded your application in one of the following ways: v Add the following line at the top of the C program: 218 z/OS V1R12.0 UNIX System Services Command Reference dbx: mutex #pragma runopts(TEST(ALL)) Or: v Code an assembler program, CEEUOPT, to invoke the CEEXOPT macro, which specifies TEST(ALL). For examples of how to code this program, see z/OS XL C/C++ Programming Guide. Usage notes The mutex subcommand can be run only while the dbx debug program is running. Examples 1. To display all mutex objects, enter: mutex 2. To display mutex objects number 1 and number 4, enter: mutex 1 4 3. To display all locked mutex objects, enter: mutex lock 4. To display all unlocked mutex objects, enter: mutex unlock 5. To display all mutex objects with waiters, enter: mutex wait 6. To display all mutex objects without waiters, enter: mutex nowait next subcommand for dbx: Run the program up to the next source line Format next [number] Description The next subcommand runs the application program up to the next source line. The number argument specifies the number of times the next subcommand runs. If the number argument is not specified, next runs once only. Usage notes 1. The next subcommand can be run only while the dbx debug program is running. 2. If the $hold_next variable is defined, dbx holds all threads except the focus thread during a next subcommand. Then dbx unholds the threads after the next subcommand finishes. Examples 1. To continue execution up to the next source line, enter: next 2. To continue execution up to the third source line following the current source line, enter: next 3 Related information The cont, goto, nexti, and step subcommands. Chapter 2. Shell command descriptions 219 dbx: nexti nexti subcommand for dbx: Run the program up to the next machine instruction Format nexti [number] Description The nexti subcommand runs the application program up to the next instruction. The number argument specifies the number of times the nexti subcommand is to be run. If the number argument is not specified, nexti runs only once. Usage notes 1. The nexti subcommand can be run only while the dbx debug program is running. 2. If the $hold_next variable is defined, dbx holds all threads except the focus thread during a nexti subcommand. Then dbx unholds the threads after the nexti subcommand finishes. Examples 1. To continue execution up to the next machine instruction, enter: nexti 2. To continue execution up to the third machine instruction following the current machine instruction, enter: nexti 3 Related information The gotoi, next, and stepi subcommands. object subcommand for dbx: Load an object file Format object filename Description The object subcommand loads the specified object file for execution, without the overhead of reloading dbx. Usage notes v The object subcommand can be run only while the dbx debug program is running. v The object subcommand is not supported in GUI (socket) mode (-p). Example To complete debugging of the current program, and to start debugging a new program without reloading dbx, enter: object myprog onload subcommand for dbx: Evaluate stop/trace after DLL load Format onload delete [all | number ...] onload list onload stop at sourceline 220 z/OS V1R12.0 UNIX System Services Command Reference dbx: onload onload stop in procedure onload trace at sourceline onload trace in procedure Description The onload subcommand defers building of stop or trace events until the procedure or sourceline is defined in the program dbx is debugging. dbx will evaluate the onload list after a DLL is loaded and generate stop/trace events if the procedure or sourcefile is now known to dbx after symbolics for the DLL are processed. If the procedure or sourceline is already known to dbx, then a normal stop or trace event will be generated and no event will be added to the onload list. Usage notes The onload subcommand can be run only while the dbx debug program is running. Examples To defer the building of a stop or trace event, enter: onload onload onload onload onload onload onload onload stop in myfunc stop in myclass::memfunc stop in myclassvar.memfunc stop at "mypgm.c":52 trace in myfunc trace in myclass::memfunc trace in myclassvar.memfunc trace in "mypgm.c":52 Related information The stop and trace subcommands. plugin subcommand for dbx: Pass the specified command to the plug-in parameter Format plugin[name[command]] Description The plugin subcommand passes the command specified by the command parameter to the plug-in specified by the name parameter. If no parameters are specified, the names of all available plug-ins are displayed. Usage notes The plugin subcommand can be run only while the dbx debug program is running. Examples 1. To list all available plug-ins, enter: plugin 2. To invoke the subcommand help of a plug-in named sample, enter: plugin sample help 3. To invoke the subcommand interpret 0x12345678of a plug-in named xyz, enter: plugin xyz interpret 0x12345678 See the pluginload subcommand and also the topic on Developing for dbx Plug-in Framework in z/OS UNIX System Services Programming Tools. Chapter 2. Shell command descriptions 221 dbx: pluginload pluginload subcommand for dbx: Load the specified plug-in Format pluginload file Description The pluginload subcommand loads the plug-in specified by the file parameter. The file parameter should specify a path to the plug-in. Usage notes The pluginload subcommand can be run only while the dbx debug program is running. Examples 1. To load the plug-in named sample located at /home/user/dbx_plugins/ libdbx_sample.dll, enter: pluginload /home/user/dbx_plugins/libdbx_sample.dll See the pluginload subcommand and also the topic on developing for the dbx plug-in framework in z/OS UNIX System Services Programming Tools. pluginunload subcommand for dbx: Unload the specified plug-in Format pluginunload name Description The pluginunload subcommand unloads the plug-in specified by the name parameter. The name parameter should specify a name of plug-in that is currently loaded. Usage notes The pluginunload subcommand can be run only while the dbx program is running. Examples 1. To unload the plug-in named sample, enter: pluginunload sample See the plugin subcommand and the pluginload subcommand. Also see the topic on developing for the dbx plug-in framework in z/OS UNIX System Services Programming Tools. print subcommand for dbx: Print the value of an expression Format print [expression,... ] [(parameters)] Description The print subcommand prints the value of a list of expressions, specified by the expression arguments. Usage notes The print subcommand can be run only while the dbx debug program is running. 222 z/OS V1R12.0 UNIX System Services Command Reference dbx: print Examples 1. To display the value of x and the value of y shifted left 2 bits, enter: print x, y << 2 2. To display a specific condition variable, enter: print $c1 3. To display the number of waiters for a specific mutex object, enter: print $m1.num_wait 4. To display the exit value of a specific thread, enter: print $t1.exit_status Related information The assign and set subcommands. prompt subcommand for dbx: Change the dbx command prompt Format prompt [“string”] Description The prompt subcommand changes the dbx command prompt to the string specified by the string argument. Usage notes The prompt subcommand can be run only while the dbx debug program is running. Example To change the prompt to dbx>, enter: prompt "dbx>" quit subcommand for dbx: End the dbx debugging session Format quit Description The quit subcommand ends the dbx debugging session. Usage notes v The quit subcommand can be run only while the dbx debug program is running. v The quit subcommand is not supported in GUI (socket) mode (-p). Example To exit the dbx debug program, enter: quit Chapter 2. Shell command descriptions 223 dbx: readwritelock readwritelock subcommand for dbx: Display a list of active read/write lock objects Format readwritelock [number ...] readwritelock lock readwritelock unlock readwritelock holder readwrite noholder Description The readwritelock subcommand displays a list of active read/write lock objects for the application program. All active read/write lock objects are listed unless you use the number parameter to specify the read/write lock objects you want listed. You can also select only locked or unlocked read/write locks, or read/write locks with or without holders, by using the lock, unlock, holder, or noholder options. In order to capture the read/write lock variables, dbx must be debugging your program before the read/write lock variable is created. You must have coded your application in one of the following ways: v Add the following line at the top of the C program: #pragma runopts(TEST(ALL)) Or: v Code an assembler program, CEEUOPT, to invoke the CEEXOPT macro, which specifies TEST(ALL). For examples of how to code this program, see z/OS XL C/C++ Programming Guide . Or: v Specify test(all) in the _CEE_RUNOPTS environment variable: export _CEE_RUNOPTS="test(all)" Usage notes The readwritelock subcommand can be run only while the dbx debug program is running. Examples 1. To display all read/write lock objects, enter: readwritelock 2. To display read/write lock objects number 1 and number 4, enter: readwritelock 1 4 3. To display all locked read/write lock objects, enter: readwritelock lock 4. To display all unlocked read/write lock objects, enter: readwritelock unlock 5. To display all read/write lock objects with holders, enter: readwritelock holder 6. To display all read/write lock objects without holders, enter: mutex noholders 224 z/OS V1R12.0 UNIX System Services Command Reference dbx: record record subcommand for dbx: Append user's commands to a file Format record filename Description The record subcommand appends the user's command lines to the specified file until a record command is entered with no parameters. The record subcommand is started by specifying a file name on the record command. A second record command with no parameters will stop the current record process and close the file. Usage notes The record subcommand can be run only while the dbx debug program is running. Examples 1. To start recording the dbx commands to file /tmp/mycmds, enter: record /tmp/mycmds 2. To stop the previous recording to file /tmp/mycmds, enter: record Related information The source subcommand. registers subcommand for dbx: Display the value of registers Format registers [>file] Description The registers subcommand displays the values of general-purpose registers, system control registers, floating-point registers, and the current instruction register, such as the program status word (PSW) for z/OS. v General-purpose registers are denoted by the $rnumber variable, where the number argument indicates the number of the register. v Floating-point registers are denoted by the $frnumber variable. By default, the floating-point registers are not displayed. To display the floating-point registers, use the unset $noflregs dbx subcommand. Options >file Redirects output to the specified file. Usage notes The registers subcommand can be run only while the dbx debug program is running. Example To display the registers, enter: registers Chapter 2. Shell command descriptions 225 dbx: registers Related information The set and unset subcommands. rerun subcommand for dbx: Begin running a program with the previous arguments Format rerun [arguments] [<file | >file | 2>file | >>file | 2>file | >&file | >>&file] Description The rerun subcommand begins execution of the object file. The values specified with the arguments argument are passed as command-line arguments. If the arguments argument is not specified, the arguments from the last run or rerun subcommand are reused. Options <file Redirects input so that input is received from file. >file Redirects output to file. 2>file Redirects standard error to file. >>file Appends redirected output to file. 2>>file Appends redirected standard error to file. >&file Redirects output and standard error to file. >>&file Appends output and standard error to file. Usage notes v The rerun subcommand can be run only while the dbx debug program is running. v The rerun subcommand is not supported in GUI (socket) mode (-p). Example To rerun the program with the previously entered arguments, enter: rerun Related information The run subcommand. return subcommand for dbx: Continue running a program until a return is reached Format return [procedure] Description The return subcommand causes the program to run until a return to the procedure specified by the procedure argument is reached. If the procedure argument is not specified, execution ceases when the current procedure returns. Usage notes The return subcommand can be run only while the dbx debug program is running. 226 z/OS V1R12.0 UNIX System Services Command Reference dbx: return Examples 1. To continue execution to the calling routine, enter: return 2. To continue execution to the main routine, enter. return main run subcommand for dbx: Run a program Format run [arguments] [<file | >file | 2>file | >>file | 2>file | >&file | >>&file] Description The run subcommand begins execution of the object file. The values specified with the arguments argument are passed as command-line arguments. Options <file Redirects input so that input is received from file. >file Redirects output to file. 2>file Redirects standard error to file. >>file Appends redirected output to file. 2>>file Appends redirected standard error to file. >&file Redirects output and standard error to file. >>&file Appends output and standard error to file. Usage notes v The run subcommand can be run only while the dbx debug program is running. v The run subcommand is not supported in GUI (socket) mode (-p). Example To run the application with the arguments blue and 12, enter: run blue 12 Related information The rerun subcommand. set subcommand for dbx: Define a value for a dbx variable Format set [variable=expression] Description The set subcommand defines a value, which is specified by the expression argument, for the dbx debug program variable, which is specified by the variable argument. The name of the variable must not conflict with names in the program being debugged. A variable is expanded to the corresponding expression within other commands. If the set subcommand is used without arguments, the variables currently set are displayed. Variables The following variables are set with the set subcommand: Chapter 2. Shell command descriptions 227 dbx: set $asciichars Any dbx operation that displays the value of a character will interpret the binary representation of the character as ASCII. $asciistrings Any dbx operation that displays the value of a string will interpret the binary representation of the string as ASCII. $c<n> Condition variables $catchbp Catches breakpoints during the execution of the next command. $charset Converts character strings before displaying them. The character strings are converted from the code page srcCodePage to destCodePage. The destCodePage must be IBM-1047. The default setting is not to convert the character strings. $commandedit Enables the command line facility. $current Defined as a constant with the value of the focus thread. $cv_events Notifies the user but does not stop when a condition variable event is processed. The following trace information is sent to the user for the different events: (dbx) cont . . cv initialize, object=0x2e04567 cv wait, object=0x2e04567, mutex=0x2d04567, thid=0x0102030405060708 cv unwait, object=0x2e04567, mutex=0x2d04567, thid=0x0102030405060708 cv destroy, object=0x2e04567 . . $dll_loads Set by default. When set, dbx processes symbolics for DLLs as they are loaded. $dll_loadstop Set by default. When set, dbx stops the function call that caused the DLL to be loaded. If the DLL was loaded due to a variable reference or an explicit load, dbx stops at the source line that caused the DLL to be loaded. $expandunions Displays values of each part of variant records or unions. $expressionexhaustivesearch Searches all scopes in a user's program to determine and verify the scope for an expression. Selecting this option might degrade performance. $flprecision Determines the precision in bytes of floating-point registers when the values of the register are displayed; for example, in expressions or during assignment. Valid values are 4, 8 or 16. $fr<n> Hexadecimal floating-point register. 228 z/OS V1R12.0 UNIX System Services Command Reference dbx: set $frb<n> Binary floating-point register $frd<n> Decimal floating-point register $hexchars Prints characters in hexadecimal format. $hexin Input is interpreted in hexadecimal format. Restriction: The $hexin variable is only supported in dbx command-line mode and does not affect the interpretation of GUI input. If the user of the GUI debugger wants input to be interpreted in hexadecimal format, the input must be prefixed with “0x”. $hexints Prints integers in decimal format instead of hexadecimal format. $historypage Specifies the number of history items to be traversed when using the page up and page down keys. $history_unique Prevents consecutive duplicate commands from being saved to the history list. $historywindow Specifies the number of commands to display and retain in the history list. $hold_next Automatically holds all threads except the focus thread during the next, nexti, step, or stepi command execution. If not set, all threads resume execution and may reach the breakpoint set by the next, nexti, step, or stepi command execution. $l<n> Read/write locks variables. $listwindow Specifies the number of lines to list around a function and to list when the list subcommand is used without parameters. $lv_events When set, dbx notifies the user but does not stop when a read/write lock object event is processed. The following trace information is sent to the user for the different events: (dbx) cont . . lv initialize, object=0x2d04567 lv wait, object=0x2d04567, thid=0x0102030405060708 lv unwait, object=0x2d04567, thid=0x0102030405060708 lv lock, object=0x2d04567, thid=0x0102030405060708 lv unlock, object=0x2d04567, thid=0x0102030405060708 lv relock, object=0x2d04567, thid=0x0102030405060708 lv unrelock, object=0x2d04567, thid=0x0102030405060708 lv destroy, object=0x2d04567 . . $m<n> Specifies mutex variables. Chapter 2. Shell command descriptions 229 dbx: set $maxstring Specifies the maximum number of characters to be displayed when printing a string. String printing stops when $maxstring characters are printed. Set to zero to completely display strings. The default value is zero. $mv_events When set, dbx notifies the user but does not stop when a mutex object event is processed. The following trace information is sent to the user for the different events: (dbx) cont . . mv initialize, object=0x2d04567 mv wait, object=0x2d04567, thid=0x0102030405060708 mv unwait, object=0x2d04567, thid=0x0102030405060708 mv lock, object=0x2d04567, thid=0x0102030405060708 mv unlock, object=0x2d04567, thid=0x0102030405060708 mv relock, object=0x2d04567, thid=0x0102030405060708 mv unrelock, object=0x2d04567, thid=0x0102030405060708 mv destroy, object=0x2d04567 . . $noargs Omits arguments from subcommands, such as where, up, down, and dump. $noflbregs Does not display the binary floating point representation of the floating point registers with the registers subcommand. $nofldregs Does not display the decimal floating point representation of the floating point registers with the registers subcommand. $noflregs Does not display the hexadecimal floating point representation of the floating point registers with the registers subcommand. $octin Interprets input in octal format. The $octin variable is only supported in dbx command-line mode and does not affect the interpretation of GUI input. If the user of the GUI debugger wants input to be interpreted in octal format, the input must be prefixed with “0”. $octints Prints integers in octal format. $pc Program counter register. $psw First word of the program status word register. $psw0 First word of the program status word register. $psw1 Second word of the program status word register. $r<n> General register. $r_precision Sets the amount of precision, in bytes, to use when displaying an integer value. Possible values are 4 and 8. $repeat Repeats the previous command if no command was entered. 230 z/OS V1R12.0 UNIX System Services Command Reference dbx: set $showbases Displays the base class data when a derived class is printed. $sigblock Blocks all signals from reaching the program being debugged. $sticky_debug When set, dbx will recognize sticky bit programs and DLLs in the loadmap. $t<n> Thread variables $tv_events Notifies the user but does not stop when a thread object event is processed. Trace information similar to the following example is sent to the user for the different events: (dbx) cont . . IPT create, thid=0x1234567890123456, stack=5200 IPT exit, thid=0x1234567890123456 tv create, thid=0x1234567890123456, created thid=0x1234567890123422, stack=5200 tv created, thid=0x1234567890123456, stack=5200 tv exit, thid=0x1234567890123456 tv wait, thid=0x1234567890123456, joining thid=0x1234567890123422 tv unwait, thid=0x1234567890123456, joined thid=0x1234567890123422 $unsafeassign Turns off strict type checking between the two sides of an assign subcommand. $unsafebounds Turns off subscript checking on arrays. $unsafegoto Turns off the goto subcommand destination checking. Usage notes 1. The $unsafe variables limit the usefulness of the dbx debug program in detecting errors. 2. The set subcommand can be run only while the dbx debug program is running. Examples 1. To change the default number of lines to be listed to 20, enter: set $listwindow=20 2. To disable type checking on the assign subcommand, enter: set $unsafeassign Related information The unset subcommand. sh subcommand for dbx: Pass a command to the shell for execution Format sh [command] Chapter 2. Shell command descriptions 231 dbx: sh Description The sh subcommand passes the command specified by the command parameter to the shell for execution. The SHELL environment variable determines which shell is used. The default is the sh shell. If no argument is specified, control is transferred to the shell. Usage notes v The sh subcommand can be run only while the dbx debug program is running. v The sh subcommand is not supported in GUI (socket) mode (-p). Examples 1. To run the ls command, enter: sh ls 2. To escape to a shell, enter: sh skip subcommand for dbx: Continue from the current stopping point Format skip [number] Description The skip subcommand continues execution of the application program from the current stopping point. A number of breakpoints equal to the value of the number argument are skipped, and execution then ceases when the next breakpoint is reached or when the program finishes. If the number argument is not specified, it defaults to a value of 1. Usage notes The skip subcommand can be run only while the dbx debug program is running. Example To continue execution until the second breakpoint is encountered, enter: skip 1 Related information The cont subcommand. source subcommand for dbx: Read subcommands from a file Format source file Description The source subcommand reads dbx subcommands from the file specified by the file argument. Usage notes The source subcommand can be run only while the dbx debug program is running. 232 z/OS V1R12.0 UNIX System Services Command Reference dbx: source Example To read the dbx subcommands in the cmdfile file, enter: source cmdfile status subcommand for dbx: Display the active trace and stop subcommands Format status [>file] Description The status subcommand displays the trace and stop subcommands currently active. The > option sends the output of the status subcommand to a file specified in the file argument. Options >file Redirects output to file. Usage notes The status subcommand can be run only while the dbx debug program is running. Examples 1. To display the currently active trace and stop subcommands, enter: status 2. To stop at line 52 only when thread $t2 reaches that line, enter: stop at 52 if $t2==$current Related information The clear, delete, stop, and trace subcommands. step subcommand for dbx: Run one or more source lines Format step [number] Description The step subcommand runs source lines of the program. Specify the number of lines to be run with the number argument. If the number argument is omitted, it defaults to a value of 1. Usage notes 1. The step subcommand can be run only while the dbx debug program is running. 2. If the $hold_next variable is defined, dbx holds all threads except the focus thread during a step subcommand. Then dbx unholds the threads after the step subcommand finishes. Examples 1. To continue execution for one source line, enter: step 2. To continue execution for five source lines, enter: step 5 Chapter 2. Shell command descriptions 233 dbx: step Related information The cont, goto, next, and stepi subcommands. stepi subcommand for dbx: Run one or more machine instructions Format stepi [number] Description The stepi subcommand runs instructions of the program. Specify the number of instructions to be run in the number argument. If the number argument is omitted, it defaults to 1. Usage notes 1. The stepi subcommand can be run only while the dbx debug program is running. 2. If the $hold_next variable is defined, dbx holds all threads except the focus thread during a stepi subcommand. Then dbx unholds the threads after the stepi subcommand finishes. Examples 1. To continue execution for one machine instruction, enter: stepi 2. To continue execution for five machine instructions, enter: stepi 5 Related information The gotoi, nexti, and step subcommands. stop subcommand for dbx: Stop execution of a program Format stop stop stop stop if condition [variable] at ["filename":]sourceline [if condition] [variable] in procedure [if condition] variable [if condition] Description The stop subcommand stops execution of the program when certain conditions are fulfilled. The program is stopped when: v The condition is true, if the if condition option is used. v The sourceline line number is reached, if the at sourceline option is used. v The procedure is called, if the in procedure option is used. v The variable is changed, if the variable argument is specified. The dbx debug program associates event numbers with each stop subcommand. To view these numbers, use the status subcommand. To turn stop off, use the delete or clear subcommand. Options at ["filename":]sourceline Specifies the source line number in either the specified filename or the file 234 z/OS V1R12.0 UNIX System Services Command Reference dbx: stop that is currently being debugged. If a specific file name is specified, the filename must be enclosed with quotation marks and a colon must separate the "filename" from the sourceline. For example: stop at "myfile":1234 if condition Specifies the condition, such as true. in procedure Specifies the procedure to be called. Usage notes The stop subcommand can be run only while the dbx debug program is running. Examples 1. To stop execution at the first executable statement in the main procedure, enter: stop in main 2. To stop execution when the value of the x variable is changed on line 12 of the execution, enter: stop x at 12 3. To stop execution at a specified line (line 23), when the value of the variable (myvar) is greater than 2, enter: stop at 23 if myvar > 2 4. To stop at line 52 only when thread $t2 reaches that line, enter: stop at 42 if $t2==$current Related information The stopi, delete, clear, and trace subcommands. stopi subcommand for dbx: Stop at a specified location Format stopi address [if condition] stopi [address] at address [if condition] stopi [address] in procedure [if condition] Description The stopi subcommand sets a stop at the specified location. v With the ifcondition option, the program stops when the condition is true. v With the address argument, the program stops when the contents of address change. v With the ataddress option, a stop is set at the specified address. v With the inprocedure option, the program stops when the procedure specified with the procedure argument is called. Options ifcondition Specifies the condition, such as true. inprocedure Specifies the procedure to be called. ataddress Specifies the machine instruction address. Chapter 2. Shell command descriptions 235 dbx: stopi Usage notes The stopi subcommand can be run only while the dbx debug program is running. Examples 1. To stop execution at address 0X100020F0, enter: stopi at 0x100020f0 2. To stop execution when the contents of address 0X100020F0 change, enter: stopi 0x100020f0 3. To stop at address 0x2d04567 only when thread $t2 reaches that address, enter: stopi at 0x2d04567 if $t2=$current Related information The stop subcommand. thread subcommand for dbx: Display a list of active threads Format thread thread thread thread thread thread thread thread thread [number ...] hold [number ...] unhold [number ...] info [number ...] current [number ...] activ async dead pcanc Description The thread subcommand displays a list of active threads for the application program. All active threads are listed unless you use the number parameter to specify the threads you want listed. You can also select threads by their states using the activ, async, dead, or pcanc options. You can use the info option to display full information about a thread, and threads can be held or unheld with the hold or unhold options. The focus thread is defaulted to the running thread; dbx uses it as the context for normal dbx subcommands such as register. You can use the current option to switch the dbx focus thread. Examples 1. To display all thread objects, enter: thread 2. To display thread objects number 1 and 2, enter: thread 1 2 3. To display all active threads, enter: thread activ 4. To display all threads in dead state, enter: thread dead 5. To display all threads in async state (that is, threads with a cancelability type of PTHREAD_INTR_ASYNCHRONOUS) that are waiting to be scheduled), enter: thread async 236 z/OS V1R12.0 UNIX System Services Command Reference dbx: thread Because this thread was created with the PTATASYNCHRONOUS attribute and the limit was reached, this thread was queued for execution. For example, if the thread limit is set to ten and there are 12 threads, two of them will be shown as async for the dbx thread command. 6. To display all threads in pcanc state (that is, threads that have been requested to be canceled by pthread_cancel(), enter: thread pcanc 7. To hold all threads, enter: thread hold 8. To hold thread number 1 and 4, enter: thread hold 1 4 9. To unhold thread number 1 and 4, enter: thread unhold 1 4 10. To display the focus thread, enter: thread current 11. To set the focus thread to thread number 1, enter: thread current 1 12. To get information about thread number 3, enter: thread info 3 trace subcommand for dbx: Print tracing information Format trace trace trace trace trace trace [if condition] procedure [if condition] [variable] at sourceline [if condition] [variable] in procedure [if condition] sourceline [if condition] expression at sourceline [if condition] Description The trace subcommand prints tracing information for the specified procedure, function, source line, expression, or variable when the program runs. A condition can be specified. The dbx debug program associates a number with each trace subcommand. To view these numbers, use the status subcommand. To turn tracing off, use the delete subcommand. Options atsourceline Specifies the source line at which to find the expression being traced. ifcondition Specifies a condition for the beginning of the trace. The trace begins only ifcondition is true. inprocedure Specifies the procedure in which to find the procedure or variable being traced. Usage notes The trace subcommand can be run only while the dbx debug program is running. Chapter 2. Shell command descriptions 237 dbx: trace Examples 1. To trace each call to the printf() procedure, enter: trace printf 2. To trace each execution of line 22 in the hello.c file, enter: trace "hello.c":22 3. To trace changes to the x variable within the main procedure, enter: trace x in main 4. To trace at line 52 only when mutex $m1 is not held, enter: trace at 52 if $m2.lock == 0 Related information The tracei subcommand. tracei subcommand for dbx: Turn on tracing Format tracei tracei tracei tracei [if condition] address [at address] [if condition] address [in procedure] [if condition] expression at address [if condition] Description The tracei subcommand turns on tracing when: v The contents of the storage at the address change, if the address argument is specified. v The instruction at the specified address is executed, if the ataddress option is specified. v The procedure specified by procedure is active, if the inprocedure option is included. v The condition specified by the condition argument is true, if the ifcondition option is included. Options ataddress Specifies an address. Tracing is enabled when the contents of this address change. ifcondition Specifies a condition, the meeting of which causes tracing to be enabled. inprocedure Specifies a procedure. Tracing is enabled when this procedure is active. Usage notes The tracei subcommand can be run only while the dbx debug program is running. Examples 1. To trace each instruction run, enter: tracei 2. To trace each time the instruction at address 0X100020F0 is run, enter: tracei at 0x100020f0 3. To trace each time the contents of memory location 0X20004020 change while the main procedure is active, enter: 238 z/OS V1R12.0 UNIX System Services Command Reference dbx: tracei tracei 0x20004020 in main 4. To trace at address 0x2d04567 only when thread $t2 reaches that address, enter: tracei at 0x2d04567 if $t2=$current Related information The trace subcommand. unalias subcommand for dbx: Remove an alias Format unalias name Description The unalias subcommand removes the alias specified by the name argument. Usage notes The unalias subcommand can be run only while the dbx debug program is running. Example To remove an alias named printx, enter: unalias printx Related information The alias subcommand. unset subcommand for dbx: Delete a variable Format unset name Description The unset subcommand deletes the dbx debug program variable associated with the name specified by the name argument. Usage notes The unset subcommand can be run only while the dbx debug program is running. Example To delete the variable inhibiting the display of floating-point registers, enter: unset $noflregs Related information The set subcommand. up subcommand for dbx: Move the current function up the stack Format up [count] Description The up subcommand moves the current function up the stack count number of levels. The current function is used for resolving names. The default for the count argument is 1. Chapter 2. Shell command descriptions 239 dbx: up Usage notes The up subcommand can be run only while the dbx debug program is running. Examples 1. To move the current function up the stack two levels, enter: up 2 2. To display the current function on the stack, enter: up 0 Related information The down subcommand. use subcommand for dbx: Set the list of directories to be searched Format use [directory...] Description The use subcommand sets the list of directories to be searched when the dbx debug program looks for source files. If the use subcommand is specified without arguments, the current list of directories to be searched is displayed. If the C primary source is in an MVS data set, the use subcommand can be specified with a double-slash (//) argument to indicate that the source file be sought outside the hierarchical file system. Usage notes The use subcommand can be run only while the dbx debug program is running. Examples 1. To change the list of directories to be searched to the working directory, the parent directory, and /tmp, enter: use . .. /tmp 2. To change the list of directories to be searched to look for the C source as an MVS data set, enter: use // Related information The edit and list subcommands. whatis subcommand for dbx: Display the type of program components Format whatis name Description The whatis subcommand displays the declaration of name, where the name argument designates a variable, procedure, or function name, optionally qualified with a block name. 240 z/OS V1R12.0 UNIX System Services Command Reference dbx: whatis Usage notes 1. Variables declared with the const attribute (in your C program) are displayed without the const attribute. 2. The whatis subcommand can be run only while the dbx debug program is running. Examples 1. To display the declaration of the x variable, enter: whatis x 2. To display the declaration of the main function, enter: whatis main 3. To display the declaration of the x variable within the main function, enter: whatis main.x 4. To display the declaration of a specific condition variable, $c1, enter: whatis $c1 5. To display the declaration of a specific mutex object, $m1, enter: whatis $m1 6. To display the declaration of a specific thread, $t1, enter: whatis $t1 where subcommand for dbx: List active procedures and functions Format where [>file] Description The where subcommand displays a list of active procedures and functions. By using the >file option, you can redirect the output of this subcommand to the specified file. Options >flag Redirects output to the specified file. Usage notes The where subcommand can be run only while the dbx debug program is running. Example To display the list of active routines, enter: where Related information The up and down subcommands. whereis subcommand for dbx: Display the full qualifications of symbols Format whereis [-exhaustive] identifier Chapter 2. Shell command descriptions 241 dbx: whereis Description The whereis subcommand displays the full qualifications of all the symbols whose names match the specified identifier. The order in which the symbols print is not significant. Options -exhaustive Specifies that whereis is to search for symbols in all compile units. This option only applies when a module map is being used. If one is being used, then the default is to use quick mode, which searches for symbols only in the current compile unit and global lists. In that case, using this option might degrade performance. If a module map is not being used, then this subcommand always searches for symbols in all compile units. Usage notes 1. The whereis subcommand can be run only while the dbx debug program is running. Examples 1. To display the qualified names of all symbols named x, enter: whereis x An example of a possible output is: "x1.c".x FDBX9998: whereis quick mode will only search symbol x in current CU and global lists. To list all symbol x, please use whereis -exhaustive x, but that will cause all debug data files to be loaded and performance will be degraded. 2. To display the qualified names of all symbols named x in exhaustive mode, enter: whereis -exhaustive x An example of a possible output is: ."x1.c".x ."x2.c".x Related information The which subcommand. which subcommand for dbx: Display the full qualification of an identifier Format which identifier Description The which subcommand displays the full qualification of the given identifier. The full qualification consists of a list of the outer blocks with which the identifier is associated. Usage notes The which subcommand can be run only while the dbx debug program is running. 242 z/OS V1R12.0 UNIX System Services Command Reference dbx: which Example To display the full qualification of the x symbol, enter: which x Related information The whereis subcommand. dd — Convert and copy a file Format dd [bs=size] [cbs=size] [conv=conversion] [count=n] [ibs=size] [if=file] [imsg=string] [iseek=n] [obs=s] [of=file] [omsg=string] [seek=n] [skip=n]> Description dd reads and writes data by blocks. It can convert data between formats. It is frequently used for such devices as tapes that have discrete block sizes, or for fast multisector reads from disks. dd performs conversions to accommodate nonprogrammable terminals, which require deblocking, conversion to and from EBCDIC, and fixed-length records. dd processes the input data as follows: 1. dd reads an input block. 2. If this input block is smaller than the specified input block size, dd pads it to the specified size with null bytes. When you also specify a block or unblock conversion, dd uses spaces instead of null bytes. 3. If you specified bs=s and requested no conversion other than sync or noerror, dd writes the padded (if necessary) input block to the output as a single block and omits the remaining steps. 4. If you specified the swab conversion, dd swaps each pair of input bytes. If there is an odd number of input bytes, dd does not attempt to swap the last byte. 5. dd performs all remaining conversions on the input data independently of the input block boundaries. A fixed-length input or output record may span these boundaries. 6. dd gathers the converted data into output blocks of the specified size. When dd reaches the end of the input, it writes the remaining output as a block (without padding if conv=sync is not specified). As a result, the final output block may be shorter than the output block size. Options bs=size Sets both input and output block sizes to size bytes. You can suffix this decimal number with w, b, k, or x number, to multiply it by 2, 512, 1024, or number, respectively. You can also specify size as two decimal numbers (with or without suffixes) separated by x to indicate the product of the two values. Processing is faster when ibs and obs are equal, since this avoids buffer copying. The default block size is 1B. bs=size supersedes any settings of ibs=size or obs=size. If you specify bs=size and you request no other conversions than noerror, notrunc, or sync, dd writes the data from each input block Chapter 2. Shell command descriptions 243 dd as a separate output block; if the input data is less than a full block and you did not request sync conversion, the output block is the same size as the input block. cbs=size Sets the size of the conversion buffer used by various conv options. conv=conversion[, conversion, ...] conversion can be any one of the following: ascii Converts EBCDIC input to ASCII for output; it is provided for compatibility purposes only. To copy a file and convert between a shell code page and ASCII, use iconv, not dd. block Converts variable-length records to fixed-length records. dd treats the input data as a sequence of variable-length records (each terminated by a newline or an EOF character) independent of the block boundaries. dd converts each input record by first removing any newline characters and then padding (with spaces) or truncating the record to the size of the conversion buffer. dd reports the number of truncated records on standard error (stderr). You must specify cbs=size with this conversion. Note: When working with double-byte characters, dd truncates the record after the last complete double-byte character that will fit in the conversion buffer. dd then pads the record with spaces if it is shorter than the conversion buffer size. convfile Uses convfile as a translation table if it is not one of the conversion formats listed here and it is the name of a file of exactly 256 bytes. You can perform multiple conversions at the same time by separating arguments to conv with commas; however, some conversions are mutually exclusive (for example, ucase and lcase). Notes: 1. When you specify one or more of the character set conversions (ascii, ebcdic, ibm, or convfile), dd assumes that all characters are single-byte characters, regardless of the locale. Do not use these conversions with double-byte character sets. 2. When working with DBCS text, dd treats the input and output files as character strings and handles DBCS characters correctly (no splitting and retaining of proper shift states). This happens only if any of the conversion options (block, unblock, ucase, or lcase) are specified. Otherwise, DBCS strings can be corrupted with the seek, count, or iseek processing. ebcdic Converts ASCII input to EBCDIC for output; it is provided for compatibility purposes only. To copy a file and convert between a shell code page and ASCII, use iconv, not dd. 244 z/OS V1R12.0 UNIX System Services Command Reference dd ibm Like ebcdic, converts ASCII to EBCDIC; it is provided for compatibility purposes only. To copy a file and convert between code page 01047 (used in the z/OS shell) and ASCII, use iconv, not dd. lcase Converts uppercase input to lowercase. noerror Ignores errors on input. notrunc Does not truncate the output file. dd preserves blocks in the output file that it does not explicitly write to. swab Swaps the order of every pair of input bytes. If the current input record has an odd number of bytes, this conversion does not attempt to swap the last byte of the record. sync Specifies that dd is to pad any input block shorter than ibs to that size with NUL bytes before conversion and output. If you also specified block or unblock, dd uses spaces instead of null bytes for padding. ucase Converts lowercase input to uppercase. unblock Converts fixed-length records to variable-length records by reading a number of bytes equal to the size of the conversion buffer, deleting all trailing spaces, and appending a newline character. You must specify cbs=size with this conversion. count=n Copies only n input blocks to the output. ibs=size Sets the input block size in bytes. You specify it in the same way as with the bs option. if=file Reads input data from file. If you don't specify this option, dd reads data from standard input (stdin). imsg=string Displays string when all data has been read from the current volume, replacing all occurrences of %d in string with the number of the next volume to be read. dd then reads and discards a line from the controlling terminal. iseek=n seeks to the nth block of the input file. The distinction between this and the skip option is that iseek does not read the discarded data. There are some devices, however, such as tape drives and communication lines, on which seeking is not possible, so only skip is appropriate. obs=size Sets the output block size in bytes. You specify it in the same way as the bs value. The size of the destination should be a multiple of the value chosen for size. For example, if you choose obs=10K, the destination's size should be a multiple of 10K. of=file Writes output data to file. If you don't specify this option, dd writes data to standard output (stdout). dd truncates the output file before writing to it, unless you specified the seek=n operand. If you specify seek=n, but do not specify conv=notrunc, dd preserves only those blocks in the output file over which it seeks. If the size Chapter 2. Shell command descriptions 245 dd of the seek plus the size of the input file is less than the size of the output file, this can result in a shortened output file. omsg=string Displays string when dd runs out of room while writing to the current volume. Any occurrences of %d in string are replaced with the number of the next volume to be written. dd then reads and discards a line from the controlling terminal. seek=n Initially seeks to the nth block of the output file. Note: Use caution when working with DBCS characters and the seek option. Seeking into the output file that contains DBCS characters can cause the DBCS string in the output file to be corrupted. Be sure that the seek count is not aligned with an existing DBCS string in the output file. Otherwise, part of the existing DBCS string either is written over with single-byte data or has extra shift codes from the input file's DBCS data. skip=n Reads and discards the first n blocks of input. Example Entering: dd if=in of=out conv=ascii cbs=80 ibs=6400 obs=512 converts 80-byte fixed-length EBCDIC card images in 6400-byte input blocks to variable-length ASCII lines, 512 bytes to the output block. Localization dd uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v I/O errors on read/write v Incorrect command-line option v Incorrect arguments to a conversion 2 Failure resulting in a usage message such as: v An option that should contain = does not v Unknown or incorrect command-line option Messages Possible error messages include: badly formed number number A value specified as a number (for example, a block size) does not have 246 z/OS V1R12.0 UNIX System Services Command Reference dd the form of a number as recognized by dd. For example, you may have followed the number with a letter that dd does not recognize as a block-size unit (w, b, k). Portability POSIX.2, X/Open Portability Guide, UNIX systems. The conv=convfile, iseek, imsg, and omsg options plus the w suffix described in the bs= option are all extensions of the POSIX standard. Related information cp, cpio, iconv, mv, tr df — Display the amount of free space in the file system Format | df [–kPStv][file ...] Description df shows the amount of free space left on a file system. Space can have the following values: Space Used Total amount of space allocated to existing files in the file system. Space Free Total amount of space available in file system for the creation of new files by unprivileged users. Space Reserved Space reserved by the system which is not normally available to a user. Total Space Includes space used, space free, and space reserved. df measures space in units of 512-byte disk sectors. You can specify a particular file system by naming any file name on that file system. If you do not give an argument, df reports space for all mounted file systems known to the system, in the following format: v File system root v File system name v Space available and total space The total space reported is the space in the already allocated extents (primary and any already allocated secondary extents) of the data set that holds this file system. Therefore, the total space may increase as new extents are allocated. v Number of free files (inodes) This number is only meaningful for file systems created using DFSMS 1.3.0 and later. For file systems created with earlier versions of DFSMS, this number will always be 4 294 967 295. v File system status Tips: For zFS file systems, the df command might not provide sufficient information to indicate whether a file system is running out of space. For complete Chapter 2. Shell command descriptions 247 df information about zFS space usage, use the zfsadm aggrinfo -long command. See z/OS Distributed File Service zSeries File System Administration for more information. Options –k Uses 1024-byte (1KB) units instead of the default 512-byte units when reporting space information. –P Lists complete information about space used, in the following order: v File system name v Total space v Space used v Space free v Percentage of space used v File system root –S Display SMF accounting fields. –t Display total allocated file slots, in addition to the total number of free files that are already displayed. –v Lists more detailed information about the file system status. v File system root v File system name v Space available and total space v Number of free files (inodes) v File system status v File system type, mode bits and device number v File system mount parm data v File system mount tag value v Whether ACLs are supported by the security product and file system. v Aggregate name, if one exists v File system ID issuing a quiesce request v User name and effective UID of the user who mounted the file system, if it was a nonprivileged user mount. | | For systems in a shared file system environment, the following additional fields are displayed: v File system ID (owner/mounted file system server) v File system automove status (yes-Y, no-N, include-I, exclude-E or unmount-U) v File system client status v System list and include/exclude indicator, if the system list exists Example If you issue a df –v on a file system whose owner is participating in shared file system, status information such as the following is displayed: Mounted on Filesystem Avail/Total Files Status /u/billyjc (OMVS.ZFS.BILLYJC) 365824/3165120 4294924769 Available ZFS, Read/Write, Device: 17,ACLS=Y, No SUID, Exported, No Security FSFULL(90,1) File System owner: AQFT Automove=E Client=N System List (Exclude): sysname1 sysname2 .... sysnameN Quiesce Owner : AQTS Quiesce Jobname : MEGA Quiesce PID: 16777321 Filetag : T=on codeset=ISO8859-1 Aggregate Name: POSIX.ZFS.ETC 248 z/OS V1R12.0 UNIX System Services Command Reference df Localization df uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion Failure due to any of the following: v Inability to access filename v Inability to access device v device is not a device Incorrect command-line option Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. Related information du, ls diff — Compare two text files and show the differences Format diff [–befHhimnrsw] [–C n] [–c[n]] [–Difname] path1 path2 Description The diff command attempts to determine the minimal set of changes needed to convert a file whose name is specified by the path1 argument into the file specified by the path2 argument. Input files must be text files. If either (but only one) filename is –, diff uses a copy of the standard input (stdin) for that file. If exactly one of path1 or path2 is a directory, diff uses a file in that directory with the same name as the other filename. If both are directories, diff compares files with the same filenames under the two directories; however, it does not compare files in subdirectories unless you specify the –r option. When comparing two directories, diff does not compare character special files, or FIFO special files with any other files. By default, output consists of descriptions of the changes in a style like that of the ed text editor. A line indicating the type of change is given. The three types are a (append), d (delete), and c (change). The output is symmetric: A delete in path1 is the counterpart of an append in path2. diff prefixes each operation with a line number (or range) in path1 and suffixes each with a line number (or range) in path2. After the line giving the type of change, diff displays the deleted or added lines, prefixing lines from path1 with < and lines from path2 with >. Options Options that control the output or style of file comparison are: Chapter 2. Shell command descriptions 249 diff –b Ignores trailing blanks and tabs and considers adjacent groups of blanks and tabs elsewhere in input lines to be equivalent. For example, if one file contained a string of three spaces and a tab at a given location while the other file contained a string of two spaces at the same location, diff would not report this as a difference. –C n Shows n lines of context before and after each change. diff marks lines removed from path1 with –, lines added to path2 with +, and lines changed in both files with !. –c[n] Is equivalent to –Cn, but n is optional. The default value for n is 3. diff marks lines removed from path1 with –, lines added to path2 with +, and lines changed in both files with !. –Difname Displays output that is the appropriate input to the C preprocessor to generate the contents of path2 when ifname is defined, and the contents of path1 when ifname is not defined. –e Writes out a script of commands for the ed text editor, which converts path1 to path2. diff sends the output to the standard output (stdout). –f Writes a script to stdout (but it will be in a form not suitable for use with the ed editor) showing the modifications necessary to convert path1 to path2 in the reverse order of that produced by the –e option. The commands produced will be reversed from that produced by –e, and the line number ranges will be separated by spaces, rather than commas. This option conflicts with the –m option. –H Uses the half-hearted (–h) algorithm only if the normal algorithm runs out of system resources. –h Uses a fast, half-hearted algorithm instead of the normal diff algorithm. This algorithm can handle arbitrarily large files; however, it is not particularly good at finding a minimal set of differences in files with many differences. –i Ignores the case of letters when doing the comparison. –m Produces the contents of path2 with extra formatter request lines interspersed to show which lines were added (those with vertical bars in the right margin) and deleted (indicated by a * in the right margin). –M Is an IBM internal option and is not supported. –n Is an IBM internal option and is not supported. –N Is an IBM internal option and is not supported. –r Compares corresponding files under the directories, and recursively compares corresponding files under corresponding subdirectories under the directories. You can use this option when you specify two directory names on the command line. –s Compares two directories, file by file, and prints messages for identical files between the two directories. –w Ignores white space when making the comparison. Examples The following example illustrates the effect of the –c option on the output of the diff command. The following two files, price1 and price2, are compared with and without the use of the –c option. The contents of price1 are as follows: Company X Price List: $ 0.39 -- Package of Groat Clusters $ 5.00 -- Candy Apple Sampler Pack $ 12.00 -- Box of Crunchy Frog Chocolates $ 15.99 -- Instant Rain (Just Add Water) $ 20.00 -- Asparagus Firmness Meter 250 z/OS V1R12.0 UNIX System Services Command Reference diff $ 25.00 $ 30.00 $ 35.00 $ 45.00 $ 75.88 $ 99.99 $125.00 -------- Package of Seeds for 35 Herbs Child’s Riding Hood (Red) Genuine Placebos Case of Simulated Soy Bean Oil No-Name Contact Lenses Kiddie Destructo-Bot Emperor’s New Clothes The contents of price2 are as follows: Company X Price List: $ 0.39 -- Package of Groat Clusters $ 5.49 -- Candy Apple Sampler Pack $ 12.00 -- Box of Crunchy Frog Chocolates $ 15.99 -- Instant Rain (Just Add Water) $ 17.00 -- Simulated Naugahyde cleaner $ 20.00 -- Asparagus Firmness Meter $ 25.00 -- Package of Seeds for 35 Herbs $ 30.00 -- Child’s Riding Hood (Red) $ 35.00 -- Genuine Placebos $ 45.00 -- Case of Simulated Soy Bean Oil $ 75.88 -- No-Name Contact Lenses $ 99.99 -- Kiddie Destructo-Bot The command: diff price1 price2 results in the following output: 3c3 < $ 5.00 -- Candy Apple Sampler Pack --> $ 5.49 -- Candy Apple Sampler Pack 5a6 > $ 17.00 -- Simulated Naugahyde cleaner 13d13 < $125.00 -- Emperor’s New Clothes The addition of the –c option, as in: diff -c price1 price2 results in the following output: *** price1 Wed Oct 1 13:59:18 1997 --- price2 Wed Oct 1 14:03:36 1997 *************** *** 1,8 **** Company X Price List: $ 0.39 -- Package of Groat Clusters ! $ 5.00 -- Candy Apple Sampler Pack $ 12.00 -- Box of Crunchy Frog Chocolates $ 15.99 -- Instant Rain (Just Add Water) $ 20.00 -- Asparagus Firmness Meter $ 25.00 -- Package of Seeds for 35 Herbs $ 30.00 -- Child’s Riding Hood (Red) --- 1,9 ---Company X Price List: $ ! $ $ $ + $ $ $ 0.39 5.49 12.00 15.99 17.00 20.00 25.00 -------- Package of Groat Clusters Candy Apple Sampler Pack Box of Crunchy Frog Chocolates Instant Rain (Just Add Water) Simulated Naugahyde cleaner Asparagus Firmness Meter Package of Seeds for 35 Herbs Chapter 2. Shell command descriptions 251 diff $ 30.00 -- Child’s Riding Hood (Red) *************** *** 10,13 **** $ 45.00 -- Case of Simulated Soy Bean Oil $ 75.88 -- No-Name Contact Lenses $ 99.99 -- Kiddie Destructo-Bot - $125.00 -- Emperor’s New Clothes --- 11,13 ---- diff –c marks lines removed from price1 with –, lines added to price1 with + and lines changed in both files with !. In the example, diff shows the default three lines of context around each changed line. One line was changed in both files (marked with !), one line was added to price1 (marked with +), and one line was removed from price1 (marked with –). Note: If there are no marks to be shown in the corresponding lines of the file being compared, the lines are not displayed. Lines 11 to 13 of price2 are suppressed for this reason. Localization diff uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_TIME v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 No differences between the files compared. 1 diff compared the files and found them to be different. 2 Failure due to any of the following: v Incorrect command-line argument v Inability to find one of the input files v Out of memory v Read error on one of the input files 4 At least one of the files is a binary file containing embedded NUL (\0) bytes or newlines that are more than LINE_MAX bytes apart. Messages Possible error messages include: file filename: no such file or directory The specified filename does not exist. filename was either typed explicitly, or generated by diff from the directory of one file argument and the basename of the other. Files file1 and file2 are identical The –s option was specified and the two named files are identical. Common subdirectories: name and name This message appears when diff is comparing the contents of directories, 252 z/OS V1R12.0 UNIX System Services Command Reference diff but you have not specified –r. When diff discovers two subdirectories with the same name, it reports that the directories exist, but it does not try to compare the contents of the two directories. Insufficient memory (try diff –h) diff ran out of memory for generating the data structures used in the file differencing algorithm. (See “Limits.”) The –h option of diff can handle any size file without running out of memory. Internal error—cannot create temporary file diff was unable to create a working file that it needed. Ensure that you either have a directory /tmp or that the environment contains a variable TMPDIR, which names a directory where diff can store temporary files. Also, ensure that there is sufficient file space in this directory. Missing ifdef symbol after -D You did not specify a conditional label on the command line after the –D option. Only one file may be – Of the two input files normally found on the command line of diff, only one can be the standard input (stdin). Too many lines in filename A file of more than the maximum number of lines (see “Limits”) was given to diff. Limits The longest input line is 1024 bytes. Except under –h, files are limited to INT_MAX lines. INT_MAX is defined in limits.h. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –D, –f, –H, –h, –i, –m, –s, and –w options, and the n argument to the –c option, are extensions of the POSIX standard. Related information cmp, comm, patch J. W. Hunt and M. D. McIlroy, An Algorithm for Differential File Comparison, Report 41, from Computing Science, Bell Laboratories, Murray Hill, NJ 07974, (June 1976), 9 pages. dircmp — Compare directories Format dircmp [–d] [–s] [–wn] dir1 dir2 Note: The dircmp utility is fully supported for compatibility with older UNIX systems. However, it is recommended that diff –r be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Chapter 2. Shell command descriptions 253 dircmp Description dircmp examines dir1 and dir2 and generates listings about the contents of the directories. Listings of files that are unique to each directory are generated for all the options. If no option is entered, a list is output indicating whether the filenames common to both directories have the same contents. Options –d Compare the contents of files with the same name in both directories and output a list telling what must be changed in the two files to bring them into agreement. The list format is described in diff. –s Suppress messages about identical files. –wn Change the width of the output line to n characters. The default width is 72. Localization dircmp uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Related information cmp, diff dirname — Return the directory components of a path name Format dirname pathname Description dirname deletes the trailing part of a file name. The result is the path name of the directory that contains the file. This is useful in shell scripts. dirname does not try to validate the path name. For validation, use pathchk. dirname follows these rules: 1. If pathname is //, return it. 2. Otherwise, if it is all slashes, return one slash. 3. Otherwise, remove all trailing slashes. 4. If there are no slashes remaining in pathname, return period (.). 5. Otherwise, remove trailing nonslash characters. 6. If the remaining string is //, return it. 7. Otherwise, remove any trailing slashes. 8. If the resulting string is empty, return period (.). 9. Otherwise, return the resulting string. Examples The command: dirname src/lib/printf.c 254 z/OS V1R12.0 UNIX System Services Command Reference dirname produces: src/lib Localization dirname uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion Failed Unknown command-line option Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information basename, pathchk . (dot) — Run a shell file in the current environment Format . file [argument ...] Description . (dot) runs a shell script in the current environment and then returns. Normally, the shell runs a command file in a child shell so that changes to the environment by such commands as cd, set, and trap are local to the command file. The . (dot) command circumvents this feature. If there are slashes in the filename, . (dot) looks for the named file. If there are no slashes . (dot) searches for file in the directories specified in the PATH variable. This may surprise some people when they use dot to run a file in the working directory, but their search rules are not set up to look at the working directory. As a result, the shell doesn't find the shell file. If you have this problem, you can use: . ./file This indicates that the shell file you want to run is in the working directory. Also, the file need not be executable, even if it is looked for on the PATH. If you specify an argument list argument ..., . (dot) sets the positional parameters to the arguments while running the shell script, then restores the invoker's positional parameters. If no argument list is specified, the shell script has the same positional parameters as the invoker. Any changes made to the positional parameters (e.g. by the set command) in the shell script remain in effect when the . (dot) command ends. Usage notes 1. . (dot) is a special built-in shell command. Chapter 2. Shell command descriptions 255 . (dot) 2. The file specified is treated as a shell script containing shell commands. Files which are not shell scripts (e.g. REXX execs, executable programs) should not be specified as file. Localization . (dot) uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 1 2 The path search failed Failure because of an incorrect command-line option Otherwise, the exit status is the exit status of the last command run from the script. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information cd, set, sh, trap dspcat — Display all or part of a message catalog Format dspcat [–gt] CatalogName [SetNumber [MessageNumber]] Description dspcat displays a particular message, all of the messages in a set, or all of the messages in a catalog. Messages are displayed as they are specified in the message catalog; no substitution of variables takes place. It directs the messages to standard output (stdout). It has the following parameters: v The CatalogName parameter specifies a message catalog. v The SetNumber parameter specifies a set in the catalog specified by the CatalogName parameter. If you specify a nonexistent SetNumber value, all messages in the catalog are displayed. v The MessageNumber parameter specifies a particular message in the set specified by the SetNumber parameter. If you include all three parameters, dspcat displays a particular message. If you do not include the MessageNumber parameter, or if the MessageNumber value is in error, all the messages in the set are displayed. If you specify only the CatalogName parameter, all the messages in the catalog are displayed. You must include the SetNumber parameter if you include the MessageNumber parameter. 256 z/OS V1R12.0 UNIX System Services Command Reference dspcat Use the NLSPATH environment variable to find the specified message catalog if slash (/) characters are not used in the value of the CatalogName parameter. Options –g Formats the output so it can be used as input to the gencat command. The MessageNumber parameter is not valid when –g is specified. –t Displays the timestamp of the message catalog. Examples To display message number 2 in set number 1 of test.cat, enter: dspcat test.cat 1 2 dspmsg — Display selected messages from message catalogs Format dspmsg [–d] [–s SetNumber] CatalogName MessageNumber ['DefaultMessage'[Arguments]] Description dspmsg displays either the text of a particular message from a message catalog generated with the gencat command or, if the message cannot be retrieved, a default message supplied as a parameter to the command. dspmsg directs the message to standard output. This command is intended for use in shell scripts as a replacement for the echo command. The NLSPATH environment variable and the LANG category are used to find the specified message catalog if / (slash) characters are not used in the value of the CatalogName parameter. If the catalog named by the CatalogName parameter is not found or if the message named by the MessageNumber parameter (and optional SetNumber value) is not found, then the supplied DefaultMessage value is displayed. If a DefaultMessage value is not specified, a system-generated error message is displayed. dspmsg allows up to ten string arguments to be substituted into the message if it contains the %s or %n$s, fprintf() conversion specification. Only string variables are allowed. If arguments are specified, then a DefaultMessage must also be specified. Missing arguments for conversion specifications result in a dspmsg error message. Normal fprintf() subroutine control character escape codes (for example, –n) are recognized. Options –d If you are receiving the default message, use this option to request debugging information about why dspmsg cannot get the message from the message catalog. –s SetNumber Specifies an optional set number. The default value for the SetNumber variable is 1. Chapter 2. Shell command descriptions 257 dspmsg Examples To display set number 1, message number 2 of the test.cat catalog, enter: dspmsg –s 1 test.cat 2 ’message %s not found’ 2 If the message is not found, message 2 not found is displayed. du — Summarize usage of file space Format du [–a|–s[–krtx] [ pathname ...] Description du reports the amount of file space used by the files indicated by the given path name. If the path name is a directory, du reports the total amount of file space used by all files in that directory and in each subdirectory in its hierarchy. If you do not specify a path name, du assumes the current directory. Files with multiple links are only counted once. On systems supporting symbolic links, only the disk space used by the symbolic link is counted. du measures file space in 512-byte units. Options –a Generates a report for all files in pathname. –k Displays file sizes in 1024-byte (1KB) units. –r Reports files that cannot be opened and directories that cannot be read; this is the default. –s Does not display file size totals for subdirectories. –t Displays the total amount of space used by all path names examined. –x Displays file sizes for only those files contained on the same device as pathname. Usage notes du computes file space in units of 512 bytes. The actual disk space used by files and directories may be more, since some systems allocate space in units of some multiple of a sector. On UNIX System V, it is usually two sectors; on UNIX Version 7, it is one sector. The allocation unit is file system specific. Localization du uses the following localization variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. 258 z/OS V1R12.0 UNIX System Services Command Reference du Exit values 0 Successful completion 1 Failure due to any of the following: v Incorrect command-line option v Cannot access a directory v Cannot read a directory v Cannot access file information Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. The –t option is an extension to the POSIX standard. Related information df, find, ls echo — Write arguments to standard output Format echo argument ... tcsh shell: echo [-n] word ... Description echo writes its arguments, specified with the argument argument, to standard output. echo accepts these C-style escape sequences: \a Bell \b Backspace \c Removes any following characters, including \n and \r. \f Form feed \n Newline \r Carriage return \t Horizontal tab \v Vertical tab \0num The byte with the numeric value specified by the zero to three-digit octal num. \– Backslash echo follows the final argument with a newline unless it finds \c in the arguments. Arguments are subject to standard argument manipulation. echo in the tcsh shell In the tcsh shell, echo writes each word to the shell's standard output, separated by spaces and terminated with a newline. tcsh echo accepts these C-style escape sequences: \a Bell \b Backspace \e Escape \f Form feed \n Newline \r Carriage return Chapter 2. Shell command descriptions 259 echo Horizontal tab Vertical tab The EBCDIC character corresponding to the octal number nnn \t \v \nnn See “tcsh — Invoke a C shell” on page 649. Examples 1. One important use of echo is to expand filenames on the command line, as in: echo *.[ch] This displays the names of all files with names ending in .c or .h—typically C source and include (header) files. echo displays the names on a single line. If there are no filenames in the working directory that end in .c or .h, echo simply displays the string *.[ch]. 2. echo is also convenient for passing small amounts of input to a filter or a file: echo 'this is\nreal handy' > testfile Usage note echo is a built-in shell command. Localization echo uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit value echo always returns the following exit status value: 0 Successful completion Portability POSIX.2, X/Open Portability Guide, UNIX System V. The POSIX.2 standard does not include escape sequences, so a strictly conforming application cannot use them. printf is suggested as a replacement. Related Information sh, tcsh ed — Use the ed line-oriented text editor Format ed [ –bs] [–p prompt] [file] 260 z/OS V1R12.0 UNIX System Services Command Reference ed Description ed is a line-oriented text editor that lets you manipulate text files interactively. ed reads the text of a file into memory and stores it in an area called a buffer. Various subcommands let you edit the text in the buffer. You can also write the contents of the buffer back out to the file, thereby overwriting the old contents of the file. Options –b Enables you to edit larger files by restricting the amount of memory dedicated to paging. Using a large amount of memory may make ed run more slowly. –p prompt Displays the given prompt string prompting you to input a subcommand. By default, ed does not typically prompt for subcommand input. See “Subcommands” on page 262 for more information about subcommand prompting. –s Puts ed into a quiet mode, in which e, E, r, and w, subcommands do not display file size counts; the q and e subcommands do not check buffer modification; and ! is not displayed after calling the shell to run a subcommand. This mode is particularly useful when you invoke ed from within a shell script. If the optional file argument is present on the command line, ed reads the specified file into the editor by simulating an efile subcommand. Addresses You can prefix subcommands in ed with zero, one, or two addresses. These addresses let you refer to single lines or ranges of lines in the buffer. You do not need to specify addresses for certain subcommands that use default addresses. Consult the description for a particular subcommand. You can construct each address out of the following components: . The single dot character represents the current line in the buffer. Many subcommands set the current line; for example the e command sets it to the last line of the new file being edited. $ The dollar sign refers to the last line in the buffer. n The number n refers to the nth line in the buffer. /regexp/ This searches for a line containing a string that matches the regular expression, regexp. The search begins at the line immediately following the current line. It proceeds forward through the buffer; if ed reaches the end of the buffer without finding a match, it wraps around to the first line of the buffer and continues the search. If ed does not find a match, the search ends when it reaches the original current line. If it does find a match, the address /regexp/ refers to the first matching line. If you omit regexp, the last used regular expression becomes the object of the search. You can omit the trailing /. Within regexp, \/ represents a literal slash and not the regexp delimiter. ?regexp? This is similar to the previous address form, except that the search goes backward through the buffer. If the search reaches the first line in the buffer without finding a match, ed wraps around and continues searching backward from the last line in the buffer. If you omit regexp, the last used Chapter 2. Shell command descriptions 261 ed regular expression becomes the object of the search. You can omit the trailing ?. Within regexp, \? represents a literal question mark and not the regexp delimiter. 'l The address is the line marked with the mark name l. The name l must be a lowercase letter set by the k subcommand. You can combine these basic addresses with numbers using the + and – operators, with the usual interpretation. Missing left operands default to . (dot); missing right operands default to 1. Missing right operands also have a cumulative effect; so an address of – – refers to the current line number less two. You can specify address ranges in the following ways: a1,a2 Specifies a range of addresses from address a1 to address a2, inclusive. If you omit a1 and a2 (that is, the comma alone is specified), this is equivalent to the range 1,$. a1;a2 Is similar to the previous form except that ed resets the current line after calculating the first address, a1, so that the second address, a2, is relative to a1. If you omit a1 and a2 (that is, the semicolon alone is specified), this is equivalent to .;$. If you specify only a1 and the command requires both a1 and a2, the command operates as though you specified a range of: a1;. command > Is equivalent to .,.+22 (that is, page forward), except that it never attempts to address any line beyond $. < Is equivalent to .–22,. (that is, page backward), except that it never addresses any line before line 1. Subcommands An ed command has the form [address] command All commands end with a newline; you must press <Enter>. Most commands allow only one command on a line, although you can modify commands by appending the l, n, and p commands. Subcommands generally take a maximum of zero, one, or two addresses, depending upon the particular subcommand. In the following descriptions, we show commands with their default addresses (that is the addresses used when you don't specify any addresses) in a form that shows the maximum number of permitted addresses for the command. In any of the subcommands that take a file argument, file can be a pathname or: !command-line If you use the ! form, ed runs the given command line, reading its standard output (stdout) or writing its standard input (stdin), depending on whether the ed command does reading or writing. If a terminal disconnect is detected: v If the buffer is not empty and has changed since the last write, the ed utility will attempt to write a copy of the buffer to a file named ed.hup in the current directory. If this write fails, ed will attempt to write a copy of the buffer to a filename ed.hup in the directory named by the HOME environment variable. If both these attempts fail, ed will exit without saving the buffer. 262 z/OS V1R12.0 UNIX System Services Command Reference ed v The ed utility will not write the file to the currently remembered pathname or return to command mode, and will terminate with the exit status of 1. If an end-of-file is detected on standard input: v If the ed utility is in input mode, ed will terminate input mode and return to command mode. Any partially entered lines (that is, input text without a terminating newline) will be saved. v If the ed utility is in command mode, it will act as if a q command had been entered. ed accepts the following subcommands: .a Appends text after the specified line. Valid addresses range from 0 (text is placed at the beginning of the buffer, before the first line) to $ (text is placed after the last line of the buffer). ed reads lines of text from the workstation until a line consisting solely of an unescaped . (dot) is entered. ed sets the current-line indicator to the last line appended. .,.c Changes the addressed range of lines by deleting the lines and then reading new text in the manner of the a or i subcommands. If the variable _UNIX03 is set to YES, address 0 is valid for this subcommand and it will be interpreted as if address 1 were specified. .,.d Deletes the addressed range of lines. The line after the last line deleted becomes the new current line. If you delete the last line of the buffer, ed sets the current line to the new last line. If no lines remain in the buffer, it sets the current line to 0. E[file] Is similar to the e command, but ed gives no warning if you have changed the buffer. e [file] Replaces the contents of the current buffer with the contents of file. If you did not specify file, ed uses the remembered filename, if any. In all cases, the e subcommand sets the remembered filename to the file that it has just read into the buffer. ed displays a count of the bytes in the file unless it is in quiet mode. If you have changed the current buffer since the last time its contents were written, ed warns you if you try to run an e subcommand, and does not run the subcommand. If you enter the e subcommand a second time, ed goes ahead and runs the command. f [file] Changes the remembered filename to file. ed displays the new remembered filename. If you do not specify file, ed displays the current remembered filename. 1,$G/regexp/ Is similar to the g command except that when ed finds a line that matches regexp, it prints the line and waits for you to type in the subcommand to be run. You cannot use the a, c, i, g, G, v, and V subcommands. If you enter &, the G subcommand reruns the last subcommand you typed in. If you just press <Enter>, G does not run any subcommand for that line. Note that the subcommands input as part of the execution of the G subcommand can address and affect any lines in the buffer. If the variable _UNIX03 is set to YES, any line modified by the subcommand will be unmarked. 1,$g/regexp/command Performs command on all lines that contain strings matching the regular expression regexp. This subcommand works in two passes. In the first pass, ed searches the given range of lines and marks all those that contain Chapter 2. Shell command descriptions 263 ed strings matching the regular expression regexp. The second pass performs command on those lines. If the variable _UNIX03 is set to YES, any line modified by the command will be unmarked. You cannot use !, g, G, V, or v as command. command consists of one or more ed subcommands, the first of which must appear on the same line as the g subcommand. All lines of a multiline command list, except the last, must end with a backslash (\). If command is empty, ed assumes it to be the p subcommand. If no lines match regexp, ed does not change the current line number; otherwise, the current line number is the one set by the last subcommand in command. Instead of the slash (/) to delimit regexp, you can use any character other than space or newline. 264 H Tells ed to display more descriptive messages when errors occur. If ed is already printing descriptive messages, H returns to terse error messages. Normally, ed indicates error messages by displaying a ?. When you turn on descriptive error messages with this subcommand, ed also displays the descriptive message for the most recent ? message. h Provides a brief explanation of the last error that occurred. This does not change the current line number. .i Works similarly to the a subcommand, except that ed places the text before the addressed line. Valid addresses range from line 1 to $ (the last line). ed sets the current line number to the last inserted line. If the variable _UNIX03 is set to YES, address 0 is valid for this subcommand and it will be interpreted as if address 1 were specified. .,.+1j Joins a range of lines into one line. To be precise, the j command removes all newline characters from the addressed range of lines, except for the last one. ed sets the current line number to the resulting combined line. .kx Marks the addressed line with the mark name x, which is any single lowercase letter of the alphabet. This lets you refer to a marked line with the construct 'x. This is called an absolute address, because it always refers to the same line, regardless of changes to the buffer. .,.l Displays the addressed range of lines, representing nonprintable (control) characters in a visible manner. The end of each line will be marked with a '$' character. The characters listed in the Base Definitions volume of IEEE Std 1003.1-2001, Table 5-1, Escape Sequences and Associated Actions ( '\\', '\a', '\b', '\f', '\r', '\t', '\v' ) shall be written as the corresponding escape sequence; the '\n' in that table is not applicable. If the variable _UNIX03 is set to YES,'$' characters within the text will be written with a preceding backslash. ed sets the current line to the last line so displayed. You can append this subcommand to most other commands, to check on the effect of those subcommands. .,.ma Moves the addressed lines to the point immediately following the line given by the address a. The address a must not be in the range of addressed lines. If address a is 0, ed moves the lines to the beginning of the buffer. The last line moved becomes the new current line. .,.n Displays the addressed lines in a way similar to the p command, but ed puts the line number and a tab character at the beginning of each line. The last line displayed becomes the new current line. You can append n to any subcommand (except for E, e, f, Q, r, w, or !) so that you can check on the effect that the subcommands had. P Turns on subcommand prompting if it is not already on. If you specified the –p prompt option on the ed command line, ed displays the prompt z/OS V1R12.0 UNIX System Services Command Reference ed string whenever it is ready for you to type in another subcommand. If you did not include the –p option, ed uses the * character as a prompt. If subcommand prompting is currently turned on, issuing the P subcommand turns it off. .,.p Displays (prints) the addressed lines. The last line displayed becomes the new current line. You can append p to most subcommands, so that you can check on the effect that the subcommands had. You can append p to any subcommand (except for E, e, f, Q, r, w, or !) so that you can check on the effect that the subcommands had. Q Quits unconditionally, without checking for buffer changes. q Causes the editor to exit. If you have made changes to the buffer since the last save and you try to quit, ed issues a warning. Entering the q subcommand again lets you quit, regardless of unsaved changes. $r [file] Reads the contents of the file into the buffer after the addressed line. If the address is 0, ed places the text before the first line in the buffer. If you do not specify file, ed uses the remembered filename; if no remembered filename exists, file becomes the new remembered name. If file contains bytes that are not valid in the current character set, they are replaced by the rubout character. The r subcommand displays the number of bytes read from file unless you specified the –s option. The last line read from the file becomes the new current line. If file is replaced by !, the rest of the line is considered a shell command line, the output of which is to be read. .,.s/regexp/new/[flags] Searches the specified range of lines for strings matching the regular expression regexp. Normally the s subcommand replaces the first such matching string in each line with the string new. The s subcommand sets the current line to the last line on which a substitution occurred. If ed makes no such replacements, ed considers it an error. flags can be one of the following: n Replaces the nth matching string in the line instead of the first one. g Replaces every matching string in each line, not just the first one. l Displays the new current line in the format of the l subcommand. n Displays the new current line in the format of the n subcommand. p Displays the new current line in the format of the p subcommand. You can use any single printable character other than space or newline instead of / to separate parts of the subcommand provided that you use the same character to delimit all parts of the subcommand. You can omit the trailing delimiter. You can include a newline in the new string by putting a \ immediately in front of the newline. This is a good way to split a line into two lines. If new consists only of the % character, s uses the new string from the previous s command. If the variable _UNIX03=YES is set and there was no previous s command, the use of % in this manner is an error. If & appears anywhere in new, ed replaces it with the text matching the regexp. If you want new to contain a literal ampersand, or percent sign, put a backslash (\) in front of the & or % character. .,.ta Copies the addressed lines to the point after the line given by the address Chapter 2. Shell command descriptions 265 ed a. The address a must not fall in the range of addressed lines. If address a is 0, ed copies the lines to the beginning of the buffer. This sets the current line to the last line copied. u Rolls back the effect of the last subcommand that changed the buffer. For the purposes of u, subcommands that change the buffer are: a, c, d, g, G, i, j, m, r, s, t, v, V, and (of course) u. This means that typing u repeatedly switches the most recent change back and forth. This subcommand sets the current line number to the value it had immediately before the subcommand being undone started. 1,$V/regexp/ Is similar to the G subcommand, except that this subcommand gives you the chance to edit only those lines that do not match the given regular expression. 1,$v/regexp/commands Is similar to the g (global) command, except that ed applies the given commands only to lines that do not match the given regular expression. 1,$W [file] Is similar to the w subcommand, except that this command appends data to the given file if the file already exists. 1,$w [file] Writes the addressed lines of the buffer to the named file. This does not change the current line. If you do not provide file, ed uses the remembered filename; if there is no remembered filename, file becomes the remembered name. If the output file does not exist, ed creates it. ed displays the number of characters written unless you had specified the –s option. X Prompts you to enter an encryption key. All subsequent e, r, and w subcommands use this key to decrypt or encrypt text read from or written to files. To turn encryption off, issue an X subcommand and press <Return> in response to the prompt for an encryption key. !command Runs command as if you typed it to your chosen command interpreter. If command contains the % character, ed replaces it with the current remembered filename. If you want a subcommand to contain a literal %, put a backslash (\) in front of the character. As a special case, typing !! reruns the previous command. $= Displays the line number of the addressed line. This does not change the current line. .= Displays the current line number. .+1.,.+1 If you supply zero, one, or two addresses without an explicit subcommand, ed displays the addressed lines in the mode of the last print subcommand: p, l, or n. This sets the current line number to the last line displayed. Environment variables ed uses the following environment variables: 266 COLUMNS Contains the terminal width in columns. ed folds lines at that point. If it is not set, ed uses the appropriate value from the terminfo database or if that is not available, it uses a default of 80. HOME Contains the path name of your home directory. z/OS V1R12.0 UNIX System Services Command Reference ed SHELL Contains the full path name of the current shell. TMPDIR The path name of the directory being used for temporary files. If it is not set, ed uses /tmp. _UNIX03 For more information about the effect of _UNIX03 on this command, see Appendix N, “Shell commands changed for UNIX03,” on page 975. Files ed uses the following files: /tmp/e* This is the paging file. It holds a copy of the file being edited. You can change the directory for temporary files using the environment variable TMPDIR. ed.hup When ed receives a hang up signal (or detects a terminal disconnect) and the current buffer has changed since the last write, ed will attempt to write the current buffer to ed.hup in the current directory. If this write fails, ed will attempt to write the current buffer to ed.hup in the $HOME directory. Localization ed uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 Successful completion Failure due to any of the following: v Addressed line out of range v Only one filename is allowed v No space for the line table v Temporary file error v Badly constructed regular expression v No remembered regular expression v File read error v Out of memory v Unknown command v Command suffix not permitted v No match found for regular expression v Wrong number of addresses for the subcommand v Not enough space after the subcommand v The name is too long v Badly formed name v Subcommand redirection is not permitted v Restricted shell v No remembered filename v The mark name must be lowercase v The mark name is not defined Chapter 2. Shell command descriptions 267 ed 2 v m and t subcommands require a destination address v The destination cannot straddle source in m and t v A subcommand not allowed inside g, v, G, or V v The x subcommand has become X (uppercase) v The global command is too long v Write error (no disk space) Usage error Messages The error messages are issued only if h or H subcommands are used after ed displays ?. Possible error messages include: Destination cannot straddle source in m and t The range of lines being moved or copied by m or t cannot include the destination address. Global command too long There is a limit on the length of a global instruction (g or v). See Limits for this limit. m and t require destination address You must follow the m or t subcommands with an address indicating where you want to move or copy text. You omitted this address. No remembered filename You tried to run a subcommand that used a remembered filename (for example, you used w to write without specifying an output filename). However, there is no remembered filename at present. Run the subcommand again, but specify a filename this time. Restricted shell The command line invoked the restricted form of ed, but you tried an action that was not allowed in the restricted editor (the ! subcommand). Temporary file error You ran out of space on disk or encountered other errors involving the page file stored in the temporary file. Warning: file not saved You entered a subcommand to quit editing the current file, for example, q or e to edit a new file; however, you have changed the file since the last time you saved it. ed is suggesting that you save the file before you exit it; otherwise, your recent changes will be lost. To save the file, use the w command. If you really do not want to save the recent changes, use q to quit or e to edit a new file. ?file An error occurred during an attempt to open or create file. This is applicable to the e, r, and w subcommands. ? An unspecified error occurred. Use the h or H subcommand for more information. If the input to ed comes from a script rather than from a workstation, ed exits when any error occurs. Limits ed allows a limit of 1024 bytes per line and 28 000 lines per file. It does not allow the NUL ('\0') character. The maximum length of a global command is 256 characters, including newlines. 268 z/OS V1R12.0 UNIX System Services Command Reference ed Portability POSIX.2, X/Open Portability Guide, UNIX systems. The addresses < and >, the –b option, and the W and X subcommands are extensions of the POSIX standard. Related information awk, diff, env, ex, grep, sed, vi See Appendix C, “Regular expressions (regexp),” on page 915 for more information about regexp. edcmtext — Display errnojr reason code text Format edcmtext errnojr_value Description edcmtext displays the description and action text for C/C++ run-time library errnojr (errno2) values. No other values are supported by this command. This command is intended as an aid for problem determination. errnojr_value is specified as 8 hexadecimal characters. You can specify one of the following in place of a errnojr value to view a help dialog: -h, help, ?. To display the output in uppercase, specify the -U option. Usage notes errnojr_values are also accepted in mixed case and with hexadecimal digits prefixed with the "0x". Message returns If the user specifies a -h, help or ? in place of the errnojr_value, the following message is displayed: Usage: edcmtext errnojr_value If no text is available for the errnojr_value the following message is displayed: errnojr_value: No information is currently available for this errnojr_value. If the errnojr_value is not comprised of 1-8 hexadecimal digits the following message is displayed: Usage: edcmtext errnojr_value If the errnojr_value is not in the C/C++ run-time library range, the following message is displayed: Notice: The errnjr_value is not in the C/C++ run-time library range. If the environment that edcmtext is being run in is not TSO/E or z/OS UNIX, the following message is displayed: Chapter 2. Shell command descriptions 269 edcmtext Error: The environment is not TSO/E or z/OS UNIX. errnojr (errno2) values will be found in z/OS Language Environment Run-Time Messages. Examples The command: edcmtext C00B0021 produces data displayed in the following format: JrEdc1opsEinval01: The mode argument passed to fopen() or freopen() did not begin with r, w, or a. Action: Correct the mode argument. The first keyword of the mode argument must be the open mode. Ensure the open mode is specified first and begins with r, w, or a. Source: edc1opst.c Exit values 0 Successful completion 2 Failure due to an argument that is not 1–8 hexadecimal digits 8 Bad input due to an errnojr_value out of the C/C++ run-time range. 14 Environment not TSO/E or z/OS UNIX >20 Internal error. Contact IBM. egrep — Search a file for a specified pattern Format egrep [–bcilnqsvx] [–e pattern] ... [–f patternfile] ... [pattern] [file ...] The egrep utility is fully supported for compatibility with older UNIX systems. However, it is recommended that grep –e be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Description See grep. env — Display or set environment variables for a process Format env [–i] [variable=value ...] [command argument ...] env [–] [variable=value ...] [command argument ...] Description If you enter env with no arguments, it displays the environment variable that it received from its parent (presumably the shell). Arguments of the form variable=value let you add new environment variables or change the value of existing environment variables. 270 z/OS V1R12.0 UNIX System Services Command Reference env If you specify command, env calls command with the arguments specified with the argument argument that appear on the command line, passing the accumulated environment variable to this command. The command is run directly as a program found in the search path, and is not interpreted by a shell. In a double-byte locale, environment variable values may contain double-byte characters. The equal sign (=) must be single-byte. Options env supports the following two options, both of which have the same effect. –i Specifies that the environment variable inherited by env not be used. – Specifies that the environment variable inherited by env not be used. Examples Compare the output of the following two examples: env foo=bar env env –i foo=bar env Localization env uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 126 127 Successful completion Failure due to any of the following: v Not enough memory v Name is too long Incorrect command-line argument env found command but could not invoke it env was unable to find command Portability POSIX.2, X/Open Portability Guide, UNIX System V. printenv on Berkeley UNIX systems works like env. Related information env, sh eval — Construct a command by concatenating arguments Format eval [argument ...] tcsh shell: eval argument ... Chapter 2. Shell command descriptions 271 eval Description The shell evaluates each argument as it would for any command. eval then concatenates the resulting strings, separated by spaces, and evaluates and executes this string in the current shell environment. eval in the tcsh shell In the tcsh shell, eval treats the arguments as input to the shell and executes the resulting commands in the context of the current shell. This is typically used to execute commands generated as the result of command or variable substitution, since parsing occurs before these substitutions. See “tcsh — Invoke a C shell” on page 649. Examples The command: for a in 1 2 3 do eval x$a=fred done sets variables x1, x2, and x3 to fred. Then: echo $x1 $x2 $x3 produces: fred fred fred Usage note eval is a special built-in shell command. Localization eval uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit value The only possible exit status value is: 0 You specified no arguments or the specified arguments were empty strings Otherwise, the exit status of eval is the exit status of the command that eval runs. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information exec, sh, tcsh 272 z/OS V1R12.0 UNIX System Services Command Reference ex ex — Use the ex text editor Format | | ex [–BelRrsv] [+command] [–c command] [–t tag] [–w size] [-W option[,option]...] [file ...] Description ex is the line-editor mode of the vi text editor. Options The ex internal commands are described in vi. It supports the following options: +command Begins the editing session by running the specified editor command. To specify multiple commands, separate them with a vertical bar (|). –c command Begins editing by executing the specified editor command. To specify multiple commands, separate them with an “or” bar (|). command can be any ex command except those that enter input mode, such as insert or append. | | –e Invokes ex. This option is intended for use with vi. –l Sets LISP mode. The ( and ) commands use blocks of LISP code as their context rather than sentences. –r Recovers named files after an editor or system fails. If you do not specify a file argument, ex lists all recoverable files and then exits. When using ex -r to recover a file that was being edited with automatic conversion, the file must also be recovered with automatic conversion enabled when writing the data back to the original tagged text file. Likewise, if explicit conversion was being used when editing the file (by using the -W filecodeset or -W pgmcodeset options), the same options must be specified when writing the recovered data back to the original file. Failure to do either of these might result in incorrectly coded character data being written to the file when you save the recovered version. | | | | | | | | –R Sets read-only mode. –s Suppresses all interactive feedback (quiet mode). This is for batch mode operation; ex assumes the terminal cannot display text and ignores the value of TERM. ex also ignores all startup files and ignores the value of EXINIT. –t tag Edits the file containing the specified tag and sets the virtual position in the edit buffer to point of definition for the tag. –v Invokes vi. | | –w size | | | -W option[,option]... Specifies z/OS-specific options. The option keywords are case sensitive. Possible options are: | | Sets the option variable window equal to size. filecodeset=codeset Performs text conversion from one code set to another when Chapter 2. Shell command descriptions 273 ex | | | | | reading from or writing to the file. The code set of the file is codeset. The filecodeset and pgmcodeset options can be used on files with any file tag. codeset can be a character code set name known to the system or a numeric coded character set identifier (CCSID). | | | | | If pgmcodeset is specified but filecodeset is omitted, then the default file code set is ISO8859-1, even if the file is tagged with a different code set. If neither filecodeset nor pgmcodeset is specified, text conversion will not occur unless automatic conversion is enabled. | | | | If filecodeset or pgmcodeset is specified, then automatic conversion is disabled for this invocation of ex and the -B option is ignored if it is also specified. See z/OS UNIX System Services Planning for more information about automatic conversion. | | Restriction: The only supported values for filecodeset are ISO8859-1 and 819. | | | | | | | pgmcodeset=codeset Performs text conversion from one code set to another when reading from or writing to the file. The code set of the editor program is codeset. The filecodeset and pgmcodeset options can be used on files with any file tag. codeset can be a character code set name known to the system or a numeric coded character set identifier (CCSID). | | | | If filecodeset is specified but pgmcodeset is omitted, then the default program code set is IBM-1047. If neither filecodeset nor pgmcodeset is specified, text conversion will not occur unless automatic conversion is enabled. | | | | If filecodeset or pgmcodeset is specified, then automatic conversion is disabled for this invocation of ex and the -B option is ignored if it is also specified. See z/OS UNIX System Services Planning for more information about automatic conversion. | | Restriction: The only supported values for pgmcodeset are IBM-1047 and 1047. File tag specific option | Disables the automatic conversion of tagged files. This option is ignored if the filecodeset or pgmcodeset options (-W option) are specified. –B | | Examples | 1. To edit or browse a file containing ASCII characters using the ex editor, assuming that: v The file is untagged and you do not want to tag it or enable automatic conversion, and v You cannot alter the tag (for example, you are browsing an untagged public file or a read-only file) | | | | | | issue: | | | | | ex -W filecodeset=ISO8859-1,pgmcodeset=IBM-1047 myAsciiFile 2. To edit or browse a file containing EBCDIC characters using the ex editor, assuming that AUTOCVT has been enabled but the file is incorrectly tagged as ASCII, issue: 274 z/OS V1R12.0 UNIX System Services Command Reference ex | ex -B myMisTaggedFile Localization ex uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. | | | | | | | | | Exit values 0 1 2 Successful completion Failure due to any of the following: v Code set is not valid v Could not turn off automatic conversion v Could not perform requested text conversion Failure due to any of the following: v Unknown command-line option v Missing or incorrect num in an –n option Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. Related information ed, vi exec — Run a command and open, close, or copy the file descriptors Format exec [–a name] [command_line] tcsh shell: exec command Description The command_line argument for exec specifies a command line for another command. exec runs this command without creating a new process. Some people picture this action as overlaying the command on top of the currently running shell. Thus, when the command exits, control returns to the parent of the shell. Input and output redirections are valid in command_line. You can change the input and output descriptors of the shell by giving only input and output redirections in the command. For example: exec 2>errors redirects the standard error stream to errors in all subsequent commands ran by the shell. If you do not specify command_line, exec returns a successful exit status. Chapter 2. Shell command descriptions 275 exec In the tcsh shell, exec executes the specified command in place of the current shell. See “tcsh — Invoke a C shell” on page 649. Options –a name The shell passes name as the zero'th argument (argv[0]) to command_line. –a name can be used to replace the current shell with a new login shell, by specifying name as a shell with a prefix of a dash (–). Examples To replace the current shell process with a new login shell (which will run the login profiles), specify: exec -a -sh /bin/sh Usage notes exec is a special built-in shell command. Localization exec uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values If you specify command_line, exec does not return to the shell. Instead, the shell exits with the exit status of command_line or one of the following exit status values: 1–125 A redirection error occurred. 126 The command in command_line was found, but it was not an executable utility. 127 The given command_line could not be run because the command could not be found in the current PATH environment. If you did not specify command_line, exec returns with an exit value of zero. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information sh, tcsh exit — Return to the shell's parent process or to TSO/E Format exit [expression] tcsh shell: exit [expr] 276 z/OS V1R12.0 UNIX System Services Command Reference exit Description exit ends the shell. If there is an expression, the value of the expression is the exit status of the shell. The value of expression should be between 0 and 255. For values outside this range, the exit status will be the least significant 8 bits of the value of the expression. The EXIT trap is raised by the exit command, unless exit is being called from inside an EXIT trap. If you have a shell background job running, you cannot exit from the shell until it completes. However, you can switch to subcommand mode and exit. In the tcsh shell, the shell exits either with the value of the specified expression or, without expression, with the value of the status variable. The value of expression should be between 0 and 255. See “tcsh — Invoke a C shell” on page 649. Usage notes exit is a special built-in shell command. Localization exit uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values exit returns the value of the arithmetic expression specified by the expression argument to the parent process as the exit status of the shell. If you omit expression, exit returns the exit status of the last command run. Related information return, sh, tcsh The exit() ANSI C function, the _exit callable service, and the _exit() POSIX C function are unrelated to the exit shell command. expand — Expand tabs to spaces Format expand [–t tablist] [file ...] expand [–number] [–number,number ...] [file ...] Description expand reads text input from the files specified on the command line, converts tabs into spaces, and writes the result to the standard output (stdout). If you do not specify any files on the command line, expand reads from the standard input (stdin). Chapter 2. Shell command descriptions 277 expand expand preserves backspace characters. By default, tab stops are set every eight columns. A tab after the last tabstop is replaced by a space. Options The first syntax of expand supports the following option: –t tablist Sets tab stops at positions indicated by tablist. Numbers in tablist must be in ascending order (origin 0) and separated by commas or blanks; however, the list must be one argument so you need shell quoting if you are using blanks. The list can consist of a single number, in which case tabs are set every tablist positions apart. The second syntax of expand (which the POSIX standard considers obsolete) supports the following options: –number Sets tab stops every number columns. –number,number ... Sets tab stops at each column number (origin 0). Localization expand uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Cannot open the input file v Insufficient memory v Incorrect tab stop specification Portability POSIX.2 User Portability Extension, X/Open Portability Guide, 4.2BSD and higher. Related information pr, unexpand export — Set a variable for export Format export [ name [=value] ...] export –p 278 z/OS V1R12.0 UNIX System Services Command Reference export Description export marks each variable name so that the current shell makes it automatically available to the environment of all commands run from that shell. Exported variables are thus available in the environment to all subsequent commands. Several commands (for example, cd, date and vi) look at environment variables for configuration or option information. Variable assignments of the form name=value assign value to name as well as marking name for export. The name can contain only the underscore and alphanumeric characters from the portable character set. Calling export without arguments lists, with appropriate quoting, the names and values of all variables in the format Variable="value". If you reinput this format to another shell, variables are assigned appropriately but not exported. The –p option lists variables in a format suitable for reinput to the shell (see the description of the –p option). Options Lists variables in a form that is suitable for reinput to the shell: –p export name="value" Usage notes export is a special built-in shell command. Localization export uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to incorrect command-line argument 2 Failure, usually due to incorrect an incorrect command-line argument, that results in a usage message Portability POSIX.2, X/Open Portability Guide. Assigning a value to name, and the behavior given for calling export with arguments are extensions of the POSIX standard. Related information cd, date, set, sh, typeset, vi Chapter 2. Shell command descriptions 279 expr expr — Evaluate arguments as an expression Format expr –W expression Description The set of arguments passed to expr constitutes an expression to be evaluated. Each command argument is a separate token of the expression. expr writes the result of the expression on the standard output. This command is primarily intended for arithmetic and string manipulation on shell variables. expr supports the following operators. Operators explained together have equal precedence; otherwise, they are in increasing order of precedence. expr stores an expression as a string and converts it to a number during the operation. If the context requires a Boolean value, a numeric value of 0 (zero) or a null string ("") is false, and any other value is true. Numbers have an optional leading sign. If the -W option is not specified, numbers are decimal. If the -W option is specified, expressions may contain octal, hexadecimal, or decimal numbers. expr determines the base of the number as follows: v Any number that starts with 0x is hexadecimal. v Any number that starts with 0 is octal. v Any number that does not start with 0x or 0 is decimal. Numbers are manipulated as long integers. expr1 | expr2 Results in the value expr1 if expr1 is true; otherwise, it results in the value of expr2. expr1 & expr2 Results in the value of expr1 if both expressions are true; otherwise, it results in 0. expr1 <= expr2 | expr1 < expr2 | expr1 = expr2 | expr1 != expr2 | expr1 >= expr2 | expr1 > expr2 If both expr1 and expr2 are numeric, expr compares them as numbers; otherwise, it compares them as strings. If the comparison is true, the expression results in 1; otherwise, it results in 0. expr1 + expr2 | expr1 – expr2 Performs addition or subtraction on the two expressions. If either expression is not a number, expr exits with an error. expr1 * expr2 | expr1 / expr2 | expr1 % expr2 Performs multiplication, division, or modulus on the two expressions. If either expression is not a number, expr exits with an error. expr1 : re | match expr1 re matches the regular expression re against expr1 treated as a string. The regular expression is the same as that accepted by ed, except that the match is always anchored—that is, there is an implied leading ^. Therefore, expr does not consider ^ to be a metacharacter. If the regular expression contains \(...\), \) and it matches at least part of expr1, expr results in only that part; if there is no match, expr results in 0. If the regular expression doesn't contain this construct, the result is the number of characters matched. The function match performs the same operation as the colon operator. 280 z/OS V1R12.0 UNIX System Services Command Reference expr substr expr1 expr2 expr3 Results in the substring of expr1 starting at position expr2 (origin 1) for the length of expr3. index expr1 expr2 Searches for any of the characters in expr2 in expr1 and results in the offset of any such character (origin 1), or 0 if no such characters are found. length expr1 Results in the length of expr1. Groups expressions. (expr) Options Allows the expression to use hexadecimal and octal numbers. –W Usage notes The parser stack depth is limited to 150 levels. Attempting to process extremely complicated expressions may result in an overflow of this stack, causing an error. Examples 1. The example fname=src/fn_abs.c expr $fname : ’*_\(.*\)\.c’ returns abs. 2. The example a=`expr $a + 1` adds 1 to the value of the shell variable a. Localization expr uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 The result of expression is true. 1 The result of expression is false. 2 Failure due to any of following: v Not enough memory. v Command-line syntax error. v Too few arguments on the command line. v Incorrect regular expression. v Regular expression is too complicated. v Nonnumeric value found where a number was expected. Chapter 2. Shell command descriptions 281 expr Messages Possible error messages include: internal tree error Syntax errors or unusual expression complexity make it impossible for expr to evaluate an expression. If an expression has syntax errors, correct them; if not, simplify the expression (perhaps by breaking it into parts). Portability POSIX.2, X/Open Portability Guide, UNIX systems. In the shell, let largely supersedes this command. match, substr, length, and index are not documented on all UNIX systems, though they do appear to exist. They are extensions of the POSIX standard. Related information ed, let, sh, test See Appendix C, “Regular expressions (regexp),” on page 915 for more information about regexp. exrecover daemon — Retrieve vi and ex files Format exrecover [–s] [name_file ...] exrecover [–v] Description The exrecover daemon recovers text files from working files created by vi and ex. (These working files are in one or more temporary directories.) It is normally invoked from a system startup file before these working files are purged. Options –s Suppresses error messages. –v Displays the version number of exrecover. Environment variables exrecover uses the following environment variables: TMP_VI Contains a directory path name that can be specified by an administrator as a location for vi temporary files. This is useful if the current default directory for these files (usually /tmp) is implemented as a TFS. In this case, all vi temporary files that the exrecover daemon uses for recovery would be gone after a system crash. IBM recommends that this environment variable be set by a system administrator as opposed to a user setting it for their environment. If the latter occurs and the user sets the TMP_VI directory to something different than what exrecover recognizes as TMP_VI, the user will need to run the exrecover daemon manually to allow the temporary files to be converted to the recoverable files used by vi (located in /etc/recover/$LOGNAME). 282 z/OS V1R12.0 UNIX System Services Command Reference exrecover daemon Restrictions: The system administrator should not do the following: v Set TMP_VI to /etc/recover/$LOGNAME. v Set TMP_VI to any directory where a path name component is an environment variable with a user's value different than the initialization process's value (for example, $HOME). vi temporary files are converted into a form recoverable by vi when exrecover is run during IPL. Because exrecover is issued during IPL, it is owned by the initialization process and will therefore contain different values for certain environment variables, if those environment variables are set. Throughout the file system, there may exist some temporary files that can only be converted by exrecover. This conversion can be done manually by a system administrator (to recover files owned by all users) or by a single user (to recover only their own files). TMPDIR The default directory. When this environment variable is set, exrecover looks in this directory for the ex and vi working files. TMP If TMPDIR is not set, TMP specifies the directory to be searched when looking for the ex and vi working files. If both TMPDIR and TMP are not set, exrecover uses the directory that the XL C/C++ Run-Time Library function tempnam() would use. Localization exrecover uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Files exrecover uses the following files: /tmp/VIl* Line table files. /tmp/VIn* Name files. /tmp/VIt* Paged text files. /etc/recover The directory containing subdirectories of user names whose files have been recovered. Only users with the appropriate privileges, such as the system administrator, can create the /etc/recover directory. /etc/recover/$LOGNAME/VIn* Contains the name of the file that was being edited. /etc/recover/$LOGNAME/VIt* Contains the recovered text of the file that corresponds to the VIn* file Rule: Using a TFS for vi temporary files will make it impossible to recover vi files after a system crash. vi writes temporary files to TMP_VI or TMPDIR (or /tmp by Chapter 2. Shell command descriptions 283 exrecover daemon default), and if the system crashes, those files can be recovered by the exrecover command, which automatically runs from /etc/rc. If the files are written to a TFS, then they will be wiped out when the system is IPLed. See the TMP_VI description under Environment Variables section of this command. Usage notes 1. To recover all the files in the temporary directory, this command must be run with appropriate permissions (for example, superuser privileges) so the recovered files can be stored in the /etc/recover directory with the appropriate ownerships and permissions. For example, the following is a shell script to recover the files from TMPDIR, where TMPDIR is the default directory: export TMPDIR=/tmp exrecover 2. If it is invoked by a nonprivileged user (for example, a user who is not a root user), then only those files owned by that user are recovered. Because vi and ex create their working files in directories specified by the TMPDIR or TMP environment variables, one of these environment variables must be set before exrecover can be issued. For example, the following is a shell script that recovers files from $HOME/tmp: export TMPDIR=$HOME/tmp exrecover 3. exrecover is also invoked by vi or ex when you issue the ex preserve command or when exrecover receives a SIGHUP signal. The working files created by vi and ex are found in a default temporary directory (such as /tmp) or in the directory specified by the TMPDIR or in the directory specified by the TMP_VI, TMPDIR, or TMP environment variable. Three working files are created: name_file Contains the actual name of the vi file. The names of all name_files begin with VIn. line_table_file Contains a dummy page followed by data that gives, in line number order, the offset for each line of text in the corresponding paged_text_file. The page size is typically 1K, but may vary on some systems. The names of all line table files begin with VIl. paged_text_file Contains lines of text that are at most LINE_MAX bytes in length. Lines shorter than LINE_MAX byte are ended by a newline. The names of all paged text files begin with VIt. 4. You can also run the program by specifying name_file on the command line. For example: exrecover /tmp/VInaaaa.111 /tmp/VInbbbb.222 ... exrecover searches for a name_file and tries to open the associated line table and paged text files. If all these files are found, exrecover builds, from the line table and paged text files, a text file and stores it in the directory /etc/recover/$LOGNAME. It also stores a corresponding name_file to identify the file that was recovered and sends mail, using the mailx utility, to the owner of the file indicating the date, time, and name of the file recovered. You can retrieve recovered files in one of the following ways: 284 z/OS V1R12.0 UNIX System Services Command Reference exrecover daemon vi –r file [issued from a shell command line] ex –r file [issued from a shell command line] :recover file [issued from within a vi session] Each command loads the most recent occurrence of the file recovered from a system failure or the ex preserve command. If vi successfully loads the file, it removes the preserved file. Exit values 0 Successful completion 1 Failure due to any of the following: v Memory allocation error v No working files were found v No /etc/recover directory errors that affect the overall operation of the exrecover command v An incomplete set of working files were found 2 Usage error 3 An error occurred while recovering a specific file. Some, but not all, files were recovered. Related information ex, vi extattr — Set, reset, and display extended attributes for files Format extattr [+alps] [−alps] [-Fformat] file ... Note: l is a lower case L, not an upper case i. Description extattr sets, resets, and displays extended attributes for files. Extended attributes The following extended attributes are defined: a When this attribute is set (+a) on an executable program file (load module), it behaves as if loaded from an APF-authorized library. For example, if this program is exec()ed at the job step level and the program is linked with the AC=1 attribute, the program will be executed as APF-authorized. To be able to use the extattr command for the +a option, you must have at least read access to the BPX.FILEATTR.APF resource in the FACILITY class profile. For more information about BPX.FILEATTR.APF, see z/OS UNIX System Services Planning. l When this attribute is set (+l) on an executable program file (load module), it will be loaded from the shared library region. To be able to use the extattr command for the +l option, you must have at least read access to the BPX.FILEATTR.SHARELIB resource in the FACILITY class. For more information about BPX.FILEATTR.SHARELIB, see z/OS UNIX System Services Planning. Chapter 2. Shell command descriptions 285 extattr Note: l is a lower case L, not an upper case i. p When this attribute is set (+p) on an executable program file (load module), it causes the program to behave as if an RDEFINE had been done for the load module to the PROGRAM class. When this program is brought into storage, it does not cause the environment to be marked dirty. To be able to use the extattr command for the +p option, you must have at least read access to the BPX.FILEATTR.PROGCTL resource in the FACILITY class. For more information about BPX.FILEATTR.PROGCTL , see z/OS UNIX System Services Planning. s When this attribute is not set (–s), the _BPX_SHAREAS=YES and _BPX_SHAREAS=REUSE environment variable settings are ignored when the file is spawn()ed. Use of the _BPX_SHAREAS=MUST setting and the –s option will result in a spawn() failure. By default, this attribute is set (+s) for all executable files. Rule: To specify any of these attributes, the user must be the owner of the file or have superuser authority. Options -F format file ... extattr command will accept the -F option flag with values consistent with the cp command to indicate the format of the file. The command will set the file format accordingly. Setting the file format flag on a file does not modify the data in the file. Use the ls -H to display the file format. For format, you can specify: BIN Binary data CR Carriage return CRLF Carriage return followed by line feed CRNL Carriage return followed by a newline character LF Line feed LFCR Line feed followed by carriage return NA Not specified NL Newline character REC File data consists of records with prefixes. The record prefix contains the length of the record that follows. The format option can be specified in lowercase, uppercase or in mixed cases. The format option can also be specified with a space or no space after the file format flag (-F). For example: extattr -FLFcr file The file format flag (-F) can be used with other extattr flags (+alps/-alps), but it must be separated by a space or tab. For example: extattr +aps -F BIN file is a valid entry. extattr -apsF NA file is not a valid entry. Examples Following are valid examples of the use of extattr: extattr +ap -F BIN -sl <filename> extattr -F NA -aps +l <filename> extattr -FCRnl <filename> 286 z/OS V1R12.0 UNIX System Services Command Reference extattr To have the c89 and tso utilities not run in an address space shared with other processes, issue: extattr -s /bin/c89 /bin/tso Related information ls, ISHELL false — Return a nonzero exit code Format false [argument ...] Description false returns an exit status value of 1 (failure). It ignores any arguments given on the command line. This can be useful in shell scripts. Usage note false is a built-in shell command. Localization false uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit value false always returns an exit status value of 1. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information sh fc — Process a command history list Format fc [–r] [–e editor] [first[last]] fc –l [–nr] [first[last]] fc –s [old=new] [specifier] Description fc displays, edits, and reenters commands that have been input to an interactive shell. fc stands for “fix commands.” If the variable HISTSIZE is not defined, 128 commands are accessible. The number of commands that are accessible is determined by the HISTSIZE variable. Chapter 2. Shell command descriptions 287 fc The shell stores these commands in a history file. When the HISTFILE environment variable is defined as the name of a writable file, the shell uses this as the history file. Otherwise, the history file is $HOME /.sh_history, if HOME is defined and the file is writable. If the HOME variable is not defined, or the file is not writable, the shell attempts to create a temporary file for the history. If a temporary file cannot be created, the shell does not keep a history file. Note: A shell shares history (commands) with all shells that have the same history file. A login shell truncates the history file if it is more than HISTSIZE lines long. Normally, the shell does not keep a history of commands run from a profile file or the ENV file. By default, however, it begins recording commands in the history file when it encounters a function definition in either of these setup files. This means that the HISTSIZE and HISTFILE variables must be set up appropriately before the first function definition. If you do not want the history file to begin at this time, use: set -o nolog For further information, see sh and set. Any variable assignment or redirection that appears on the fc command line affects both the fc command itself and the commands that fc produces. The first form of fc in “Format” on page 287 puts you into an editor with a range of commands to edit. When you leave the editor, fc inputs the edited commands to the shell. The first and last command in the range are specified with first and last. There are three ways to specify a command. v If the command specifier is an unsigned or positive number, fc edits the command with that number. v If the command specifier is a negative number –n, fc edits the command that came n commands before the current command. v If the command specifier is a string, fc edits the most recent command beginning with that string. The default value of last is first. If you specify neither first nor last, the default command range is the previous command entered to the shell. Options –e editor Invokes editor to edit the commands. If you do not specify the –e option, fc assumes that the environment variable FCEDIT, if defined, contains the name of the editor for fc to use. If FCEDIT is not defined, fc invokes ed to edit the commands. 288 –l Displays the command list. This option does not edit or reenter the commands. If you omit last with this option, fc displays all commands from the one indicated by first through to the previous command entered. If you omit both first and last with this option, the default command range is the 16 most recently entered commands. –n Suppresses command numbers when displaying commands. –r Reverses the order of the commands in the command range. z/OS V1R12.0 UNIX System Services Command Reference fc Reenters exactly one command without going through an editor. If a command specifier is given, fc selects the command to reenter as described earlier; otherwise, fc uses the last command entered. To perform a simple substitution on the command before reentry, use a parameter of the form old=new. The string new replaces the first occurrence of string old. fc displays the (possibly modified) command before reentering it. –s Environment variables FCEDIT Contains the default editor to be used if none is specified with the –e option. HISTFILE Contains the path name of the history file. HISTSIZE Gives the maximum number of previous commands that are accessible. Files Used to store temporary files. You can use the TMPDIR environment variable to dictate a different directory to store temporary files. /tmp $HOME/.sh_history This default history file is created. Localization fc uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Usage notes 1. fc is a built-in shell command. 2. r is a built-in alias for fc –s. history is a built-in alias for fc –l. Exit values 0 1 2 If you specified –l, this indicates successful completion. Failure due to any of the following: v Missing history file v Inability to find the desired line in the history file v Inability to create temporary file An incorrect command-line option or argument If fc runs one or more commands, the exit status of fc is the exit status of the last run command. Messages Possible error messages include: Chapter 2. Shell command descriptions 289 fc Cannot create temporary file fc must create a temporary file to do some operations, such as editing. It prints this message when it cannot create its temporary file—for example, because the disk is full. No command matches string You asked to edit a command beginning with a particular string, but there was no such command in the history file. Portability POSIX.2. Related information alias, ed, print, read, sh, vi fg — Bring a job into the foreground Format fg [%job-identifier] tcsh shell: fg [%job ...] Description fg restarts a suspended job or moves a job from the background to the foreground. To identify the job, you give a job-identifier (preceded by %) as given by the jobs command. If you do not specify job-identifier, fg uses the most recent job to be suspended (with the kill command) or placed in the background (with the bg command). fg is available only if you have enabled job control. See the –m option of set for more information. fg in the tcsh shell In the tcsh shell, fg brings the specified jobs (or, without arguments, the current job) into the foreground, continuing each if it is stopped. job may be '', %, +, –, a number, or a string. See also the run-fg-editor editor command described in “tcsh — Invoke a C shell” on page 649. Localization fg uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 >0 290 Successful completion No current job z/OS V1R12.0 UNIX System Services Command Reference fg Messages Possible error messages include: Not a stopped job Job was not stopped. Portability POSIX.2 User Portability Extension. Related information bg, jobs, kill, ps, tcsh fgrep — Search a file for a specified pattern Format fgrep [–bcilnqsvx] [–e pattern] ... [–f patternfile] ... [pattern] [file ...] Note: The fgrep utility is fully supported for compatibility with older UNIX systems. However, it is recommended that grep –f be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Description See grep. file — Determine file type Format file [–BcdEh] [–f filelist] [-M magic] [–m magic] file ... file -i [-h] [–f filelist] file ... Description | file determines the format of each file by inspecting the attributes and (for a regular file) reading the contents of the file. If the file is an executable, its addressing mode is determined for output. If file is not an executable, file compares each file to entries found in one or more magic files to determine their file type. If you specify - as a file name, file reads from the standard input (stdin). file then divides files that do not match a template in the magic file into text files and binary data. Then, by reading the text files and making an informed guess based on the contents, file further divides text files into various types such as C programs, assembler programs, files of commands to the shell, and yacc or lex programs. file displays the name of each file along with the file type. v If the variable _UNIX03=YES is set, a space is used to separate the file name and the type. Chapter 2. Shell command descriptions 291 file v If the variable _UNIX03 is unset or is not set to YES, a tab is used to separate the file name and the file type. The file utility uses three types of tests to determine the file type: the file attribute tests, the position-sensitive tests and the context-sensitive tests. v The "file attribute tests" determine file types such as directory, character special, FIFO, socket, symbolic link, and external link. v The "position-sensitive tests" determine file types by looking for certain string or binary values at specific offsets in the file being examined. The "default position-sensitive tests" are defined by: – The /etc/magic file – The AMODE test built into the file utility If a magic file test succeeds, the message field of the line will be printed and no further tests will be applied, except for tests on immediately following lines beginning with a single '>' character. v The "default context-sensitive tests" are built into the file utility. These tests look for language constructs in text files trying to identify shell scripts, C, FORTRAN, and other computer language source files, and even plain text files. The "default context-sensitive tests" will never be applied before any "position-sensitive tests" even if the -d option is specified before an -m magic option or -M magic option. Options –B Disables the automatic conversion of tagged files. –c Only checks the file magic (specified by -m or -M) and /etc/magic (If the semantics imply it, see the usage notes for the validity of the format. -d Apply any default position-sensitive tests and default context-sensitive tests to the file. This is the default if no -M or -m option is specified. See the usage notes for more information. -E Uses the magic file and bypasses the checking of regular files for executables. –f filelist Examines the files listed in the file filelist. -h When a symbolic link is encountered, identify file as a symbolic link instead of following the link. If -h is not specified and file is an external link or file is a symbolic link referring to a nonexistent file: If the variable _UNIX03=YES is set The type will be reported as if -h was specified. If the variable _UNIX03 is unset or is not set to YES The type will be reported as if -h was not specified. -i If file is a regular file, does not attempt to classify the type of the file further. This option can only be used with -h and -f options. "Usage Note" for the file types that file command does not attempt to classify. –M magic Uses the file magic to classify the file type. No default position-sensitive 292 z/OS V1R12.0 UNIX System Services Command Reference file tests, default context-sensitive tests, nor AMODE tests shall be applied, unless the -d option is also specified. See the usage notes for more information. –m magic Alters the classification of regular files when examining the file content. If the variable _UNIX03=YES is set Then file attempts to classify the file type using the following tests, in order: 1. Using the file magic. 2. Using the default position-sensitive tests (/etc/magic ). 3. Using the default context-sensitive tests built into the file command. If the variable _UNIX03 is unset or is not set to YES Then file attempts to classify the file type using the following tests, in order: 1. Using the file magic rather than /etc/magic. 2. Using the default context-sensitive built into the file command. Environment variable file uses the following environment variable: v _UNIX03 See Appendix N, “Shell commands changed for UNIX03” for more information about the effect of _UNIX03 on this command. Localization file uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization,” on page 937 for more information. Files file uses the following file: /etc/magic Default system magic file. For file to work, you need to copy the magic file from the /samples directory to the /etc directory. For more information about enabling file, see the section on copying configuration files in z/OS UNIX System Services Planning. Additional information about the magic file can be found in “magic — Format of the /etc/magic file” on page 944. Usage notes 1. LC_SYNTAX only affects the interpretation of the input file that did not match any magic file template. It does not affect the interpretation of the magic file. Chapter 2. Shell command descriptions 293 file Because of this, an input file that contains characters from a code page other than IBM-1047 cannot match the magic file, which contains IBM-1047 characters. If you need to match character in different code pages, you can use -m or -M to specify a magic file created with the desired code page. 2. The tests applying to a file when running the command follow the rules outlined in Table 11. Table 11. file command tests Then the position-sensitive tests are applied in the following sequence... Default contextsensitive tests applied? AMODE > /etc/magic Yes -d AMODE > /etc/magic Yes -M MAGIC MAGIC No If the following options are specified... -m magic If the variable _UNIX03=YES is set, Yes magic > AMODE > /etc/magic If the variable _UNIX03 is unset or is not set to YES, AMODE > magic -d -M MAGIC AMODE > /etc/magic > MAGIC Yes -M MAGIC -d MAGIC > AMODE > /etc/magic Yes -d -m magic AMODE > /etc/magic > magic Yes -m magic -d magic > AMODE > /etc/magic Yes -M MAGIC -m magic MAGIC > magic No -m magic -M MAGIC magic > MAGIC No -d -M MAGIC -m magic AMODE > /etc/magic > MAGIC > magic Yes -d -m magic -M MAGIC AMODE > /etc/magic > magic > MAGIC Yes -M MAGIC -d -m magic MAGIC > AMODE > /etc/magic > magic Yes -M MAGIC -m magic -d MAGIC > magic > AMODE > /etc/magic Yes -m magic -d -M MAGIC magic > AMODE > /etc/magic > MAGIC Yes -m magic -M MAGIC -d magic > MAGIC > AMODE > /etc/magic Yes Notes: a. The first column specifies the appearance of the -d, -M and -m options in the command line. b. The second column gives what position-sensitive tests are applied and in what sequence, given the options specified in the first column: v AMODE is a default position-sensitive system test which is only used on an executable file to determine the addressing mode. v "/etc/magic" means the default position-sensitive tests in /etc/magic. v "MAGIC" means the position-sensitive tests in the magic file specified by "-M". v "magic" means the position-sensitive tests in the magic file specified by "-m". v Tests not appearing in the cell are not applied. 294 z/OS V1R12.0 UNIX System Services Command Reference file c. The third column gives whether the default context-sensitive tests (built into the file command) are applied, given the options specified in the first column. 3. If -d option is specified together with -E option, the AMODE tests will not be applied. If -M magic option is specified alone, the AMODE tests will not be applied. 4. The standard output messages of file utility will contain the specified strings, but not limited to, listed in Table 12. Table 12. Output messages of the file utility If file is: Will contain the string: See note Nonexistent Cannot open None Block special Block special a Character special Character special a Directory Directory a FIFO Fifo a Socket Socket a Symbolic link Symbolic link to a External symbolic link External link to a Regular file Regular file a,b Empty regular file Empty c Regular file that cannot be read Cannot open c Executable binary Executable d,f ar archive library (see ar ) Archive d,f Extended cpio format (see pax) cpio archive d,f Extended tar format (ustar in tar archive pax) d,f Shell script Commands text e,f C-language source C program text e,f FORTRAN source Fortran program text e,f Regular file whose type cannot be determined Data None Notes: a. This is a file attribute test. b. This test is applied only if the -i option is specified. c. This test is applied only if the -i option is not specified. d. This is a default position-sensitive test. e. This is a default context-sensitive test. f. Default position-sensitive tests and default context-sensitive tests are not applied if the -M magic option is specified unless the -d option is also specified. Exit values 0 Successful completion Chapter 2. Shell command descriptions 295 file 1 Failure due to any of the following: v A missing filelist after –f v More than one –f option on the command line v Cannot find the magic file v Incorrect command-line option v Too few command-line arguments v Cannot access a specified file v Cannot open filelist v Cannot open the magic file v A format error in the magic file v Out of memory for reading or magic entries v A bad number in the magic file v A misplaced > in the magic file. Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. All options are extensions to the POSIX standard. Related information “magic — Format of the /etc/magic file” on page 944 for more information about the magic file format. find — Find a file meeting specified criteria Format find path ... expression Description find searches a given file hierarchy specified by path, finding files that match the criteria given by expression. Each directory, file, and special file is “passed through” expression. If you use the -exec, -ok, or -cpio primary, expression runs a specified command on each file found. A nonexistent expression or an expression with commands to run automatically uses the -print primary to display the name of any file that matches the criteria of expression. find builds expression from a set of primaries and operators; juxtaposition of two primaries implies a logical AND operator. Operators and primaries find supports the following operators: –a Used between primaries for a logical AND. You can omit this operator to get the same result, because logical AND is assumed when no operator is used between two primaries. –o Used between primaries for a logical OR. ! Precedes an expression in order to negate it. Rules: When using the find command, follow these rules: v When grouping primaries and operators using parentheses, you must escape the parentheses with the \ (backslash) character if the command is being executed in the shell environment. 296 z/OS V1R12.0 UNIX System Services Command Reference find v You must delimit all primaries, operators, numbers, arguments, and parentheses with white space. Each number in the primary list is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than” and a minus sign implies “less than” or “newer than”. Options This section lists the primaries that find supports. Tip: If you use the ACL primaries, with the exception of -acl, performance might be affected. –aaudit auditmask The -aaudit primary is used to match the auditor audit bits. See –audit auditmask. -acl c Matches if the type of ACL is the same as the type given by the character c. Possible values of the character are: a Access ACL (matches only if there are extended ACL entries) d Directory default ACL f File default ACL If acl c is not defined, then find matches any of these ACLs when other ACL primaries are used. -acl_count number Matches if the numbers of extended ACL entries for any of the types of ACLs for the object is number. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. -acl_entry acl_text Matches if the ACL on the file contains an entry equivalent to acl_text where acl_text is a single extended ACL entry. This primary matches using user and group names rather than UID and GID numbers. If aliases exist for a name, then it is possible a match may not occur. This behavior is different than the -acl_user and -acl_group primaries which match based on UID and GID. Extended ACL entries have the following format: [d[efault]: | f[default]:]u[ser]:uid:[+|^]perm [d[efault]: | f[default]:]g[roup]:gid:[+|^]perm where: d[efault] If specified, extended ACL refers to directory default ACL f[default] If specified, extended ACL refers to file default ACL u[ser] Extended ACL refers to a particular numeric user ID (UID) or user name g[roup] Extended ACL refers to a particular numeric group ID (GID) or group name uid User name or numeric user ID (UID) gid Group name, or numeric group ID (GID) Chapter 2. Shell command descriptions 297 find perm Permissions specified either in absolute form (string rwx with - as a placeholder or octal form), or in relative format (using the + or^ modifiers). Rule: For relative permission settings, specifying “+perm” means that you want the ACL entry to have that permission turned on. Specifying “^perm” means that you want the ACL entry to have that permission off. For example, specifying the following will find files with an extended access ACL entry for user Billy in which the permissions are either -w- or rw-: user:Billy:+w^x If the permission field of acl_text is omitted, then the ACL entries are searched to match only the ACL type, and user or group portions of the user-supplied entry. If you want to find any of the base ACL entries (user, group, or other), you can use the -perm primary. The first field of an ACL entry may specify the type of ACL (access, directory default, or file default) that will be processed. If the type is not specified, the operation applies only to the access ACL. If you are updating the ACL entries, you can specify the base ACL entries; however, specifying the base ACL entries may cause the file or directory's permission bits to change if what is specified is different than the current settings. -acl_group groupid Matches if the object has an extended group ACL entry for groupid. groupid can also be a group ID number. If your security product supports ACLs, the group base ACL entry can be matched using this primary. If a numeric group exists as a group name in the group data base, the group ID number associated with that group is used. -acl_nogroup Matches if a group ACL entry (for any type of ACL) exists in which a group is not defined. The GID for at least one extended ACL entry for the file does not have a group name associated with it. -acl_nouser Matches if a user ACL entry (for any type of ACL) exists in which a user is not defined. The UID for at least one extended ACL entry for the file does not have a user name associated with it. -acl_user userid Matches if the ACL of the object has an extended user ACL entry for userid. userid can also be a user ID number. If a numeric owner exists as a user name in the user data base, the user ID number associated with that user name is used. If your security product supports ACLs, the user base ACL entry can be matched, using this primary. –atime number Matches if someone has accessed the file exactly number days ago. 298 z/OS V1R12.0 UNIX System Services Command Reference find number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –audit auditmask The -audit primary is used to match the user audit bits. auditmask can be in octal or in symbolic form. The mask can be preceded by a - character (as in the perm primary), but it is ignored. Symbolic form is an operation=condition list, separated by commas: [rwx]=[sf] where: =sf Success or failure on any of rwx r=s Success on read r=s, x=sf Success on read or exec, failure on exec r, w=s Incorrect syntax x Incorrect syntax Octal form is specified by using the chaudit bit constant definitions in the /usr/include/sys/stat.h header file. For example, in stat.h, the flag for failing read accesses is AUDTREADFAIL. It is defined to be 0x02000000, which has an octal value of 200000000. This octal value can be used as the auditmask to find failure on read. –cpio cpio-file Writes the file found to the target file cpio-file in cpio format. This is equivalent to: find ... | cpio -o >cpio-file This primary matches if the command succeeds. –ctime number Matches if someone has changed the attributes of the file exactly number days ago. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –depth Processes directories after their contents. If present, this primary always matches. –exec command ; Takes all arguments between –exec and the semicolon as a command line, replacing any argument that is exactly {} (that is, the two brace characters) with the current file name. It then executes the resulting command line, treating a return status of zero from this command as a successful match, nonzero as failure. You must delimit the terminal semicolon with white space. Rule: The semicolon is a shell metacharacter. To use it in expression, you must escape it, either by enclosing it in single quotation marks or by preceding it with /. Chapter 2. Shell command descriptions 299 find –ext c Matches when the regular file has the extended attribute specified by character c. See “extattr — Set, reset, and display extended attributes for files” on page 285 for details on extended attributes. Possible values of the character are: a Program runs APF authorized if linked AC = 1 l Program is loaded from the shared library region p Program is considered program-controlled s Program is allowed to run in a shared address space –follow Follows symbolic links. If present, this primary always matches. –group name Matches if the group owner is name. If name is not a valid group name, it is treated as a group ID. –inum number Matches if the file has inode number number. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –level number Does not descend below number levels. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –links number Matches if there are number links to the file. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –mtime number Matches if someone has modified the file exactly number days ago. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality; a plus sign implies “greater than” or “older than,” and a minus sign implies “less than” or “newer than”. –name pattern Compares the current file name with pattern. If there is no match, the expression fails. The pattern uses the same syntax as file name generation (see sh). It matches as many trailing path name components as specified in pattern. Slashes in the pattern are matched explicitly. –ncpio cpio-file Writes the file found to the target file cpio-file in cpio –c format. This is equivalent to: find ... | cpio -oc >cpio-file This primary matches if the command succeeds. 300 z/OS V1R12.0 UNIX System Services Command Reference find –newer file Compares the modification date of the found file with that of the file given. This matches if someone has modified the found file more recently than file. –nogroup Matches if no defined group owns the file. –none Indicates that some action has been taken; thus find does not invoke the default –print action. If present, this primary always matches. –nouser Matches if no defined user owns the file. –okcommand; Is similar to –exec, but before find executes the command, it displays the command to confirm that you want to go ahead. find executes the command line only if your input matches the expression for “yes” (yes and no expressions are defined in LC_MESSAGES). If you type the expression for “no”, the primary does not match. You must delimit the terminal semicolon with white space. Rule: The semicolon is a shell metacharacter. To use it in expression, you must quote it. –perm[-] mask By default, matches if the permissions on file are identical to the ones given in mask. You can specify mask in octal or in symbolic mode (see chmod). If you use symbolic mode, find assumes that you begin with no bits set in mask, and that the symbolic mode is a recipe for turning the bits you want on and off. A leading minus sign (−) is special. It means that a file matches if at least all the bits in mask are set. As a result, with symbolic mode, you cannot use a mask value that begins with a minus sign (−). If you use octal mode, find uses only the bottom 12 bits of mask. With an initial minus sign (−), find again matches only if at least all the limits in mask are set in the file permissions lists. –print Displays the current file name. This primary always matches. –prune Stops searching deeper into the tree at this point. If present, this primary always matches. –prune has no effect if –depth is also specified. –seclabel pattern Compares the file's security label with pattern. If there is no match, the expression fails. The pattern uses the same syntax as file name generation (see “File name generation” on page 586). –size number[c] Matches if the size of the file is number blocks long, where a block is 512 bytes. If you include the suffix c, the file size is number bytes. number is a decimal number, optionally preceded by a plus or minus sign. If a number is given without a sign, find tests for equality. A plus sign implies “greater than” or “older than” while a minus sign implies “less than” or “newer than.” –type c Matches if the type of the file is the same as the type given by the character c. Possible values of the character are: b Block special file (not supported for z/OS UNIX System Services) Chapter 2. Shell command descriptions 301 find c d f l n p s Character special file Directory Regular file Symbolic link Network file FIFO (named pipe) Socket –user name Matches if the owner of the file is name. name can also be a user ID number. –xdev Does not cross device boundaries from the root of the tree search. If present, this primary always matches. File Tag Specific Options –filetag c Matches if the file tag is the same as the one given by character c. Possible values of the character are: b Matches if the file is tagged as binary (txtflag = OFF and ccsid = 0xFFFF) n Matches if the file has txtflag = OFF t Matches if the file is tagged as text (txtflag = ON) u Matches if the file is untagged (ccsid = 0) –filetag_codeset codeset Matches if the file is tagged with the given code set Note: Code sets which are aliases of each other exist which may cause the test to fail, because the file inquiry operator may return an alias of the code set you are testing. Examples 1. To find all files with a suffix of .c that have the audit mode set to rwx (read, write, execute), issue: find / –name "*.c" –audit rwx=sf The quotes are required around the "*.c" if you do not want the shell to expand this value to all files with a suffix of .c from within the current directory. 2. To find all files with a suffix of .c and audit mode bits set to 777 (rwx), issue: find / –name "*.c" –audit 777 3. To find all files with the extensions .c and .h, starting at the current point in the directory hierarchy: find . –name "*.[ch]" 4. To find all files that have the extension .Z and that have not been accessed in the last three days: find . –name "*.Z" –mtime +3 5. To find all files that have a security label of OS390: find . -seclabel OS390 6. To find all files that have a security label starting with OS390: find . -seclabel "OS390*" 7. To find all files that have no security labels: find . ! -seclabel "*" 302 z/OS V1R12.0 UNIX System Services Command Reference find 8. To find all files and directories starting at the current directory point, with an extended ACL user entry for user Billy for any ACL (access, file default, or directory default), issue: find . -acl_user Billy or find . -acl_entry user:Billy -o -acl_entry d:u:Billy -o -acl_entry f:u:Billy 9. To find all files and directories (starting from the current directory) that have more than 10 extended ACL entries for any of the ACL types, issue: find . -acl_count +10 10. To find all files and directories containing access ACLs which have an extended ACL entry for user Averi, starting from the current user's home directory: find ~ -acl_entry user:Averi 11. To find all directories whose file default ACLs have a group entry for Lakers, starting at the current point in the directory hierarchy: find . -acl_entry fdefault:group:Lakers 12. To find all files for user Marc (in other words, all the files that Marc owns), starting from his home directory: find /u/marc -user marc 13. To find all directories (starting from current directory) which have file default ACLs: find . -acl f 14. To find all directories whose file default or directory default ACLs have a group entry for Lakers, starting at the current point in the directory hierarchy: find . -acl_entry fdefault:group:Lakers -o -acl_entry default:group:Lakers Localization find uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 Successful completion Failure due to any of the following: v Not enough memory v Incorrect character specified after –type v Inability to get information about a file for –newer v Incorrect permissions for –perm v Inability to open a file for the –cpio option v Unknown user or group name v Unable to access the PATH variable v Cannot run a command specified for –exec or –ok v Syntax error v Stack overflow caused by an expression that is too complex Chapter 2. Shell command descriptions 303 find 2 Failure due to one of the following: v Incorrect command-line option v Not enough arguments on the command line v Missing option v Argument list that is not properly ended Messages Possible error messages include: bad number specification in string You specified an option that takes a numeric value (for example, –atime, –ctime) but did not specify a valid number after the option. cannot stat file name for -newer You used a –newer option to compare one file with another; however, find could not obtain a modification time for the specified file. Typically, this happens because the file does not exist or you do not have appropriate permissions to obtain this information. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Most UNIX systems do not have a default action of –print. Therefore, they do not need the –none option. The –a operator is not documented on many UNIX systems. The following primaries are extensions of the POSIX standard: –aaudit, –acl, –acl_count, –acl_entry, –acl_group, –acl_nogroup–acl_nouser, –acl_user, –audit, –audit, –cpio, –follow, –level, –ncpio, –none The aaudit and audit options are unique to the z/OS shell. Related information chaudit, chmod, cpio, sh filecache — Manage file caches The filecache command manages the kernel file cache for files that are only read. While it continues to be shipped in /usr/sbin/filecache, the filecache command is not operational and will not return any cached data. fold — Break lines into shorter lines Format fold [–bs] [–w width] [–width] [file...] Description fold reads the standard input (stdin) or each file, if you specify any. Each input line is broken into lines no longer than width characters. If you do not specify width on the command line, the default line length is 80. The output is sent to the standard output (stdout). 304 z/OS V1R12.0 UNIX System Services Command Reference fold Options –b Specifies width in bytes rather than in column positions; that is, fold does not interpret tab, backspace, and carriage return characters. If the last byte specified by width is part of a double-byte character, fold does not break the character. Instead, the line is broken before the double-byte character. –s Breaks each line at the last blank within width column positions. If there is no blank that meets the requirement, fold breaks the line normally. –w width Specifies a maximum line length of width characters. –width Is identical in effect to –w width. Localization fold uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion Failure because the input file could not be opened Invalid command-line option or a missing width argument Portability POSIX.2, 4.2BSD. The –width option is an extension of the POSIX standard. Related information pr functions — Display or assign attributes to functions Format functions [*tux][name ...] Note: * indicates a + or – character. Description functions is an alias for typeset –f. See “typeset — Assign attributes and values to variables” on page 742 for more information. Related Information typeset, sh Chapter 2. Shell command descriptions 305 fuser fuser — List process IDs of processes with open files Format fuser [–cfku] file ... Description The fuser command writes to standard output the process IDs of all processes running on the local system that have one or more named files open. file is the path name of the file for which information is to be reported, or, if the –c options is used, the path name of a file on the file system for which information is to be reported. It also writes additional information to standard error, such as the user name of the process and a character indicating how the process is using the file. fuser only reports on local processes, not remote ones.It only reports information for processes that the user has appropriate privileges to access. Only a superuser can access information for processes that belong to another user. Options –c Reports on all open files within the file system that the specified file is a member of –f Reports on only the named files. This is the default. –k Sends the SIGKILL signal to each local process (with the exception of the fuser process and parent processes of fuser). Only a superuser can terminate a process that belongs to another user. This option is a z/OS extension. –u Writes to standard error the user name associated with each process ID written to standard output. Usage notes fuser writes the process ID for each process to standard output. fuser also writes the following to standard error: v The path name of each file specified on the command line. v An indicator of how the process is using this file (written after the process ID): –c The process is using the file as its current directory. –r The process is using the file as its root directory. If no character follows the PID, this means that the process has the file open. v When the –u option is specified, fuser writes the user name corresponding to the process' real user ID. Examples 1. To list the process numbers of local processes using the /etc/magic file, enter: fuser /etc/magic which will give you the following output: /etc/magic: 67109274 144 2. To display the user names associated with the processes accessing the file /etc/magic: fuser -u /etc/magic 306 z/OS V1R12.0 UNIX System Services Command Reference fuser Your output would be: /etc/magic: 67109274(Steve) 144(Fred) 3. To terminate all of the processes using a given file system, enter either the mount point name or the name of a file in that file system: fuser -ku /u/home or fuser -kuc /u/home/code Your output would look like: /u/home/code: 111111c(Steve) 222222r(Erin) 333333(Garth) 444444c(Steve) 555555r(Renata) 66666c(Angie) This command lists the process number and user name, and then sends a kill signal to each process that is using the /u/home file system. Only a superuser can terminate processes that belong to another user. You might want to use this command if you are trying to unmount the /u/home file system and a process that is accessing the file system prevents this. Exit values 0 1 Successful completion An error occurred Related information kill, ps gencat — Create or modify message catalogs Format gencat CatalogFile MessageFile ... Description gencat merges the message text source files MessageFile (typically *.msg) into a formatted message catalog CatalogFile (typically *.cat). The file CatalogFile is created if it does not already exist. If CatalogFile does exist, its messages are modified according to the directives in the MessageFiles. If set and message numbers are the same, the new message text defined in MessageFile replaces the message text defined in CatalogFile. You can specify any number of MessageFiles. gencat processes the MessageFiles one after another, in the sequence specified. Each successive MessageFile modifies the CatalogFile. If – is specified for CatalogFile, standard output (stdout) is used. If – is specified for MessageFile, standard input (stdin) is used. gencat does not accept symbolic message identifiers. You must use mkcatdefs if you want to use symbolic message identifiers. Extended description The format of a message text source file is defined as follows. All characters must be encoded as single-byte characters except where noted. The fields of a message Chapter 2. Shell command descriptions 307 gencat text source line are separated by a single blank character. Any other blank characters are considered as being a part of the subsequent field. $set n comment Specifies the set identifier of the following messages until the next $set or end of file appears. The n denotes the set identifier, which is defined as a number in the range 1–NL_SETMAX. Set identifiers must be in ascending order within a single source file, but need not be contiguous. Any string following the set identifier is treated as a comment. If no $set directive is specified in a message text source file, all messages are located in default message set NL_SETD. $delset n comment Deletes message set n from an existing message catalog. The n denotes the set number, 1–NL_SETMAX. Any string following the set number is treated as a comment. $ comment A line beginning with $ followed by a blank character is treated as a comment. m message-text The m denotes the message identifier, which is defined as a number in the range 1–NL_MSGMAX. Message identifiers must be in ascending order within a single set, but need not be contiguous. The length of message-text must be in the range –NL_TEXTMAX. The message text is stored in the message catalog with the set identifier specified by the last $set directive, and with message identifier m. If the message text is empty, and a blank character field separator is present, an empty string is stored in the message catalog. If a message source line has a message number, but not a field separator or message text, the existing message with that number (if any) is deleted from the catalog. The message text can contain double-byte characters. $quote c Specifies an optional quote character c, which can be used to surround message-text so trailing spaces or null (empty) messages are visible in a message source line. By default, or if an empty $quote directive is supplied, no quoting of message-text is recognized. The quote character can be a double-byte character. $timestamp Specifies a time stamp that can be used to identity the subsequent .cat file as having come from this file. The timestamp can be up to 20 characters long and can be any format you wish. Typically it follows this format: $timestamp 1994 137 19:09 UTC The mkcatdefs command automatically generates a timestamp in the file it creates for input to gencat. Empty lines in a message text source file are ignored. Lines starting with any character other than those defined are considered invalid. Text strings can contain the special characters and escape sequences defined in the following table: Description Backspace backslash 308 z/OS V1R12.0 UNIX System Services Command Reference Sequence \b \ gencat Description Carriage-return Double quotation mark Form-feed Horizontal tab Newline Octal bit pattern Vertical tab Sequence \r \" \f \t \n \ddd \v These sequences must be encoded as single-byte characters. The escape sequence \ddd consists of backslash followed by one, two, or three octal digits, which are taken to specify the value of the desired character. If the character following a backslash is not one of those specified, the backslash is ignored. A backslash (\) followed by a newline character is also used to continue a string on the following line. Thus the following two lines describe a single message string: 1 This line continues \ to the next line which is equivalent to: 1 This line continues to the next line Portability of message catalogs gencat works with the z/OS XL C/C++ runtime library function catgets() to correctly display message text in the locale that the C program using catgets() is running in. gencat adds information to the CatalogFile about the codeset that was in effect when gencat processed the CatalogFile. gencat should be run with the same locale that the recipients of the messages will be using. This should be the same locale that was used to create the message text in MessageFile. Message catalogs produced by gencat are binary-encoded, meaning that their portability cannot be guaranteed between systems. Thus, just as C programs need to be recompiled, so message catalogs must be re-created via gencat when moved to another system. Example To generate a test.cat catalog from the source file test.msg, enter: gencat test.cat test.msg Localization gencat uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Chapter 2. Shell command descriptions 309 gencat Exits Successful completion An error occurred 0 1 Portability X/Open Portability Guide. getconf — Get configuration values Format getconf –a getconf system_var getconf [–a] path_var pathname Description getconf writes the value of a configuration variable to the standard output (stdout). You can specify the configuration variable using one of forms listed in the Format section. If you use the first form, getconf writes the value of the variable system_var. If you use the second form, getconf writes the value of the variable path_var for the path name given by pathname. The –a option prompts getconf to display all current configuration variables, and their values, to stdout. getconf writes numeric values in decimal format and nonnumeric values as simple strings. If the value is not defined, getconf writes the string undefined to stdout. Options –a Writes out all the configuration variables for the current system, and their values, to stdout. Path variables are written based on a path name of dot (.). Configuration variables You can use the second form of getconf to find the value of the following POSIX.1-1990 standard configuration variables for the specified path name: LINK_MAX Specifies the maximum number of links that this file can have. MAX_CANON Specifies the maximum number of bytes in the workstation's canonical input queue (before line editing). MAX_INPUT Specifies the space available in the workstation's input queue. NAME_MAX Specifies the largest filename size. PATH Specifies the standard PATH setting. _CS_PATH Specifies the standard PATH setting. PATH_MAX Specifies the maximum number of bytes in a path name. 310 z/OS V1R12.0 UNIX System Services Command Reference getconf PIPE_BUF Specifies the largest atomic write to a pipe. _POSIX_CHOWN_RESTRICTED Specifies the restrictions that apply to file ownership changes. _POSIX_NO_TRUNC If set, it is an error for any path name component to be longer than NAME_MAX bytes. _POSIX_VDISABLE Specifies that processes are allowed to disable ending special characters. You can use the first form of getconf to find the value of the following POSIX.1-1990 standard configuration variables: ARG_MAX Specifies the maximum length of arguments for running a program, including environment data. CHILD_MAX Specifies the maximum number of simultaneous processes allowed per real user. CLK_TCK Specifies the number of intervals per second in the machine clock. NGROUPS_MAX Specifies the number of simultaneous group IDs per process. OPEN_MAX Specifies the maximum number of open files at any time per process. STREAM_MAX Specifies the number of streams that one process can have open at one time. TZNAME_MAX Specifies the maximum number of bytes supported for the name of a time zone (not of the TZ variable). _POSIX_ARG_MAX Specifies the minimum conforming value for ARG_MAX. _POSIX_CHILD_MAX Specifies the minimum conforming value for CHILD_MAX. _POSIX_JOB_CONTROL Specifies the POSIX job control supported. _POSIX_LINK_MAX Specifies the minimum conforming value for LINK_MAX. _POSIX_MAX_CANON Specifies the minimum conforming value for MAX_CANON. _POSIX_MAX_INPUT Specifies the minimum conforming value for MAX_INPUT. _POSIX_NAME_MAX Specifies the minimum conforming value for NAME_MAX. _POSIX_NGROUPS_MAX Specifies the minimum conforming value for NGROUPS_MAX. Chapter 2. Shell command descriptions 311 getconf _POSIX_OPEN_MAX Specifies the minimum conforming value for OPEN_MAX. _POSIX_PATH_MAX Specifies the minimum conforming value for PATH_MAX. _POSIX_PIPE_BUF Specifies the minimum conforming value for PIPE_BUF. _POSIX_SAVED_IDS Specifies that processes have saved set-user-ID and saved set-group-ID bits set. _POSIX_SSIZE_MAX Specifies the value that can be stored in an object of type ssize_t. _POSIX_STREAM_MAX Specifies the minimum conforming value for STREAM_MAX. _POSIX_TZNAME_MAX Specifies the minimum conforming value for TZNAME_MAX. _POSIX_VERSION Specifies the version of POSIX adhered to in this release. You can use the first form of getconf to find the value of the POSIX.2 standard configuration variables: BC_BASE_MAX Specifies the maximum ibase and obase values for the bc command. BC_DIM_MAX Specifies the maximum number of elements permitted in a bc array. BC_SCALE_MAX Specifies the maximum scale size allowed in bc. BC_STRING_MAX Specifies the maximum number of characters in a string in bc. COLL_WEIGHTS_MAX Specifies the maximum number of weights assignable to an entry of the LC_COLLATE order keyword. EXPR_NEST_MAX Specifies the maximum number of expressions that you can nest inside parentheses in an expression evaluated by expr. LINE_MAX Specifies the maximum number of bytes that a utility can accept as an input line (either from the standard input or a text file) when the utility takes text files as input. This number includes the trailing <newline>. RE_DUP_MAX Specifies the maximum number of repeated occurrences of a regular expression when using the interval notation \{m,n\}. See Appendix C, “Regular expressions (regexp),” on page 915 for more information. POSIX2_C_BIND Indicates if the system supports the C Language Bindings Option. 312 z/OS V1R12.0 UNIX System Services Command Reference getconf POSIX2_C_DEV Indicates if the system supports the C Language Development Utilities Option. POSIX2_FORT_DEV Indicates if the system supports the FORTRAN Development Utilities Option. POSIX2_FORT_RUN Indicates if the system supports the FORTRAN Runtime Utilities Option. POSIX2_LOCALEDEF Indicates if the system supports the creation of locales. POSIX2_SW_DEV Indicates if the system supports the Software Development Utilities Option. POSIX2_CHAR_TERM Indicates if the system supports at least one terminal type capable of all operations necessary for the User Portability Utilities Option. This parameter name is correct only on if POSIX2_UPE is on. POSIX2_UPE Indicates if the system supports the User Portability Utilities Option. POSIX2_VERSION Specifies the version of POSIX.2 adhered to in this release. POSIX2_BC_BASE_MAX Specifies the minimum conforming value for BC_BASE_MAX. POSIX2_BC_DIM_MAX Specifies the minimum conforming value for BC_DIM_MAX. POSIX2_BC_SCALE_MAX Specifies the minimum conforming value for BC_SCALE_MAX. POSIX2_BC_STRING_MAX Specifies the minimum conforming value for BC_STRING_MAX. POSIX2_COLL_WEIGHTS_MAX Specifies the minimum conforming value for EQUIV_CLASS_MAX. POSIX2_EXPR_NEST_MAX Specifies the minimum conforming value for EXPR_NEST_MAX. POSIX2_LINE_MAX Specifies the minimum conforming value for LINE_MAX. POSIX2_RE_DUP_MAX Specifies the minimum conforming value for RE_DUP_MAX. You can use the third form of getconf to find the value of the POSIX.2 standard configuration variables: _ACL Specifies that access control lists (ACLs) are supported by the security product and file system. _PC_ACL_ENTRIES_MAX Specifies the maximum number of extended ACL entries that can be placed in an access control list for the specified file. This implementation of getconf also supports the following non-POSIX-conforming name: Chapter 2. Shell command descriptions 313 getconf _CS_SHELL Specifies the default shell (command interpreter). _PC_ACL Security product supports access control lists (ACLs). _PC_ACL_ENTRIES_MAX Maximum number of entries that can be placed in an access control list for a specified file. Example This example uses getconf to find the minimum conforming value for PATH_MAX, which is contained in the variable _POSIX_PATH_MAX. If you issue getconf _POSIX_PATH_MAX getconf displays 255 Localization getconf uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES See Appendix F, “Localization” for more information. Exit values 0 >0 The specified parameter_name was valid and getconf displayed its value successfully. An error occurred. Portability POSIX.2, X/Open Portability Guide. _CS_SHELL is an extension of the POSIX standard. Some symbols are supported only on systems that support POSIX.2. Related information bc, expr, sh See Appendix C, “Regular expressions (regexp),” on page 915 for more information about regexp. getfacl — Display owner, group, and access control list (ACL) entries Format getfacl [–acdfhmoqs] [-e user ] file ... Description getfacl displays the comment header, base ACL (access control list) entries, and extended ACL entries, if there are any, for each file that is specified. It also resolves 314 z/OS V1R12.0 UNIX System Services Command Reference getfacl symbolic links. You can specify whether to display access, file default, or directory default. You can also change the default display format. The output can be used as input to setfacl. A description of access control list entries can be found in z/OS UNIX System Services Planning. Options –a Displays the access ACL entries. This is the default if -a, -d, or -f is not specified. –c Displays each ACL entry, using commas to separate the ACL entries instead of newlines, which is the default. Does not display the header. –d Displays the directory default ACL entries. If the file is not a directory, a warning is issued. –e user Displays only the ACL entries for the specified types of access control lists (-a, -d, -f) which affects the specified user's access. If users look at the output, they may be able to determine why the access is granted or denied. The user can be an UID or user name. The output includes the user's entry, if it exists, as well as entries for any group to which the user is connected. –f Displays the file default ACL entries. If the file is not a directory, a warning is issued. –h Does not resolve the symbolic link. (ACLs are not allowed on symbolic links, so the file will not have anything displayed.) –m Specifies that the comment header (the first three lines of each file's output) is not to be displayed. –o Displays only the extended ACL entries. Does not display the base ACL entries. –q Quiet mode. Suppresses the warning messages and gives a successful return code if there are no other errors. –s Skips files that only have the base ACL entries (such as owner, group, other). Only files that have the extended ACL entries are displayed. Examples 1. To display access ACL information for file file, issue: getfacl file Where the following is a sample of the output: #file: file #owner: WELLIE #group: SYS user::rwx <=== The owner’s permission bit setting group::rwx <=== The group’s permission bit setting other::rw- <=== Permission bit setting if neither user nor group user: WELLIE2: rwgroup:SYS1:rwx 2. To display access, file default, and directory default ACL information for directory directory, issue: getfacl -a -f -d directory Chapter 2. Shell command descriptions 315 getfacl Where the following is a sample of the output: #file: file #owner: WELLIE #group: SYS user::rwx group::rwx other::rwuser: WELLIE2: rwgroup:SYS1:rwx fdefault:user: WELLIE2: rwfdefault:group:SYS1:rwx default:user:WELLIE4:--- 3. To copy the ACL entries from file foo such that the file bar will have the same ACL entries: getfacl foo | setfacl -S - bar Localization getfacl uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 >0 Successful completion Failure getfacl displays the ACL entries in the following order: access, file default, and directory default. Errors will occur in the following situations: v If a file is not a directory and the -d or -f option was used, you will get a warning and getfacl will continue to the next file. v If the user does not have access to a file, you will get a warning and getfacl will continue to the next file. Portability An approved POSIX standard does not exist for getfacl. Related information find, ls, setfacl getopts — Parse utility options Format getopts opstring name [arg ...] Description getopts obtains options and their arguments from a list of parameters that follows the standard POSIX.2 option syntax (that is, single letters preceded by a hyphen (–) and possibly followed by an argument value). Typically, shell scripts use getopts to parse arguments passed to them. When you specify arguments with the arg 316 z/OS V1R12.0 UNIX System Services Command Reference getopts argument on the getopts command line, getopts parses those arguments instead of the script command-line arguments (see set). Options opstring Gives all the option letters that the script recognizes. For example, if the script recognizes –a, –f, and –s, opstring is afs. If you want an option letter to be followed by an argument value or group of values, put a colon after the letter, as in a:fs. This indicates that getopts expects the –a option to have the form –a value. Normally one or more blanks separate value from the option letter; however, getopts also handles values that follow the letter immediately, as in –avalue. opstring cannot contain a question mark (?) character. name Specifies the name of a shell variable. Each time you invoke getopts, it obtains the next option from the positional parameters and places the option letter in the shell variable name. getopts places a question mark (?) in name if it finds an option that does not appear in opstring, or if an option value is missing. arg ... Each option on the script command line has a numeric index. The first option found has an index of 1, the second has an index of 2, and so on. When getopts obtains an option from the script command line, it stores the index of the script in the shell variable OPTIND. When an option letter has a following argument (indicated with a : in opstring), getopts stores the argument as a string in the shell variable OPTARG. If an option doesn't take an argument, or if getopts expects an argument but doesn't find one, getopts unsets OPTARG. When getopts reaches the end of the options, it exits with a status value of 1. It also sets name to the character ? and sets OPTIND to the index of the first argument after the options. getopts recognizes the end of the options by any of the following: v Finding an argument that doesn't start with – v Finding the special argument ––, marking the end of options v Encountering an error (for example, an unrecognized option letter) OPTIND and OPTARG are local to the shell script. If you want to export them, you must do so explicitly. If the script invoking getopts sets OPTIND to 1, it can call getopts again with a new set of parameters, either the current positional parameters or new arg values. By default, getopts issues an error message if it finds an unrecognized option or some other error. If you do not want such messages printed, specify a colon as the first character in opstring. Example Following is an example of using getopts in a shell script: # Example illustrating use of getopts builtin. This # shell script would implement the paste command, # using getopts to process options, if the underlying # functionality was embedded in hypothetical utilities # hpaste and vpaste, which perform horizontal and # vertical pasting respectively. # paste=vpaste # default is vertical pasting seplist="" # default separator is tab Chapter 2. Shell command descriptions 317 getopts while getopts d:s o do case "$o" in d) seplist="$OPTARG";; s) paste=hpaste;; [?]) print >&2 "Usage: $0 [-s] [-d seplist] file ..." exit 1;; esac done shift $OPTIND-1 # perform actual paste command $paste -d "$seplist" "$@" Environment variables getopts uses the following environment variables: OPTARG Stores the value of the option argument found by getopts. OPTIND Contains the index of the next argument to be processed. Localization getopts uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES See Appendix F, “Localization” for more information. Usage notes getopts is a built-in shell command. Exit values 0 getopts found a script command line with the form of an option. This happens whether or not it recognizes the option. 1 getopts reached the end of the options, or an error occurred. 2 Failure because of an incorrect command-line option Portability POSIX.2, X/Open Portability Guide. On UNIX systems, getopts is built in both the KornShell and Bourne shell. Related information sh 318 z/OS V1R12.0 UNIX System Services Command Reference grep grep — Search a file for a specified pattern Format grep [–bcEFilnqsvx] [–e pattern] ... [–f patternfile] ... [pattern] [file ...] egrep [–bcilnqsvx] [–e pattern] ... [–f patternfile] ... [pattern] [file ...] fgrep [–bcilnqsvx] [–e pattern] ... [–f patternfile] ... [pattern] [file ...] Description | | | fgrep searches files for one or more pattern arguments. It does not use regular expressions; instead, it uses fixed string comparisons to find matching lines of text in the input. egrep works in a similar way, but uses extended regular expression matching. (For information about regular expression matching, see Appendix C, “Regular expressions (regexp),” on page 915.) If you include special characters in patterns typed on the command line, escape them by enclosing them in apostrophes to prevent inadvertent misinterpretation by the shell or command interpreter. To match a character that is special to egrep, put a backslash (\) in front of the character. It is usually simpler to use fgrep when you do not need special pattern matching. grep is a combination of fgrep and egrep. If you do not specify either –E or –F, grep behaves like egrep, but matches basic regular expressions instead of extended ones. You can specify a pattern to search with either the –e or –f option. If you do not specify either option, grep (or egrep or fgrep) takes the first non-option argument as the pattern for which to search. If grep finds a line that matches a pattern, it displays the entire line. If you specify multiple input files, the name of the current file precedes each output line. | If you do not specify any files, the command reads from the standard input (stdin). Options grep accepts all the following options while egrep and fgrep accept all but the –E and –F options. –b Precedes each matched line with its file block number. –c Displays only a count of the number of matched lines and not the lines themselves. –E Matches using extended regular expressions (causes grep to behave like egrep). –e pattern Specifies one or more patterns separated by newlines for which grep is to search. You can indicate each pattern with a separate –e option character, or with newlines within pattern. For example, the following two commands are equivalent: grep –e pattern_one –epattern_two file grep –e 'pattern_one pattern_two' file –F Matches using fixed strings (causes grep to behave like fgrep). Chapter 2. Shell command descriptions 319 grep –f patternfile Reads one or more patterns from patternfile. Patterns in patternfile are separated by newlines. –i Ignores the case of the strings being matched. –l Lists only the filenames that contain the matching lines. –n Precedes each matched line with its fileline number. –q Suppresses output and returns the appropriate return code. –s Suppresses the display of any error messages for nonexistent or unreadable files. –v Complements the sense of the match—that is, displays all lines not matching a pattern. –x Requires a string to match an entire line. Example To display every line mentioning an astrological element: egrep "earth|air|fire|water" astro.log Localization grep uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 At least one match for pattern was found. 1 No matches for pattern were found. 2 Failure due to any of the following: v The –e option was missing pattern. v The –f option was missing patternfile. v Out of memory for input or to hold a pattern. v patternfile could not be opened. v Incorrect regular expression. v Incorrect command-line option. v The command line had too few arguments. v The input file could not be opened. If the program fails to open one input file, it tries to go on to look at any remaining input files, but it returns 2 even if it succeeds in finding matches in other input files. Messages Possible error messages include: 320 z/OS V1R12.0 UNIX System Services Command Reference grep input lines truncated—result questionable One or more input lines were longer than grep could handle; the line has been truncated or split into two lines. Shorten the line or lines, if possible. This message does not affect the exit status. out of space for pattern string grep did not have enough memory available to store the code needed to work with the given pattern (regular expression). The usual cause is that the pattern is very complex. Make the pattern simpler, or try to release memory so that grep has more space to work with. Limits The longest input record (line) is restricted by the system variable LINE_MAX. It is always at least 2048 bytes. fgrep may be able to handle lines longer than LINE_MAX. Longer lines are treated as two or more records. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Only the grep command is part of the POSIX and X/Open standards. The egrep and fgrep commands are extensions. The –b option is an extension of the POSIX standard. Related information ed, find See Appendix C, “Regular expressions (regexp),” on page 915 for more information about regexp. hash — Create a tracked alias Format hash [name ...] hash -r Description hash creates one or more tracked aliases. Each name on the command line becomes an alias that is resolved to its full path name; thus the shell avoids searching the PATH directories for the command whenever you issue it. A tracked alias is assigned its full path name the first time that the alias is used. It is reassigned a path name the first time that it is used after the variable PATH is changed or the shell command cd is used. hash is a built-in alias defined with alias hash='alias -t' If you specify hash without any arguments on the command line, hash displays the current list of tracked aliases. Options –r Removes all current tracked aliases. Chapter 2. Shell command descriptions 321 hash Usage notes hash is a built-in shell command. Localization hash uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure because of an incorrect command-line option Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information alias, sh head — Display the first part of a file Format head [–bcklmnB num] [file ...] head [–num] [file ...] Description By default, head displays the first 10 lines of each file given on the command line. If you do not specify file, head reads standard input (stdin). Options –b num Displays the first num blocks (a block is 512 bytes) of each file. –c num Displays the first num bytes of each file. –k num Displays the first num kilobytes (1024 bytes) of each file. –l num Displays the first num lines of each file. –m num Displays the first num megabytes of each file. –n num Displays the first num lines of each file. –num 322 Displays the first num lines of each file. z/OS V1R12.0 UNIX System Services Command Reference head File tag specific option Disables the automatic conversion of tagged files. -B Localization head uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion Failure due to any of the following: v Inability to open an input file v Read error on standard input (stdin) v Write error on standard output (stdout) Failure due to any of the following: v Unknown command-line option v Missing or incorrect num in an –n option Messages Possible error messages include: Badly formed line or character count num The value num, following a –b, –c, –k, –l, –m, or –n option, was not a valid number. Portability POSIX.2, X/Open Portability Guide. This program originated with Berkeley Software Distribution (BSD) and is a frequent add-on to UNIX systems. The POSIX.2 standard included only the –n num and –num options, though it considers the latter obsolete. Related information cat, sed, tail history — Display a command history list Format history [first[last]] tcsh shell: history [-hTr] [n] history -S|-L|-M [filename] Chapter 2. Shell command descriptions 323 history history -c Description history is an alias for fc –l. Like fc –l, history displays the list of commands that have been input to an interactive shell. This command does not edit or reenter the commands. If you omit last, history displays all commands from the one indicated by first through to the previous command entered. If you omit both first and last with this command, the default command range is the 16 most recently entered commands. See “fc — Process a command history list” on page 287 for more information. history in the tcsh shell In the tcsh shell, history, used alone, prints the history event list. If n is given only the n most recent events are printed or saved. Note: See “tcsh — Invoke a C shell” on page 649 for descriptions of the tcsh shell variables and commands. The tcsh shell history built-in command uses the following options: v With -h, the history list is printed without leading numbers. v With -T, timestamps are printed also in comment form. (This can be used to produce files suitable for loading with history -L or source -h.) v With -r, the order of printing is most recent first rather than oldest first. v With -S, history saves the history list to filename. If the first word of the savehist shell variable is set to a number, at most that many lines are saved. If the second word of savehist is set to merge, the history list is merged with the existing history file instead of replacing it (if there is one) and sorted by time stamp. Merging is intended for an environment like the X Window System with several shells in simultaneous use. Currently it only succeeds when the shells quit one after another. v With -L, the shell appends filename, which is presumably a history list saved by the -S option or the savehist mechanism, to the history list. -M is like -L, but the contents of filename are merged into the history list and sorted by timestamp. In either case, histfile is used if filename is not given and ~/.history is used if histfile is unset. history -L is exactly like source -h except that it does not require a filename. v With -c, clears the history list. tcsh login shells do the equivalent of history -L on startup and, if savehist is set, history -S before exiting. Because only ~/.tcshrc is normally sourced before ~/.history, histfile should be set in ~/.tcshrc rather than ~/.login. If histlit is set, the first form (history [-hTr] [n]) and second form (history -S|-L|-M [filename]) print and save the literal (unexpanded) form of the history list. Related Information fc, sh, tcsh iconv — Convert characters from one code set to another Format iconv [–sc] –f oldset –t newset [file ...] iconv –l[–v] 324 z/OS V1R12.0 UNIX System Services Command Reference iconv File Tag Specific Options: v iconv [–F] [–M] [–T] Description iconv converts characters in file (or from standard input if no file is specified) from one code page set to another. The converted text is written to standard output (stdout). See z/OS XL C/C++ Programming Guide for more information about the code sets supported for this command. If the input contains a character that is not valid in the source code set, iconv replaces it with the byte 0xff and continues, unless the –c option is specified. If the input contains a character that is not valid in the destination code set, behavior depends on the system's iconv() function. See z/OS XL C/C++ Run-Time Library Reference for more information about the character used for converting incorrect characters. Also, z/OS XL C/C++ Programming Guide has a list of code pages supported by the z/OS shell. You can use iconv to convert single-byte data or double-byte data. Options –c Characters containing conversion errors are not written to the output. By default, characters not in the source character set are converted to the value 0xff and written to the output. –f oldset oldset can be either the code set name or a path name to a file containing an external code set. –F Uses the input file's code set (as defined in the file tag) as the source code set. If –f is also specified, and the oldset matches the file tag or if there is no file tag code set, then oldset is used as the source code set. If –F and –f are specified and oldset does not match the file tag code set, then iconv fails with an error. –l Lists supported code sets and CCSIDs. (This option was accepted in releases prior to V1R3, but was not supported.) –M Tags a new output file as mixed. The text flag (txtflag) will be off and the value for code set will be the same as what's specified on the –t option. –s Suppresses all error messages about faulty encodings. –t newset Specifies the destination code set for the output. newset can be either the code set name or a path name to a file containing an external code set. –T Tag a new output file as text. The txtflag will be on and the value for code set will be the same as what's specified on the –t option. –v Specifies verbose output. For information about file tagging and code set specifications, see z/OS UNIX System Services Planning. Chapter 2. Shell command descriptions 325 iconv Localization iconv uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Examples 1. To convert the file words.txt from the IBM-1047 standard code set to the ISO 8859-1 standard code set and store it in converted: iconv –f IBM-1047 –t ISO8859-1 words.txt > converted Also, for the exact conversion table names, refer to z/OS XL C/C++ Programming Guide. 2. To convert the file mbcsdata, which is in code page IBM-932 (double-byte ASCII), to code page IBM-939 and put the output in a file called dbcsdata: iconv –f IBM-932 –t IBM-939 mbcsdata > dbcsdata Exit values 0 Successful completion 1 Failure due to any of the following: v Insufficient memory v Inability to open the input file v Incorrect or unknown option 2 Input contained a character sequence that is not permitted in the source code set Portability X/Open Portability Guide. –v is an extension to the POSIX.2 standard. The –c, –l, and –s options are extensions to the XPG standard. id — Return the user identity Format id id id id id [user] –G [–n] [user] –g [–nr] [user] –u [–nr] [user] –M Description id displays the user name and group affiliations of the user who issued the command. Specifying a user argument on the command line displays the same information for the given user instead of the person invoking id. In this case, you require appropriate permissions. 326 z/OS V1R12.0 UNIX System Services Command Reference id The output has the format: uid=runum(username) gid=rgnum(groupname) where runum is the user's real user ID (UID) number, username is the user's real user name, rgnum is the user's real group ID (GID) number, and groupname is the user's real group name. A user's real and effective IDs may differ. In this case, there may be separate entries for effective user ID (UID) with the format: euid=eunum(euname) where eunum is the effective user ID number and euname is the effective user name. An entry for effective group ID has the format: egid=egnum(egname) where egnum is the effective group ID number and egname is the effective group name. If a user is a member of other supplemental groups, these are listed at the end of the output, with this format: groups=gnum(groupname) where gnumis the user's supplemental group ID number and groupname is the user's supplemental group name. id may also display the multilevel security label for the user's current address space. See z/OS Planning for Multilevel Security and the Common Criteria for more information about multilevel security. Options –G Displays all different group IDs (effective, real, and supplementary) as numbers separated by spaces. –g Displays only the effective group ID number. –M Displays the multilevel security label for the user's current address space. See z/OS Planning for Multilevel Security and the Common Criteria for more information about multilevel security. –n With –G, –g, or –u, displays the name rather than the number. –r With –g or –u, displays the real ID rather than the effective one. –u Displays only the effective user ID number. Localization id uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_NUMERIC v NLSPATH See Appendix F, “Localization” for more information. Chapter 2. Shell command descriptions 327 id Example > id -M SYSHIGH Usage note See z/OS Planning for Multilevel Security and the Common Criteria for more information about multilevel security and seclabels. Exits 0 Successful completion 1 You specified an incorrect user with the –u option 2 Failure due to an incorrect command-line argument Portability POSIX.2, X/Open Portability Guide, UNIX System V. Related information logname inetd daemon — Provide service management for networks Format inetd [–d] [configuration file] Description The inetd daemon provides service management for a network. For example, it starts the rlogind program whenever there is a remote login request from a workstation. The rlogind program is the server for the remote login command rlogin commonly found on UNIX systems. It validates the remote login request and verifies the password or password phrase of the target user. It starts a z/OS shell for the user and handles translation between ASCII and EBCDIC code pages as data flows between the workstation and the shell. When inetd is running and receives a request for a connection, it processes that request for the program associated with that socket. For example, if a user tries to log in from a remote system into the z/OS shell while inetd is running, inetd processes the request for connection and then issues a fork() and execl() to the rlogin program to process the rlogin request. It then goes back to monitoring for further requests for those applications that can be found as defined in the /etc/inetd.conf file. Options –d Specifies that the inetd daemon be started in debug mode. All debug messages are written to stderr. configuration file Specifies that the inetd daemon be started with a configuration file other than the default /etc/inetd.conf file. 328 z/OS V1R12.0 UNIX System Services Command Reference inetd daemon Signals inetd recognizes the following signals: SIGTERM Terminates inetd in an ordinary fashion and deletes /etc/inetd.pid. You can restart inetd, if you want. SIGINT Same as SIGTERM. SIGHUP Rereads the inetd configuration file. This can be used to start new services, or to restart services with a different port. Other signals that normally end a process (such as SIGQUIT or SIGKILL) should not normally be sent to inetd because the program will not have a chance to remove /etc/init.pid. Usage notes 1. Buffer sizes should only be specified if the documentation for the daemon being specified in the inetd.conf statement calls for something other than the default. 2. The configuration file is field-sensitive, but not column-sensitive. Fields should be arranged in the order shown in Table 13. Continuation lines for an entry must begin with a space or tab. Each entry must contain all fields. The inetd daemon uses the configuration file entry to properly set up the environment expected by the server. Specifying an incorrect value for one or more of the parameters is likely to cause the server to fail. Table 13. Fields in the configuration file (inetd daemon) [ip_address:]service_name ip_address is a local IP, followed by a colon. If specified, the address is used instead of INADDR_ANY or the current default. To specifically request INADDR_ANY, use "*:". If ip_address (or a colon) is specified, without any other entries on the line, it becomes the default for subsequent lines until a new default is specified. service_name is a well-known service name such as login or shell. The name and protocol specified must match one of the server names defined in /etc/services. For more information about /etc/services, see z/OS Communications Server: IP Configuration Reference. and z/OS Communications Server: New Function Summary socket_type Stream or dgram protocol [,sndbuf=n][,rcvbuf=n] protocol can be tcp or udp, or (for IPv6) tcp6 or udp6. tcp4 and udp4 can also be specified to explicitly request IPv4. The protocol is used to further qualify the service name. Both the service name and the protocol should match an entry in /etc/services, except that, the "4" or the "6" should not be included in the /etc/services entry. For more information about /etc/services, see z/OS Communications Server: IP Configuration Reference and z/OS Communications Server: New Function Summary. Note that, if tcp6 or udp6 is specified, the socket will support IPv6 (that is, AF_INET6 will be used.) sndbuf and rcvbuf specify the size of the send and receive buffers. The size may be in bytes, or a "k" or "m" may be added to indicate kilobytes or megabytes respectively. sndbug and rcvbuf can be used in either order. Chapter 2. Shell command descriptions 329 inetd daemon Table 13. Fields in the configuration file (inetd daemon) (continued) Wait or nowait. Wait indicates the daemon is single-threaded and another request will not be serviced until the first one completes. wait_flag [.max] If nowait is specified, the inet daemon issues an accept when a connect request is received on a stream socket. If wait is specified, the inet daemon does not issue the accept. It is the responsibility of the server to issue the accept if this is a stream socket. max is the maximum number of users allowed to request service in a 60 second interval. Default is 40. If exceeded, the service's port is shut down. User ID and group that the forked daemon is to execute under. inetd can run a program with a UID that is not 0. However, if the program that inetd runs needs to change the identity of the process to that of the user, then the login_name must have been defined to RACF via ADDUSER as a superuser with a UID of 0 (UID 0) and the login_name must have been defined to RACF. This will allow inetd to use special functions like setgid() and setuid(). login_name If the program that will be invoked by inetd requires the use of special functions like setuid() and seteuid(), then it must be permitted to the BPX.DAEMON class as in the following example for login, which is a typical ADDUSER command. ADDUSER rlogind omvs(uid(0) home(/) A typical permit command is: permit bpx.daemon class(facility) id(rlogind) access(read) How you set up security for daemons is the final determining factor. For more information, see the topic on establishing the correct level of security for daemons in z/OS UNIX System Services Planning. Full path name of the service. For example: server_program /usr/sbin/rlogind is the full path name for the rlogind command. Maximum of 20 arguments. The first argument is the server name. server_arguments Related information The inetd daemon creates a temporary file, /etc/inetd.pid, that contains the PID of the currently executing inetd daemon. This PID value is used to identify syslog records that originated from the inetd daemon process, and also to provide the PID value for commands such as kill that require you to specify a PID, and to provide a lock to prevent more than one inetd from being active at one time. For more information about setting up the inetd configuration file and configuring daemons in general, see the topic on daemons in z/OS UNIX System Services Planning or z/OS Communications Server: IP Configuration Reference. infocmp — Compare or print the terminal description Format infocmp [–ducn] [–ILC] [–1Vv] [–s d|i|l|c] [–A directory] [–B directory] [term_names...] 330 z/OS V1R12.0 UNIX System Services Command Reference infocmp Description infocmp compares terminfo database entries, or prints a terminfo database entry. Output is written to standard output (stdout). The Curses application uses the terminfo database, which contains a list of terminal descriptions. This enables you to manipulate a terminal's display regardless of the terminal type. To create the terminfo database, use tic. For information about defining the terminfo database database, see z/OS UNIX System Services Planning. For more information about curses, see z/OS C Curses. Options d Prints the two terminal definitions showing the differences between the capabilities. u Prints the differences between the two terminal definitions. c Prints entries that are common to the two terminfo databases. n Does not print entries in either terminfo database. I Prints the current terminal description using capname. (capname is the short name for a capability specified in the terminfo source file.) C Prints the current terminal description using termcap. L Prints the current terminal description using variables (names that the curses functions can use when working with the terminfo database) 1 Single-column output. V Prints the program version. v Prints debugging information (verbose) to stderr. s Changes sort order of the fields printed. d Sorts by database i Sorts by terminfo c Sorts by termcap l Sorts by the variables (names that the curses function can use when working with the terminfo database) A First terminfo database. B Other terminfo database. term_names Names of entries to be processed. Usage notes When displaying terminal database information for entries that are to be processed, infocmp operates as follows: 1. If you omit term_names, infocmp locates the terminal database information specified by the TERM environment variable and displays that as the entry's terminal database information. 2. If you specify a single term_name, infocmp displays terminal database information for that named entry. 3. If you specify more than one term_name, infocmp displays the results of a terminal database comparison between all of the specified term_names. Chapter 2. Shell command descriptions 331 infocmp Examples 1. To print out the current terminal description using capname, issue: infocmp You will see: infocmp ibm3101 # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ ibm3101|IBM 3101-10, am, cols#80, lines#24, bel=¬?, clear=¬.\322, cr=\r, cub1=\b, cud1=\n, cuf1=¬.\303, 2. To print out the current terminal description using the curses capability names, issue: infocmp –L You will get: infocmp –L ibm3101 # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ Terminal type ibm3101 ibm3101|IBM 3101-10 flags auto_right_margin, numbers columns = 80, lines = 24, strings bell = ’¬?’, carriage_return = ’\r’, clear_all_tabs = ’¬.\310’, clear_screen = ’¬.\322’, clr_eol = ’¬.\311’, clr_eos = ’¬.\321’, 3. To print out the current terminal description using capname, issue: infocmp –I You will get: infocmp –I ibm3101 # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ ibm3101|IBM 3101-10, am, cols#80, lines#24, bel=¬?, clear=¬.\322, cr=\r, cub1=\b, cud1=\n, cuf1=¬.\303, 4. To print out the current terminal description using termcap, issue: infocmp –C You will get: infocmp –C ibm3101 # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ :am:bs:\ :.co#80:li#24:kn#2:\ :.cd=\EJ:.ce=\EI:.cl=\EK:\ :.c:.cm=\EY%p1%’ ’%+%c%p2%’ ’%+%c:.ct=\EH:.ho=\EH:\ :.nd=\EC:.st=\E0:.up=\EA: 332 z/OS V1R12.0 UNIX System Services Command Reference infocmp 5. To print entries in single-column format, issue: infocmp –1 You will get: infocmp –C –1 ibm3101 # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ :am:\ :bs:\ :co#80:\ :li#24:\ :kn#2:\ :.cd=\EJ:\ :.ce=\EI:\ :.cl=\EK:\ 6. To print the two terminal definitions showing the difference between the capabilities (F indicates False, entry not present; T indicates True, entry present): infocmp –d ibm3101 hft-c You will get: # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ comparing ibm3101 to hft-c. comparing booleans. bw:F:T. msgr:F:T. xon:F:T. comparing numbers. it:-1:8. lines:24:25. comparing strings. batt1:’NULL’,’\206\361’. batt2:’NULL’,’\206\361\224\204’. To print the capabilities that are different between the two terminal definitions. The values for the first terminal definitions are shown. infocmp –u ibm3101 hft-c You will get: # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ ibm3101|IBM 3101-10, bw@, msgr@, xon@, it@, lines#24, batt1@, batt2@, blink@, bold@, box1@, box2@, clear=¬.\322, colb0@, colb1@, colb2@, colb3@, colb4@, colb5@, colb6@, colb7@, colf0@, colf1@, colf2@, colf3@, colf4@, colf5@, colf6@, colf7@, cub@, cud@, cuf@, cuf1=¬.\303, 7. To print the capabilities that are the same in both terminal definitions, issue: infocmp –c ibm3101 hft-c You will get: # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ comparing ibm3101 to hft-c. comparing booleans. am= T. comparing numbers. Chapter 2. Shell command descriptions 333 infocmp cols= 80. comparing strings. bel= ’¬?’. cr= ’\r’. cub1= ’\b’. cud1= ’\n’. 8. To print the capabilities that are not found in either terminal definition, issue: infocmp –u ibm3101 hft-c You will get: # Reconstructed via infocmp from file:/usr/share/lib/terminfo/i ibm3101|IBM 3101-10:\ comparing ibm3101 to hft-c. comparing booleans. !bce. !ccc. !chts. !cpix. !crxm. !da. !daisy. Environment variables infocmp uses the following environment variables: TERMINFO Contains the pathname of the terminfo database. TERM Contains the name of your terminal, that is, the current terminal definition. Related information captoinfo, tic integer — Mark each variable with an integer value Format integer [number] Description integer is an alias for typeset –i. Like typeset –i, integer marks each variable as having an integer value, thus making arithmetic faster. If number is given and is nonzero, the output base of each variable is number. The default is decimal. See “typeset — Assign attributes and values to variables” on page 742 for more information. Related information typeset, sh 334 z/OS V1R12.0 UNIX System Services Command Reference ipcrm ipcrm — Remove message queues, semaphore sets, or shared memory IDs Format ipcrm [–m SharedMemoryID] [–M SharedMemoryKey] [–q QMessageID] [–Q MessageKey] [–s SemaphoreID] [–S SemaphoreKey] Description ipcrm removes one or more message queues, semaphores set, or shared memory identifiers. Options –m SharedMemoryID Removes the shared memory identifier SharedMemoryID. The shared memory segment and data structure associated with SharedMemoryID are also removed after the last detach operation. –M SharedMemoryKey Removes the shared memory identifier, created with the key SharedMemoryKey. The shared memory segment and data structure associated with it are also removed after the last detach operation. –q MessageID Removes the message queue identifier MessageID and the message queue and data structure associated with it. –Q MessageKey Removes the message queue identifier, created with the key MessageKey, and the message queue and data structure associated with it. –s SemaphoreID Removes the semaphore identifier SemaphoreID and the set of semaphores and data structure associated with it. –S SemaphoreKey Removes the semaphore identifier, created with the key SemaphoreKey, and the set of semaphores and data structure associated with it. The msgctl, shmctl, and semctl subroutines provide details of the remove operations. You can use the ipcs command to find the identifiers and keys. Examples 1. To remove the shared memory segment associated with SharedMemoryID 18602, enter: ipcrm –m 18602 2. To remove the message queue that was created with a key of 0xC1C2C3C3, enter: ipcrm –Q 0xC1C2C3C4 Exit values 0 Successful completion 1 Incorrect command-line option Chapter 2. Shell command descriptions 335 ipcrm Related information ipcs ipcs — Report status of the interprocess communication facility Format ipcs [–mqsS] [–a b c o p t w x y M B] Description ipcs writes to the standard output information for active interprocess communication facilities. If you do not specify any flags, ipcs writes information in a short form about currently active message queues, shared memory segments, and semaphores. The column headings and the meaning of the columns in an ipcs command listing are listed in Table 14. The letters in parentheses indicate the command flags that cause the corresponding heading to appear. (all) means that the heading is always displayed. These flags determine what information is provided for each facility. They do not determine which facilities are listed. Table 14. Explanation of the ipcs command listing 336 Column heading Meaning of the column T (all except y) The type of facility: q Message queue m Shared memory segment s Semaphore S Map Memory Service ID (all except x,w,y,S,B) The identifier for the facility entry KEY (all except y,S,B) The key used as a parameter to the msgget subroutine, the semget subroutine, or the shmget subroutine to make the facility entry. (The key of a shared memory segment is changed to IPC_PRIVATE when the segment is removed until all processes attached to the segment detach it.) z/OS V1R12.0 UNIX System Services Command Reference ipcs Table 14. Explanation of the ipcs command listing (continued) Column heading Meaning of the column MODE (all except x,w,y,S,B) The facility access modes and flags. The mode consists of 11 characters that are interpreted as follows: The first two characters can be the following: R If a process is waiting in a msgrcv() system call. S If a process is waiting in a msgsnd() system call. If the associated shared memory segment has been removed. It disappears when the last process attached to the segment detaches it. The next nine characters are interpreted as three sets of three characters each. The first set refers to the owner's permissions; the next to permissions of others in the user group of the facility entry; and the last to all others. Within each set, the first character indicates permission to read, the second character indicates permission to write or alter the facility entry, and the last character is currently unused. D The permissions are indicated as follows: r If read permission is granted w If write permission is granted a If alter permission is granted – If the indicated permission is not granted OWNER (all, except S,B) The login name or user ID of the owner of the facility entry. GROUP (all) The name or group ID of the group that owns the facility entry. CREATOR (a,c) The login name or user ID of the creator of the facility entry. CGROUP (a,c) The group name or group ID of the creator of the facility entry. CBYTES (a,x,o) The number of bytes in messages currently outstanding on the associated message queue. Chapter 2. Shell command descriptions 337 ipcs Table 14. Explanation of the ipcs command listing (continued) Column heading Meaning of the column INFO (x) Provides additional extended state information. Under this field will be returned one or more of the following codes (codes are not mutually exclusive unless noted): For shared memory output: M megaroo For semaphore output: P PLO in use. Mutually exclusive with L. L Latch in use. Mutually exclusive with P. B Binary semaphore. For message queue output: 338 P PLO in use. Mutually exclusive with L. L Latch in use. Mutually exclusive with P. R RCV type PID. S Send type PID. 1 PLO1 flag on––IPC_PLO1 set on msgget() 2 PLO2 flag on––IPC_PLO2 set on msgget() QNUM (a,o) The number of messages currently outstanding on the associated message queue. QBYTES (a,b) The maximum number of bytes allowed in messages outstanding on the associated message queue. LSPID (p) The ID of the last process that sent a message to the associated queue. LRPID (p) The ID of the last process that received a message from the associated queue. STIME (a,t) The time when the last message was sent to the associated queue. RTIME (a,t) The time when the last message was received from the associated queue. CTIME (a,t) The time when the associated entry was created or changed. NATTCH (a,o) The number of processes attached to the associated shared memory segment. SEGSZPG (a,b,x) The size in pages of the associated shared memory segment. PGSZ (a,b,x) The page size of the associated shared memory segment. SEGSZ (a,b,x) The size in bytes of the associated shared memory segment. CPID (p) The process ID of the creator of the shared memory entry. LPID (p) The process ID of the last process to attach or detach the shared memory segment. ATIME (a,t) The time when the last attach was completed to the associated shared memory segment. DTIME (a,t) The time the last detach was completed on the associated shared memory segment. z/OS V1R12.0 UNIX System Services Command Reference ipcs Table 14. Explanation of the ipcs command listing (continued) Column heading Meaning of the column NSEMS (a,b) The number of semaphores in the set associated with the semaphore entry. OTIME (a,t) The time the last semaphore operation was completed on the set associated with the semaphore entry. RCVWAIT (x) A count of msgrcv() waiters. SNDWAIT (x) A count of msgsnd() waiters. MSGQPID (w) For the message Q report, up to 10 lines of data will be shown under this heading. MSGQTYPE (w) For the message Q report, up to 10 lines of data will be shown under this heading. RCVPID (w) The process ID of a msgrcv() waiter. A maximum of 10 process IDs can be written. RCVTYP (w) The message type of a msgrcv() waiter associated with RCVPID. A maximum of 10 message type will be written. If the caller does not have read access, this field is not displayed. SNDPID (w) The process ID of a msgsnd() waiter. A maximum of 10 process IDs can be written SNDLEN (w) The message send length of a msgsnd() waiter associated with SNDPID. A maximum of 10 message send lengths can be written. TERMA (x) The number of times sem_val was changed during termination for semaphore adjustments. CNADJ (x) The current number of processes with semaphore adjustments. SNCNT (x) The number of waiters waiting for a sem_val greater than zero. SZCNT (x) The number of waiters waiting for a sem_val equal to zero. WTRPID (w) The process IDs of a semop waiter. A maximum of 10 semop waiters are written. WTRNM (w) The semaphore number associated with WTRPID. A maximum of 10 semaphore numbers are written. WTROP (w) The semaphore operation value associated with WTRNM and WTRPID. A maximum of 10 semaphore operation values are written. AJPID (w) The process ID of a process with semaphore adjustments. A maximum of 10 process IDs are written. AJNUM (w) The semaphore number of the semaphore adjustment associated with AJPID. A maximum of 10 semaphore numbers are written. AJPID (w) The process ID of a process with semaphore adjustments. A maximum of 10 process IDs are written. AJNUM (w) The semaphore number of the semaphore adjustments associated with AJPID. A maximum of 10 semaphore numbers are written. AJVAL (w) The semaphore adjustment value associated with AJNUM and AJPID. A maximum of 10 semaphore adjustment values are written. Chapter 2. Shell command descriptions 339 ipcs Table 14. Explanation of the ipcs command listing (continued) 340 Column heading Meaning of the column ATPID (x) The process ID of a process that is attached to this shared memory segment. A maximum of 10 process IDs are written. ATADDR (x) The shared memory address where the process ATPID is attached to this segment. A maximum of 10 addresses are written. MNIDS (y) The system limit for maximum number of message queues, semaphores, or shared memory IDs. HWIDS (y) The most message queues, semaphores, or shared memory IDs created. CIDSA (y) The current number of message queues, semaphores, or shared memory IDs available. CPRIV (y) The current number of message queues, semaphores, or shared memory IDs created with IPC_PRIVATE CKEY (y) The current number of message queues, semaphores, or shared memory IDs created with a key. GETEX (y) The number of times msgget, semget, or shmget exceeded the maximum number of IDs MNID. MAXQB (y) The system limit for maximum number of bytes on a message queue. QMNUM (y) The system limit for maximum number messages on a message queue. ENOMEM (y) The number of times msgsnd() calls returned ENOMEM. MNSEMS (y) The system limit for maximum number of semaphores per set. MNOPS (y) The system limit for maximum number of operations per semop. CSBYTES (y) The current number of bytes used by the system for semaphores. TPAGES (y) The system limit for number of system-wide shared memory pages SPAGES (y) The system limit for number of pages per shared memory segment. SEGPR (y) The system limit for number of segments per process. CPAGES (y) The current number of system-wide shared memory pages MAXSEG (y) The largest number of shared memory pages allocated to a single shared memory segment. CREATEPID (S,B) The creator PID of the map memory area. It is an unique identifier of the map area. USERPID (S,B) The user PID of the map memory area, which is currently using it. USER (S,B) The user name of the user of the map memory segments entry. SHUTDOWN (S,B) This field indicates that for this particular map memory object, shutdown flag has been marked for freeing of this area. While blocks can be freed in this area, the map memory object is not freed until the last process using it terminates. z/OS V1R12.0 UNIX System Services Command Reference ipcs Table 14. Explanation of the ipcs command listing (continued) Column heading Meaning of the column BLKSIZE (B) The block size of the map area object in megabytes. BLKSINUSE (B) The number of blocks is in use in the map memory area object. BLKSINMAP (B) The number of blocks in this map area object. BLKSMAPPED (B) The number of blocks mapped by this process. SECLABEL (M) The multilevel security label associated with Message queues, Semaphores, and Shared Memory. Options –q Writes information about active message queues. –m Writes information about active shared memory segments. –s Writes information about active semaphore set. –S Write information about active __map memory segments. If –q, –m, –s, or –S are specified, only information about those facilities is written. If none of these four are specified, information about message queues, shared memory segments and semaphores are written subject to the following options. __Map memory information will not written unless the –S is specified. –a Uses the –b, –c, –o, –p, and –t flags. –b Writes the maximum number of bytes in messages on queue for message queues, the size of segments for shared memory, and the number of semaphores in each semaphores set. This option will be ignored for __map memory option [–S]. –c Writes the login name and group name of the user that made the facility. This option will be ignored for __map memory option [–S]. –m Writes information about active shared memory segments. –o Writes the following usage information: v Number of messages on queue v Total number of bytes in messages in queue for message queues v Number of processes attached to shared memory segments –p Writes the following: v Process number of the last process to receive a message on message queues v Process number of the creating process v Process number of last process to attach or detach on shared memory segments –q Writes information about active message queues. –s Writes information about active semaphore set. –t v Time of the last control operation that changed the access permissions for all facilities v Time of the last msgsnd() and msgrcv() on message queues Chapter 2. Shell command descriptions 341 ipcs v Time of the last shmat and shmdt on shared memory v Time of the last semop on semaphore sets –w Writes message queue wait status and semaphore adjustment status in these fields: AJNUM AJPID AJVAL GROUP KEY MSGQPID MSGQTYP OWNER RCVPID RCVTYP SNDLEN SNDPID T WTRNM WTROP WTRPID This option ignores all other print options except –x and –y. –x Writes extended status in these fields: ATADDR ATPID CNADJ GROUP INFO KEY OWNER PGSZ QCBYTES RCVWAIT SEGSZ SEGSZPG SNCNT SNDWAIT SZCNT T TERMA This option will be ignored for __map memory option [–S]. This option ignores all other print options except the –y option. –y Writes summary and system limit status in these fields: CIDSA CKEY CPAGES CPRIV CSBYTES ENOMEM GETEX HWIDS QMNUM MAXQB MAXSEG MNIDS MNOPS MNSEMS SEGPR SPAGES TPAGES This option ignores all other print options. This option is a summary and system limit status for message queues, semaphores and shared memory. It will not include the __map memory segments [–S] summary and system limit status. –M Writes multilevel security label associate with the resources except __map memory facility. See z/OS Planning for Multilevel Security and the Common Criteria for more information about multilevel security. –B Writes extended information about __map memory segments in these fields: BLKSIZE BLKSINUSE BLKSINMAP BLKSMAPPED This option only applies to __map memory segments [–S]. 342 z/OS V1R12.0 UNIX System Services Command Reference ipcs Examples Following is a sample output from entering ipcs without flags: IPC status as of Wed Apr Message Queues: T ID KEY q 1234567890 0x4107001c Shared Memory: T ID KEY m 0 0x0d07021e m 1 0x0d08c984 Semaphores: T ID KEY s 4096 0x0108c86e s 1 0x6208c8ef s 2 0x4d0b00a6 s 24579 0x00bc614e s 176132 0x00000058 6 14:56:22 EDT 1994 MODE -Rrw-rw---- OWNER root GROUP printq MODE --rw--------rw-rw-rw- OWNER root root GROUP system system MODE --ra--------ra-r--r---ra-ra-----ra-ra-ra--ra-ra-ra- OWNER root root root xlin xlin GROUP system system system vendor vendor Following is a sample output from entering ipcs -S: IPC status as of Wed Oct 6 14:56:22 EDT Map Memory Service: T CREATEPID USERPID USER S 1096 165 root S 4 114 John S 6 324 John S 1052 111 Andrew S 96 678 xlin 2002 GROUP system system system vendor vendor SHUTDOWN Y Y N N Y Exits 0 1 Successful completion Failure due to incorrect command-line option Related information ipcrm jobs — Return the status of jobs in the current session Format jobs [–l|–p] [job-identifier...] tcsh shell: jobs [-l] Description jobs produces a list of the processes in the current session. Each such process is numbered for easy identification by fg or kill, and is described by a line of information: [job-identifier] default state shell_command job-identifier Is a decimal number that identifies the process for such commands as fg and kill (preface job-identifier with % when used with these commands). default Identifies the process that would be the default for the fg and bg commands (that is, the most recently suspended process). If default is a +, Chapter 2. Shell command descriptions 343 jobs this process is the default job. If default is a –, this job becomes the default when the current default job exits. There is at most one + job and one – job. state Shows a job as: Running If it is not suspended and has not exited Done If it exited successfully Done(exit status) If it exited with a nonzero exit status Stopped (signal) If it is suspended; signal is the signal that suspended the job shell_command Is the associated shell command that created the process. jobs in the tcsh shell In the tcsh shell, jobs lists the active jobs. With-l, lists process IDs in addition to the normal information. See “tcsh — Invoke a C shell” on page 649. Options –l Displays the process group ID of a job (before state). –p Displays the process IDs of all processes. The –l and –p options are mutually exclusive. Localization jobs uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Usage note jobs is a built-in shell command. Exit values 0 2 Successful completion Failure due to an incorrect command-line argument Portability POSIX.2 User Portability Extension. Related information bg, fg, kill, ps, wait, tcsh 344 z/OS V1R12.0 UNIX System Services Command Reference join join — Join two sorted textual relational databases Format join [–a n] [–e s] [–o list] [–t c] [–v n] [–1 n] [–2 n] file1 file2 join [–a n] [–e s] [–j[n] m] [–o list] [–t c] file1 file2 Description join joins two databases. It assumes that both file1 and file2 contain textual databases in which each input line is a record and that the input records are sorted in ascending order on a particular join key field (by default the first field in each file). If you specify – in place of file1 or file2, join uses the standard input (stdin) for that file. If you specify – – in place of both file1 and file2, the output is undefined. Conceptually, join computes the Cartesian product of records from both files. By default, spaces or tabs separate input fields and join discards any leading or trailing white space. (There can be no white-space-delimited empty input fields.) It then generates output for those combined records in which the join key field (the first field by default) matches in each file. The default output for join is the common join key field, followed by all the other fields in file1, and then all the other fields in file2. The other fields from each file appear in the same order they appeared in the original file. The default output field separator is a space character. Options –a n Produces an output line for lines that do not match in addition to one for a pair of records that does match. If you specify n as one of 1 or 2, join produces unpaired records from only that file. If you specify both –a 1 and –a 2, it produces unpaired records from both files. –e string Replaces an empty field with string on output. In a double-byte locale, string can contain double-byte characters. –j[n] m Uses field number m as the join key field. By default, the join key field is the first field in each input line. As with the –a option, if n is present, this option specifies the key field just for that file; otherwise, it specifies it for both files. –o list Specifies the fields to be output. You can specify each element in list as either n.m, where n is a file number (1 or 2) and m is a field number, or as 0 (zero), which represents the join field. You can specify any number of output fields by separating them with blanks or commas. The POSIX-compatible version of this command (first form in the syntax) requires multiple output fields to be specified as a single argument; therefore, shell quoting may be necessary. join outputs the fields in the order you list them. –t c Sets the field separator to the character c. Each instance of c introduces a new field, making empty fields possible. In a double-byte locale, c can be a double-byte character. –v n Suppresses matching lines. If you specify n as one of 1 or 2, join produces unpaired records from only that file. If you specify both –v 1 and –v 2, it produces unpaired records from both files. This does not suppress any lines produced using the –a option. Chapter 2. Shell command descriptions 345 join –1 n Uses the nth field of file1 as the join key field. –2 n Uses the nth field of file2 as the join key field. Examples 1. The following script produces a report about files in the working directory containing filename, file mode, and an estimate at what the file contains: file * | tr –s ':' ';' >temp1 ls –l | tr –s ' ' ' ';' >temp2 join –t';' –j2 9 –o 1.1 2.1 1.2 --temp1 temp2 rm temp[12] 2. This example uses the historical implementation of the join command. The third line in the POSIX-compatible script could be: join –t';' –2 9 –o 1.1,2.1,1.2 -- temp1 temp2 Localization join uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Incorrect syntax v The wrong number of command-line arguments v Inability to open the input file v Badly constructed output list v Too many –o options on the command line 2 Failure due to an incorrect command-line argument Messages Most diagnostics deal with argument syntax and are self-explanatory. For example: Badly constructed output list at list Indicates that the list for a –o option did not have the proper syntax. Portability POSIX.2, X/Open Portability Guide, UNIX systems. POSIX considers the –j option to be obsolete. Related information awk, comm, cut, paste, sort 346 z/OS V1R12.0 UNIX System Services Command Reference kill kill — End a process or job, or send it a signal Format kill kill kill kill kill –l [exit_status] [–s signal_name] [ –K [pid...][job-identifier...] [–signal_name] [pid ...] [job-identifier ...] [–signal_number] [pid ...] [job-identifier ...] tcsh shell: kill [-signal] %job|pid ... kill –K %job|pid... kill -l Description kill ends a process by sending it a signal. The default signal is SIGTERM. kill is a built-in shell command. kill in the tcsh shell In the tcsh shell, kill [-signal] %job|pid ... sends the specified signal (or if none is given, the TERM (terminate) signal) to the specified jobs or processes. job can be a number, a string, '', %, + or - . Signals are either given by number or by name. Enter the signal_name with uppercase characters. For example, if you want to send the SIGTERM signal, you would enter kill -TERM pid not kill -SIGTERM pid. Restriction: When using the tcsh kill command, do not use the first three characters (SIG) of the signal_name. There is no default job. Specifying kill alone does not send a signal to the current job. If the signal being sent is TERM or HUP (hangup), then the job or process is sent a CONT (continue) signal as well. kill -l lists the signal names. See “tcsh — Invoke a C shell” on page 649. The signal_numbers and signal_names described in “Options” are also used with the tcsh kill command. Options –K Sends a superkill signal to force the ending of a process or job that did not end as a result of a prior KILL signal. The process is ended with a non-retryable abend. The regular KILL signal must have been sent at least 3 seconds before the superkill signal is sent. The superkill signal cannot be sent to a process group (by using pid of 0 or a negative number) or to all processes (by using a pid of -1). –l Displays the names of all supported signals. If you specify exit_status and it is the exit code of a ended process, kill displays the ending signal of that process. –s signal_name Sends the signal signal_name to the process instead of the SIGTERM signal. When using the kill command, do not use the first three characters (SIG) of the signal_name. Enter the signal_name with uppercase characters. For example, if you want to send the SIGABRT signal, enter: Chapter 2. Shell command descriptions 347 kill kill –s ABRT pid –signal_name (Obsolete.) Same as –s signal_name. –signal_number (Obsolete.) A non-negative integer representing the signal to be sent to the process, instead of SIGTERM. The signal_number represents the following signal names: 0 SIGNULL 1 SIGHUP 2 SIGINT 3 SIGQUIT 4 SIGILL 5 SIGPOLL 6 SIGABRT 7 SIGSTOP 8 SIGFPE 9 SIGKILL 10 SIGBUS 11 SIGSEGV 12 SIGSYS 13 SIGPIPE 14 SIGALRM 15 SIGTERM 16 SIGUSR1 17 SIGUSR2 18 SIGABND 19 SIGCONT 20 SIGCHLD 21 SIGTTIN 22 SIGTTOU 23 SIGIO 24 SIGQUIT 25 SIGTSTP 26 SIGTRAP 27 SIGIOERR 28 SIGWINCH 29 SIGXCPU 30 SIGXFSZ 31 SIGVTALRM 32 SIGPROF 37 SIGTRACE 38 SIGDCE 39 SIGDUMP The signal_numbers (3 and 6) associated with SIGQUIT and SIGABRT, respectively, differ from the values of SIGQUIT and SIGABRT used by the z/OS kernel, but they are supported for compatibility with other UNIX platforms. (The kill command will send the SIGQUIT or SIGABRT to the process.) This note is also true for kill in the tcsh shell. Operands job-identifier Specifies the job identifier reported by the shell when a process is started with &. It is one way to identify a process. It is also reported by the jobs 348 z/OS V1R12.0 UNIX System Services Command Reference kill command. When using the job identifier with the kill command, the job identifier must be prefaced with a percent (%) sign. For example, if the job identifier is 2, the kill command would be entered as follows: kill –s KILL %2 pid Specifies the process ID that the shell reports when a process is started with &. You can also find it using the ps command. The pid argument is a number that may be specified as octal, decimal, or hexadecimal. Process IDs are reported in decimal. kill supports negative values for pid. If pid is negative but not −1, the signal is sent to all processes whose process group ID is equal to the absolute value of pid. The negative pid is specified in this way: kill –KILL –– –nn where nn is the process group ID and may have a range of 2 to 7 digits (nn to nnnnnnn). kill –s KILL –– –9812753 The format must include the –– before the –nn in order to specify the process group ID. If pid is 0, the signal is sent to all processes in the process group of the invoker. The process to be killed must belong to the current user; however, any process can be killed by a superuser. Localization kill uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Usage notes 1. z/OS UNIX signal delivery restrictions are documented in the "Environmental Restrictions" section of z/OS UNIX System Services Programming: Assembler Callable Services Reference. Exit values 0 1 2 >2 Successful completion Failure due to one of the following: v The job or process did not exist v There was an error in command-line syntax Failure due to one of the following: v Two jobs or processes did not exist v Incorrect command-line argument v Incorrect signal Tells the number of processes that could not be killed Chapter 2. Shell command descriptions 349 kill Messages Possible error messages include: job-identifier is not a job You specified an incorrect ID. signal_name is not a valid signal You specified a noninteger signal for kill, or you specified a signal that is outside the range of valid signal numbers. Portability POSIX.2, X/Open Portability Guide. Related information jobs, ps, sh, tcsh [ (left bracket) — Test for a condition See the test command. Note: When working in the shell, to view man page information about [ (left bracket), type: man left. ld — Link object files Format ld [–cVv] [–b option[,option]...]... [–e function] [–f filename]... [–L directory]... [–l libname]... [–O name[,name]...] [–o outfile] [–S syslibdset]... [–u function] [–x sidefile] [file.o ] ... [file.a ] ... [file.x]... [–l libname] ... Description The ld utility combines object files and archive files into an output executable file, resolving external references. ld runs the Program Management Binder. Options -b option[,option]... Specifies options to be passed to the binder. For more information about the binder and its options, see z/OS MVS Program Management: User's Guide and Reference. Binder options that are not specified will take the binder default, except when other ld options affect binder options. –c 350 Causes pseudo-JCL to be written to stdout without actually running the binder. Pseudo-JCL provides information about exactly which binder options are being passed, and also which data sets are being used. z/OS V1R12.0 UNIX System Services Command Reference ld Also see –v. -e function Specifies the name of the function to be used as the entry point of the program. The default value of the -e option is affected by the setting of environment variable _LD_ENTRY_POINT (see Environment Variables). If the -e option is not specified and _LD_ENTRY_POINT is null, or if function is null, the default rules of the binder will determine the entry point of the program. For more information about the binder and the ENTRY control statement, see z/OS MVS Program Management: User's Guide and Reference. Also see -O. -f filename Specifies a file that contains a list of the names of object and archive files to be used as input. The listed files will be used in addition to any files specified as operands. -L directory Specifies the directories to be used to search for archive libraries specified by the -l operand. The directories are searched in the order specified, and then in the directories specified by the _LD_LIBDIRS environment variable or its default. You cannot specify an MVS data set as an archive library directory. -l libname Specifies the name of an archive library. ld searches for the file lib libname.a in the directories specified on the -L option and then in the directories specified by the _LD_LIBDIRS environment variable or its default. The first occurrence of the archive library is used. You can also specify an MVS data set; you must specify the full data set name, because there are no rules for searching library directories. The data set specified must be a C370LIB object library or a load library. If a data set specified as a library has undefined (U) record format, then it is assumed to be a load library. For more information about the object library utility, see z/OS XL C/C++ User's Guide. -O name[, name]... Specifies the name of the code topic to be ordered to the beginning of the executable. The binder control statement order will be generated. The default value of -O can be provided by the environment variable _LD_ORDER (see Environment Variables). -o outfile Specifies the name of the executable file produced by ld. The default output file is a.out. -S syslibdset Specifies the name of a system library (SYSLIB) data set that will be used to resolve symbols. -u function Specifies the name of the function to be added to the list of external symbols to be resolved. This option can be useful if the only input is archive libraries. If this option is not specified, no external symbol is added. -V This verbose option produces binder listings and directs them to stdout. Chapter 2. Shell command descriptions 351 ld -v This verbose option causes pseudo-JCL to be written to stdout before the binder is run. It provides information about exactly which binder options are being passed, and also which data sets are being used. -X sidefile Specifies the name of a side deck file or data set that ld will write to when producing a DLL (dynamic link library). Operands file.a Specifies the name of an archive file, as produced by the ar command, to be used by the binder for resolving external references. To specify an MVS data set name, precede the name with double slash (//), in which case the last qualifier of the data set name must be LIB. The data set specified must be a C370LIB object library or a load library. See the description of the –l libname operand for more information about using data sets as libraries. file.o Specifies the name of an object file, produced by the C/C++ run-time compiler or assembler, to be link-edited. To specify an MVS data set name to be link-edited, precede the file name with double slash (//), in which case the last qualifier of the data set name must be OBJ. If a partitioned data set is specified, more than one member name may be specified by separating each with a comma. For example: ld //file.OBJ(mem1,mem2,mem3) file.x Specifies the name of a definition side-deck produced by ld when creating a DLL (dynamic link library), and used by ld when linking an application using the DLL. See the description of side-deck processing in z/OS MVS Program Management: User's Guide and Reference. To specify an MVS data set name, precede the file name with double slash (//), in which case the last qualifier of the data set name must be EXP. If a partitioned data set is specified, more than one member name can be specified by separating each with a comma. For example: ld //file.EXP(mem1,mem2,mem3) Environment variables You can use environment variables to specify necessary system and operational information to ld. When a particular environment variable is not set, ld uses the default shown. For information about the JCL parameters used in these environment variables, see z/OS MVS JCL User's Guide. _LD_ACCEPTABLE_RC The maximum allowed return code (result) of the binder invocation. If the result is between zero and this value (inclusive), then it is treated internally by ld exactly as if it were a zero result, except that message IEW5033 might be issued. For more information about binder return codes, see z/OS MVS Program Management: User's Guide and Reference. The default value is: "4" _LD_ASUFFIX The suffix by which ld recognizes an archive file. This environment variable does not affect the treatment of archive libraries specified as -l operands, which are always prefixed with lib and suffixed with .a. The default value is: 352 z/OS V1R12.0 UNIX System Services Command Reference ld "a" _LD_ASUFFIX_HOST The suffix by which ld recognizes a library data set. This environment variable does not affect the treatment of data set libraries specified as -l operands, which are always used exactly as specified. The default value is: "LIB" _LD_DAMPLEVEL The minimum severity level of dynamic allocation messages returned by dynamic allocation message processing. Messages with severity greater than or equal to this number are written to stderr. However, if the number is out of the range shown here (that is, less than 0 or greater than 8), thenld dynamic allocation message processing is disabled. The default value is: "4" Following are the values: 0 Informational 1–4 Warning 5–8 Severe _LD_DAMPNAME The name of the dynamic allocation message processing program called by ld. It must be a member of a data set in the search order used for MVS programs. The default dynamic allocation message processing program is described in z/OS MVS Programming: Authorized Assembler Services Guide. The default value is: "IEFDB476" _LD_DCBU The DCB parameters used by ld for data sets with the attributes of record format undefined and data set organization partitioned. This DCB is used by ld for the output file when it is to be written to a data set. The default value is: "(RECFM=U,LRECL=0,BLKSIZE=6144,DSORG=PO)" _LD_DCB80 The DCB parameters used by ld for data sets with the attributes of record format fixed blocked and logical record length 80. The default value is: "(RECFM=FB,LRECL=80,BLKSIZE=5680)" _LD_DEBUG_DUMP The name of a data set to be used for capturing diagnosis data during execution of the binder. An unformatted dump will be written to this data set by the binder when it encounters a binder ABEND situation (usually accompanied by message IEW2900W) or when the binder option DUMP is specified. The data set must have been created before ld is invoked, and must be created with RECFM=VBA and LRECL=125. If this environment variable is null, the binder dump will not be captured. The default value is "" (null) _LD_DEBUG_TRACE The name of a data set to be used for capturing diagnosis data during execution of the binder. An unformatted trace will be written to this data set by the binder. The data set must have been created before ld is Chapter 2. Shell command descriptions 353 ld invoked, and must be created with RECFM=VB and LRECL=84. If this environment variable is null, the binder trace will not be captured. The default value is "" (null) _LD_ENTRY_POINT The value to be used as the -e option if -e is not specified. The default value is "" (null) _LD_EXTRA_SYMBOL The value to be used as the -u option if -u is not specified. The default value is "" (null) _LD_LIBDIRS_ The directories used by ld as the default place to search for archive libraries which are specified using the –l operand. The default value is: "/lib /usr/lib" _LD_ORDER The value to be used as the -O option if -O is not specified. The default value is "" (null) _LD_NEW_DATACLAS The DATACLAS parameter used by ld for any new data sets it creates. The default value is "" (null) _LD_NEW_DSNTYPE The DSNTYPE parameter used by ld for any new data sets it creates. The default value is "LIBRARY" which means that new data sets will be created as type PDSE. _LD_NEW_MGMTCLAS The MGMTCLAS parameter used by ld for any new data sets it creates. The default value is "" (null) _LD_NEW_SPACE The SPACE parameter used by ld for any new data sets it creates. The default value is "" (null) _LD_NEW_STORCLAS The STORCLAS parameter used by ld for any new data sets it creates. The default value is "" (null) _LD_NEW_UNIT The UNIT parameter used by ld for any new data sets it creates. The default value is "" (null) _LD_OPERANDS These operands are parsed as if they were specified after all other operands on the ld command line. The default value is 354 z/OS V1R12.0 UNIX System Services Command Reference ld "" (null) _LD_OPTIONS These options are parsed as if they were specified after all other operands on the ld command line. The default value is "" (null) _LD_OSUFFIX The suffix by which ld recognizes an object file. The default value is "o" _LD_OSUFFIX_HOST The suffix by which ld recognizes an object data set. The default value is "OBJ" _LD_SYSLIB The system library data set concatenation to be used to resolve symbols. The default value is: " " (null) _LD_SYSIX The system definition side-deck list to be used to resolve symbols. A definition side-deck contains link-editing phase IMPORT control statements naming symbols which are exported by a DLL. The default value is "" (null) _LD_XSUFFIX The suffix by which ld recognizes a definition side-deck file of exported symbols. The default value is "x" _LD_XSUFFIXHOST The suffix by which ld recognizes a definition side-deck data set of exported symbols. The default value is "EXP" Usage notes 1. Messages generated from the use of the ld command are provided in z/OS MVS System Messages, Vol 8 (IEF-IGD). 2. ld provides similar function to the link-edit step of the c89 command. It does not provide any functions of the compile and assembly phases of c89, nor any steps of the link-edit phase except for the link-edit step --ld merely calls the program management binder. The other main difference is that c89 has default settings that are designed for linking an object file produced by the C/C++ run-time compiler for execution in the Language Environment, whereas the default settings of ld do not include compiler or environment assumptions, and it can therefore be more easily used to link objects from other compilers or that are destined for environments other than Language Environment. You can use ld options, operands, or environment variables to cause ld to create executable modules that are compatible with those c89 produces by default: Option or operand Environment variable Value for c89 compatibility -e _LD_ENTRY_POINT CEESTART or, for AMODE 64 code, CELQSTRT Chapter 2. Shell command descriptions 355 ld -O _LD_ORDER CEESTART or, for AMODE 64 code, CELQSTRT -S _LD_SYSLIB //’CEE.SCEELKEX’: //’CEE.SCEELKED’: //’CBC.SCCNOBJ’: //’SYS1.CSSLIB’ or installation equivalent names -u _LD_EXTRA_SYMBOL CEEMAIN or, for AMODE 64 code, CELQMAIN file.a _LD_OPERANDS //CEE.SCEEOBJ 3. When a data set name is specified, the argument must start with double-slash (//) followed by the data set name. If the name is enclosed in single quotes, it is assumed to be fully qualified and is taken as is. Otherwise, the user login name followed by a period is prefixed. 4. To be able to specify an operand that begins with a dash (-), you must use the double dash (--) end-of-options delimiter. 5. When ld is invoked from the shell, any option-arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, source files specified as PDS member names contain parentheses; and if they are specified as fully qualified names, they contain single quotes. To escape these special characters, either enclose the option-argument or operand in double quotes, or precede each character with a backslash. 6. Options and arguments are processed in the order read (from left to right). Where there are conflicts, the last specification is used. If options that require arguments are specified more than once, the last specification is used except as follows: -b Binder options are appended in the order they are specified -f Each file is processed when the -f option is encountered -L Library directories are appended in the order they are specified -l Libraries are searched when the -l option is encountered -S SYSLIB data sets are appended in the order they are specified All operands are processed in the order they are specified. 7. Because archive library files are searched when their names are encountered, the placement of -l operands and file.a operands is significant. You may have to specify a library multiple times on the command string, if subsequent specification of file.o files requires that additional symbols be resolved from that library. 8. The following environment variable specifies the name of an MVS program to be executed and can be at most eight characters in length. You can dynamically alter the search order used to find MVS programs by using the STEPLIB environment variable. For more information about the STEPLIB 356 z/OS V1R12.0 UNIX System Services Command Reference ld environment variable, see the section on commonly used environment variables in z/OS UNIX System Services Planning. It is also described under the sh command. v _LD_DAMP_NAME 9. The following environment variables can be at most 15 characters in length. You should not specify any periods (.) when setting these environment variables because they would then never match their corresponding operands: v _LD_ASUFFIX v _LD_ASUFFIX_HOST v _LD_OSUFFIX v _LD_OSUFFIX_HOST v _LD_XSUFFIX v _LD_XSUFFIX_HOST 10. The following environment variable is a parsed colon-delimited data set name, and represents a data set concatenation or a data set list: v _LD_SYSLIB 11. The following environment variables specify the names of MVS databases and can be at most 44 characters in length: v _LD_DEBUG_DUMP v _LD_DEBUG_TRACE 12. The following environment variables can be at most 63 characters in length: v _LD_NEW_DATACLAS v _LD_NEW_DSNTYPE v _LD_NEW_MGMTCLAS v _LD_NEW_SPACE v _LD_NEW_STORCLAS v _LD_NEW_UNIT 13. The following environment variable is for specification of the SPACE parameter, and supports only the syntax as shown below, including all commas and parentheses (example: "(,(10,10,10))"). PRIMARY is the number of tracks of primary to be allocated, SECONDARY the number of secondary tracks, and DIRBLOCKS the number of directory blocks. DIRBLKS must be specified even when it is not needed. v _LD_NEW_SPACE 14. The following environment variable is for specification of the DSNTYPE parameter, and supports only the sub-parameters LIBRARY or PDS (or null for the default, LIBRARY): v _LD_NEW_DSNTYPE 15. The following environment variables can be at most 127 characters in length: v _LD_DCBU v _LD_DCB80 Restriction: These environment variables are for specification of DCB information, and support only the following DCB sub-parameters, with the noted restrictions: RECFM Incorrect values are ignored. LRECL None Chapter 2. Shell command descriptions 357 ld BLKSIZE None DSORG Incorrect values are treated as if no value had been specified. 16. The following environment variables are parsed as blank-delimited words, and therefore no embedded blanks or other white space is allowed in the value specified. The maximum length of each word is 1024 characters: v _LD_LIBDIRS v _LD_OPTIONS v _LD_OPERANDS Localization ld uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES See Appendix F, “Localization” for more information. Exit values 0 Successful completion. >0 An error occurred during processing. Related information c89 let — Evaluate an arithmetic expression Format let expression ... ((expression)) Description let evaluates each arithmetic expression from left to right, with normal algebraic precedence (multiplication before addition, for example). let uses long integer arithmetic with no checks for overflow. No output is generated; the exit status is 0 if the last expression argument has a nonzero value, and 1 otherwise. The following two lines are equivalent: the second form avoids quoting and enhances readability. These two forms are extensions to the POSIX standard. let "expression" ((expression)) The POSIX version of this command is as follows: $((expression)) Expressions consist of named variables, numeric constants, and operators. Characters in the names of named variables must come from the POSIX portable character set. 358 z/OS V1R12.0 UNIX System Services Command Reference let See “Arithmetic substitution” on page 582 Examples Examples of the three forms of the let command are as follows: 1. The example let a=7 echo $a produces: 7 2. The example echo $((a=7*9)) produces: 63 3. The example ((a=3*4)) echo $a produces: 12 Usage note let is a built-in shell command. Localization let uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 The last argument evaluated to a nonzero value 1 The last argument evaluated to a zero value, or the expression contained a syntax error or tried to divide by zero Portability POSIX.2. let and ((expression)) are extensions to the POSIX.2 standard. The POSIX.2 portable facility for arithmetic expression evaluation is $((expression)). See “Arithmetic substitution” on page 582 for more information. The (( )) syntax only works if the set –o korn option is in effect. Related information expr, sh, test Chapter 2. Shell command descriptions 359 lex lex — Generate a program for lexical tasks Format lex [–achlntTv] [–o file.c] [–P proto] [–p prefix] [file.l ...] Description lex reads a description of a lexical syntax, in the form of regular expressions and actions, from file.l. If you do not provide file.l, or if the file is named –, lex reads the description from standard input (stdin). It produces a set of tables that, together with additional prototype code from /etc/yylex.c, constitute a lexical analyzer to scan those expressions. The resulting recognizer is suitable for use with yacc. You can find detailed information regarding the use of lex in z/OS UNIX System Services Programming Tools. For a description of the typedefs, constants, variables, macros, and functions in the table file, which can be used to access the lexical analyzer's variables or to control its operations, see z/OS UNIX System Services Programming Tools. Options –a Generates 8-bit tables instead of 7-bit tables. On systems with 8-bit character sets (such as this one), this option is always enabled. –c Generates C code. Because this is the default, this option is provided only for compatibility with other implementations. –h Prints a brief list of the options and quits. –l Suppresses #line directives in the generated code. –n Suppresses the display of table sizes by the –v option. If you did not specify –v and their are no table sizes specified in file.1, lex behaves as though you specified –n. –o file.c Writes the lexical analyzer (internal state tables) onto the named output file, instead of the default file lex.yy.c. –P proto Uses the named code file, instead of the default prototype file /etc/yylex.c. –p prefix Uses the given prefix instead of the prefix yy in the generated code. –T Writes a description of the analyzer onto the file l.output. –t Writes the lexical analyzer onto standard output (stdout) instead of the file lex.yy.c. –v Displays the space used by the various internal tables. Normally lex displays these statistics on stdout, but if you also specified the –t option, it displays them on stderr. If you did not choose this option and file.1 specifies table sizes, lex still displays these statistics unless you specified the –n option. The lex library contains a number of functions essential for use with lex. These functions are described in z/OS UNIX System Services Programming Tools . The actual library to use depends on your system and compiler. For z/OS programs, you should use –ll. 360 z/OS V1R12.0 UNIX System Services Command Reference lex Some lex programs can cause one or more tables within lex to overflow. These tables are the NFA, DFA, and move tables; lex displays an appropriate message if an overflow occurs. You can change table sizes by inserting the appropriate line into the definition section of the lex input, with the number size giving the number of entries to use. This is shown in Table 15. Table 15. Internal table sizes (lex command) Line Table size affected %esize Number of NFA entries %nsize Number of DFA entries %psize Number of move entries Default 1000 500 2500 You can often reduce the NFA and DFA space to make room for more move entries. Locale A locale is the subset of a user's environment that depends on language and cultural conventions. A locale defines such things as the definition of characters, and the collation sequence of those characters. POSIX.2 defines a POSIX locale, which is essentially USASCII. Since lex generates code that is then compiled before being executed, it is difficult for lex to act properly on collation information. The POSIX.2 standard therefore does not require lex to accept any locales other than the POSIX locale. lex accepts regular expressions in this locale only. Files lex uses the following files: l.output Scanner machine description lex.yy.c Tables and action routines /etc/yylex.c The prototype lex scanner /usr/lib/libl.a lex archive library with functions compiled for 31–bit addressing mode. /usr/lib/liblxp.a lex archive library with functions compiled with XPLINK. Includes two versions: 64–bit addressing mode and 31–bit addressing mode. Localization lex uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Chapter 2. Shell command descriptions 361 lex Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to create an output file v Inability to open the file v Missing output filename after –o v Missing prefix after –p v No lex rules v No memory for DFA moves v Out of NFA state space v Out of DFA move space v Out of DFA state space v Push-back buffer overflow v Read error on file v Table too large for machine v Too many character classes v Too many translations v Unknown option v Write error on file v Incomplete %{ declaration v Token buffer overflow Limits The parser stack depth is limited to 150 levels. Attempting to process extremely complicated syntaxes may result in an overflow, causing an error. Portability POSIX.2, POSIX.2 C-Language Development Utilities Option, UNIX systems. The –a, –h, –l, –o, –p, –P, and –T options are extensions of the POSIX standard. Related information yacc For more information, see z/OS UNIX System Services Programming Tools. line — Copy one line of standard input Format line The line utility is fully supported for compatibility with older UNIX systems. However, it is recommended that the read utility be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Description line copies one input line from its standard input (stdin) to its standard output (stdout). The end of the line is the first newline encountered. This is useful in shell files that need small amounts of input (for example, responses to prompts). 362 z/OS V1R12.0 UNIX System Services Command Reference line Examples echo “Enter name:\c” NAME=`line` Localization line uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 A line was read successfully 1 line reached end-of-file before finding a newline character Portability X/Open Portability Guide, UNIX System V. Related information cat, head, read, sh, tail link — Create a hard link to a file Format link oldfile newfile Description link creates a hard link to an existing file. A link is a new directory entry that refers to the same file. This entry can be in the same directory that currently contains the file or in a different directory. The result is that you get a new path name that refers to the file. You can access the file under the old or new path name since both path names are of equal importance. If you use rm to remove one path name, the other remains and the file contents are still available under that name. The contents of the file do not disappear until the last remaining link associated with the file is removed. Following the format, new becomes a new path name for the existing file old. If old names a symbolic link, link creates a hard link to the file that results from resolving the path name contained in the symbolic link. Links are allowed to files only, not to directories. A file can have any number of links to it. Thus, you can establish any number of different path names for any file. link is implemented as a shell built-in. Localization link uses the following localization environment variables: v LANG v LC_ALL Chapter 2. Shell command descriptions 363 link v v v v LC_CTYPE LC_MESSAGES LC_SYNTAX NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v A file specified could not be found v No write permission on the directory intended to contain the link v No search permission on a path name component of old or new v No permission to access old v The path name of one of the arguments is a directory v The new link file already exists 2 Failure due to incorrect number of arguments Related Information link, ln, rm ln — Create a link to a file Format ln [–fiRrs] old new ln [–fiRrs] old old ... dir ln -e [-fi] old new Description ln creates a link to an existing file or set of files. A link is a new directory entry that refers to the same file. This entry can be in the same directory that currently contains the file or in a different directory. The result is that you get a new path name that refers to the file. You can access the file under the old path name or the new one. Both path names are of equal importance. If you use rm to remove either name, the other one still remains and the file contents are still available under that name. The contents of the file do not disappear until you remove the last link. A file can have any number of links to it. Thus you can establish any number of different path names for any file. In the first form given in the syntax, new becomes a new path name for the existing file old. In the second form, ln creates entries for all the old files under the directory dir. For example, ln yourdir/* mydir creates links under mydir to all the files under yourdir. The files have the same names under mydir that they had under yourdir. ln always assumes this directory form when the last operand on the command line is the name of a directory. In this case, none of the old names can be a directory, unless -r or -R is specified. 364 z/OS V1R12.0 UNIX System Services Command Reference ln There could already be a file with the same name as the link you are trying to set up: a conflicting path name. To deal with a conflicting path name, ln follows these steps. v If you have specified –i, ln writes a prompt to stderr to ask if you want to get rid of the conflicting path name. If you answer affirmatively, ln attempts to remove it. v Otherwise, if you have specified –f, ln attempts to remove the existing file without a warning. v Otherwise, ln prints a diagnostic message. v ln gets to this point if it is going to get rid of the conflicting path name. It therefore attempts to get rid of the conflicting path name in the same way that rm does. ln deletes the file associated with the path name if this path name is the last link to the file. If ln can't get rid of the conflicting path name, it does not attempt to establish the new link; it simply prints an error message on stderr and goes on to process any other files. v If ln successfully gets rid of the conflicting path name, it then establishes the link. Options –e Specifies that the link created by ln is to be an external link. One purpose for creating an external link is to create a mount point that an NFS client can use to access a data set through the Network File System feature. If you specify one of these options with -e, the command will fail. The normal content of an external link is a name that refers to an object outside the hierarchical file system, such as a data set. The data set that the Network File System feature uses can be any type of MVS data set. For a partitioned data set, however, you specify a fully qualified name in all caps. For example: ln -e NOLL.PLIB.PGMA /u/noll/plib/pgma The -e option is mutually exclusive with -r, -R and -s. Restriction: Due to the NFS protocol limitation, -e does not create an external link on NFS. If you want to create an external link on NFS, see the topic on creating an external link for details in z/OS Network File System Guide and Reference. External links can also be used to map a z/OS UNIX file name to a PDS or PDSE member name for an executable load module. An example of how you would define the external link is: ln -e MYPGM /u/smorg/mylongpgmname If an application attempts to access /u/smorg/mylongpgmname as an executable file, the kernel will attempt to load MYPGM from the current MVS search order (Job Pack Queue, STEPLIB/JOBLIB, LPA, LINK LIST). The kernel services which behave this way for external links are: v exec() (all flavors) v spawn() (including _spawn2, spawnp, _spawnp2) v loadhfs which is used for all DLL processing and locales An external link can be used as a shell command to invoke a program in the current MVS search order. –f Deletes any conflicting path names without asking you for confirmation. If -i is also specified, regardless of the order in which -i and -f appear on the command line, -i is ignored. Chapter 2. Shell command descriptions 365 ln –i Checks with you before deleting conflicting path names. If -f is also specified, regardless of the order in which -i and -f appear on the command line, -i is ignored. –R Links files recursively. That is, you can link an entire hierarchy of subdirectories at once. -R is mutually exclusive with the -e option. –r Is identical to –R. -r is mutually exclusive with the -e option. –s Creates a symbolic link. The -s option is mutually exclusive with the -e option. For a symbolic link, old refers to the file you want to create the link to. That file does not have to exist. The name of the symbolic link that you are creating is new. Example: If you have a file called f1 and you want to create a symbolic link to it called my_sym, issue: ln -s f1 my_sym The locale settings for LC_COLLATE, LC_CTYPE, and LC_MESSAGES affect the program's interpretation of what constitutes a “yes” answer when ln asks if you want to delete a conflicting path name. Examples If you define /u/user1/name1 as a symbolic link to /u/user1/name2, and then invoke name1: 1. The shell will spawn name1. 2. spawn() will access the file for name1 unaware that there is a symbolic link already established. It will access the name2 file by its underlying vnode, not the name2 handle. 3. If the sticky bit is on for the name2 file, spawn() will do the MVS search for name1 (the only name it has to work with). Symbolic and external links with a sticky bit: Note: DLLs, and all flavors of spawn() and exec(), follow the same processing as described in this section. Where it says exec(), it covers all forms of module loading. 1. External links: exec() does a stat() on the passed filename. stat() does the search, not exec(). If the filename is an external link, then stat() fails with a unique reason code which causes exec() to read the external link. If the external link name is a valid PDS member name (1–8 alphanumeric or special characters), then exec() will attempt to locate the module in the MVS search order. If it cannot be found, exec() fails. The external link is normally used when you want to set the sticky bit on for a file name which is longer than 8 characters or contains characters unacceptable for a PDS member name. 2. Symbolic links: If the filename you specify is a symbolic link, and exec() sees the sticky bit on, then it will truncate any dot qualifiers. So, as long as the base filename is an acceptable PDS member name, the need to set up links in order to get exec() to go to the MVS search order should not be an issue. 366 z/OS V1R12.0 UNIX System Services Command Reference ln For example, if you have a file named java.jll, when you put the sticky bit on, exec() will attempt to load JAVA. If exec() cannot find JAVA, it will revert to using the java.jll file in the file system. The important thing to understand is that exec() never sees the name that the symbolic link resolves to even though it can see the stat() data for the final file. Localization ln uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 All requested links were established successfully. 1 Failure due to any of the following: v An argument had a trailing / but was not the name of a directory. v A file could not be found. v An input file could not be opened for reading. v An output file could not be created or opened for output. v The new link file already exists. v A link could not be established. v A read error occurred on an input file. v A write error occurred on an output file. v The input and output files were the same file. v Inability to access a file when using –r. v Inability to read a directory when using –r. v Inability to create a directory when using –r. v A target is not a directory when using –r. v Source and destination directory are the same when using –r. 2 Failure due to any of the following: v Incorrect command-line option. v Too few arguments on the command line. v A target that should be a directory but isn't. v No space left on target device. v Out of memory to hold the data to be copied. v Inability to create a directory to hold a target file. Messages Possible error messages include: link to target name failed ln could not establish the link to the given file or directory. This may be because you do not have appropriate permissions, or because the target did not exist. source name and target name are identical The source and the target are actually the same file (for example, because of links, on UNIX systems). In this case, ln does nothing. Chapter 2. Shell command descriptions 367 ln target directory name on different file system than source name You cannot establish a normal link between files that are two different file systems. target name must be a directory The target name must be a directory cannot find file name The file name could not be found. target file name already exists The target file name already exists. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Only the -f option is part of the POSIX standard. Related information cp, locale, mv, rm locale — Get locale-specific information Format locale [–a|–m]locale [–ck] name ... Description locale displays information about the current locale and all locales accessible to the current application. locale searches directory /usr/lib/nls/locale for all the compiled locales. Invoking locale with no options or operands displays the values of the LANG and LC_* environment variables. If a LC_* variable is not set or is overridden by LC_ALL, locale displays its implied value in double quotes. The operand name can be a category name, keyword name, or the reserved name charmap. If it is a category name, locale selects the given category and all keywords within it for output. If name is a keyword name, locale selects the given keyword and its category for output. If name is charmap, locale displays the name of the charmap used with the localedef –f option when the locale was created. Options –a Displays information about all accessible locales including POSIX, the POSIX locale. –c Displays the names of selected categories. –k Displays the names of selected keywords. If you do not specify the –k option, locale displays the values of selected keywords but not their names. With –k, strings are written in an unambiguous form using the escape character from the current locale. –m Displays a list of all available character maps. The following list contains valid locale keywords: 368 z/OS V1R12.0 UNIX System Services Command Reference locale abday abmon alpha am_pm backslash blank character-collation charmap circumflex cntrl codeset code_set_name commercial_at currency_symbol d_fmt d_t_fmt day decimal_point digit dollar_sign daylight_name end_day end_month end_time end_week exclamation_mark frac_digits graph grave_accent grouping int_curr_symbol int_frac_digits left_brace left_bracket lower Abbreviated day names Abbreviated month names All alphabetic characters (upper and lower case) A.m. and p.m. string Encoding of \ How a blank is represented The collating sequence Mapping of character symbols to actual character encodings Encoding of ^ Control characters Same as code_set_name Name of the coded character set used Encoding of @ Local currency symbol of the current locale Date format Date and time format Full day names Decimal-point characters All numeric characters Encoding of $ The name of the daylight saving time zone (DST). The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Day of the week when daylight saving time (DST) ends. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Week of the month when daylight saving time (DST) ends. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Number of seconds after midnight when daylight saving time (DST) ends. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Month of the year when daylight saving time (DST) ends. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Encoding of ! Number of digits to the right of the decimal place in monetary quantities Graphic characters Encoding of ` String indicating the size of each group of digits in formatted nonmonetary quantities International currency symbol for the current locale The number of displayed digits to the right of the decimal place for internationally formatted monetary quantities Encoding of { Encoding of [ Lowercase alphabet Chapter 2. Shell command descriptions 369 locale mb_cur_max mon mon_decimal_point mon_grouping mon_thousands_sep n_cs_precedes n_sep_by_space n_sign_posn negative_sign noexpr number_sign p_cs_precedes p_sep_by_space p_sign_posn positive_sign print punct right_brace right_bracket shift space start_day start_month start_time start_week 370 z/OS V1R12.0 UNIX System Services Command Reference Maximum number of bytes used to represent a character Full month names Decimal-point character used to format monetary quantities String indicating the size of each group of digits in formatted monetary quantities Separator for digits in formatted monetary quantities 1 if the currency_symbol precedes the value for a negative formatted monetary quantity; 0 if it does not 1 if the currency_symbol is separated by a space from the value of a negative formatted monetary quantity; 0 if it does not; 2 if a space separates the symbol and the sign string–if adjacent Value indicating the position of the negative_sign for a negative formatted monetary quantity String indicating the negative sign used in monetary quantities Expression for negative Encoding of # 1 if the currency_symbol precedes the value for a nonnegative formatted monetary quantity; 0 if it does not 1 if the currency_symbol is separated by a space from the value of a nonnegative formatted monetary quantity; 0 if it does not; 2 if a space separates the symbol and the string–if adjacent Value indicating the position of the positive_sign for a nonnegative formatted monetary quantity String indicating the positive sign used in monetary quantities Printable characters Punctuation characters Encoding of } Encoding of ] DST time shift in seconds. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. How white space is represented Day of the week when daylight saving time (DST) starts. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Month of the year when daylight saving time (DST) starts. The value ranges from 1 through 12. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Number of seconds after midnight when daylight saving time (DST) starts. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Week of the month when daylight saving time locale t_fmt t_fmt_ampm tilde timezone_difference timezone_name tolower thousands_sep toupper uctname upper vertical_line xdigit yesexpr (DST) starts. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Time format Long date format Encoding of ~ Time zone difference in minutes. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Time zone name. The value will be overwritten if it is different from the keyword setting defined by the TZ environment variable. Uppercase to lowercase conversion Character used to separate groups of digits to the left of the decimal-point character in formatted nonmonetary quantities Lowercase to uppercase conversion Coordinated Universal Time. The value will be overwritten if it is different from the keyword setting may be overridden if TZ is set. Uppercase alphabet Encoding of | Hexadecimal digits Expression for affirmative Examples In the following examples, let's assume that locale environment variables are set as follows: LANG=locale_x LC_COLLATE=locale_y 1. The command: locale produces the following output: LANG=locale_x LC_CTYPE="locale_x" LC_COLLATE=locale_y LC_TIME="locale_x" LC_NUMERIC="locale_x" LC_MONETARY="locale_x" LC_SYNTAX="locale_x" LC_TOD="locale_x" LC_MESSAGES="locale_x" LC_ALL= 2. The command: LC_ALL=POSIX locale -ck decimal_point produces: LC_NUMERIC decimal_point="." 3. The following command shows an application of locale to determine whether a user supplied response is affirmative: Chapter 2. Shell command descriptions 371 locale if printf "s%\n" "$response" | grep -Eq "$(locale yesexpr)" then affirmative processing goes here else nonaffirmative processing goes here fi Environment variable locale uses the following environment variable: Contains the time zone to be used when displaying date and time strings. TZ Localization locale uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 1 2 Successful completion An error occurred A usage message was printed Portability POSIX.2, UNIX System V. Related information localedef localedef — Define the locale environment Format localedef [–c] [–f charmap] [–i sourcefile] [–m methodfile] [–w] [–A] [–L binderoptions] [–X] [–6] name Description localedef converts source definitions for locale categories into a format usable by functions and utilities. localedef, which is installed as part of the Language Environment element of z/OS, utilizes c89, which is installed as part of z/OS Run-Time Library Extensions. c89 requires the installation of the C/C++ optional feature of z/OS (which provides among other things a C compiler). A TSO/E utility called LOCALDEF is installed as part of Language Environment. v It is not supported by the z/OS shell; for more information see z/OS XL C/C++ User's Guide. 372 z/OS V1R12.0 UNIX System Services Command Reference localedef v The TSO/E BATCH versions of the utility do not support ASCII (-A) nor AMODE-64 (-6) options. For information about the charmap file and locale definition source file formats, see z/OS XL C/C++ Programming Guide. Options –c Creates permanent output even if there were warning messages. Normally, localedef does not create permanent output when it has issued warning messages. –f charmap Specifies a charmap file that contains a mapping of character symbols and collating element symbols to actual character encodings. –i sourcefile Specifies the file that contains the source definitions. If there is no –i, localedef reads the source definitions from the standard input. –m methodfile Specifies the name of a method file that describes the methods to be overridden when constructing a locale. localedef reads the method file and uses entry points when constructing the locale objects. The code set methods specified are also used in parsing the file pointed to by the CharMap variable. This requires that you provide the overriding methods in a DLL which is explicitly loaded by localedef before processing the charmap file. User method files are supported only for ASCII locales. The -m option is invalid without the -A option. –w Produces warning messages for duplicate definitions. –A Instructs localedef to generate an ASCII locale object. The –X option is implied when this option is specified. –L binderoptions Instructs localedef to pass additional binder options (mostly for diagnostic purposes). –X Instructs localedef to generate an XPLINK AMODE 31 locale object (DLL). –6 Instructs localedef to generate an XPLINK AMODE 64 locale object (DLL). The -X option is implied when this option is specified. name Is the target locale. If it contains no slashes, the locale is public and localedef converts name to a full path name using the NLSPATH environment variable. If name contains one or more slashes, localedef interprets it as a full path name of where to store the created definition. See “locale” on page 368 for related information. Localization localedef uses the following localization environment variables: v LANG v LC_ALL v LC_MESSAGES v NLSPATH The LC_COLLATE and LC_CTYPE environment variables do not affect localedef. localedef always behaves as though these variables were set to the POSIX locale. Chapter 2. Shell command descriptions 373 localedef See Appendix F, “Localization” for more information. Exit values 0 No errors occurred; the locale was successfully created. 1 Warnings occurred; the locale was successfully created. 2 The locale specification exceeded implementation limits, or the coded character set used was not supported by implementation. No locale was created. 3 The capability to create new locales is not supported by the implementation. (POSIX2_LOCALEDEF is not defined.) >3 Warnings or errors occurred; no output was created. localedef issues warnings when: v The LC_CTYPE or LC_COLLATE category description uses a symbolic name that was not found in the charmap file. v The number of operands to the order keyword exceeds the COLL_WEIGHTS_MAX limit. Portability POSIX.2; UNIX System V. Related information locale logger — Log messages Format logger [–IisTu] [–d dest] [–f filename] [–p priority] [–t tag] [–a tag2] string ... Description logger saves a message in the console log; the message consists of the string operand on the command line. Some options of logger may be in effect by default; if they are on by default, they cannot be disabled. The –u and –i options are in effect by default, so all messages from logger are prefixed by process ID and user login user name. If there is no message specified on the command line, the standard input is read; each line of standard input is treated as a log message, and, thus, all terminal input will be logged as a message. To stop all subsequent input from being processed by logger, enter the designated escape character, such as ¢, followed by a capital C, for example: ¢C. If –f filename is specified, the file is read instead of the standard input. Options –f filename Reads log messages from the file filename rather than from the standard input. 374 z/OS V1R12.0 UNIX System Services Command Reference logger –I Adds the parent process ID (PPID) of logger to the message. –i Adds the process ID (PID) of logger to the message. This option is in effect by default, so all messages from logger are prefixed by the PID. –s Overrides any destination options and causes logging to the standard error output. –T Adds a time stamp (%x %X format, per date) to the message. This time stamp is always in the POSIX locale, no matter the locale of the message. –u Adds the login name of the controlling terminal to the message. This option is in effect by default, so all messages from logger are prefixed by the login name. Note: The following options work on z/OS. However, because they are system-specific, they may or may not actually work on another system. –d destination Must be a list of numbers, separated by spaces, tabs, or commas, in the range of 1 to 128, and represents a bit in the routing code number (that is, ROUTCDE=) in the WTO macro. The default destination value is 0 (no bits set in the routing code number). If you use d1, the message goes to the system console. –p priority Must be a list of numbers, separated by spaces, tabs, or commas, in the range of 1 to 16 and represents a bit in the message descriptor code (that is, DESC=) in the WTO macro (WTO == write to operator). The default priority value is 0 (that is, no bits set). –t tag Adds tag to the start of the message. –a tag2 Adds tag2 in front of all the options and the message. For more information about the destination and priority options, refer to z/OS MVS JCL Reference. Examples 1. If you issue: logger -d1 This is a message. You will see: +WELLIE4: 2097152017: This is a message. 2. If you issue: logger -dl -a TheTag A message. You will see: +TheTag: WELLIE4: 213076449: A message. Localization logger uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES Chapter 2. Shell command descriptions 375 logger v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion >0 An error occurred Messages Possible error messages include: -f filename invalid if message given Both a file name and message was specified; only one is allowed. file filename: system error The file specified by –f filename could not be opened. Formatted log message too long -- limit LINE_MAX (number) The log message specified was longer than the limit specified by LINE_MAX. Unknown option option You specified an incorrect option to logger. Portability POSIX.2, X/Open Portability Guide. All the options are extensions of the POSIX standard. logname — Return a user's login name Format logname Description logname displays the login name of the person who issued the command. It obtains the login name through the getlogin() function defined in the POSIX.1. standard. The login name is displayed as all uppercase letters, regardless of how it was entered. Environment variables logname uses the following environment variable: LOGNAME Contains your user name. Localization logname uses the following localization environment variables: v LANG v LC_ALL v LC_TYPE v LC_MESSAGES v NLSPATH 376 z/OS V1R12.0 UNIX System Services Command Reference logname See Appendix F, “Localization” for more information. Exit values 0 1 Successful completion logname could not determine the login name Portability POSIX.2, X/Open Portability Guide, UNIX System V. Related information env, id lp — Send a file to a printer Format lp [–cmsw] [–d dest] [–n number] [–o printer-option] [–t title] [file ...] Description lp prints one or more input files on a printer. If you do not specify any files on the command line, or if you specify a file name of – (dash), lp reads and prints the standard input. The files are printed in the same order that they are specified on the command line. Note: If you are using the z/OS Infoprint Server Feature, your system automatically uses that version of the lp command. For more information about the z/OS Infoprint Server commands, see z/OS Infoprint Server User's Guide. Options –c Immediately copies the files to be printed. This ensures that the version of the file that exists when the print request is made is the version printed. –d dest Specifies dest as the output device. –d takes precedence over the LPDEST environment variable, which in turn takes precedence over the PRINTER environment variable. dest is a comma-separated list of arguments that is passed to JES. The first item must be the “destination_name”. The destination name can take the form NODE.USER. The second item must be the “class”. The third item must be the “forms”. Not all items must be specified, but the items must be specified in the proper order. The definition of “destination_name”, “class”, and “forms” is defined by JES. For more information about the dest option, see z/OS MVS JCL Reference. –m This option is not implemented. –n number Prints number copies of each input file (the default is 1 copy). –o printer-option This option is not implemented. –s This option is not implemented. Chapter 2. Shell command descriptions 377 lp –t This option is not implemented. –w This option is not implemented. Examples 1. To send a previously formatted file to a JES printer: lp filename You can specify more than one file name with the command. 2. The following prints the file temp.prt using the default printer destination and specifying class c (where c is the locally designated class for secured information): lp –d ,c temp.prt lp –d,c temp.prt The parameters on the -d option are positional, so if you omit a destination, you must still include the comma. Environment variables lp uses the following environment variables: LPDEST Names the output device. This variable takes precedence over PRINTER. PRINTER Names the output device if LPDEST is not defined. Localization lp uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion >0 An error occurred Portability POSIX.2, X/Open Portability Guide. The –m, –o, –s, –t, and –w options are extensions to the POSIX standard. lpstat — Show status of print queues (stub command) Format lpstat [–drst ] [–a [list]] [–c [list]] [–o [list]] [–p [list]] [–u [list]] [–v] [list] [queue_id ...] 378 z/OS V1R12.0 UNIX System Services Command Reference lpstat Description lpstat shows the status of print queue or queues, specified by queue_id. If no queue_id is given, lpstat lists information for all of the printers on the system. lpstat is recognized, but its functions are not supported. If you are using the z/OS Print Server Feature, your system automatically uses that version of the lpstat command. For more information about the z/OS Infoprint Server commands, see z/OS Infoprint Server User's Guide. ls — List file and directory names and attributes Format ls [–AabCcdEFfgHikLlmMnopqRrstuWx1] [pathname ...] The file tag specific option is as follows: ls [–T] Description ls lists files and directories. If the pathname is a file, ls displays information about the file according to the requested options. If it is a directory, ls displays information about the files and subdirectories therein. You can get information about a directory itself using the –d option. If you do not specify any options, ls displays only the file names. When ls sends output to a pipe or a file, it writes one name per line; when it sends output to the terminal, it uses the –C (multicolumn) format. Note: Code sets that are aliases of each other exist which might cause the test to fail, because the file inquiry operator might return an alias of the code set that you are testing. Options ls displays at least the file name; you can request more information with the following options: –A Lists all entries including those starting with periods (.); but excluding any . or .. entries. –a Lists all entries including those starting with a period (.). –b Displays nonprintable characters as octal bytes with the form \ooo. –C Puts output into columns, sorted vertically; this is the default output format to the terminal. –c Uses the time of the last change of the file's attributes for sorting (–t) or displaying (–l) . –d Does not display the contents of named directories, but information about the directories themselves. –D Displays from directories. –E Displays extended attributes for regular files: a Program runs APF-authorized if linked AC=1 Chapter 2. Shell command descriptions 379 ls p s l — Program is considered program-controlled Program is enabled to run in a shared address space Program is loaded from the shared library region Attribute not set See “Long output format” on page 381. –F Puts a / after each directory name, a * after every executable file, a | after every FIFO file, a @ after every symbolic link, and a = after every socket. It also puts an & character after an external link name. –f Forces the pathname argument to be a directory; turns off sorting. ls gives the ordered list of file names in a directory file. The directory file is read and the file names are listed in the same order as they are returned. The contents of a directory file are shown. –g Same as –l except that it does not display owner. –g turns on the Long Output Format. See “Long output format” on page 381 for details. –H Displays file formats for regular files: –––– Not specified bin Binary data rec Record. (File data consists of records with prefixes. The record prefix contains the length of the record that follows. From the shell command perspective, files with this format will be treated as if they were binary files.) Or the nl cr lf crlf lfcr crnl following text data delimiters: Newline character Carriage return Line feed Carriage return followed by line feed Line feed followed by carriage return Carriage return followed by new line –H turns on the Long Output Format. See “Long output format” on page 381 for details. –i Displays file serial (inode) numbers along with file names. –k Uses 1024 bytes for block size. –L Follows symbolic links. –l Displays permissions, links, owner, group, size, time, name. See “Long output format” on page 381 for details. –M Displays the security label of the file, as in this example: > ls -M has_seclabel no_seclabel SECLABEL has_seclabel no_seclabel ls –M does not turn on the –l option. ls –M can be used with other options. See “Long output format” on page 381 for details. 380 –m Displays names in a single line, with commas separating names. –n Displays UID number and GID number. –o Same as –l except that it does not display group. z/OS V1R12.0 UNIX System Services Command Reference ls –o turns on the Long Output Format. See “Long output format” for details. –p Puts / after directory names. –q Displays nonprintable characters as ?. –R Lists subdirectories recursively. –r Sorts in reverse of typical order; you can combine this with other options that sort the list. –s Displays size in blocks, after the file serial (inode) number, but before other information. The block size is 512 bytes unless the –k option is used. –t Sorts by time. By default, this option sorts the output by the modification times of files. You can change this with the –c and –u options. –u Uses the last access time for sorting (–t) or displaying (–l) . –W Enables the audit bits to be displayed. This option turns on the –l option. These bits are printed in a 6-character field directly after the field displaying the file permission bits. These 6 characters are really two groups of 3 bits each. The first group of 3 describes the user-requested audit information. The second group of 3 describes the auditor-requested audit information. Each 3 characters displayed are the read, write, and execute (or search) audit options. Each character indicates the audit option as: s f a – (Audit successful audit attempts) (Audit failed access attempts) (Audit all accesses) (No audit) –W turns on the Long Output Format. See “Long output format” for details. –x Puts output into sorted columns, with output going across the rows. –1 Forces output to be one entry per line. Note: When you specify options that are mutually exclusive (for example, –c and –u), the option that appears last on the command line is used. File tag specific option –T Displays file tag information associated with the file. The format of this output will be similar to the output from chtag –p. An example output: > ls -T file t IBM-1047 T=on file1 ls –T does not turn on the –l option. ls –T can be used with other options. See “Long output format” for details. Long output format The output from ls –l summarizes the most important information about the file on a single line. If the specified pathname is a directory, ls displays information about every file in that directory (one file per line). It precedes this list with a status line that indicates the total number of file system blocks occupied by files in the directory (in 512-byte chunks or 1024-bytes if –k option is used). Following is a sample of the output along with an explanation: Chapter 2. Shell command descriptions 381 ls total 11 drwxr-xr-x drwxrwxrwx drwxr-xr-x -rwxr--r--rwxr--r-- 3 4 2 1 1 ROOT ROOT ROOT ROOT ROOT SYS1 SYS1 SYS1 SYS1 SYS1 0 0 0 572 640 Mar Mar Mar Mar Mar 12 12 12 12 12 19:32 19:32 19:32 19:32 19:33 tmp usr bin foo abc If –T is specified, file tag information is displayed first on the line. The first character identifies the file type: – Regular file b Block special file (not supported for z/OS UNIX System Services) c Character special file d Directory e External link l Symbolic link p FIFO s Socket file type The next 9 characters are in three groups of 3; they describe the permissions on the file. The first group of 3 describes owner permissions; the second describes group permissions; the third describes other (or “world”) permissions. Characters that might appear are: r Permission to read the file w Permission to write on the file x Permission to execute the file The following characters appear only in the execute permission (x) position of the output. S Same as s, except that the execute bit is turned off. s If in owner permissions section, the set-user-ID bit is on; if in group permissions section, the set-group-ID bit is on. T Same as t, except that the execute bit is turned off. t The sticky bit is on. The following character appears after the permissions if the file contains extended ACL entries: + Example: ls -l file -rwxrwxrw-+ WELLIE SYS 167 Jan 11 09:54 file Use getfacl to display the extended ACL entries. You can set permissions with either chmod or setfacl. After the permissions are set, ls displays the following (using the preceding example), in order: v The number of links to the file. v The name of the owner of the file or directory. v The name of the group that owns the file or directory. v The size of the file, expressed in bytes. For character special files, it displays the major and minor device types. 382 z/OS V1R12.0 UNIX System Services Command Reference ls v For a file, the date and time the file was last changed; for a directory, when it was created. The –c and –u options can change which time value is used. If the date is more than 6 months old or if the date is in the future, the year is shown instead of the time. v The name of the file or directory. Note: When files owned by user ID 0 (UID=0) are transferred from any UNIX-type system across an NFS connection to another UNIX-type system, the UID changes to –2 (UID = –2). Because –2 is not a valid UID on a z/OS system, ls displays a –2 in place of the user name. If ls –E is issued, an additional four characters follow the original 10 characters: total 11 -rwxr-xr-x -rwxrwxrwx -rwxr-xr-x -rwxr--r--rwxr--r-- -psa-sa-ap-l --sl 1 1 1 1 1 ROOT ROOT ROOT ROOT ROOT SYS1 SYS1 SYS1 SYS1 SYS1 101 654 40 572 640 Mar Mar Mar Mar Mar 12 12 12 12 12 19:32 19:32 19:32 19:32 19:33 her test temp foo abc If ls –H is issued, an additional four characters follow the original 10 characters: total 32 -rwxr-xr-x drwxr-xr-x -rwxr--r--rwxr-x--- ---- 1 2 1 1 cr rec ROOT ROOT ROOT ROOT SYS1 0 Mar 26 SYS1 8192 Mar 26 SYS1 40 Mar 26 SYS1 80 Dec 26 08:47 08:50 08:55 09:55 tmp usr abc newfmt If ls –E is used in conjunction with –H, then the four characters will follow the four characters that are normally associated with ls –E: ls -EH -rwxr-xr-x ap-l bin 1 ROOT SYS1 101 Mar 12 19:21 foo If ls –W is issued, an additional 6 characters, in two groups of 3, follow the original 10 characters. The first group of 3 describes the user-requested audit information; the second group describes auditor-requested audit information. total 11 drwxr-xr-x drwxrwxrwx drwxr-xr-x -rwxr--r--rwxr--r-- fff--fff--fff--fff--fff--- 3 4 2 1 1 ROOT ROOT ROOT ROOT ROOT SYS1 SYS1 SYS1 SYS1 SYS1 0 0 0 572 640 Mar Mar Mar Mar Mar 12 12 12 12 12 19:32 19:32 19:32 19:32 19:33 tmp usr bin foo abc Usage note To display information about a directory from a symbolic link to the directory, either add a trailing slash to the symbolic link name, or use the -L option. For example, if the /etc directory has been converted into a symbolic link, issuing an ls on /etc without a trailing slash will give you the following information: > ls -l /etc lrwxrwxrwx 1 BPXROOT BIN 12 Oct 18 19:46 /etc -> $SYSNAME/etc However, if you add the trailing slash, the following information about /etc is displayed: > ls /etc/ IBM NetQ Printsrv TextTools cmx csh.cshrc csh.login dfs ioepdcf ldap log magic rc recover security socks.conf yylex.c yyparse.c zoneinfo Chapter 2. Shell command descriptions 383 ls booksrv bpe imoisinf init.options mailx.rc profile startup.mk utmpx The same information is displayed when the -L option is used: ls -L /etc IBM NetQ Printsrv TextTools booksrv bpe cmx csh.cshrc csh.login dfs imoisinf init.options ioepdcf ldap log magic mailx.rc profile rc recover security socks.conf startup.mk utmpx yylex.c yyparse.c zoneinfo Environment variables ls uses the following environment variables: COLUMNS Contains the terminal width in columns. ls uses this value to determine the number of output columns to write using the –C option. Contains the time zone to be used when displaying date and time strings. TZ Localization ls v v v v v v v v uses the following localization environment variables: LANG LC_ALL LC_COLLATE LC_CTYPE LC_MESSAGES LC_TIME LC_SYNTAX NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Out of memory v Inability to find a file's information v Too many directories v File or directory not found v Specified on the command line 2 Incorrect command-line option Messages Possible error messages include: File or directory name is not found The requested file or directory does not exist. 384 z/OS V1R12.0 UNIX System Services Command Reference ls Cannot allocate memory for sorting To sort its output, ls needs to allocate memory; this message says that there was not enough memory for the sorting operation. Too many directory entries in dir This message appears only when ls runs out of dynamically allocated memory. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –A, –b, –E, –f, –g, –L, –m, –n, –o, –p, –s, –W, and –x options are extensions of the POSIX standard. Related information Appendix I, “Format of the TZ environment variable,” on page 961 explains how to set the local time zone with the TZ environment variable. ls-f, sh, tcsh mail — Read and send mail messages Format mail [–e | –p] [–qr] [–f file...] mail [–t] name... Note: The mail utility is fully supported for compatibility with older UNIX systems. However, it is recommended that the mailx utility be used instead because it may provide greater functionality and is considered the standard for portable UNIX applications as defined by POSIX.2 IEEE standard 1003.2-1992. Description mail lets you read mail sent to you and sends mail to other users. It has two modes of operation, one for reading mail and one for sending mail. If you start mail without any arguments, it checks for mail to be read and then presents the messages in read mode. If you start it with an argument or arguments, it assumes you are sending a message to the address named as the argument and enters send mode. The text of the message is taken from standard input until mail encounters either EOF or a line consisting of only a single dot (.). For example, to read mail, enter: mail To send a mail message to the users Chris and Lee, enter: mail chris lee Options The –t option is used only when sending mail; the others only when reading mail. –e Tests for the existence of mail and exits. If there is mail in the system mailbox, the return status is successful. Chapter 2. Shell command descriptions 385 mail –f Reads mail from file instead of the system mailbox. This option is often used to read mail saved in other files. –p Prints all mail to standard output without querying. –q Quits the mail session after an interrupt signal; normally, an interrupt ends only the message being written. –r Saves messages in first-in, first-out order, the reverse of the default. Normally, the most recently received message is written first. –t Lists the recipients at the beginning of the message (default). Reading mail When you start mail without arguments, mail checks your system mailbox for mail. If there is no mail, mail exits with a return code of 1; if there is waiting mail, mail displays the first message. (If you specify –p on the command line, it displays all messages.) Commands within mail control how messages are handled. The following commands are available: d Deletes the current message. m[name...] Sends the current message to the specified user. If a user is not specified, the mail is sent to you. p Prints the message on the screen again. q Quits mail, storing any undeleted messages in the file $HOME/mbox. s[file] Saves the message in the specified file. If a file is not specified, mail saves the message in mbox in your home directory. w[file] Saves the message (same as s), but without header lines. x Exits mail without changing the mailbox file. ENTER (or newline) Displays the next message. !command Runs command using the shell. + Displays the next message (same as ENTER or newline). — Displays the previous message. * Displays a summary of internal commands. Because the commands are read from standard input, you can create mail command files and use input redirection to have mail execute them. Sending mail To send mail, start mail with a list of addresses as arguments. Enter the text of the message, and end the message with either EOF or with a single dot (.) on a line followed by a <newline>. The –t option inserts at the beginning of the message a list of the addresses; a path name beginning with a slash (/) is recognized as a valid address (assuming you have the correct permissions). 386 z/OS V1R12.0 UNIX System Services Command Reference mail If the address is not valid or recognized, or if the message is interrupted (see the –q option), mail stores the message in the file dead.letter in the current directory. If it can't create dead.letter in the current directory, it creates the file in your home directory. If dead.letter already exists, the new contents overwrite the old. The mail program modifies the message text slightly; because lines beginning with From (including the trailing space) are used to separate files in the mailbox, mail changes any lines in the message that begin with From to read >From. Example To send the file how2mail to user Chris, enter: mail chris < how2mail Usage notes 1. Wherever the POSIX standard doesn't define the behavior of mail, this implementation resembles mailx. 2. mail doesn't require a delivery path or mechanism to the destination, though for most uses, this is preferable. Environment variables mail uses the following environment variables: HOME Specifies your home directory; used to locate the mbox and dead.letter files. Specifies the time zone to be used in date and time strings. TZ Localization mail uses the following localization environment variables: v LC_CTYPE v LC_MESSAGES v LC_TIME v NLSPATH See Appendix F, “Localization” for more information. The ability of mail to handle double-byte characters (or even 8-bit ASCII depends on the underlying mail transport mechanism. You should restrict all messages to the POSIX portable character set. To send messages containing double-byte characters or even binary files, encode them first with uuencode. Files mail uses the following files: dead.letter The most recently canceled message. mbox The default file for saving read mail, stored in the directory specified by HOME. Exit values 0 The session was successfully completed; if reading, there was mail. 1 There was no mail, or the session could not be started. Chapter 2. Shell command descriptions 387 mail 2 An error occurred after starting the session, or you supplied an invalid option, resulting in a usage message. Portability POSIX.2 Because this utility is due to be withdrawn from POSIX, you may want to use mailx for portable applications. The ability to write directly to a file is an extension to POSIX. Limits Any individual line is limited to LINE_MAX bytes; of course, transport mechanisms between systems may impose shorter limits. Related information mailx, uudecode, uuencode Appendix I, “Format of the TZ environment variable” also explains how to set the local time zone with the TZ environment variable. mailx — Send or receive electronic mail Format mailx [–efHiNn] [–u user] [filename] mailx [–FinU] [–h number] [–r address] [–s subject] user ... Description mailx helps you read electronic mail messages. It can also send messages to users on your system, but it has no built-in facilities for sending messages to other systems. The command line: mailx [options] user user user ... sends a mail message to the given users. If you do not specify any users on the command line, mailx lets you read incoming mail interactively. For more information, see sendmail. In a double-byte locale, aliases, variables, and addresses can contain double-byte characters. This description of mailx is divided into several sections: v Options v General overview v Command-mode subcommands v Input-mode subcommands v Startup files v Example v Environment variables v Files v Exit values v Portability 388 z/OS V1R12.0 UNIX System Services Command Reference mailx v Related information Options You can use the following options when reading messages: –e Checks to see if you have any messages waiting to be read. With this option, nothing is displayed. If you have waiting messages, mailx exits with a successful status return; otherwise, mailx exits with a failure return. –f filename Looks for messages in the specified file instead of in your current mailbox. If you do not specify filename, mailx reads messages from $HOME/mbox. –H Displays only the header summary of a message. –N Does not display the header summary of messages. –u user Looks for messages in the system mailbox of the specified user. This works only if you have read permission on the user's system mailbox. You can use the following options only when sending messages: –F Records your message in a file with the same name as the first user specified on the command line. This option overrides the record variable, if it has been set. –h number Indicates how many “hops” a message has already made from one machine to another (in a network of machines). This option is not intended for most users; network mail software uses the option to prevent infinite loops (the same message cycling through a sequence of machines without ever getting to its intended destination). –r address Passes the given address to network mail software. If this option is present, it disables all input mode commands. Again, this option is not intended for most users. –s subject Uses the given subject string in the Subject heading line of the message. If the subject contains spaces or tab characters, the string should be enclosed in double quotation marks or single quotation marks. If you specify this option on the command line, mailx does not prompt you to enter a subject line when you type in the text of the message. The subject accepts at most LINE_MAX-10(2038) bytes. Any subjects longer than that will be truncated at 2038. –U Converts the address from UNIX-to-UNIX Copy Program (UUCP) style to Internet Protocol standards. This option overrides the effect of the conv variable. This option is not supported. You can use these options for both sending and reading messages: –i Ignores interrupts (for example, from pressing <Break> or <Ctrl-c>). –n Does not initialize your mailx session from the system's /etc/mailx.rc file. Chapter 2. Shell command descriptions 389 mailx General overview This section describes the default behavior of mailx. The simplest command to send a message is: mailx address address address ... where each address names someone who is to receive the message. The simplest kind of address is the login name of someone else who uses your shell. You can also send messages as input to commands. To do this, use an address that consists of a pipe symbol (|) followed by a command line that invokes the appropriate command; enclose this whole address in single quotation marks. For example: mailx ROBIN ’|cat >save’ mails a message to ROBIN and also copies the message into a file called save. After you type in the command to send a message, mailx asks you to enter the subject of the message (a brief description of what the message is about), and then lets you type in the text of the message. This brief description can be up to 256 characters long. Your message can consist of any number of lines, and may include blank lines. When you finish entering the message, type a line consisting only of a tilde (~), followed by a period (.); then press the enter key. This tells mailx that the message is ready to be sent. mailx puts the completed message into a file called the recipient's system mailbox. The message stays in the system mailbox until the recipient asks to read the message. At that point, the message is obtained from the system mailbox and displayed on the recipient's workstation. The message is then saved in the recipient's personal mailbox. Since this is typically a file named mbox in the recipient's home directory, we use the name mbox to represent the personal mailbox and mailbox for a system mailbox. The simplest way to read incoming messages is to type the command mailx (with no addresses on the command line). This starts an interactive session in which mailx lets you read your mail and perform other operations. For example, you can display new messages, delete old ones, reply to messages, or forward them to someone else, and so on. When you are performing operations in this way, you are in command mode. When you are typing in the text of a message, you are in input mode. A message consists of a sequence of header lines, followed by the body of the message. The header lines tell who sent the message, the time and date that the message was sent, the subject of the message, and so on. mailx automatically creates header lines. Some of the common header lines are: Cc: name name ... Stands for “carbon copies”. This indicates that copies of this message are to be sent to the specified recipients. The names of these recipients appear in the header lines of everyone receiving the message. Bcc: name name ... Stands for “blind carbon copies”. This is similar to Cc:, but the names of people receiving carbon copies do not appear in the 390 z/OS V1R12.0 UNIX System Services Command Reference mailx header lines of the message. Recipients do not know that these people received a copy of the message. Subject: text Gives the subject of the message. To: name name ... Gives the names of people who were sent the message directly. All messages are in one of the following states: deleted You used a delete, dp, or dt command to delete the message. When mailx quits, messages in this state are deleted. new The message is in the system mailbox and you have not yet read it or otherwise changed its state. When mailx quits, messages in this state are kept in your system mailbox. preserved You used a preserve command on the message. When mailx quits, messages in this state are kept in their current locations. read You used one of the following commands on the message: ~F ~f ~M ~m copy mbox next pipe Print print top Type type undelete or you used delete , dp, or dt on the preceding message and the autoprint variable was set. When mailx quits and you are in your system mailbox, read messages are kept in your personal mailbox—unless the hold variable is set, in which case, read messages are kept in your system mailbox. If you are in your personal or a secondary mailbox when mailx quits, read messages are kept in their current location. saved You used a save or write command on the message. If the current mailbox is the system mailbox and the variable keepsave was set, messages in the state saved are saved to the mbox. If the current mailbox is the system mailbox and you used a quit or file command to exit the current mailbox, messages in the state saved are deleted from the current mailbox. unread You have run more than one mailx session with the message in the system mailbox and you have not read it or otherwise changed its state. When mailx quits, messages in this state are kept in your system mailbox. Command-mode subcommands The standard format of a command-mode subcommand is: [subcommand][refs][arguments] If no subcommand is specified, the default subcommand depends on the setting of the _UNIX03 variable: If the variable _UNIX03=YES is set, then n[ext] is assumed. If the variable _UNIX03 is unset or is not set to YES, then p[rint] is assumed. The refs argument indicates the messages to which you want to apply the subcommand. mailx numbers incoming messages sequentially as they are received. The easiest way to refer to a message is to give its number. For example, the subcommand: p 3 Chapter 2. Shell command descriptions 391 mailx displays message number 3. At any point in a mailx session, there is one message that is considered the current message. This is the message you most recently did something with (for example, the one you most recently read). If you omit the refs argument in a subcommand that uses refs, the subcommand works with the current message. You can also use special notations as the refs value: refs Meaning n Message number n n-m Messages n through m . The current message ^ The first undeleted message (or first deleted message for undelete) $ The last message + Next message − Previous message * All messages user All messages from the given user /string All messages with string in the subject line (the case of characters in string is ignored) :d All deleted messages :n All new messages :o All old messages :r All messages that have already been read :u All unread messages Several refs arguments may be specified for the same subcommand, separated by spaces. For example: p alice lewis displays all messages from alice plus all messages from lewis. The arguments allowed at the end of a command-mode subcommand depend on the subcommand itself. If a subcommand allows a file name as an argument, you can use the usual file name generation characters in the file name (see sh). File names, where expected, are subjected to the following transformation, in sequence: v If the file name begins with an unquoted plus sign, and the folder variable is defined, the plus sign will be replaced by the value of the folder variable followed by a slash. If the folder variable is unset or set to null, the file name will be unchanged. v 392 Shell word expansions will be applied to the file name. If more than one path name results from this expansion and the command is expecting one file, the multiple path names will be combined into one argument. z/OS V1R12.0 UNIX System Services Command Reference mailx The following list shows the subcommands recognized in command mode. In every subcommand name, some characters are enclosed in square brackets. These characters are optional. For example, the p[rint] command may be given as p, pr, pri, prin or print. a[lias] [alias [name ...]] Sets up an address alias. If you enter a subcommand to send mail to the given alias, the messages are sent to the given list of names. For example, you might enter the subcommand: alias joe JSMITH From this point onward, you can address messages to joe and they are sent to jsmith. You may also set up an alias for several people, as in: alias choir SOPRANO ALTO TENOR BASS After you have done this, you can send messages to choir and they are sent to the names that follow choir in the command. Alias substitution only takes place when alias is used as the whole mail address. Alias substitution doesn't take place when replying to a message that has an alias match in the addresses. If you use only one argument, alias lists the value of that alias. For example, alias joe would display jsmith. Entering the alias subcommand without any arguments displays a list of the currently defined aliases. Note: Aliases entered interactively remain in effect only until the end of the current interactive session. To make an alias permanent, include the alias subcommand in your startup file (see “Startup files” on page 401). See also group. alt[ernates] name Lists a set of alternate names for your own login name. This is useful for people who login under several different names. When you reply to a message, mailx typically sends your reply to the author of the message and all the recipients as well; however, it does not send the message to any of your alternate login names. You don't have to worry about sending mail to yourself. Specifying alternates without names displays your list of currently defined alternate names. cd directory Makes directory your new working directory. If no directory is specified, cd goes to your HOME directory. ch[dir] directory Is the same as cd. c[opy] [refs] [filename] Copies the messages referred to by refs into the given file. The filename must be specified. If the file does not already exist, it is created. If no refs are specified, the current message is saved. If no filename is specified, your mbox is saved. This operation does not mark the message as saved; if it was previously unread, it is still regarded as an unread message. Thus, the original message remains in your system mailbox. See also save. Chapter 2. Shell command descriptions 393 mailx C[opy] [refs] Is similar to the copy command, except that the messages referred to are saved in a file the name of which is derived from the author of the first message referred to. The name of the file is the author's name, stripped of any network addressing. If the folder variable is set, the file is saved to the specified directory. The copied messages are not marked as “saved”. If refs is not specified, the current message is copied. d[elete] [refs] Deletes the specified messages from your system mailbox. If refs is not specified, the current message is deleted. After a delete operation, the current message is set to the message after the last message deleted. Deleted messages are not thrown away until you end your session with the current mailbox (see quit and file). Until then, they can be undeleted (see undelete). di[scard] [header...] Does not display the given header fields when displaying a message. For example: discard References tells mailx not to display the References line at the beginning of any mail message. These header lines are retained when the message is saved; they are just not shown when the message is displayed. See also ignore and retain. dp [refs] Deletes the specified messages and then displays the message after the last message deleted. If there is no subsequent message, mailx displays its command prompt. dt [refs] Is the same as the dp subcommand. ec[ho] string ... Echoes the given strings (like the echo subcommand). e[dit] [refs] Lets you edit the messages specified by refs. The messages are stored in a temporary file and an editor is invoked to let you edit the file. The default editor is ed, but you can change this using the EDITOR environment variable. ex[it] Quits mailx without changing the system mailbox. Contrast this with quit, which ordinarily removes from the system mailbox those messages you've read, saved, or deleted. fi[le] [filename] Quits the system mailbox (as if a q[uit] subcommand were run) and then reads in the specified file as the new mailbox to examine. If no file name is specified, the default is your current mailbox. Several % %user # & +file special strings can be used in place of filename: Your system mailbox. The system mailbox for user The previous file Your mbox (personal mailbox) The named file in the folder directory fold[er] [filename] Is the same as the file subcommand. 394 z/OS V1R12.0 UNIX System Services Command Reference mailx folders Displays the names of the files in the directory given by the folder variable. See “Environment variables” on page 402. F[ollowup] [refs] Replies to the first message given in refs; mailx sends this reply to the authors of every message given in refs. The Subject line is taken from the first message in refs. Your reply is automatically saved in a file which derives its name from the author of the message to which you are replying. If the variable _UNIX03=YES is set, then the command overrides the record variable if record is set. If the variable _UNIX03 is unset or is not set to YES, then the command does not override the record variable. To create your reply, mailx puts you into input mode, where you can use all of the input mode commands. fo[llowup] [ref] Replies to the specified message; if no message ref is given, you reply to the current message. Your reply is automatically saved in a file which derives its name from the author of the message to which you are replying. This overrides the record environment variable if record is set. To create your reply, mailx puts you into input mode, where you can use all of the input mode commands. f[rom] [refs] Displays the header summary for the specified messages. If refs is not given, the current message is used. g[roup] [alias [name ...]] Is the same as the alias command. h[eaders] [ref] Displays the headers of a screenful of messages surrounding the message given by ref. The number of lines in a screen is given by the screen variable. If no ref is specified, the current message doesn't change; otherwise the current message is changed to the message specified by ref. hel[p] Displays a summary of the command-mode subcommands. ho[ld] [refs] Retains the specified messages in your system mailbox. For example, you might decide to hold a message if you read it, but decide not to act upon it immediately. If refs is not specified, the current message is held. If any of the specified messages have been marked as deleted, the hold subcommand overrides that and still retains the messages. Subsequent delete, dp, and dt commands during the same mailx session can delete files marked for retention. See also preserve and the variables hold and keepsave. i[f] code mailx subcommands | [el[se] mailx subcommands] | [en[dif]] Is primarily intended for use in startup files. The code must be the character r or s. If it is r, the first set of mailx subcommands are executed if mailx is in receive mode, and the second set if mailx is in send mode. If code is s, the opposite is true. The else part is optional. See “Startup files” on page 401. ig[nore] [header ...] Is the same as the discard subcommand. Chapter 2. Shell command descriptions 395 mailx l[ist] Displays the names of all command-mode subcommands. m[ail] address ... Sends a message to the specified recipients. mailx goes into input mode to let you enter the text of the message. mb[ox] [refs] Indicates that the given messages are to be saved in your mbox (personal mailbox) when mailx quits normally (that is, through the quit command as opposed to exit). n[ext] [refs] Goes to the next message in the mailbox that appears in the list of refs. For example: n user goes to the next message from the specified user. pi[pe] [[refs] command] Pipes the messages given by refs through the specified shell command. These messages are considered read. If refs is not specified, the current message is used. If no command is specified, mailx uses the command specified by the cmd variable. See “Environment variables” on page 402. If the page variable has a value, a form feed character is sent into the pipe after every message. The subcommand | [refs] [command] is equivalent to pipe. pre[serve] [refs] Is the same as the hold subcommand. P[rint] [refs] Displays the specified messages on the screen. If refs is not specified, the current message is displayed. All header fields are displayed; the discard, ignore and retain subcommands do not affect Print. If the crt variable is set to an integer, messages with more lines than that integer are "paginated" using the command specified by the PAGER variable. p[rint] [refs] Displays the specified messages on the screen. If refs is not specified, the current message is displayed. Header fields specified by discard, ignore and retain subcommands affect print. If the crt variable is set to an integer, messages with more lines than that integer are “paginated” using the command specified by the PAGER variable. For more information, see “Environment variables” on page 402. q[uit] Ends a mailx session. This is the usual method to leave mailx. Messages that have been read but not saved or deleted are stored in your mbox (personal mailbox). Messages that are still unread are retained in your system mailbox. Messages that have been deleted or explicitly saved in other files are discarded. Typing the end-of-file character has the same effect. R[eply] [refs] Sends a reply to the authors of each of the messages specified by refs. If refs is not specified, the current message is used. The Subject line of the reply message is taken from the first message in refs. If the record environment variable is set to a file name, your reply message is appended to the end of that file. 396 z/OS V1R12.0 UNIX System Services Command Reference mailx Normally, you use Reply if you just want to send your reply to the author of a message, and reply if you want to send your reply to the author and all recipients. If set, the flipr environment variable reverses the meanings of the R and r commands. See “Environment variables” on page 402. r[eply] [ref] Sends a reply to the author of a specific message, and all other recipients of the message. If ref is not specified, mailx replies to the current message. If the record environment variable is set to a file name, your reply message is appended to the end of that file. R[espond] [refs] Is the same as the Reply subcommand. r[espond] [ref] Is the same as the reply subcommand. ret[ain] [header ...] Is the opposite of the discard subcommand. It tells mailx to display the given header fields when displaying a message. The comparison of header fields is not case sensitive. You can use retain to override existing discard and ignore commands. If you do not specify any header fields, retain displays a list of currently retained header fields. S[ave] [refs] Saves the specified messages in a file the name of which is taken from the author of the first message (the file name is the author's name, without any attached network addressing). If the folder variable is set, the file is saved to the specified directory. s[ave] [refs][filename] Saves the specified messages in the given file. If refs is not given, the current message is added to the mbox. (The value of the append variable determines whether the message is added to the beginning or the end of the mbox). The file is created if it does not already exist. If you do not specify filename, mailx saves the messages in mbox (your personal mailbox). A message that has been saved with save is normally deleted from mailbox when mailx ends (see quit); but see the variables hold and keepsave. se[t] name Defines a variable with the given name and assigns it a null value. If you omit name, set displays a list of all defined variables and their values. se[t] name=value Defines a variable with the given name and assigns it the given value, which may be a string or a number. se[t] noname Is the same as the unset name subcommand. sh[ell] Invokes the shell given by the SHELL environment variable. si[ze] [refs] Displays the size in bytes of each of the specified messages. If no refs are specified, the current message is used. so[urce] file Reads the specified text file, executes its contents as command-mode subcommands, and then returns to read more commands from the original source. Chapter 2. Shell command descriptions 397 mailx to[p] [refs] Displays the first few lines of each of the specified messages. If refs is not specified, the current message is used. If the toplines variable has a numeric value, that many lines are displayed from each message; otherwise, five lines are displayed from each message. tou[ch] [refs] “Touches” the specified messages, making them appear to have been read. This means that when you quit mailx, the messages are saved in your mbox (personal mailbox) if they are not deleted or explicitly saved in another file. If refs is not specified, the current message is touched. T[ype] [refs] Is the same as the Print subcommand. t[ype] [refs] Is the same as the print command. una[lias] [alias[name ...]] Deletes specified alias names. u[ndelete] [refs] Restores previously deleted messages. When messages are deleted, they are not discarded immediately; they are just marked for deletion and are deleted when mailx ends. Until mailx ends, you can use undelete to restore the specified messages. You cannot undelete messages deleted in previous sessions. If you do not specify refs, this command restores the first deleted (but not yet undeleted) message following the current message; if no such message exists, it restores the last deleted (but not yet undeleted) message preceding the current message. If the autoprint variable is set, the last restored message is displayed. This is the only subcommand that lets you give a ref to a message that has been deleted. U[nread] [refs] Marks the specified messages as unread. uns[et] name ... Discards the specified variables. ve[rsion] Displays version information about mailx. v[isual] [refs] Edits the specified messages with a screen editor. If refs is not specified, the current message is edited. The messages are saved in a temporary file and the screen editor is invoked to edit that file. The editor used is given by the VISUAL variable. See “Environment variables” on page 402. w[rite] [refs] filename Writes the specified messages into the given file. If refs is not specified, the current message is written. write is the same as save, except that it does not write out the header lines and the blank line at the end of the message. x[it] Is the same as the exit command. z[+|-] Scrolls the header display forward (if z or z+ is specified) or backward (if z- is specified) one screenful. ! command Executes the given shell command. For example: !lc 398 z/OS V1R12.0 UNIX System Services Command Reference mailx lists all files in the current directory. The shell that will be used to run the command is given by the SHELL environment variable. See “Environment variables” on page 402. #comment Specifies that mailx should ignore everything from the # to the end of the line. This is useful for putting comments into startup files. ? Is the same as the help command (it displays a summary of the command-mode subcommands). = Displays the current message number. Input-mode subcommands You can use input-mode subcommands when entering the text of a message. You must type mode subcommands at the beginning of an input line; you cannot type them in the middle of a line. By default, each input-mode subcommand begins with the tilde (~) character, called the escape character. You can use the escape variable to change the escape character, but in the documentation that follows, we always use tilde. ~. Marks the end of input in a mail message. ~? Displays a summary of the input-mode subcommands. ~A Inserts the autograph string at this point in the message. This autograph string is given by the Sign variable. ~a Is similar to ~A, except that it uses the variable sign. ~b name ... Adds the specified names to the blind carbon copy list. ~c name ... Adds the specified names to the carbon copy list. ~d Reads in the dead.letter file. ~e Invokes an editor on the message that you have composed. The editor variable determines the editor that is invoked. ~F [refs] Forwards the given messages. The text of the messages is inserted at this point in the message you are composing. The message headers are also inserted with all header fields regardless of the discard, ignore, and retain subcommands. This is valid only when you entered mailx in command mode and then went into input mode to compose a message. ~f [refs] Is similar to ~F except that the header fields included are determined by the discard, ignore, and retain subcommands. ~h Prompts you to enter the following header lines: Subject Cc Bcc To For some of these, mailx displays an initial value for the header. You can edit this initial value as if you had just typed it in yourself, using backspaces and line deletes. ~i name Inserts the value of the named variable followed by a newline at this point in the message. Chapter 2. Shell command descriptions 399 mailx ~M [refs] Inserts the text of the specified messages at this point in the message. If refs is not specified, the current message is used. Messages inserted in this way have each line prefixed with the value of the indentprefix variable. The message headers are also inserted with all header fields included regardless of the discard, ignore, and retain subcommands. This is valid only when you entered mailx in command mode and then went into input mode to reply to a message. ~m [refs] Is similar to ~M, except that the header fields are determined by the discard, ignore, and retain subcommands. ~p Displays the message being composed. ~q Quits input mode as if you had interrupted the message. If you have already composed part of a message, the partial message is saved in the dead.letter file; the description of the dead environment variable has more information.. ~r filename Reads in the contents of the specified file and adds that text at this point in the message. ~s text Sets the Subject line to the given text. ~t address address ... Adds the given addresses to the To: list (people who will receive the message). ~v Invokes a screen (visual) editor on the message that you have composed. The VISUAL variable determines the editor that is invoked. ~w file Writes the current text of your message to the specified file. The header lines for the message are not written. ~x Quits in the same way as ~q, except that the message is not saved in the dead.letter file. ~< filename Is the same as the ~r command. ~< !command Runs the given shell command and adds the standard output of that command at this point in the message. For example, your message might contain: My program is giving me this odd output: ~< !prog What do you think is causing it? ~: mail_command Runs the given command-mode mail_command. This is valid only when you entered mailx in command mode and then went into input mode to compose a message. ~_ mail_command Is the same as the ~: command. ~! command Runs the given shell command. For example, you can use: >~! ls 400 z/OS V1R12.0 UNIX System Services Command Reference mailx to get a list of files in the working directory. The shell that is invoked to run the command is given by the SHELL environment variable. If the bang variable is set, mailx replaces each unescaped exclamation mark (!) in command with the command run by the previous command or ~! command escape. ~ command Pipes the current message through the specified shell command. If the command ends with a successful exit status, the output of the command replaces the text of the current message. For example: ~|fmt fills and justifies the lines of your message and replaces the message with the formatted message. ~| uses the shell given by the SHELL environment variable to run command. Startup files When you run mailx in command mode, mailx does the following: v Sets all variables to their default values. mailx processes command-line options, using them to override any corresponding default values. v Imports appropriate external environment variables, using them to override any corresponding default values. v Reads commands from the system startup file, /etc/mailx.rc. This sets up variable values and definitions that should be common to all users. If you do not want mailx to read the system startup file, use the –n option on the mailx command line. v After reading and processing the system startup file, mailx does the same with a personal startup file, which is MAILRC by default. This is a file in your HOME directory. The name of the file is .mailrc. Startup files typically set up display options and define aliases. However, any command is valid in a startup file except for the following: v Copy v edit v followup v Followup v hold v mail v preserve v reply v Reply v respond v Respond v shell v visual v ! If a line in a startup file contains an error or an incorrect command, the rest of the startup file is ignored. mailx ignores blank lines in a startup file. Example The following example composes and sends a message to several users. Items shown in bold are output by mailx itself. Chapter 2. Shell command descriptions 401 mailx mailx JEAN Subject: Greetings This is just a short note to say hello. ~c JUAN JOHN JOHANN ~. On the first line, the message is just addressed to jean. The ~c line adds more people who will receive copies of the message. Environment variables A large number of variables are used to control the behavior of mailx. These environment variables are divided into two classes: those that always come from the external environment, and those that may be set up in either the external environment or within a mailx session. The following variables always come from the external environment; they can be changed inside a mailx session, except where marked. 402 DEAD Gives the name of a file that can be used as the dead.letter file. Partial messages are saved in this file if an interrupt or error occurs during creation of the message or delivery. By default, the name of this file is $HOME/dead.letter. EDITOR Gives a command, possibly with options, that is run when using the command mode edit or the input mode ~e. The default is ed (see “ed — Use the ed line-oriented text editor” on page 260 for more information about ed). HOME Gives the name of your home directory. This cannot be changed inside mailx . LISTER Gives a command, possibly with options, that mailx invokes when displaying the content of the folder directory for the folders subcommand. If this variable is null or unset, mailx uses ls. By default, this variable is unset. LOGNAME Gives your login name. MAIL Gives the path name of the user's mailbox file for purposes of incoming mail notification. MAILDIR Gives the name of the directory where system mailboxes are stored. If this is not set, the default is /usr/mail. The actual name of a user's system mailbox is derived in a system-dependent way by combining MAILDIR and the user's login name. For mailx to work properly, the MAILDIR directory must exist. MAILRC Gives the name of your startup file. This cannot be changed inside mailx. By default, MAILRC has the value $HOME/.mailrc. For more information about startup files, see “Startup files” on page 401. MBOX Gives the name of your mbox (personal mailbox) file. Messages that have been read but not saved elsewhere are saved here when you run quit (but not when you run exit). The default is $HOME/mbox. PAGER Gives a command, possibly including options. mailx sends display output through this command if the output is longer than the z/OS V1R12.0 UNIX System Services Command Reference mailx screen length given by crt. The default value is more (see “more — Display files on a page-by-page basis” on page 446 for more information about more). SHELL Gives a command, possibly with options. mailx assumes that this command is a command interpreter. mailx invokes this command interpreter whenever it is asked to run a system command (for example, through the ! command-mode command). The default is sh (see “sh — Invoke a shell” on page 568 for more information about sh). TERM Contains the name of the terminal type. This cannot be changed inside mailx. TZ This variable may determine the time zone used to calculate date and time strings written in mailx. This cannot be changed inside mailx . _UNIX03 For more information about the affect of _UNIX03 on this command, see Appendix N, “Shell commands changed for UNIX03,” on page 975. VISUAL Gives a command, possibly with options, that mailx invokes when using the command-mode visual subcommand or the input mode ~v subcommand. The default is vi (see “vi — Use the display-oriented interactive text editor” on page 784 for more information about vi). The HOME and LOGNAME variables must be set before you enter mailx. Otherwise, mailx will not work properly. The TZ variables can only be set before you enter mailx. If not set or set to null, a default time zone ("UTC0") will be used. These variables are typically set during shell login. (You can login with theOMVS TSO/E command, telnet, rlogin, or ssh.) If you do not log in, you must set the variables in some other way, using the commands: export LOGNAME=name export HOME=directory The remaining variables can be set in the external environment or in the course of a mailx session. You can set or change the value of a variable with the set subcommand; you can discard a variable with the unset subcommand. You may find it convenient to create a startup file that sets these variables according to your preferences; this eliminates the need to set variables each time you enter mailx. Many of the following variables represent on-off options. If you set the variable itself (to any value), the option is turned on. To turn the option off, you can unset the variable, or set a variable consisting of no followed by the name of the original variable. For example, setting autoprint turns the autoprint option on, and setting noautoprint turns it off. allnet Assumes that network addresses with the same login component refer to the same person. Network addresses typically consist of several components, giving information that lets a mail server identify a machine on the network, a route to that machine, and the login name of a user on that machine. mailx assumes that the login name is the last component. For example: print name displays all messages that originated from the same login name, regardless of the rest of the network address. The default is Chapter 2. Shell command descriptions 403 mailx noallnet, where different addresses are assumed to be different users, even if the login name components are the same. append Appends messages to the end of the mbox file (your personal mailbox) after termination. The default is noappend; messages are placed at the beginning of the mbox file instead of the end. ask Prompts you for a Subject: line when composing a message (if you have not already specified one with the –s option). This option is on by default; to turn it off, set noask. ask is the same as asksub. noask is the same as noasksub. askbcc Prompts you for a Bcc: list when composing a message. The default is noaskbcc; you are not prompted. askcc Prompts you for a Cc: list when composing a message. The default is noaskcc; you are not prompted. asksub Prompts you for a Subject: line when composing a message (if you have not already specified one with the –s option). This option is turned on by default; to turn it off, set noasksub. asksub is the same as ask. noasksub is the same as noask. autoprint Automatically displays the last message deleted with the delete subcommand or the last message undeleted with undelete. The default is noautoprint; you are not shown messages that you delete or undelete. bang Records shell commands run inside the mailx session (for example, through the ~! input-mode command). Then, if you issue a shell command and the shell command contains a ! character, mailx replaces that character with the command line for the previous shell command. The default is nobang, in which case a ! in a shell command line is not treated specially. cmd Contains a command, possibly with options. This specifies a default command line to be used for the command-mode pipe subcommand. For example: set cmd="cat" pipes messages through cat when the pipe subcommand is invoked. The default is nocmd. 404 crt Contains an integer number. If a message has more than this number of lines, the message is piped through the command given by the PAGER variable, whenever the message is displayed. crt is not set; the default is nocrt. debug Enables verbose diagnostics for debugging. Messages are not delivered. The default is nodebug. dot Accepts a line consisting only of a dot (.) to indicate the end of a message in input mode. Thus . is equivalent to ~.. The default is nodot. If ignoreeof is set, mailx ignores a setting of nodot; the period is the only way to end input mode. escape Gives the character used to begin input-mode subcommands. The default is the tilde (~). If this variable is unset, tilde is used as the escaping character. If this variable is set to null, mailx disables command escaping. z/OS V1R12.0 UNIX System Services Command Reference mailx flipr Reverses the meanings of the R and r subcommands. The default is noflipr. See also Replyall. folder Contains the name of a directory in which mailx saves mail files, if you use a plus sign + in front of the filename. This lets you specify a standard directory for saving mail files. Whenever you specify a filename for a mailx command, putting a plus sign (+) in front of the name specifies that the file is to be accessed or stored in the folder directory. If the value of folder begins with a slash, it is taken as an absolute path name; otherwise, mailx assumes that the directory is directly under your HOME directory. The default is nofolder. If you want to use + in file names that appear on the mailx command line itself (as opposed to commands in a mailx session), you must make folder an exported shell environment variable. header Displays a summary of message headers at the beginning of a mailx command-mode session. This is the default. hold Keeps all messages in your system mailbox instead of saving them in your personal mbox. The default is nohold. ignore Ignores interrupts received while composing a message. The default is noignore. ignoreeof Ignores end-of-file markers found while entering a message. The message can be ended by “.” or ~. on a line by itself. The default is noignoreeof. indent Contains a string that mailx uses as a prefix to each line in messages that ~m and ~M insert. The default is one tab character. indentprefix As with indent, contains a string that mailx uses as a prefix to each line in messages that ~m and ~M insert. The default is one tab character. If both indent and indentprefix are set, indentprefix takes precedence. keep Does not remove your system mailbox if the mailbox contains no messages. The mailbox is truncated to zero length—that is, it is merely emptied, although it still exists. If the default nokeep is in effect, empty mailboxes are removed. keepsave Keeps messages in your system mailbox even if they have been saved in other files. The default, nokeepsave, deletes messages from the system mailbox if they have been saved elsewhere. mailserv Identifies the mail server being used for remote mail. metoo When replying to a message with your login name in the recipient list, sends a reply to all other recipients, the author, and you. If nometoo is set, you are not to be sent the reply. The default is nometoo. onehop Attempts to send replies directly to the recipients instead of going through the original author's machine. When you reply to a message, your reply is sent to the author and to all recipients of the message. On a network, mailx normally specifies the recipient addresses so that all the replies go to the original author's machine first, and then on to the other recipients. The default is noonehop. outfolder Causes files used to record outgoing messages (see the description Chapter 2. Shell command descriptions 405 mailx of record) to be located in the directory given by folder unless folder contains an absolute path name. The default is nooutfolder. page Tells the pipe subcommand to insert a form-feed character after each message that it sends through the pipe. The default is nopage. prompt Contains a string that mailx displays to prompt for output in command mode. The default is a question mark followed by a space (? ). quiet Does not display the opening message and version number when mailx begins a session. The default is noquiet. record Contains a file name where every message you send is to be recorded. If record is not an absolute path name and the outfolder variable has not been set, the file is located in the current directory. If the outfolder variable is set, the file is located in your folder directory. The default is norecord. replyall Reverses the senses of the reply and Reply subcommands (so that reply replies only to the author of a message, and Reply replies to the author and all other recipients). See also flipr. save Saves messages in your dead.letter file if they are interrupted while being composed. The name of your dead.letter file is given by the dead variable. Setting nosave disables this automatic save feature. The default is save. screen Gives the number of headers that are to be displayed by the headers and z subcommands. If screen is not specified, the current window size shall be used to determine the number of headers displayed. sendmail Contains a command, possibly with options, that mailx invokes to send mail. The default is /usr/lib/tsmail. It can be any command that takes addresses on the command line and message contents on standard input. sendwait When sending a message through a network, mailx waits for the mail server to finish before returning to your session. Normally, it just submits the message to the server and then returns immediately. The default is nosendwait. showto When displaying a header summary, displays the recipient's name instead of the author's for messages where you are the author. The default is noshowto. sign Contains a string that is inserted into a message when you use the input mode ~a subcommand. mailx interprets \n and \t in this string as the newline and tab characters, respectively. The default is nosign. Sign Contains a string that is inserted into a message when you use the input mode ~A subcommand. The default is noSign. toplines Gives the number of header lines that the top subcommand is to display. The default is 5. Files mailx uses the following files: 406 z/OS V1R12.0 UNIX System Services Command Reference mailx /etc/mailx.rc System-wide startup file. $MAILRC Personal startup file. By default, MAILRC has the value $HOME/.mailrc. $HOME/mbox Default location to save read messages. You can choose a different file by assigning the file name to the environment variable MBOX. $MAILDIR Directory containing system mailboxes. By default, this is /usr/mail. The system programmer must create the MAILDIR directory if it does not already exist. See z/OS UNIX System Services Planning for information about electronic mail. If you use a system mailbox directory other than /usr/mail, identify it in the $MAIL environment variable in /etc/profile. See the section on customizing /etc/profile in z/OS UNIX System Services Planning. $HOME/dead.letter Default location to save partial letters. Localization mailx uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_TIME v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 v Successfully sent. (However, this does not guarantee that the mail was successfully received.) v 0 is returned if -e is specified and mail was found. 1 Returned if –e is specified and mail was not found or an error occurred. Also returned to indicate failure due to any of the following: v There is no mail to read. v Inability to create temporary file name or temporary file. v Receipt of user interrupt while message was being composed. v Inability to determine the user's identity. 2 Failure due to any of the following: v Missing number after –h v Missing address after –r v Missing subject after –s v Missing user after –u v Incorrect command-line option v Use of interactive options when not using command interactively Chapter 2. Shell command descriptions 407 mailx Portability POSIX.2, X/Open Portability Guide, UNIX System V. UNIX System V has a compatible mailx utility, whereas Berkeley Software Distribution (BSD) has a similar utility, known as Mail. The –F, –r, and –U options; the Copy, echo, followup, Followup, Save, Unread, and version subcommands; and the allnet, conv, mailserv, onehop, replyall, sendmail, and sendwait variables are extensions of the POSIX standard. Related information echo, ed, sh, vi make — Maintain program-generated and interdependent files Format make [–EeinpqrstuVvx] [–k|–S] [–c dir] [–f file] ... [macro definition ...] [–D macro definition ...] [target ...] Description make helps you manage projects containing a set of interdependent files, such as a program with many source and object files, or a document built from source files, macro files, and so on. make keeps all such files up to date with one another. If one file changes, make updates all the other files that depend on the changed file. Note: This implementation of make features the .POSIX special target to provide maximum portability. When you specify this target, make processes the makefile as specified in the POSIX standard. For details, see the description of .POSIX in “Special target directives” on page 420. In a double-byte locale, environment variable values, here-documents, and the command line may all contain environment values. Options –c dir Attempts to change into the specified directory when make starts up. If make cannot change to the directory, an error message is printed. This is useful for recursive makefiles when building in a different directory. –D macro definition Define macro on the command line before reading any makefile. Use the same form as a normal macro definition (macro=string). If you use this option, make assigns the value to the macro before reading the makefile; any definition of the same macro contained in the makefile supersedes this definition. Note: make uses any macros defined in this way before reading any makefile, including the startup file. This allows you to define a startup file by providing a value for MAKESTARTUP on the command line: make –D MAKESTARTUP=$HOME/project/startup.mk –E 408 Suppresses reading of the environment. If you do not specify either –E or –e, make reads the environment before reading the makefile. z/OS V1R12.0 UNIX System Services Command Reference make –e Reads the environment after reading the makefile. If neither –E nor –e are specified, make reads the environment before reading the makefile, except for the SHELL environment variable, which you must explicitly export. This option does not affect the value of MAKEFLAGS. –f file Uses file as the source for the makefile description. make ignores the makefiles specified as prerequisites to the .MAKEFILES target. If you specify a minus sign (−) in place of file, make reads the standard input. (In other words, make expects you to enter the makefile from the terminal or to redirect it from a file.) You can use more than one –f option. –i Tells make to ignore all errors and continue making other targets. This is equivalent to the .IGNORE attribute or macro. –k Makes all independent targets, even if an error occurs. Ordinarily, make stops after a command returns a nonzero status. Specifying –k tells make to ignore the error and continue to make other targets, as long as they are not related to the target that received the error. make does not attempt to update anything that depends on the target that was being made when the error occurred. –n Displays the commands that make would execute to update the chosen targets, but does not actually execute any recipe lines unless they have a plus sign (+) command prefix. make displays recipe lines with an at sign (@) command prefix on standard output (stdout). For more information about recipe lines, see z/OS UNIX System Services Programming Tools. With group recipes, make displays the commands it uses to update a given target, but it also executes the commands. Note: z/OS make supports group recipes, but traditional implementations of make do not. A group recipe signifies a collection of command lines fed as a unit to the command interpreter. By contrast, make executes commands in a normal recipe one by one. For more information about group recipes, see z/OS UNIX System Services Programming Tools. If make finds the string $ (MAKE) in a recipe line, it expands it, adds –n to the MAKEFLAGS, and then executes the recipe line. This enables you to see what happens when recursive calls are made to make. The output correctly shows line breaks in recipes that are divided into several lines of text using the \<newline> sequence. –p Prints the makefile after it has been processed to include macro and target definitions. This display is in human-readable form useful for debugging, but you cannot use it as input to make. –q Checks whether the target is up to date. If it is up to date, make exits with a status of 0; otherwise, it exits with a status of 1 (typically interpreted as an error by other software). No commands are run when –q is specified. –r Does not read the startup file. Various control macros and default rules will not be defined. –S Ends make if an error occurs during operations to bring a target up to date (opposite of –k). This is the default. –s Specifies that recipe commands, warning messages, or touch messages (see the –t option) not be displayed. This is equivalent to the .SILENT attribute or macro. –t Touches the target to mark them as up-to-date, but only executes Chapter 2. Shell command descriptions 409 make commands to change a target if the target has a plus sign (+) command prefix. make does not touch up-to-date targets or targets that have prerequisites but not recipes. make displays a message for each touched target file indicating the file name. –u Forces an unconditional update: make behaves as if all the prerequisites of the given target are out of date. –V Prints the version number of make and a list of built-in rules. –v Causes make to display a detailed account of its progress. This includes what files it reads, the definition and redefinition of each macro, metarule and suffix rule searches, and other information. –x Exports all macro definitions to the environment. This happens just before make begins making targets (but after it has read the entire makefile). Targets A target is normally a file that you want to ensure is up to date with the files on which it is dependent (the prerequisites). For example, you may want to check to see if a is based on the most recent version of the corresponding source code. If it is not, then have the source code recompiled to get an up-to-date version. In this case, the compiled program file is the target and the corresponding source files are prerequisites (that is, the files on which a target is dependent). make updates all targets that are specified on the command line. If you do not specify any target, make updates the targets in the first rule of the makefile. A target is out of date if it is older than any of its prerequisites (based on modification times) or if it does not exist. To update a target, make first recursively ensures that all the target's prerequisites are up to date, processing them in the order in which they appear in the rule. If the target itself is out of date, make then runs the recipe associated with the target. If the target has no associated recipe, make considers it up to date. make also supports another form of targets, known as special targets, described in “Special target directives” on page 420. Makefiles A makefile is a text file that describes the dependencies between various files. It normally contains a list of targets and identifies the prerequisites on which each depends. It also contains a series of instructions, called recipes, which describe the actions to be taken if a given target is out of date with its prerequisites. By default, if you do not specify the –f option, make looks for a file in your current directory named makefile. If it does not find this file, it searches your current directory for a file named Makefile. If make finds either file, it uses this file as your makefile. You can change the default makefiles with the .MAKEFILES special target. This target is already specified in the startup.mk file. See “Special target directives” on page 420 for more information. Macro definitions Macro definitions can appear on the command line or in makefiles. Macro definitions on the command line overrule definitions in makefiles; makefile 410 z/OS V1R12.0 UNIX System Services Command Reference make definitions never overrule command-line definitions. Macro definitions on the command line may not have any white space between the macro name and the = character. Macro definitions may take several forms. macro = string is the usual form. If string contains macro references, make does not expand them when the macro is defined, but when the macro itself is expanded. macro := string expands macros inside string before assigning a value to macro. macro += string adds string to the previous value of macro. You can use any amount of white space on both sides of macro operators. make defines the name macro to have the value string and replaces it with that value whenever it is used as $(macro) or ${macro} within the makefile. It is possible to specify a $(macro_name) or ${macro_name} macro expansion, where macro_name contains more $(....) or ${...} macro expansions itself. Normally, make does not include white space at the beginning and end of string in the definition of macro; however, it never strips white space from macros imported from the environment. If you want to include white space in a macro definition specified on the make command line, you must enclose the definition in quotes. make resolves macro definitions in the following order: 1. Macro definitions in the built-in rules 2. Macro definitions on the command line associated with the –D option 3. Macro definitions in the startup file 4. Contents of the environment 5. Macro definitions in the makefiles (in the order they appear) 6. Macro definitions on the command line without the –D option If you specify the –e options, make reads the makefiles before reading the contents of the environment. If you specify the –E option, make does not read the contents of the environment. If a macro is already defined when make encounters a new definition for it, the new definition replaces the old one. For example, a macro definition for name on the command line overrides a definition for name in the makefile. You can use the –v option to display macro assignments, as make performs them. Macro modifiers make supports macro expansions of the form: $(macro_name:modifier_list:modifier_list:...) Possible modifiers are: ^"string" Prefix tokens +"string" Suffix tokens Chapter 2. Shell command descriptions 411 make b File portion of all path names, without suffix d Directory portion of all path names f File portion of all path names, including suffix l All characters mapped to lowercase s/pat/string/ Simple pattern substitution (you can use any character to separate the pattern from the substitution text) suffix=string Suffix replacement t"separator" Tokenization with given separator u All characters mapped to uppercase You can specify macro modifiers in either uppercase or lowercase. For example, the macro assignment: test = D1/D2/d3/a.out f.out d1/k.out produces the following expansion: $(test:d) $(test:b) $(test:f) ${test:db} ${test:s/out/in} $(test:f:t"+") $(test:t"+") $(test:u) $(test:l) $(test:^"/rd/") $(test:+".Z") → → → → → → → → → → → D1/D2/d3 . d1 a f k a.out f.out k.out D1/D2/d3/a f d1/k D1/D2/d3/a.in f.in d1/k.in a.out+f.out+k.out D1/D2/d3/a.out+f.out+d1/k.out D1/D2/D3/A.OUT F.OUT D1/K.OUT d1/d2/d3/a.out f.out d1/k.out /rd/D1/D2/d3/a.out /rd/f.out /rd/d1/k.out D1/D2/d3/a.out.Z f.out.Z d1/k.out.Z Runtime macros Runtime macros can take on different values for each target. $@ The full target name. When building a normal target, this macro evaluates to the full name of the target. When building a library, it expands to the name of the archive library. For example, if the target is: mylib(member) $@ expands to: mylib $% The full target name. When building a normal target, this macro evaluates to the full name of the target. When building a library, it expands to the name of the archive member. For example, if the target is: mylib(member) $% expands to: member 412 $& The list of all prerequisites. $? The list of all prerequisites that are newer than the target. $^ The list of all prerequisites taken from the list specified on the rule line of the recipe where the $^ appears. z/OS V1R12.0 UNIX System Services Command Reference make $< In inference rules, it evaluates to the single prerequisite that caused the execution of the rule. In normal rules it evaluates the same as $?. $> The name of the library if the current target is a library member. $* The target name with no suffix ($(%:db)) or the value of the stem in a metarule. The constructs $$@, $$%, $$>, and $$* can appear in a prerequisite list as dynamic prerequisites. $$@ stands for the target currently being made. For example: fred : [email protected] fred : fred.c are equivalent. The construct can be modified, as in: fred.o : $$(@:b).c The runtime macros can be modified by the letters D and F to indicate only the directory portion of the target name or only the file portion of the target name. (The working directory is represented by a dot.) If define.h is the only prerequisite that is newer than the target, the macros $?D and $?F expand to dot ( .) and to define.h. If you are building a library, $$% stands for the name of the archive member being made. If you are building a normal target, $$% stands for the name of the target currently being made. $$* stands for the name of the current target being made, but with no suffix. If you are building a library, $$> stands for the name of the archive library being made. If you are not building a library, $$> is not valid. Usage note Comments begin with the pound (#) character and extend to the end of the line. make discards all comment text. Makefile contents Inside makefiles, you can split long lines over several lines of text. To do this, put a backslash (\) at the very end of the line. You can use this technique to extend comments as well as recipe lines and macro definitions, for example. If a rule or macro definition must contain a # character, use \#; otherwise, make mistakes the # for the beginning of a comment. Also, if a macro definition must contain a single $ character, use $$. File names that contain a colon must always be enclosed in quotes, as in: "a:target" : "a:prereq" Rules The general format of a rule is: targets [attributes] ruleop [prerequisites] [;recipe] {<tab> recipe} Chapter 2. Shell command descriptions 413 make where the items enclosed in square brackets are optional. (This is just a documentation convention; you do not actually enter the square brackets.) The parts of the rule are described as follows: targets One or more target names. attributes A list, possibly empty, of attributes to apply to the list of targets. ruleop An operator token, usually a colon (:), that separates the target names from the prerequisite names and may also affect the processing of the specified targets. prerequisites A list of zero or more names on which the specified targets depend. recipe A command to execute to update targets. May follow on the same line as the prerequisites, separated from them by a semicolon. If such a recipe is present, make takes it as the first in the list of recipe lines defining how to make the named targets. Additional recipe lines may follow the first line of the rule. Each subsequent recipe line must begin with a tab character. The possible rule operators are listed as follows: targets : prereqs Is a simple rule definition. For explicit targets, at most one simple rule may have a recipe, in contrast with the :: rule operator, whose description follows. targets :! prereqs Executes the recipe for the associated targets once for each recently changed prerequisite. In simple rules, the recipe is executed only once, for all recently changed prerequisites at the same time. The $< macro expands to the current recently changed prerequisites if it appears in rules with this rule operator. targets :^ prereqs Inserts the specified prerequisites before any other prerequisites already associated with the specified targets. targets :– prereqs Clears the previous list of prerequisites before adding the new prerequisites. targets :: prereqs If no prerequisites are specified, the targets are always remade. Otherwise it is used for multiple rules applying to the same targets. Each rule can specify a different set of prerequisites with a different recipe for updating the target. Each rule is treated independently; the target is remade for each rule with recently changed prerequisites, using the corresponding recipe. targets : | prereqs Can only be used in metarules. It tells make to treat each metadependency as an independent rule. For example: %$0 : | archive/%.c rcs/%.c /srcarc/RCS/%period.c recipe... is equivalent to 414 z/OS V1R12.0 UNIX System Services Command Reference make %$0 : archive/$.c recipe: %$0 : rcs/%.c recipe: %$0 : /srcarc/rcs/%.c recipe: Circular dependencies There are two types of circular dependencies: within-rule and between-rule. A within-rule circular dependency occurs when the target's name is included in the list of prerequisites for that target. For example, c.o : a.o b.o c.o is a within-rule circular dependency. make detects a within-rule circular dependency when it is parsing the makefile to build the dependency tree. A between-rule circular dependency occurs when you have two targets, each of which includes the other's name in its prerequisite list. For example, a.o : b:o b:o : a.o is a between-rules circular dependency. make detects a between-rule circular dependency when it is processing the dependency tree built during the parse phase. Typically, make only detects circular dependencies for those targets actually being built. When a circular dependency is encountered, make issues a warning message, removes the offending prerequisite from the list, and continues parsing the makefile. You can use the .CYCLECHECK special target to alter. make's treatment of circular dependencies. See also “Special target directives” on page 420, which describes special targets.) Recipes You can use a target that has prerequisites but no recipes to add the given prerequisites to that target's list of prerequisites. You can preface any recipe line with a command prefix immediately after the tab character –, @, + or all three. The method of entering tab characters using an ISPF editor is discussed in z/OS UNIX System Services User's Guide. v – indicates that make is to ignore nonzero exit values when it runs this recipe line. v @ indicates that make is not to display the recipe line before running it. v + tells make to always run this line, even when –n, –p, or –t is specified. Group recipes begin with [ in the first non-white-space position of a line, and end with ] in the first non-white-space position of a line. Recipe lines in a group recipe need not have a leading tab. make executes a group recipe by feeding it as a single unit to a shell. If you immediately follow the [ at the beginning of a group recipe with one of –, @ or +, they apply to the entire group in the same way that they apply to single recipe lines. Inference rules With inference rules you can specify general rules for building files rather than creating a specific rule for each target. Chapter 2. Shell command descriptions 415 make make provides two forms of inference rules: suffix rules and metarules. It includes suffix rules to ensure compatibility with older makefiles. Metarules, however, provide a more general mechanism for specifying make's default behavior. They provide a superset of the functionality of suffix rules. make searches all metarules before using suffix rules. make uses the inference rules to infer how it can bring a target up to date. A list of inference rules defines the commands to be run. The default startup.mk file contains a set of inference rules for the most common targets. You can specify additional rules in the makefile. When make finds no explicit target rule to update a target, it checks the inference rules. If make finds an applicable inference rule with an out-of-date prerequisite, it runs on that rule's recipe. See “Special target directives” on page 420 for information about the .DEFAULT special target). Metarules Metarules have one target with a single percent symbol that matches an arbitrary string called the stem; The % in a dependency stands for the stem. The inference rule to update a target matching pattern p1%s1, where p1 and s1 are prefix and suffix strings of the target, having a prerequisite p2%s2, where % is the stem from the target, is specified as a rule: p1%s1 : p2%s2 ; recipe.... Either the prefix or suffix string may be empty. Transitive closure Metarules provide a mechanism that allows several metarules to chain together to eventually create the target. This is called transitive closure. For example, if you have metarules: %.o : %.c ... rule body.... and: %.c : %.y ... rule body ... When you specify: make file.o make uses the first metarule to look for file.c. If it can't find an explicit rule to build file.c, it again looks through the metarules and finds the rule that tells it to look for file.y. make allows each metarule to be applied only once when performing transitive closure to avoid a situation where it loops forever. (For example, if you have the rule: % : %.c ... rule body ... the command: 416 z/OS V1R12.0 UNIX System Services Command Reference make make file causes make to look for file.c. If the metarules were not restricted and file.c did not exist, then make would look for file.c.c, and then file.c.c.c, and so on. Because each metarule is applied only once, this can't happen.) Transitive closure is computed once for each metarule head the first time the pattern matches a target. When transitive closure is computed, all the computed rules are added to the rule set for that metarule head. For example, if you have the rules: % : %.o recipe 1... %.o : %c recipe 2... and you are making file, this target matches successfully against % causing transitive closure to be computed for %. As a result of this computation, a new rule is created: % : %.c recipe 2... recipe from .REMOVE target for %.o, if not .PRECIOUS recipe 1... which is executed if file.o doesn't exist. When the computation for the rule head has been done, it is marked as transitive closure computed. Since all possible new rules have been added to the rule set the first time the computation is done, it is not necessary to do it again: Nothing new is added. The term transitive closure is adapted from the mathematical set theory. Note: In set theory, if you have a set composed of pairs (a,b) and (b,c), then the set would be transitively closed if (a,c) is also in the set. The best way to understand how this works is to experiment with little make files with the –v flag specified. This shows you in detail what rules are being searched, when transitive closure is calculated, and what rules are added. Order of rule generation Since transitive closure allows make to generate new rules, it is important to understand the order in which this is done: 1. make searches for explicit rules in the order in which they appear, so explicit rules always take precedence. 2. make reads metarules in the order in which they appear in the makefile. The first rule that appears in the makefile is the first one checked. 3. New explicit metarules (as distinct from metarules generated by transitive closure) replace old ones. In other words, if your makefile contains an explicit rule like this one, it replaces the default rule in startup.mk: %$O : %.c rule1 If you use the –v option, make prints a warning when it replaces a metarule. 4. When transitive closure is calculated, the new metarules generated are added to the end of the list of possible metarules. Thus, make always finds the explicit rules first, so they take precedence over generated rules. You can use the –v option to see what rules make generates and the order in which they appear. Chapter 2. Shell command descriptions 417 make 5. make performs two passes through the rules. On the first pass it tries to find a match with an explicit rule in the makefile; if this does not succeed, make performs a second pass to find a match with an existing file. Suffix rules make treats targets that begin with a period and contain no slashes or percent signs as suffix rules. If there is only one period in the target, it is a single suffix inference rule. Targets with two periods are double-suffix inference rules. Suffix rules do not have prerequisites but do have commands associated with them. When make finds no explicit rule to update a target, it checks the suffix of the target (.s1) to be built against the suffix rules. make examines a prerequisite based on the basename of the target with the second suffix (.s2) appended, and if the target is out of date with respect to this prerequisite, make runs the recipe for that inference rule. Metarules take precedence over suffix rules. If the target to be built does not contain a suffix and there is no rule for the target, make checks the single suffix inference rules. The single suffix inference rules define how to build a target if make finds a rule with one of the single suffixes appended. A rule with one suffix .s2 defines how to build target from target.s2. make treats the other suffix (.s1) as null. For a suffix rule to work, the component suffixes must appear in the prerequisite list of the .SUFFIXES special target. You can turn off suffix rules by placing the following in your makefile: .SUFFIXES: This clears the prerequisites of the .SUFFIXES target, which prevents suffix rules from being enacted. The order that the suffixes appear in the .SUFFIXES rule determines the order in which make checks the suffix rules. The search algorithm used for suffix rules depends on whether the .POSIX special target is specified. When .POSIX is specified, the following steps describe the search algorithm for suffix rules: 1. Extract the suffix from the target. If that target does not have a suffix, go to step 6. 2. Is it in the .SUFFIXES list? If not, quit the search. 3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix. 4. If there is a match, extract the base name of the file, add on the second suffix, and determine if the resulting file exists. If the resulting file does not exist, keep searching the double suffix rules. If the resulting file does exist, use the recipe for this rule. 5. If a successful match is not made, the inference has failed. 6. If the target did not have a suffix, check the single suffix rules in the order that the suffixes are specified in the .SUFFIXES target. 7. For each single suffix rule, add the suffix to the target name and determine if the resulting file name exists. 8. If the file name exists, execute the recipe associated with that suffix rule. If the file name doesn't exist, continue trying the rest of the single suffix rules. If a successful match is not made, the inference has failed. 418 z/OS V1R12.0 UNIX System Services Command Reference make When the .POSIX special target is not specified, make handles suffix rules in the same manner as traditional implementations of make. The following steps describe the search algorithm for suffix rules in this situation. 1. Extract the suffix from the target. If that target does not have a suffix, go to step 8. 2. Is it in the .SUFFIXES list? If not, then quit the search. 3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix. 4. If you find one, then extract the base name of the file, add on the second suffix and see if the resulting file exists. If it does, go to step 7. If not, continue with step 5. 5. Is there an inference rule for the resulting file? If yes, run the recipe associated with that rule (which should describe how to make the file exist) and go to step 7. 6. Search for the next double-suffix rule that matches the target suffix and return to step 4. If the double-suffix rules are exhausted, then the inference has failed. 7. Use the recipe for the target rule. 8. If the target did not have a suffix, then check the single-suffix rules in the order that the suffixes are specified in the .SUFFIXES target. 9. For each single-suffix rule, add the suffix to the target name and see if the resulting file name exists. 10. If the file exists, then run the recipe associated with that suffix rule. If it doesn't exist, continue trying the rest of the single-suffix rules. 11. If a successful match is not made, then the inference has failed. make also provides a special feature in the suffix rule mechanism for archive library handling. If you specify a suffix rule of the form: .suf.a: recipe the rule matches any target having the LIBRARY attribute set, regardless of what the actual suffix was. For example, if your makefile contains the rules: .SUFFIXES: .a .c echo adding $< to library $@ then if mem$0 exists, then the following command: make "mylib(mem.o)" causes: adding mem.o to library mylib to be printed. Attributes make defines several target attributes. Attributes can be assigned to a single target, a group of targets, or to all targets in the makefile. Attributes affect what make does when it needs to update a target. You can associate attributes with targets by specifying a rule of the form: attribute_list : targets Chapter 2. Shell command descriptions 419 make This assigns the attributes in attribute_list to the given targets. If you do not specify any targets, the attributes apply to every target in the makefile. You can also put attributes inside a normal rule, as in: targets attribute_list : prerequisites The recognized attributes are: .EPILOG Insert shell epilog code when running a group recipe associated with any target having this attribute set. .IGNORE Ignore an error when trying to make any target with this attribute set. .LIBRARY Target is a library. .PRECIOUS Do not remove this target under any circumstances. Any automatically inferred prerequisite inherits this attribute. .PROLOG Insert shell prolog code when running a group recipe associated with any target having this attribute set. .SETDIR Change the working directory to a specified directory when making associated targets. The syntax of this attribute is .SETDIR=path, where path is the path name of desired working directory. If path contains any : characters, the entire attribute string must be quoted, not just the path name. .SILENT Do not echo the recipe lines when making any target with this attribute set, and do not issue any warnings. You can use any attribute with any target, including special targets. Special target directives Special target directives are called targets because they appear in the target position of rules; however, they are really keywords, not targets. The rules they appear in are really directives that control the behavior of make. The special target must be the only target in a special rule; you cannot list other normal or special targets. Some special targets are affected by some attributes. Any special target can be given any attribute, but often the combination is meaningless and the attribute has no effect. .BRACEEXPAND This target may have no prerequisites and no recipes associated with it. If set, the target enables the outdated brace expansion feature used in older versions of make. Older makes would expand a construct of the following form, beginning with each token in the token list: string1{token_list}string2 Older makes would append string1 to the front of each token in the list, and string2 to the end of each token in the list. A more productive means 420 z/OS V1R12.0 UNIX System Services Command Reference make for achieving the same result with modern versions of make relies on macro expansion with prefix and suffix modifiers: $ (TOKEN_BASE:^"prefix:+"suffix") The double quotes are required. Brace expansion is an outdated feature available in past versions of make. .CYCLECHECK This special target cannot have any prerequisites or recipes associated with it. If set, it determines how make treaters circular dependencies (see “Circular dependencies” on page 415). You can specify one of five attributes with this target. If you specify more than one attribute, an error message results. The five attributes are: .SILENT make remains silent about any within-rule and between-rule circular dependencies, removes the offending dependency from the list of prerequisites, and continues. .WARNTARG make issues warnings for named targets with circular dependencies. If the name of the dependency is the same as the named target, it is removed from the list of prerequisites and make continues. This is the default behavior if .CYCLECHECK is not specified or is specified with no attributes. .WARNALL make issues warnings for all within-rule circular dependencies regardless of whether the target is being built or not and for all between-rule circular dependencies for the named targets. The offending dependency is removed from the list of prerequisites and make continues. .FATALTARG make treats all circular dependencies for named targets as fatal errors. It issues an error message and exits. .FATALALL make treats all within-rule circular dependencies as fatal errors regardless of whether the target is being built or not. It also treats all between-rule circular dependencies for named targets as fatal errors. make issues an error message and exits. For example, to set the circular dependency check to make's default, use the rule: .CYCLECHECK .WARNTARG: .DEFAULT This target has no prerequisites, but it does have a recipe. If make can apply no other rule to produce a target, it uses this rule if it has been defined. .ERROR make runs the recipe associated with this target whenever it detects an error condition. .EXPORT All prerequisites associated with this target that correspond to macro names are exported to the environment at the point in the makefile at which this target appears. Chapter 2. Shell command descriptions 421 make .GROUPEPILOG make adds the recipe associated with this target after any group recipe for a target that has the .EPILOG attribute. .GROUPPROLOG make adds the recipe associated with this target after any group recipe for a target that has the .PROLOG attribute. .IMPORT make searches in the environment for prerequisite names specified for this target and defines them as macros with their value taken from the environment. If the prerequisite .EVERYTHING is given, make reads in the entire environment (see –e and –E options). .INCLUDE make reads one or more additional makefiles (specified in the prerequisite list), as if their contents had been inserted at this point. If the prerequisite list contains more than one file, make reads them in order from left to right. make uses the following rules to search for extra makefiles: v If a relative file name is enclosed in quotes, or is not enclosed with angle brackets (< and >), make looks in the current directory. If the file isn't present, make then looks for it in each directory specified by the .INCLUDEDIRS special target. v If a relative name is enclosed with angle brackets (< and >), make make only searches in directories specified by the .INCLUDEDIRS special v If an absolute path name is given, make looks for that file and ignores the list associated with the .INCLUDEDIRS special target. .INCLUDEDIRS The list of prerequisites specified for this target defines the set of directories to search when including a makefile. .MAKEFILES The list of prerequisites is the set of files to try to read as the user makefile. These files are made in the order they are specified (from left to right) until one is found to be up to date. This is the file that is used. .NOAUTODEPEND Disables the autodependency feature when building libraries. When this special target is used, only library members that have been explicitly given as dependents are considered prerequisites. .POSIX make processes the makefile as specified in the POSIX.2 draft standard. This target may have no prerequisite and no recipes associated with it. This special target must appear before the first non-comment line in the makefile. If this special target is present, the following facilities are disabled: v All recipe lines are run by the shell, one shell per line, regardless of the setting of SHELLMETAS. v Metarule inferencing is disabled. v Conditionals are disabled. v Dynamic prerequisites are disabled. v Group recipes are disabled. v Disables brace expansion (set with the .BRACEEXPAND special target). 422 z/OS V1R12.0 UNIX System Services Command Reference make v make does not check for the string $ (MAKE) when run with the –n options specified. .REMOVE make uses the recipe of this target to remove any intermediate files that it creates if an error is encountered before the final target is created. This .REMOVE target only deletes files that satisfy all of the following criteria: v The file didn't exist when make began running. v The file is named as an intermediate target, produced by invoking a metarule that was produced by transitive closure. v The file is not explicitly named in the makefile. v The generated target doesn't have the .PRECIOUS attribute. v The file is a prerequisite of a rule that is actually used. .SOURCE The prerequisite list of this target defines a set of directories to check when trying to locate a target file name. make defaults to creating target files in the same directory that it finds the source file. .SOURCE.x Same as .SOURCE, except that make searches the .SOURCE.x list first when trying to locate a file matching a target with a name that ends in the suffix .x. .SUFFIXES mk appends the prerequisite list of this target to the set of suffixes used when trying to infer a prerequisite for making a target using suffix rules. If you specify no prerequisites, make clears the list of suffixes, effectively disabling suffix rules from that point on. A name of the form library(member) indicates a member of a library. The library portion is a target with the .LIBRARY attribute, and the member portion is a prerequisite of the library target. A name of the form library((entry)) indicates the library module that contains the given entry point. Once again, the library portion is a target with the .LIBRARY attribute. make regards the library member that contains the entry point entry as a prerequisite of the library target. Control macros make defines a number of control macros that control make's behavior. When there are several ways of doing the same thing, control macros are usually the best. A control macro that has the same function as a special target or attribute also has the same name. Macros that are said to be defined internally are automatically created by make and can be used with the usual $(name) construct. For example, $(PWD) can be used to obtain the current directory name. Recognized control macros are: DIRSEPSTR Contains the characters used to separate parts in a path name and can be set by the user. make uses the first character in this string to build path names when necessary. Chapter 2. Shell command descriptions 423 make .EPILOG If assigned a nonnull value, the .EPILOG attribute is given to every target. GROUPFLAGS Specifies option flags to pass to GROUPSHELL when make invokes it to run a group recipe. GROUPSHELL Gives the path name of the command interpreter (shell) that make calls to process group recipes. GROUPSUFFIX Specifies a string for make to use as a suffix when creating group recipe files to be run by the command interpreter. .IGNORE If this is assigned a nonnull value, make assigns the .IGNORE attribute to every target. INCDEPTH This is the current depth of makefile inclusion. It is set internally. MAKE This is set by the startup file and can be changed by the user. The standard startup file defines it as: $(MAKECMD) $(MFLAGS) The MAKE macro is not used by make itself, but the string $(MAKE) is recognized when using the –n option for single-line recipes. MAKECMD This is the name with which make was invoked. MAKEDIR This is the full path name of the initial directory in which make began execution. MAKEFLAGS The MAKEFLAGS macro contains all the options (flags) and macros specified in the MAKEFLAGS environment variable plus all of the options and macros specified on the command line, with the following exceptions. v Specifying –c, –f, or –p in the environment variable results in an error v These same options specified on the command line do not appear in the MAKEFLAGS macro. Options in the MAKEFLAGS environment variable may have optional leading dashes and spaces separating the options. These are stripped out when the MAKEFLAGS macro is constructed. Note: make always reads the MAKEFLAGS environment variable before reading the makefile. The –E and –e options do not affect this. MAKESTARTUP This has the default value: /etc/startup.mk To change this value, you can set the MAKESTARTUP environment variable before running make. You can also specify a value for this control macro on the command line if you use the –D option: make –DMAKESTARTUP=$HOME/project/startup.mk 424 z/OS V1R12.0 UNIX System Services Command Reference make Because make processes command-line macros after reading the startup file, setting this macro on the command line does not have the desired effect. MFLAGS This is the same as MAKEFLAGS, except that it includes the leading switch character. NULL This is permanently defined to be the null string. .PRECIOUS If this is assigned a nonnull value, make assigns the .PRECIOUS attribute to every target. .PROLOG If this is assigned a nonnull value, make assigns the .PROLOG attribute to every target. PWD This is the full path name of the working directory in which make is executing. SHELL Specifies the full path name of the command interpreter that make calls to process single-line recipes, when necessary. make passes recipe lines to this shell only if they contain one or more of the characters given in SHELLMETAS; otherwise, it runs them directly. By default, the value of the SHELL environment variable does not affect the value of this macro; however, you can use the .IMPORT special target to assign the environment variable's value to this macro. You can also use the .EXPORT special target to assign this macro's value to the SHELL environment variable. SHELLFLAGS Specifies option flags to pass to the shell when invoking it to runs a single-line recipe. SHELLMETAS Specifies a list of metacharacters that can appear in single recipe lines. If make finds any metacharacter, it invokes the recipe using the shell specified by SHELL; otherwise, it runs the recipe without the shell. .SILENT If this is assigned a nonnull value, make assigns the .SILENT attribute to every target. Making libraries A library is a file containing a collection of object files. To make a library, you specify it as a target with the .LIBRARY attribute and list its prerequisites. The prerequisites should be the object members that are to go into the library. make tries to handle the old library construct format in a sensible way. When it finds lib(member), it declares the lib portion as a target with the .LIBRARY attribute and the member portion as a prerequisite of the lib target. To make the library properly, old makefile scripts using this format must name the lib as a target and must try to bring it up to date. The same thing happens for any target of the form lib((entry)). These targets have an additional feature in that the entry target has the .SYMBOL attribute set automatically. Conditionals You specify the conditional expression as follows: Chapter 2. Shell command descriptions 425 make .IF expression ... if text ... .ELSE ... else text ... .END or: .IF expression ... if text ... .ELSIF expression2 ... elsif text ... .ELSE ... else text ... .END The .ELSE or .ELSIF portion is optional, and you can nest the conditionals (that is, the text may contain another conditional). The .IF, .ELSE, .ELSIF, and .END conditionals must start in the first column of the line. expression or expression2 can have one of three forms: string is true if the given string is nonnull, string == string is true if the two strings are equal, and: string != string is true if the two strings are not equal. Typically, one or both strings contain macros, which make expands before making comparisons. make also discards white space at the start and end of the text portion before the comparison. This means that a macro that expands to nothing but white space is considered a null value for the purpose of the comparison. If a macro expression needs to be compared with a null string, compare it to the value of the macro $(NULL). The text enclosed in the conditional construct must have the same format that it would have outside the conditional. In particular, make assumes that anything that starts with a tab inside the conditional is a recipe line. This means that you cannot use tabs to indent text inside the conditional (except, of course, for recipe lines, which always begin with tabs). Files make uses the following file: /etc/startup.mk The default startup file containing default rules. Environment variables make uses the following environment variables: MAKEFLAGS Contains a series of make options that are used as the default options for any make command. You can specify the options with or without leading minus signs (−) and blanks between them. It can also include macro definitions of the form usually found on the command line. MAKESTARTUP Contains the path name of the make stamp file. By default, make uses the 426 z/OS V1R12.0 UNIX System Services Command Reference make file /etc/startup.mk as its startup file. To use a different file, set this environment variable before running make. SHELL Contains a name of a command interpreter. To assign this value to the SHELL control macro, use the .IMPORT special target. You can also use the .EXPORT special target to assign the value of the SHELL macro to the environment variable. Localization make uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values If a command in a recipe line fails (exits with a nonzero status), make returns the exit status of that command. Because most commands use exit status values between 0 and 10, make uses exit status values below 10 only for failures that do not run recipe lines. 0 Successful completion 1 Returned if you specified –q and file is not up to date 2 Failure due to any of the following: v Unknown command-line option v Missing argument to option, such as no file name for –f. 126 Recipe command was not executable. 127 Recipe command was not found. 129–254 make was interrupted by a signal; the error code is the signal number ORed with 128. For example, SIGINT is frequently signal 1; the return code from make is 128|1, or 129. 255 Failure due to any of the following: v Macro cannot be redefined v Macro variables not assigned with := v Special target cannot be a prerequisite v Too many makefiles specified v Configuration file not found v No makefile present v Missing .END for .IF v No target v Inability to return to directory v Too many open files v Open failed v File not found v Inability to change directory v No more memory v Line too long Chapter 2. Shell command descriptions 427 make v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v 428 Circular macro detected Unterminated pattern string Unterminated replacement string Token separator string not quoted Unterminated separator string Expansion too long Suffix too long Unmatched quote .IF .ELSE ... END nesting too deep .ELSE without .IF Unmatched .END Inference rules resulting in circular dependency No macro name Write error on temp file Target not found, and cannot be made Inability to make NAME <+ diversion unterminated <+ diversion cannot be nested <+ missing before +> Incomplete rule recipe group detected Inability to mix single and group recipe lines Unmatched ] found Macro or rule definition expected but not found Name too long Inability to determine working directory Only one NAME attribute allowed in rule line Multiple targets not allowed in % rules Special target must appear alone Duplicate entry in target list Syntax error in % rule, missing % target Duplicate entry in prerequisite list Missing targets or attributes in rule Multiply defined recipe for target Empty recipe for special target Imported macro NAME not found in environment No .INCLUDE files specified Include file NAME, not found NAME ignored on special target Attributes possibly ignored Inability to find member defining SYMBOL((NAME)) Incorrect library format Inability to touch library member SHELL macro not defined Too many arguments Inability to export NAME Inability to open file Circular dependency detected Inability to stat / Inability to stat . Inability to open .. Read error in .. Metarule too long: "rule" z/OS V1R12.0 UNIX System Services Command Reference make Limits 1. The length of a single makefile script line cannot exceed 32768 characters. 2. The length of an argument string cannot exceed 32768 characters. 3. The length of a macro name gets truncated after 256 characters. Usage notes 1. When the .SETDIR special target is used, make checks the file attributes of targets and prerequisites on every pass through a rule. This can significantly increase the number of system accesses. 2. In a double-byte environment, any character interpreted by make can be a double-byte character, including those in macro definitions and targets. 3. In a double-byte locale, if make encounters an incorrect double-byte sequence, it ends with an error message. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The following features of make are enhancements to POSIX.2: v The options: –cdir, –D macro definition, –E, –u, –V, –v, and –x. v The –n option has enhanced functionality not covered by the standard; for more information, see the –n option and the POSIX special target for make. v The runtime macros: $&, $^ , $>. v The dynamic prerequisites: $$%, $$>, $$*, $$@. v All macro expansions. v Macro assignments of the following form: macroname macroname := += stringassigned stringassigned v Brace expansion. v Backslash continuation. v The quoting mechanism, as in the following example: "a:target" : "a:prerequisite" v All rule operators except the colon (:). v Conditionals. v Metarules. v All make attributes except .IGNORE, .PRECIOUS, .SILENT (referred to in POSIX.2 as special targets). v All make special targets except .DEFAULT, .POSIX, .SUFFIXES (referred to in POSIX.2 as special targets). v All make macros except SHELL (referred to in POSIX.2 as control macros). Related information c89, cc, c++, makedepend S. I. Feldman, “Make—Program for Maintaining Computer Programs,” Software—Practice and Experience 9 (no. 4, April 1979):225–65 [Bell Labs, Murray Hill, NJ] Chapter 2. Shell command descriptions 429 makedepend makedepend — Generate source dependency information Format makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend makedepend [–S directory] [–W m,option[,option]...]... sourcefile [(sourcefiles)]... [–S directory] [–W m,a] [–W m,c89 | –W m,cc] [–W m,file(MakeFile) | –W m,f(MakeFile)] [–W m,list(FileName) | –W m,lis (FileName)] [–W m,o(ObjSuffix)] [–W m,p(ObjPrefix)] [–W m,s(String)] [–W m,showinc | –W m,show] [–W m,type(c|C(t1,t2,...)) | –W m,t(c|C(t1,t2,...))] [–W m,V(OSVvRr) | –W m,V(zOSVvRr)] [–W m,w(Width)] For z/OS UNIX makedepend [c89|cc|c++options]: makedepend [+−] makedepend [–D name[=value]] makedepend [–Idir1[,dir2]...] makedepend [–0, –O (–1), –2, –3] makedepend [–Uname] makedepend [–Wphase,option[,option]...] Description Guideline: As of z/OS V1R11, consider using the z/OS XL C/C++ -qmakedep compiler option instead of the makedepend tool. The -qmakedep compiler option improves the accuracy of source dependency information and is intended to replace the stand-alone makedepend tool. For more information about -qmakedep, see z/OS XL C/C++ User's Guide. The makedepend tool is used to analyze source files and determine source dependencies. makedepend calls files, which are directly or indirectly included by a source file, "dependencies." If the makedepend W m,-list option is specified, this tool produces a listing file with the following topics: v v v v v The list of The list of The list of The list of Messages compiler options and variables applied to all C source compiler options and variables applied to all C++ source makedepend options applied include and source search paths v Message summary, and v Statistics (in other words, total number of source files processed, number of ignored sources files, and so forth). Options –S directory Specifies the directory or directories where you can locate the source files. The default location for source files is the current directory, "./". –W m,a Instructs makedepend to append the source dependencies to the end of 430 z/OS V1R12.0 UNIX System Services Command Reference makedepend the makefile rather than replacing any existing ones. If –W m,a is not specified, then makedepend will erase any source dependencies after the marker line and write the new determined source dependencies instead. If there are no existing makefiles, then this option is ignored. –W m,c89 | –W m,cc Instructs makedepend to use either the c89 or the cc compiler mode for the c source files. The c89 mode is the default. The c89/cc mode is overridden if the c++ [+−] option, described below, is specified. –W m,file(MakeFile) | –W m,f(MakeFile) Specifies the name of the makefile to which makedepend writes the determined source dependencies. If this option is specified on the makedepend command line, then the string value of the MakeFile is used as the name for the makefile. Otherwise, makedepend will search in the current directory for a file named "makefile". If no "makefile" exists, then makedepend searches for a file named "Makefile". If no "Makefile" exists, then makedepend creates a new file with the name "makefile" in the current directory and writes the default marker string (see –W m, s(String) below) at the beginning of the new file. If file (./) is specified, the option is ignored silently. –W m,list(FileName) | –W m,lis (FileName) Instructs makedepend to generate a listing file with the specified FileName name. The name depend.1st is the default file name if FileName is not specified with the –W m,list option. If –W m,list(./) is specified, the default listing file name (depend.lst) is used. If the –W m,list option is not specified, listings are not generated. –W m,o(ObjSuffix) Specifies a suffix (file name extension) for the object file names in the source file dependencies. If the environment variable {_OSUFFIX} is defined, then its value will be the default. If it is not defined, the default suffix is o. –W m,p(ObjPrefix) Prefixes object file names in the source dependencies with a path name. The default object file name prefix is an empty string. –W m,s(String) Specifies a new string literal to be used as a marker in the output makefile. All source dependencies are placed after that marker. The default marker string value is "# DO NOT DELETE THIS LINE, makedepend depends on it." If the –W m,s(String) is specified on the makedepend command line, then the marker line and anything after it will be erased from the output makefile, the new marker string literal will be written instead, and the newly determined source dependencies will be written after the new marker line. If both –W m,a and –W m,s(String) are specified on the makedepend command line, then –W m,s(String) will be ignored if a makefile already exists. –W m,showinc | –W m,show Instructs makedepend to report on the include files for each source file. The include files are reported in the includes topic of the listing file. If the –W m,showinc option is specified, the list option is automatically turned on. If the –W m,showinc option is not specified, the include file list will not be reported. –W m,type(c|C(t1,t2,...)) | –W m,t(c|C(t1,t2,...)) Instructs makedepend to treat source files with any file name type that Chapter 2. Shell command descriptions 431 makedepend belong to the set {t1,t2,...} as either c source files if the c is used with the type, or as C++ source files if the C is used. Default types are as follows: v Any source file with a file name extension of c will be treated as a c source file. If the –W m,type(c(t1,t2,...)) option is specified on the makedepend command line, then any source file with a file name extension that belongs to the set {c, t1, t2,...} will be treated as a c file. Notice that the types {t1,t2,...} that are specified with the –W m,type option are added to the default c file name extension type. v Any source file with a file name extension of C, cpp, or cxx will be treated as a C++ source file. If the –W m,type(C(t1,t2,...)) option is specified on the makedepend command line, then any source file with a file name extension that belongs to the set {C, CPP, cpp, CXX, cxx, t1, t2,...} is treated as a C++ file. Notice that the types {t1,t2,...} that are specified with the –W m,type option are added to the default {C,CPP,cpp,CXX,cxx} file name extension types. v If both –W m,type(c(...)) and –W m,type(C(...)) options are specified on the makedepend command line with conflicting file name types, then whichever option is specified last becomes the overriding value, including the default file types. For example, when both –W m,type(c(t1,t2)) and –W m,type(C(c,t1,t3) are specified, only files with extension t2 will be treated as c files and files with extensions {c, C, cpp, Cpp, cxx, CXX, t1, t3} will be treated as C++ files. When –W m,type(c(cpp,t1,t2)) and –W m,type(C(t1,t2)) options are specified, files with extensions {c, cpp} will be treated as c source files and files with extensions {C, CPP, cxx, CXX, t1, t2} will be treated as C++ source files. For C source files, if the environment variables {_CSUFFIX} pt {_CSUFFIX_HOST} are defined, the variable value updates the default value. The default C source file extension is c. For C++ source file, if the environment variables {_CXXSUFFIX} and/or {_CXXSUFFIX_HOST} are defined, its value updates the default value. The default C++ source file extensions are {C, CPP, cpp, CXX, cxx}. For example, if {_CXXSUFFIX} is defined as {cdd} and the default C++ source file extensions are {C, CPP, cpp, CXX, cxx}, then the resulting set would be {C, CPP, cpp, CXX, cxx, cdd}. –W m,V(OSVvRr) | –W m,V(zOSVvRr) Specifies the compiler version that will be used, where v and r represent the compiler's version and release respectively. The default version is the current C/C++ compiler version if {_CVERSION} is not defined. If {_CVERSION} is defined, then its value is used as the default compiler version. This option is used to set the _COMPILER_VER_ macro. –W m,w(Width) Sets the maximum line width of the output source dependencies lines. The default value is 78. The following options correspond to the z/OS UNIX c89,cc,c++ compiler options. For more information about these options and their corresponding usage notes, see c89 — Compiler invocation using host environment variables. –+ 432 Specifies that all source files are to be recognized as C++ source files. All file.s, file.o, and file.a files will continue to be recognized as assembler source, object, and archive files respectively. However, any C file.c or file.i z/OS V1R12.0 UNIX System Services Command Reference makedepend files will be processed as corresponding C++ file.C or file.i files, and any other file suffix which would otherwise be unrecognized will be processed as a file.C file. –D name[=value] Defines a C or C++ macro for use in compilation. If only name is provided, a value of 1 is used for the macro it specifies. For information about macros that c89/cc/c++ automatically define, see Usage Note 2. Also see Usage Note 3. –Idir1[,dir2]... Note: The –I option is an uppercase i, not a lowercase L. –I specifies the directories to be used during compilation in searching for include files (also called header files). Absolute pathnames specified on #include directives are searched exactly as specified. The directories specified using the –I option or from the usual places are not searched. If absolute pathnames are not specified on #include directives, then the search order is as follows: 1. Include files enclosed in double quotes (") are first searched for in the directory of the file containing the #include directive. Include files enclosed in angle-brackets (< >) skip this initial search. 2. The include files are then searched for in all directories specified by the –I option, in the order specified. 3. Finally, the include files are searched for in the usual places. (See Usage Note 1 for a description of the usual places.) You can specify an MVS data set name as an include file search directory. Also, MVS data set names can explicitly be specified on #include directives. You can indicate both by specifying a leading double slash (//). For example, to include the include file DEF that is a member of the MVS PDS ABC.HDRS, code your C or C++ source as follows: #include <//’abc.hdrs(def)’> MVS data set include files are handled according to z/OS XL C/C++ compiler conversion rules (see Usage Note 1).. When specifying an #include directive with a leading double slash (in a format other than #include<//'dsname'> and #include<//dd:ddname>), the specified name is paired only with MVS data set names specified on the –I option. That is, when you explicitly specify an MVS data set name, any hierarchical file system (HFS) directory names specified on the –I option are ignored. –0, –O (–1), –2, –3 Specifies the level of compiler optimization (including inlining) to be used. The level –1 (number one) is equivalent to –O (letter capital O). The level –3 gives the highest level of optimization. The default is –0 (level zero), no optimization and no inlining, when not using IPA (Interprocedural Analysis). –Uname Undefines a C or C++ macro specified with name. This option affects only macros defined by the –D option, including those automatically specified by c89/cc/c++. For information about macros that c89/cc/c++ automatically define, see Usage Note 2. Also see Usage Note 3. Chapter 2. Shell command descriptions 433 makedepend –Wphase,option[,option]... Specifies options to be passed to the steps associated with the compile, assemble, or link-editing phases of c89/cc/c++. The valid phase codes are: 0 Specifies the compile phase (used for both non-IPA and IPA compilation). c Same as phase code 0. I Enables IPA (Interprocedural Analysis) optimization. Note: I is an uppercase i, not a lowercase L. Unlike other phase codes, the IPA phase code I does not require that any additional options be specified, but it does allow them. In order to pass IPA suboptions, specify those suboptions using the IPA phase code. For example, to specify that an IPA compile should save source line number information, without writing a listing file, specify: c89 -W I,list file.c To specify that an IPA link-edit should write the map file to stdout, specify: c89 -W I,map file.o Note: c89/cc/c++ options other than the ones listed are ignored by makedepend. Any compiler option can be passed to makedepend through the –W option. For more information about the compiler options, see z/OS XL C/C++ User's Guide. Examples 1. makedepend file1.c file2.c Imagine you are compiling two files, file1.c and file2.c, and each includes the header file header.h. The header.h file includes the files def1.h and def2.h. When you run the command makedepend file1.c file2.c, makedepend parses file1.c and consequently, header.h, and then def1.h and def2.h. It then decides that the dependencies for this file are: v file1.o: header.h def1.h def2.h v file2.o: header.h def1.h def2.h 2. Imagine you are compiling a file, file1.c, and it includes the header file header.h. The header.h file includes the files def1.h and def2.h. When you run the command makedepend file1.c, makedepend parses file1.c and consequently, header.h, and then def1.h and def2.h. It then decides that the dependencies for this file are: file1.o: header.h def1.h def2.h Environment variables makedepend uses the following environment variables. For a full description of these variables, see the Environment Variables topic of c89 — Compiler invocation using host environment variables. {_ACCEPTABLE_RC} Used by c89/cc/c++ to determine the maximum allowed return code (result) of any step (compile, assemble, IPA link, prelink, or link-edit). If the result is between zero and this value (inclusive), 434 z/OS V1R12.0 UNIX System Services Command Reference makedepend then it is treated internally by makedepend exactly as if it were a zero result. The default value is 4. {_CLASSLIB_PREFIX} Provides a prefix for the data sets used during the compilation and execution phases. For makedepend, the focus is the {_CLASSLIB_PREFIX}.SCLBH.+ data set that contains the z/OS C/C++ Class Library include files. {_CSUFFIX} Used by c89/cc/c++ to recognize a C source file. The default value is c. {_CSUFFIX_HOST} Used by c89/cc/c++ to recognize a C source file. The default value is C. {_CXXSUFFIX} Used by c++ to recognize a C++ source file. The default is C. This variable is only supported by the c++ command. {_CXXSUFFIX_HOST} Used by c++ to recognize a C++ source data set. The default is CXX. This variable is only supported by the c++ command. {_CSYSLIB} Used for system library data set concatenation, which resolves #include directives during compilation. {_INCDIRS} Provides directories used by c89/cc/c++ as a default place to search for include files during compilation (after searching {_INCDIRS} and before searching {_CSYSLIB}). {_INCLIBS} The directories used by c89/cc/c++ as a default place to search for include files during compilation (after searching {_INCDIRS} and before searching {_INCLIBS} and {_CSYSLIB}). {_OSUFFIX} Provides a suffix by which c89/cc/c++ recognizes an object file. {_CVERSION} The version of the C/C++ compiler to be invoked by c89/cc/c++. The setting of this variable allows c89/cc/c++ to control which C/C++ compiler program is invoked. It also sets default values for other environment variables. The format of this variable is the same as the result of the Language Environment C/C++ Run-Time Library function _librel(). The default value is the result of the C/C++ Run-Time library _librel() function. Actual variable names are: _C89_CVERSION, _CC_CVERSION, _CXX_CVERSION {NO_CMDOPTS} Controls how the compiler processes the default options set by c89. Setting this variable to 1 reverts the compiler to the behavior that was available prior to z/OS V1R5, when the compiler was unable to distinguish between the c89 defaults and the user-specified options. Setting this variable to 0 (zero) results in the default behavior where the compiler is now able to recognize c89 defaults.The default value is: 0 (zero). Actual variable names are: _C89_NO_CMDOPTS, _CC_NO_CMDOPTS, _CXX_NO_CMDOPTS Localization makedepend uses the LC_ALL localization environment variable, which specifies the locale to be used to override any values for locale categories specified by LANG or certain LC_ variables. Chapter 2. Shell command descriptions 435 makedepend See Appendix F, “Localization” for more information. Usage notes 1. MVS data sets may be used as the usual place to resolve C and C++ #include directives during compilation. Such data sets are installed with Language Environment. When it is allocated, searching for these include files can be specified on the –I option as //DD:SYSLIB. (See the description of environment variable {_CSYSLIB} for information. When include files are MVS PDS members, z/OS XL C/C++ uses conversion rules to transform the include (header) file name on a #include preprocessor directive into a member name. If the "//'dataset_prefix.+'" syntax is not used for the MVS data set which is being searched for the include file, then this transformation strips any directory name on the #include directive, and then takes the first 8 or fewer characters up to the first dot (.). If the "//'dataset_prefix.+'" syntax is used for the MVS data set which is being searched for the include file, then this transformation uses any directory name on the #include directive, and the characters following the first dot (.), and substitutes the "+" of the data set being searched with these qualifiers. In both cases the data set name and member name are converted to uppercase and underscores (_) are changed to at signs (@). If the include (header) files provided by Language Environment are installed into the hierarchical file system in the default location (in accordance with the {_INCDIRS} environment variable), then the compiler will use those files to resolve #include directives during compilation. c89/cc/c++ by default searches the directory /usr/include as the usual place, just before searching the data sets just described. See the description of environment variables {_CSYSLIB}, {_INCDIRS}, and {_INCLIBS} for information about customizing the default directories to search. 2. Feature test macros control which symbols are made visible in a source file (typically a header file). c89/cc/c++ automatically defines the following feature test macros along with the errno macro, according to whether or not cc was invoked. v Other than cc – –D "errno=(*__errno())" – –D _OPEN_DEFAULT=1 v cc – –D "errno=(*__errno())" – –D _OPEN_DEFAULT=0 – –D _NO_PROTO=1 c89/cc/c++add these macro definitions only after processing the command string. Therefore, you can override these macros by specifying –D or –U options for them on the command string. 3. For options that have option-arguments, the meaning of multiple specifications of the options is as follows: –D All specifications are used. If the same name is specified on more than one –D option, only the first definition is used. –I All specifications are used. If the same directory is specified on more than one –I option, the directory is searched only the first time. –U All specifications are used. The name is not defined, regardless of the position of this option relative to any –D option specifying the same name. 436 z/OS V1R12.0 UNIX System Services Command Reference makedepend All specifications are used. All options specified for a phase are passed to it, as if they were concatenated together in the order specified. –W Exit values 0 4 Successful completion Warning error detected Related information c89, cc, c++, make man — Display sections of the online reference manual Format man [–wx] [–M path] [section] entry ... man –k [–M path] keyword ... Description man displays help information about both shell commands and the z/OS UNIX set of TSO/E commands. You can use it to search help files having the specified keywords associated with them. Options –k Searches a precomputed database of syntax lines for information about keywords. –M path Searches the directories indicated by path for help files. If –M is not specified, man uses the path specified in the MANPATH environment variable if set; otherwise man searches /usr/man/%L. The value of the LANG environment variable is substituted for %L in this directory and in the directories specified by MANPATH. All help files are found by searching similarly structured file trees rooted at one or more places. See “Files” on page 439 for a description of what files and directories man should find in each directory that it searches. –w Displays only the filename of the file containing the help file. –x Displays what files man is searching to find the help file. –x also displays any errors man encounters in extracting man pages from online book files. section Is a number (0–9) representing a section of the online help. When you specify a section number, man searches only that section for entry, instead of searching all sections. The online help available for z/OS UNIX contains one section: 1 Commands To find a given entry, man checks each directory in MANPATH for a file with a specific name. For each section number requested, man searches MANPATH for the following files in this order: 1. catn/entry.n in each directory in MANPATH 2. entry.n in /var/man/LANG (the man "cache") 3. mann/*.book in each directory in MANPATH 4. mann/entry.n in each directory in MANPATH Chapter 2. Shell command descriptions 437 man If no section number is specified then man searches all sections in order from 1 to 9, then 0. The first entry found by man is the one displayed. If output is to the terminal, then man invokes a pager command to filter and display the manual pages. If MANPAGER is defined, it is used. If not, then if PAGER is defined, it is used; otherwise, man defaults to using the command: pg –e –p '(Page %d)' If you are running in a double-byte locale, set MANPAGER or PAGER to invoke a command which supports double-byte characters, such as the more command. pg does not support double-byte characters. Examples To find out which utilities do comparisons, issue: man –k compare You can use the man command to view manual descriptions of the z/OS UNIX set of TSO/E commands. To do this, you must prefix all commands with tso. For example, to view a description of the z/OS UNIX variation of the MOUNT command, you would enter: man tsomount You can also use the man command to view manual descriptions of commands that support subcommands. To do this, you must prefix all subcommands with the name of the command. For example, to view a description of the dbx alias subcommand, you would enter: man dbxalias The same applies for the pdbx subcommands. For example, enter: man pdbxcont to display information about the cont subcommand. To view an online manual description for the tcsh ls-F built-in command, you must type ls-F without the dash. So, to see the man page you would issue: man lsF To view an online manual description for the tcsh @ (at) built-in command, you must type at with tcsh in front of it. So, to see the man page you would issue: man tcshat Environment variables man uses the following environment variables: MANPATH Contains a list of paths to search for man pages. MANPAGER, PAGER Contains an output filtering command for use when displaying man pages on a terminal. If you are running in a double-byte locale, verify that this variable is set to a command which supports double-byte characters, such as the more command. 438 z/OS V1R12.0 UNIX System Services Command Reference man TMPDIR Identifies the directory where temporary files reside. Localization man uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Files man uses the following files: /usr/man/%L/man¬0–9|/*.book BookManager® book files containing man pages. /var/man/%L/entry.¬0–9|/*.bookname Cached man pages extracted from book files. /usr/man/%L/cat¬0–9|/ * .¬0–9| Subdirectories containing formatted help files. /usr/man/%L/whatis Database used by –k option. Exit values 0 Successful completion 1 Failure due to any of the following: v Unknown command-line option v Missing path after an –M option v No information available on the desired subject v Unable to create a child process to format man page v Child process returned with nonzero exit status Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. The elements of the environment variable MANPATH are separated by colons. The –M option, the –x option, the –w option, the MANPAGER environment variable, the default pager, and the ability to specify section on the command line are all extensions to the POSIX standard. Related information help, more mesg — Allow or refuse messages Format mesg [y] [n] Chapter 2. Shell command descriptions 439 mesg Description mesg determines whether other users can send messages to your terminal with talk, write, or similar utilities. Options y Specifies that other people can send you messages. n Specifies that other people cannot send you messages. Examples 1. To let other people send you messages, issue: mesg y 2. To tell the system not to let other people send you messages, issue: mesg n 3. To display the current setting without changing it, issue: mesg The terminal is determined by the first of standard input, output, or error which is directed to a terminal. Localization mesg uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Receiving messages is currently allowed 1 Receiving messages is not currently allowed 2 Failure due to any of the following: v Unknown command-line option v Unknown argument v An error accessing the terminal Portability POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems. Related information talk, write mkcatdefs — Preprocess a message source file Format mkcatdefs [–h] MsgFile [SourceFile ... ] 440 z/OS V1R12.0 UNIX System Services Command Reference mkcatdefs Description mkcatdefs preprocesses a message source file for input to the gencat utility. | | SourceFile is a message file (usually with a .msf extension) containing symbolic identifiers. If you do not specify a SourceFile, mkcatdefs reads from the standard input (stdin). mkcatdefs produces two outputs: v MsgFile.h, which contains statements that equate your symbolic identifiers with set numbers and message numbers that mkcatdefs assigns. You must include this header file in your application in order to refer to the messages. v Message source data, with numbers instead of symbolic identifiers, is sent to standard output. This output is suitable as input to the gencat utility. You should either save standard output to a file using redirection, or pipe the output of mkcatdefs to the gencat utility. Options –h Suppresses the generation of a MsgFile.h file. This flag must be the first argument to mkcatdefs. Extended description The format of SourceFile is defined as follows: The fields of a message source line must begin in column 1 and are separated by a single blank character. Any other blank characters are considered as part of the subsequent field. $quote See gencat. $set symbolic_name The symbolic_name denotes the set identifier that will be used in an application program to reference this set of messages. This name can be up to 255 characters long and can contain any alphanumeric character and the underscore character, but must begin with a non-numeric character. Any string following the set identifier is treated as a comment. $ comment See gencat. Symbolic_Name message_text The Symbolic_Name denotes a message identifier that will be used in an application program to reference this message. This name can be up to 255 characters long and can contain any alphanumeric character and the underscore character, but must begin with a non-numeric character. There must be a single blank character separating the symbolic_name from the message_text. If no quote character is defined, then any blank characters after the separating blank character are considered part of the message text. See gencat for more information about how to specify message_text. Examples To process the comp1.msf and comp2.msf message source files and put the output into the comp.msg file, enter: mkcatdefs comp comp1.msf comp2.msf >comp.msg The source message file looks similar to the following: $ This is the message source file for COMP1 $ $quote " Use double quotation marks to delimit message text Chapter 2. Shell command descriptions 441 mkcatdefs $set MSFAC1 Message set for component comp1 $ SYM_FORM "Symbolic identifiers can only contain alphanumeric \ characters or the _ (underscore character)\n" SYM_LEN "Symbolic identifiers cannot be more than 65 characters long\n" 5 "You can mix symbolic identifiers and numbers\n" The generated comp.h file looks similar to the following: #ifdef _H_COMP_MSG #include <limits.h> #include <nl_types.h> /* Time stamp: 1994 137 19:09 UTC */ /* The following was generated from comp1.msf. */ /* definitions for set MSFAC1 */ /* The following was generated from comp2.msf. */ /* definitions for set MSFAC2 */ #endif mkcatdef creates the comp.msg message catalog source file for gencat with numbers assigned to the symbolic identifiers: $timestamp 1994 137 19:09 UTC $quote " Use double quotation marks to delimit message text $delset 1 $set 1 1 "Symbolic identifiers can only contain alphanumeric \ characters or the _ (underscore character)\n" 2 "Symbolic identifiers cannot be more than 65 characters long\n" 5 "You can mix symbolic identifiers and numbers\n" The assigned message numbers are noncontiguous because the source file contained a specific number. mkcatdefs always assigns the previous number plus 1 to a symbolic identifier. Restriction: mkcatdefs inserts a $delset command before a $set command in the output message source file. This means you cannot add, delete, or replace single messages in an existing catalog when piping to the gencat utility. You must enter all messages in the set. mkdir — Make a directory Format mkdir [–p] [–m mode] directory ... Description The mkdir command creates a new directory for each named directory argument. The mode for a directory created by mkdir is determined by taking the initial mode setting of 777 (a=rwx) or the value of –m if specified and applying the umask value to it. Options –m mode Lets you specify permissions for the directories. The mode argument can have the same value as the mode for chmod; see chmod for more details. 442 z/OS V1R12.0 UNIX System Services Command Reference mkdir You can also set the sticky bit on for directories. For more information, see chmod. The umask value is applied to the mode value to determine the new directory's actual mode setting. Note: A superuser or the file owner can use a chmod command or chmod() function to change two options for an executable file. The options are set in two file mode bits: v Set-user-ID (S_ISUID) with the setuid option v Set-group-ID (S_ISGID) with the setgid option If one or both of these bits are on, the effective UID, effective GID, or both, plus the saved UID, saved GID, or both, for the process running the program are changed to the owning UID, GID, or both, for the file. This change temporarily gives the process running the program access to data the file owner or group can access. In a new file, both bits are set off. Also, if the owning UID or GID of a file is changed or if the file is written in, the bits are turned off. In shell scripts, these bits are ignored. If the RACF profile named FILE.GROUPOWNER.SETGID exists in the UNIXPRIV class, then the set-group-ID bit for a directory determines how the group owner is initialized for new objects created within the directory: v If the set-gid bit is on, then the owning GID is set to that of the directory. v If the set-gid bit is off, then the owning GID is set to the effective GID of the process. Creates intermediate directory components that don't already exist. For example, if one of the directory arguments is dir/subdir/subsub and subdir doesn't already exist, mkdir creates it. Such intermediate directories are created with mode bits determined in the following way: Take a default mode setting of 777 (a=rwx), apply the process's setting to it, and then turn on the user write and user execute permissions (u+wx). The –m mode specification on the command line is not used for computing the mode of intermediate directories. –p Localization mkdir uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Missing mode after –m v Incorrect mode v Incorrect command-line option Chapter 2. Shell command descriptions 443 mkdir v Missing directory name v Inability to create the directory Messages Possible error messages include: Path not found The preceding structure (parent directory) of the named directory does not exist. Access denied The requested directory already exists or is otherwise inaccessible. Cannot create directory Some other error occurred during creation of the directory. Portability POSIX.2, X/Open Portability Guide, UNIX systems. Related information rm, rmdir, mkfifo — Make a FIFO special file Format mkfifo [–m mode] file [–p] Description mkfifo creates one or more FIFO special files with the given names. Options –m mode Lets you specify file permissions for the files. The mode argument can have the same value as the mode argument for chmod; see chmod for more details. –p Creates intermediate directory components that do not already exist. For example, if one of the file arguments is dir/subdir/file and if subdir does not exist already, this option creates it. Such intermediate directories are created with mode bits determined in the following way: Take a default mode setting 777 (a=rwx), apply the umask setting of the process to it, and then turn on user read, write, and user execute permissions (u+rwx). The –m mode specification on the command line is not used for computing the mode of intermediate directories. The resulting mode settings permit the file owner to access the new files without concern for any umask setting that may be in place. Localization mkfifo uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES 444 z/OS V1R12.0 UNIX System Services Command Reference mkfifo v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v A missing mode after –m v An incorrect mode: v An incorrect command-line option v A missing filename v Inability to create the desired file Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –p option is an extension of the POSIX standard. Related information chmod, create, mkdir mknod — Make a FIFO or character special file Format mknod pathname [b c] major minor mknod pathname p Description mknod creates a FIFO special file or a character special file with the given path name. It is located in the directory /usr/sbin. Operands b Indicates block special files. b is accepted for compatibility with other UNIX implementations. Restriction: Block special files are not supported on z/OS. c Indicates character special files (for example, terminals and other devices). c can only be used by a superuser. major minor major gives the major device type; minor, the minor device type. You can specify device types in decimal, hexadecimal, or octal. mknod differentiates between octal and decimal as follows: v Any number that starts with 0 but not 0x is octal. v Any number that starts with 0x is hexadecimal. v Any number that does not start with 0x or 0 is decimal. p Creates a FIFO special file (that is, a named pipe). Chapter 2. Shell command descriptions 445 mknod Localization mknod uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v Inability to create the desired file v Incorrect major or minor number 2 Failure due to any of the following: v Too few command-line arguments v A missing major or minor device number Portability UNIX systems. Within POSIX, mknod has been superseded by mkfifo for pipes. The POSIX family of standards has not yet designed an alternative to mknod for special files. Related information mkfifo more — Display files on a page-by-page basis Format more [–ceiSsU] [–A|–u] [–n number] [–P prompt] [–p command] [–t tag] [file ...] more [–ceiSsU] [–A|–u] [–n number] [–P prompt] [–t tag] [+command] [file ...] Description more displays files one page at a time. It obtains the number of lines per page from the environment or from the –n option. If standard output (stdout) is not a terminal device, the number of lines per page is infinite. more displays the files specified by file ... (that is, a list of filenames) one at a time. When more finishes displaying one file, it begins displaying the next one in the list. If you give – as one of the filenames, more reads the standard input at that point in the sequence. more allows paging forwards and backwards (if possible) and searching for strings. Options –A 446 Displays all characters, including unprintable ones. Typically, unprintable characters are displayed in a format which is printable, such as octal. However, with –A, the actual glyph (graphical character) is displayed. z/OS V1R12.0 UNIX System Services Command Reference more Also, by using this option, ANSI escape sequences for display modes are processed. This option cannot be used with –u. Note: The character in the top left corner of the screen is always displayed in normal mode. –c Displays one page at a time starting at the top of the screen, and clears the screen before displaying a new file. more may ignore this option if the terminal doesn't support such operations. –e Exits immediately after displaying the last line of the last file. Typically, if stdout is a terminal device, more stops after displaying the last line of the last file and prompts for a new command. If the command that displays text causes more to reach the end of the file again, more exits. –i Ignores case during searches. –n number Specifies the number of lines per page. This overrides any values obtained from the environment. Use this option when you need to override the curses screen length or LINES setting to work with your terminal. This option will give incorrect results if used while in the OMVS shell (or another dumb terminal) and specifying number to be something other than the current number of screen lines. –P string Sets the prompt that appears at end of each page of text to string. The default prompt is [filename]. more typically displays the prompt in standout mode. –p command Initially executes the more command on each file. If it executes successfully and command is a positioning command such as a line number or a regular expression search, more displays the resulting page; otherwise more displays the first page of the file. If both the –t and –p options are specified, the –t option is processed first. +command Initially executes the more command on each file. If it executes successfully and command is a positioning command such as a line number or a regular expression search, more displays the resulting page; otherwise more displays the first page of the file. If both the –t and –p options are specified, the –t option is processed first. –S Displays the prompt in normal mode rather than standout (reverse video) mode. –s Replaces consecutive empty lines with a single empty line. –t tag Searches for the named tag and displays the page of text containing it. See ctags for more information. –U Allows more to refresh the display screen for each new line. –u Displays all backspaces as ^H. Typically, characterbackspace_(underscore) displays character as underlined and characterbackspacecharacter Chapter 2. Shell command descriptions 447 more Interactive commands more also supports the following interactive commands. [n]b [n]Ctrl-B [n]PgUp Moves backward n lines, with a default of one page. If n is more than the page size, more displays only the final page. [n]d [n]Ctrl-D Scrolls forward n lines, with a default of one half of the page size. If you specify n, it becomes the new default for subsequent d and u commands. [n]f [n]Ctrl-F [n]PgDn Moves forward n lines, with a default of one page. At end-of-file, more continues with the next file in the list, or exits if the current file is the last one in the list. [n]G Goes to the nth line in the file. If you do not specify n, more advances to the end of the file. [n]g Goes to the nth line in the file, with the default being the first line of the file. h Displays a summary of interactive commands. [n]j [n]SPACE [n]ENTER [n]↓ Scrolls forward n lines, with a default of one line for j, ENTER and ↓, and a default of one page for SPACE. This command displays the entire n lines even if n is more than the page size. At end-of-file, these commands cause more to begin displaying the next file in the list, or to exit if the current file is the last one in the list. [n]k [n]↑ Scrolls backward n lines, with a default of one line. This command displays the entire n lines even if n is more than the page size. mletter Marks the current position with the lowercase letter. When you view a new file, all previous marks are lost. [n]N Repeats the previous search, but in the opposite direction. If you specify n, more repeats the search n times. [n]n Repeats the previous search. If you specify n, more repeats the search n times. For example if there are eight occurrences of pattern in the file and /pattern found the second occurrence then a follow-up command of 5n finds and sets the current position to the 7th occurrence of pattern. q Exits more. :q ZZ 448 R Refreshes the screen and discards any buffered input. r Ctrl-L Refreshes the screen. [n]s Skips forward n lines (with a default of one line) and displays one page beginning at that point. If n would cause less than one page to be displayed, more displays the last page in the file. [n]u [n]Ctrl-U Scrolls backward n lines, with a default of one half of the page size. If you specify n, it becomes the new default for subsequent d and u commands. v Invokes an editor to edit the current file. more uses the editor named by the environment variable EDITOR. The default editor is vi. 'letter Returns to the position marked with letter. '' Returns to the position from which you last issued a movement command of greater than one page or the beginning of the file if you have issued no such commands. Note: '' indicates two single quotes, not one double quote. [n]/[!]pattern Searches forward in the file for the nth line containing pattern. n defaults to one if not specified. If pattern is the null regular expression (/) more uses the previous pattern. If the character ! precedes pattern, more searches for lines that do not contain pattern. z/OS V1R12.0 UNIX System Services Command Reference more [n]?[!]pattern Searches backward in the file for the nth line containing pattern. The search begins at the line immediately before the top line displayed. n defaults to one if not specified. If pattern is the null regular expression (?), more uses the previous pattern. If the character ! precedes pattern, more searches for lines that do not contain pattern. :e [filename]newline Stops viewing the current file and views filename instead. If you do not specify filename, more returns to the beginning of the current file. If filename is #, more returns to the last file viewed before the current one. [n]:n Views the next file from the list given on the command line. If you specify n, more views the nth next file from the list. [n]:p Views the previous file from the list given in the command line. If you specify n, more views the nth previous file from the list. :t tagname Goes to tagname. :w filename Writes the contents of the current file to the file filename. !<shell command> Escape to shell and execute shell command. = Displays, where possible, the name of the file currently being viewed, its number (relative to the total number of files specified in the command line), the current line number, the current byte number, the total bytes to display and what percentage of the file has been displayed. Ctrl-G Displays, where possible, the name of the file currently being viewed, its number (relative to the total number of files specified in the command line), the current line number, the current byte number, the total bytes to display and what percentage of the file has been displayed. Home Goes to the first line in the file. End Goes to the last line in the file. Environment variables more uses the following environment variables: COLUMNS Contains the maximum number of columns to display on one line. EDITOR Contains the name of the editor that the v command invokes. LINES Contains the number of lines in a page. This value takes precedence over value from TERM. However, the –n value takes precedence over the LINES value. MORE Contains a list of options as they would appear on the command line. This variable takes preference over the TERM and LINES variables. TERM Contains the name of the terminal type. Usage note more is designed for raw-mode terminals. It can be used with 3270 terminals with certain restrictions. Line-mode terminals require a user to press Enter to allow the keys typed to be processed. However, the Enter key has a special meaning to more. Specifically, it causes more to scroll down a single line. Therefore, when attempting to use more while in line-mode, each time a user presses "Enter" to process any command, this causes the screen to scroll down a single line at a time. Localization more uses the following localization environment variables: v LANG Chapter 2. Shell command descriptions 449 more v v v v LC_ALL LC_MESSAGES LC_SYNTAX NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion >0 Failure due to any of the following: v filename not a text file v –n option too large v Syntax error in regular expression v Inability to create a file v Inability to open input file v Insufficient memory v Incorrect command v Inability to access the terminal v Missing string after -p option Portability POSIX.2 User Portability Extension, UNIX systems. The –A, –P, and –S options and the :w and ! commands are extensions of the POSIX standard. The Home, End, PgDn, PgUp, ↓, and ↑ commands are extensions to traditional implementations of more, available only on terminal types which support these keys. Related information cat, vi mount — Logically mount a file system Format mount [–t fstype] [–rv] [–a yes|include,sysname1,... sysnameN |exclude,|no|unmount] [–o fsoptions] [–d destsys] [–s nosecurity|nosetuid] –f fsname pathname[-wn] mount –q [–d destsys][–v] pathname File tag specific option: mount [–c ccsid,text|notext] Description The mount shell command, located in /usr/sbin, is used to mount a file system or list all mounts over a file system. Rule: You must have mount authority before you can issue the mount command. See the section on mount authority in z/OS UNIX System Services Planning. | | 450 z/OS V1R12.0 UNIX System Services Command Reference mount Options –a yes|include,sysname1,...,sysnameN|exclude,sysname1,...,sysnameN|no|unmount The -a option specifies the AUTOMOVE attribute of the file system in a sysplex environment where systems are exploiting the shared file system capability. –a yes allows the system to automatically move logical ownership for a specified file system as needed. This is the default. –a no prevents ownership movement in some situations. –a unmount unmounts the file system in some situations. –a include,sysname1,...,sysnameN specifies a list of systems, in priority order, to which the file system's ownership can be moved. include can be abbreviated to i. –a exclude,sysname1,...,sysnameN specifies a list of systems, in priority order, to which the file system's ownership cannot be moved. exclude can be abbreviated to e. See z/OS UNIX System Services Planning for details about the behavior of the AUTOMOVE options. –d destsys Specifies the name of the system in a shared file system environment that will be the logical owner of the mount. Note, if –q is specified, the mount –q output will only list mounts that are owned by destsys. | | –f fsname Names the file system to be mounted. All file system names must be unique. File system names are case sensitive. However, if the file system type is HFS, or if the type was not specified on the command and the file system is zFS, fsname is translated to uppercase. The file system name has a maximum length of 44 characters; any additional characters are truncated. Options –q and –f are mutually exclusive, but one must be specified. -wn Specifies the amount of time the mount will wait in seconds for async mounts to complete. If n is specified as a 0 the wait will be indefinite. This option flag is tolerated on any form of the mount command and is ignored if not appropriate (no wait needs to be done). –o fsoptions Specifies an option string to be passed to the file system type. NFS, for example, uses this to identify the remote server and the object on that server. The format and content are specified by the physical file system that is to perform the logical mount. You can specify lowercase or uppercase characters. Enclose the string in single quotes. Refer to the following for the appropriate file system-specific options to specify for fsoptions: v For HFS-specific options, see the BPXPRMxx section in z/OS MVS Initialization and Tuning Reference. v For zFS-specific options, see Mount, in z/OS Distributed File Service zSeries File System Administration. v For NFS-specific options, see Mount processing parameters, in z/OS Network File System Guide and Reference. v For TFS-specific options, see Mounting the TFS, in z/OS UNIX System Services Planning. –q Prints a list of path names for the mount points of file systems mounted Chapter 2. Shell command descriptions 451 mount over a another file system, including that system. Options –q and –f are mutually exclusive, but one must be specified. If –v is not specified, only path names for mount points are printed. Note that the output of mount –q can be used by the unmount utility as input. See “Examples.” Specifies mounting a file system read-only. –r –s nosecurity|nosetuid Specifies that a file system is unsecured. Setuid, setgid, APF and program controlled attributes are ignored when you use nosetuid. To additionally disable authorization checking, use nosecurity. Minimum unique abbreviations can be used for the option arguments. Note: When a file system is mounted with the NOSECURITY option enabled, any new files or directories that are created are assigned an owner of UID 0, no matter what UID issued the request. –t fstype Identifies the file system type. fstype may be entered in mixed case but will be treated as upper case. If this option is not specified, the default is –t HFS. Verbose output. Includes additional information, if available, on output. If –v is specified on the mount command and the mount fails, the file system name that had the mount failure will be included in the failure information. –v pathname specifies the path name for the mount point. File tag specific option –c ccsid,text|notext Specifies the file tag that will be implicitly set for untagged files in the mounted file system. ccsid Identifies the coded character set identifier to be implicitly set for the untagged file. ccsid is specified as a decimal value from 0 to 65535. However, when text is specified, the value must be between 0 and 65535. Other than this, the value is not checked as being valid and the corresponding code page is not checked as being installed. For more information about file tagging, see z/OS UNIX System Services Planning. text Specifies that each untagged file is implicitly marked as containing pure text data that can be converted. notext Specifies that none of the untagged files in the file system are automatically converted during file reading and writing. Examples 1. The output of mount –q can be used for the input of unmount. For example: mount -q /ict/hfsfir can be used as input: unmount $(mount -q /ict/hfsdir) 452 z/OS V1R12.0 UNIX System Services Command Reference mount 2. To mount an HFS file system over /u/wjs with a sync interval of 120 seconds: mount -f omvs.hfs.user.wjs -o ’SYNC(120)’ /u/wjs 3. To display a list of path names for all mount points under /u: mount -q /u Usage notes 1. Systems exploiting shared file system will have I/O to an OMVS couple data set. Because of these I/O operations to the CDS, each mount request requires additional system overhead. You will need to consider the affect that this will have on your recovery time if a large number of mounts are required on any system participating in shared file system. 2. The –a unmount is not available to automounted file systems. 3. The –a no specification will only be accepted on z/OS V1R3 systems and later. File system recovery and mount File system recovery in a shared file system environment takes into consideration file system specifications such as –a yes|no|unmount and whether or not the file system is mounted read-only or read/write. Generally, when an owning system fails, ownership over its –a yes mounted file system is moved to another system and the file is usable. However, if a file system is mounted read/write and the owning system fails, then all file system operations for files in that file system will fail. This is because data integrity is lost when the file system owner fails. All files should be closed (BPX1CLO) and reopened (BPX1OPN) when the file system is recovered. (The BPX1CLO and BPX1OPN callable services are discussed in z/OS UNIX System Services Programming: Assembler Callable Services Reference.) For file systems that are mounted read-only, specific I/O operations that were in progress at the time the file system owner failed may need to be submitted again. Otherwise, the file system is usable. In some situations, even though a file system is mounted with the –a yes option, ownership of the file system may not be immediately moved to another system. This may occur, for example, when a physical I/O path from another system to the volume where the file system resides is not available. As a result, the file system becomes "unowned" (the system will issue message BPXF213E when this occurs). This is true if the file system is mounted either read/write or read-only. The file system still exists in the file system hierarchy so that any dependent file systems that are owned by another system are still usable. However, all file operations for the unowned file system will fail until a new owner is established. The shared file system support will continue to attempt recovery of –a yes mounted file systems on all systems in the sysplex that are enabled for shared file system. Should a subsequent recovery attempt succeed, the file system transitions from the unowned to the active state. Applications using files in unowned file systems will need to close (BPX1CLO) those files and re-open (BPX1OPN) them after the file system is recovered. File systems that are mounted with the –a no option will become unowned when the file system owner exits the sysplex. The file system will remain unowned until Chapter 2. Shell command descriptions 453 mount the original owning system restarts or until the unowned file system is unmounted. Note that since the file system still exists in the file system hierarchy, the file system mount point is still in use. An unowned file system is a mounted file system that does not have an owner. The file system still exists in the file system hierarchy. As such, you can recover or unmount an unowned file system. File systems associated with a 'never move' PFS will be unmounted during dead system recovery. For example, TFS is a 'never move' PFS and will be unmounted, as well as any file systems mounted on it, when the owning system leaves the sysplex. As stated in “Usage notes” on page 453, –a unmount is not available to automounted file systems. However, during dead system recovery processing for an automounted file system (whose owner is the dead system), the file system will be unmounted if it is not being referenced by any other system in the sysplex. For more information about mounts and the AUTOMOVE and NOAUTOMOVE parameters, see “mount — Logically mount a file system” on page 450. Exit values 0 Successful completion Related information chmount, unmount mv — Rename or move a file or directory Format mv [–fiMUv] [–F format|B|T|X] [–P params] [-W seqparms=params] [–Z] [[–O u | c=codeset] file1 file2 mv [–ACfiMUv] [–F format|B|T|X] [–S suffix] [–Z] [–O u | c=codeset] file ... directory mv –Rr [–fi] [–Z] [–O u | c=codeset] directory1 directory2 Description mv renames files or moves them to a different directory. If you specify multiple files, the target (that is, the last path name on the command line) must be a directory. mv moves the files into that directory and gives them names that match the final components of the source path names. When you specify a single source file and the target is not a directory, mv moves the source to the new name, by a simple rename if possible. You can also use mv to move files to and from MVS data sets. If you specify more than one file to be moved, the target (last path name on command line) must be either a directory or a partitioned data set. If the target is an MVS partitioned data set, the source cannot be a UNIX directory. 454 z/OS V1R12.0 UNIX System Services Command Reference mv | | mv does not support the moving to or from generation data groups (GDGs). To use those MVS data sets, user must specify the real data set name. mv also does not support copying to a temporary PDSE. When moving records, the string " \n" is moved the same way as the string "\n": both are read back as "\n", where "\n" indicates that z/OS XL C++ will write a record containing a single blank to the file (the default behavior of z/OS XL C/C++). All other blanks in your output are read back as blanks, and any empty (zero-length) records are ignored on input. However, if the environment variable _EDC_ZERO_RECLEN is set to Y before calling mv, an empty record is treated as a single newline and is not ignored. Also, if _EDC_ZERO_RECLEN is set to Y, a single newline is written to the file as an empty record, and a single blank will be represented by " \n". A file can be moved by any user who has write permission to the directory containing the file, unless that directory has its sticky bit turned on. If the file is in a directory whose sticky bit is turned on, only the file owner or a superuser can move the file. You can move: v One file to another file in the working directory v One file to a new file on another directory v A set of directories and files to another place in your file system v A UNIX file to an MVS data set v An MVS data set to a file system v An MVS data set to an MVS data set Options –A Specifies that all suffixes (from the first period till the end of the target) be truncated. –A has precedence over –M and –C options. –S will be turned off if –A is the last option specified. –B Specifies that the data to be moved contains binary data. When you specify –B, mv operates without any consideration for <newline> characters or special characteristics of DBCS data (this type of behavior is typical when moving across a UNIX system). –B is mutually exclusive with –F, –X, and –T. You will get an error if you specify more than one of these options. –C Specifies truncating the file names to 8 characters to meet the restriction in the MVS data set member. –F format Specifies whether the file is to be treated as binary, text, or record file format when moved; for text files, specifies the end-of-line delimiter. Also sets the file format to format only if the source is an MVS data set and the target is a UNIX file. Only cp sets the file format for UNIX to UNIX operations. For text files, when moving from UNIX to MVS, the end-of-line delimiter will be stripped. When moving from MVS to UNIX, the end-of-line delimiter will be added. (Code page IBM-1047 is used to check for end-of-line delimiters). Record file formats are treated as if they were binary files. –F is mutually exclusive with –B, –X, and –T. If you specify one of these options with –F, you will get an error. If –F is specified more than once, the last –F specified will be used. For format, you can specify: not Not specified Chapter 2. Shell command descriptions 455 mv bin rec Or the nl cr lf crlf lfcr crnl Binary data Record. (File data consists of records with prefixes. The record prefix contains the length of the record that follows. From the shell command perspective, files with this format will be treated as if they were binary files.) following text data delimiters: Newline character Carriage return Line feed Carriage return followed by line feed Line feed followed by carriage return Carriage return followed by a new line character –f Does not ask if you want to overwrite an existing UNIX destination file; it automatically behaves as if you answered yes. If you specify both –f and –i, mv uses the option that appears last on the command line. –i When moving to a UNIX target, always prompts before overwriting an existing file, but does not overwrite the file if you do not have permission. If you specify both –f and –i, mv uses the option that appears last on the command line. –M Specifies that some characters of the file name are translated when moving between a UNIX file and a data set member. Characters are translated as follows: v _ (underscore) in UNIX is translated to @ in MVS dataset members and vice versa. v . (period) in UNIX is translated to # in MVS dataset members and vice versa. v – (dash) in UNIX is translated to $ in MVS dataset members and vice versa. –P params Specifies the parameters needed to create a sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format that the fopen() function uses. SPACE=(units,(primary,secondary) where the following values are supported for units: v Any positive integer indicating BLKSIZE v CYL (mixed case) v TRK (mixed case). For example: SPACE=(500,(100,500)) units, primary, secondary SPACE=(500,100) units and primary only For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide. Notes: 1. The fopen() argument LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. 2. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. 3. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets. 456 z/OS V1R12.0 UNIX System Services Command Reference mv –R (UNIX to UNIX only) Moves a directory and all its contents (files, subdirectories, files in subdirectories, and so on). For example: mv –R dir1 dir2 moves the entire contents of dir1 to dir2/dir1. mv creates any directories that it needs. –r (UNIX to UNIX only) Is identical to –R. –S d=suffix|a=suffix v d=suffix Removes the specified suffix from a file. v a=suffix Appends the specified suffix to a file. –S has precedence over –M and –C. It also turns off the –A option (if –S is the last specified option). –T Specifies that the data to be moved contains text data. See “Usage notes” on page 464 for details on how to treat text data. This option looks for IBM-1047 end-of-line delimiters, and is mutually exclusive with –F, –X, and –B. You will get an error if you specify more than one of these options. Note: –T is ignored when moving across UNIX file systems. –U Keeps file names in uppercase when moving from MVS data set members to UNIX files. The default is to make file names lowercase. –v Verbose -W seqparms=params Specifies the parameters needed to create a sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format that the fopen() function uses. SPACE=(units,(primary,secondary) where the following values are supported for units: v Any positive integer indicating BLKSIZE v CYL (mixed case) v TRK (mixed case). For example: SPACE=(500,(100,500)) units, primary, secondary SPACE=(500,100) units and primary only For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide. Note: The fopen() arguments: LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets. This option is the same as -P params. –X Specifies that the data to be moved is an executable. Cannot be used in conjunction with –F, –T, or –B. -Z Specifies that error messages are not to be displayed when setting ACLs on the target. The return code will be zero. mv will try to preserve the ACLs, Chapter 2. Shell command descriptions 457 mv if possible. The ACLs are not preserved if a file system does not support ACLs, or if you are moving files to MVS Note: If you do not specify –F|B|T or X, mv will first check the format of the MVS data set indicated and then try to determine the type of file. Automatic conversion and file tag specific options –Z Suppresses failure when setting the file tag by default or on empty untagged files. For a description of the default behavior, see “Automatic conversion and file tagging behavior for mv.” –O u | c=codeset Allow automatic conversion on source and target files. –O u If the target exists and is not empty or already tagged, mv will not change the target's tag in order for the target to be a candidate for automatic conversion. For new targets and existing, untagged, empty files, this option has no effect and mv behaves the same as the default. For a description of the default behavior, see “Automatic conversion and file tagging behavior for mv.” When using mv to move from a UNIX file to an MVS data set, if the source is a tagged text file, then it might be a candidate for automatic conversion. When using mv to move executables from or to MVS, automatic conversion is disabled for both source and target. –O c=codeset For a detailed description of the behavior of this option on mv, see “Automatic conversion and file tagging behavior for mv.” To prevent the corruption of text files, mv will fail if it cannot set the tag to text or code set. If automatic conversion is not set properly or the source is not tagged properly, the target might end up with a tag code set that does not match the file content. Automatic conversion and file tagging behavior for mv The following tables describe the behavior of file tagging and automatic conversion for various source and target scenarios depending on whether the –O option is specified on the mv command. 458 z/OS V1R12.0 UNIX System Services Command Reference mv Table 16. Automatic conversion and file tagging behavior: Moving UNIX files to UNIX files Default (without -O option) If the target file system supports setting file tags... File tagging Target file is tagged the same as the source file. If the target file system does not support setting file tags (such as NFS)... With -O c=codeset With -O u option option Target's tag is unchanged. v An existing target's tag is unchanged. v A new target is created with a tag according to the file system's attributes (MOUNT parm can specify TAG). Automatic Disabled for conversion source and target files The source or target file is a candidate for automatic conversion when its txtflag is tagged TEXT. Target's txtflag is set to TEXT and its code set is set to codeset. Allowed for source and target files Table 17. Automatic conversion and file tagging behavior: Moving MVS data sets to UNIX files Default (without -O option) If the target file system supports setting file tags... If the target file system does not support setting file tags (such as NFS)... With -O c=codeset With -O u option option If the SOURCE is text: File tagging Target is set to UNTAG Target's tag is unchanged v An existing target's tag is unchanged. v A new target is created with a tag according to the file system's attributes (MOUNT parm can specify TAG). Automatic Disabled for conversion target file Target's txtflag is set to TEXT and its code set is set to codeset. Allowed for target file Note: The target file is a candidate for automatic conversion when its txtflag is tagged TEXT. If the SOURCE is binary or executable: File tagging Target is set to UNTAG Target's tag is unchanged Target's txtflag is set to BINARY and its code set is set to codeset. Chapter 2. Shell command descriptions 459 mv Table 17. Automatic conversion and file tagging behavior: Moving MVS data sets to UNIX files (continued) Default (without -O option) If the target file system supports setting file tags... If the target file system does not support setting file tags (such as NFS)... With -O c=codeset With -O u option option Disabled for target file Automatic conversion Table 18. Automatic conversion and file tagging behavior: Moving UNIX files to MVS data sets Default (without -O option) With -O u option With -O c=codeset option If the SOURCE is text or binary: File tagging Not applicable for target data set Automatic Disabled for source file conversion Allowed for source file Disabled for source file Note: The source file is a candidate for automatic conversion when its txtflag is tagged TEXT. If the SOURCE is executable: File tagging Not applicable for target data set Automatic conversion Disabled for source file Limits and requirements General requirements are as follows: 1. To specify an MVS data set name, precede the name with double slashes (//). For example, to specify the fully qualified data set names 'turbo.gammalib' and 'turbo.gammalib(pgm1)', you write: "//’turbo.gammalib’" "//’turbo.gammalib(pgm1)’" The same goes for data set names that are not fully qualified: //turbo 2. For PDS (partitioned data set) or PDSE (partitioned data set extended), to avoid parsing by the shell, the name should be quoted or minimally, the parenthesis should be escaped. For example, to specify 'turbo(pgm1)', you can use quotes: "//turbo(pgm1)" or escape the parenthesis: //turbo\(pgm1\) As indicated, a fully qualified name must be single-quoted (as is done within TSO). To prevent the single quotes from being interpreted by the shell, they must be escaped or the name must be placed within regular quotation marks. See the 'turbo.gammalib' examples. 460 z/OS V1R12.0 UNIX System Services Command Reference mv 3. If you specify a UNIX file as source and the MVS data set (target) does not exist, a sequential data set will be created. If the partitioned data set exists, the UNIX file will be moved to the partitioned data set member. 4. If source is an MVS data set and target is a UNIX directory, the UNIX directory must exist. 5. You cannot have a UNIX directory, partitioned data set, or sequential data set as source if the target is a partitioned data set. 6. To move all members from a partitioned data set, you can specify the partitioned data set as source and a UNIX directory as target. MVS data set naming limitations are as follows: v Data set names can only contain uppercase alphabetic characters (A-Z). Lowercase characters will be converted to uppercase during any moves to MVS data sets. v Data set names can contain numeric characters 0–9 and special characters @, #, and $. v Data set names cannot begin with a numeric character. v A data set member name cannot be more than 8 characters. If a file name is longer than 8 characters or uses characters that are not allowed in an MVS data set name, the file is not moved. You can use the –C option to truncate names to 8 characters. Limitations: UNIX to MVS data set. The limitations are as follows: 1. If you specify a sequential MVS data set that is in undefined record format, the file is moved as binary. 2. If you specify a PDSE that is in undefined record format, the first file successfully moved determines in what format files will be moved. Note that PDSE does not allow mixture. So if the first successfully moved file is an executable, the PDSE will have program objects only and all other files will fail. However, if the first file is data, then all files are moved as binary. 3. If you specify a PDS that is in undefined record format, UNIX executables are saved as PDS load modules. All other files are moved as binary. 4. If you specify an MVS data set that is either in variable length or fixed record length and you have not set the file format, text files are moved as text, binaries as binary, and executables as binary. (IBM-1047 end-of-line delimiters are detected in the data) 5. If you set the file format, the set value is used to determine if data is binary, text, or record file format. Limitations: MVS data set to UNIX. The limitations are as follows: 1. If an UNIX file does not exist, one is created using 666 mode value, whether the data to be copied is binary or text: 666 mode value: owner(rw-) group(rw-) other(rw-) If the data to be copied is a shell script or executable residing in a PDS or PDSE with undefined record format, the UNIX file is created using 777 mode value: 777 mode value: owner(rwx) group(rwx) other(rwx) 2. If a UNIX file exists and the file format is set, mv moves the file as that format. Otherwise, v Load modules (PDS) are stored as UNIX executables and program objects (PDSE) are moved since they are the same as executables; Chapter 2. Shell command descriptions 461 mv v Data within data sets of undefined record format are moved as binary if the data is not a program object or load module; v Data found within data sets of fixed length or variable record length are moved as text. (IBM-1047 end-of-line delimiters are detected in the data Limitations: MVS to MVS. The limitations are as follows: 1. Options –A, –C, –f, and –S are ignored. 2. If target and source are in undefined record format (and neither is a sequential data set), mv will attempt to move the data as a load module. If that fails, then mv will move the data as binary. 3. If target and source are in undefined record format and either is a sequential data set, mv moves the data as binary. 4. If the source has a fixed or variable record length and the target is in undefined record format, mv moves the data as binary. 5. If the source is in undefined record format and the target has a fixed or variable record length, mv moves the data as binary. 6. If both source and target are in fixed or variable record length, mv moves the data as text. Limitations: Moving executables into a PDS. The limitations are as follows: 1. A PDS cannot store load modules that incorporate program management features. 2. c89, by default, produces objects using the highest level of program management. 3. If you plan on moving a load module to a PDS, you can use a prelinker which produces output compatible with linkage editor. Linkage editor generated output can always be stored in a PDS. The following table is a quick reference for determining the correct use of options with mv. Table 19. mv Format: File to File and File ... (multiple files) to directory 462 Source/Target Options Allowed Options Ignored UNIX file/UNIX file Ffi ABCMPSTUX UNIX file/Sequential data set BFiPT ACfMSU UNIX file/PDS or PDSE member BFiTX ACfMPSU Sequential data set/UNIX file BFfiTU ACMPS X Sequential data set/sequential data set BFiPT ACfMSU X Sequential data set/PDS or BFiT PDSE member ACfMPSU X PDS or PDSE member/UNIX file BFfiTUX ACMPS PDS or PDSE member/sequential data set BFiPT ACfMSU z/OS V1R12.0 UNIX System Services Command Reference Options Failed X X mv Table 19. mv Format: File to File and File ... (multiple files) to directory (continued) Source/Target Options Allowed Options Ignored PDS or PDSE member/PDS or PDSE member BFiTX ACfMPSU UNIX file/UNIX Directory Fi ABCFMPSTUX PDSE or PDSE member/UNIX Directory ACP BFfiMSTUX UNIX file/Partitioned data ABCFiMSTX set fPU PDS or PDSE member/Partitioned data set BFiTX ACfMPSU UNIX directory/UNIX directory fi ABCFMPSTUX Partitioned data set/UNIX ABCFfiMSTUX directory Options Failed P The tables that follow indicate the kind of moves allowed using mv. Table 20. mv Format: File to File Source Target Allowed UNIX file, sequential data set, or partitioned data set member UNIX file, sequential data set, or partitioned data set member Yes UNIX directory (dir) UNIX directory (dir2 exists) Yes (Results will be found in dir2/dir1/ ..). UNIX directory (dir) UNIX directory (dir2 does not exist) Yes (Results will be found in dir2/...). Partitioned data set UNIX directory (dir). Results Yes in each member of data set are moved to dir. UNIX directory Partitioned data set No Partitioned data set Partitioned data set No UNIX file, UNIX directory, or UNIX directory Partitioned data set member Yes Partitioned data set member Yes Partitioned data set (must exist) Table 21. mv Format: File... (multiple files) to directory Source Target Allowed Any combination of UNIX file or partitioned data set member UNIX directory or partitioned data set Yes Any combination of UNIX directory, partitioned data set, sequential data set Partitioned data set No Sequential data set UNIX directory No Chapter 2. Shell command descriptions 463 mv Table 21. mv Format: File... (multiple files) to directory (continued) Source Target Allowed Any combination of UNIX directory, UNIX file, partitioned data set, partitioned data set member UNIX directory Yes Usage notes For UNIX to MVS: 1. To move from UNIX to a partitioned data set, you must allocate the data set before doing the mv. 2. If an MVS data set does not exist, mv will allocate a new sequential data set of variable record format. 3. For text files, all <newline> characters are stripped during the move. Each line in the file ending with a <newline> character is moved into a record of the MVS data set. If text file format is specified or already exists for the source file, that file format will be used for end-of-line delimiter instead of <newline>. Note that mv looks for IBM-1047 end-of-line delimiters in data. You cannot move a text file to an MVS data set that has an undefined record format: v For an MVS data set in fixed record format, any line moved longer than the record size will cause mv to fail with a displayed error message and error code. If the line is shorter than the record size, the record is padded with blanks. v For an MVS data set in variable record format: Any line moved longer than the largest record size will cause mv to fail with a displayed error message and error code. Record length is set to the length of the line. 4. For binary files, all moved data is preserved: v For an MVS data set in fixed record format, data is cut into chunks of size equal to the record length. Each chunk is put into one record. The last record is padded with blanks. v For an MVS data set in variable record format, data is cut into chunks of size equal to the largest record length. Each chunk is put into one record. The length of the last record is equal to length of the data left. v For an MVS data set in undefined record format, data is cut into chunks of size equal to the block size. Each chunk is put into one record. The length of the last record is equal to the length of the data left. 5. For load modules, the partitioned data set specified must be in undefined record format otherwise the executable will not be moved. 6. If more than one file name is the same, the file is overwritten on each subsequent move. 7. If a UNIX file name contains characters that are not allowed in an MVS data set, it will not be moved. If the UNIX file name has more than 8 characters, it cannot be moved to an MVS data set member. (See the –ACMS options for converting file names.) 8. You are not allowed to move files into data sets with spanned records. 9. PDSE cannot have a mixture of program objects and data members. PDS allows mixing, but it is not recommended. 10. Special files such as external links and FIFO will not be moved to MVS data sets. However, you can move character special files to MVS data sets. 464 z/OS V1R12.0 UNIX System Services Command Reference mv 11. If a file is a symbolic link, mv will move the resolved file, not the link itself. 12. UNIX file attributes are lost when moving to MVS. If you want to preserve file attributes, you should use the pax utility. For MVS to UNIX: 1. If the target UNIX file exists, the new data overwrites the existing data. The mode of the file is unchanged (except the S_ISUID and S_ISGID bits are turned off). 2. If the specified UNIX file does not exist, it will be created using a 666 mode value whether the data is binary or text (this is subject to umask). If the data to be moved is a shell script or executable, the UNIX file will be created with a 777 mode value (also subject to umask). 3. For an MVS data set in variable record format RECFM(VB) or undefined record format RECFM(U), trailing blanks are preserved when moving from MVS to UNIX. For an MVS data set in fixed record format, trailing blanks are not preserved when moving from MVS to UNIX. 4. When you move MVS data sets to text files in the z/OS UNIX file system, a <newline> character is appended to the end of each record. If trailing blanks exist in the record, the <newline> character is appended after the trailing blanks. If the file format option is specified or the target file has the file format set, that file format is used as the end-of-line delimiter instead of a <newline> character. 5. When you move MVS data sets to UNIX binary files, the <newline> character is not appended to the record. 6. You cannot use mv to move data sets with spanned record lengths. 7. Due to an z/OS XL C/C++ run-time restriction, when moving a file from a file system to an MVS sequential data set with the same name and case, you need to prefix the file in the file system with "./". For example: mv ./SMPL.DATA "//’’SMPL.DATA’’" Examples 1. To specify –P params for a nonexisting sequential target: mv -P "RECFM=U,space=(500,100)" file "//’turbo.gammalib’" This mv command is equivalent to: mv -W "seqparms=’RECFM=U,space=(500,100)’" file "//’turbo.gammalib’" 2. To move file f1 to a fully qualified sequential data set ’turbo.gammalib’ and treat it as a binary: mv -F bin f1 "//’turbo.gammalib’" 3. To move all members from a fully qualified PDS ’turbo.gammalib’ to an existing UNIX directory dir: mv "//turbo.gammalib’" dir 4. To drop .c suffixes before moving all files in UNIX directory dir to an existing PDS ’turbo.gammalib’: mv -S d=.c dir/* "//’turbo.gammalib’" Environment variable mv uses the following environment variable when moving records to or from MVS data sets: _EDC_ZERO_RECLEN If set to Y before calling mv, an empty record is treated as a single newline Chapter 2. Shell command descriptions 465 mv character and is not ignored. Also, a single newline is written to the file as an empty record, and a single blank will be represented by "\n". If you do not set this environment variable when moving records, then the string "\n" is moved the same way as the string "\n": both are read and written as "\n", where "\n" indicates that z/OS XL C/C++ will write a record containing a single blank to the file (the default behavior of z/OS XL C/C++). All other blanks in the output are read back as blanks, and any empty (zero-length) records are ignored on input. Localization mv uses the following localization environment variables: v LANG v LC_ALL v LC_COLLATE v LC_CTYPE v LC_MESSAGES v LC_SYNTAX v NLSPATH See Appendix F, “Localization” for more information. Exit values 0 Successful completion 1 Failure due to any of the following: v The argument had a trailing / but was not a directory v Inability to find file v Inability to open input file for reading v Inability to create or open output file for output v Read error on an input file v Write error on an output file v Input and output files identical v Inability to unlink input file v Inability to rename input file v Unrecoverable error when using the –r option, such as: – Inability to access a file – Inability to read a directory – Inability to remove a directory – Inability to create a directory – A target that is not a directory – Source and destination directories identical 2 Failure due to any of the following: v Incorrect command-line option v Too few arguments on the command line v A target that should be a directory but isn't v No space left on target device v Out of memory to hold the data to be moved v Inability to create a directory to hold a target file Messages Possible error messages include: cannot allocate target string mv has no space to hold the name of the target file. Try to free some memory to give mv more space. 466 z/OS V1R12.0 UNIX System Services Command Reference mv filename? You are attempting to move a file, but there is already a file with the target name and the file is read-only. If you really want to write over the existing file, type y and press <Enter>. If you do not want to write over the existing file, type n and press <Enter>. source name and target name are identical The source and the target are actually the same file (for example, because of links). In this case, mv does nothing. unreadable directory name mv cannot read the specified directory—for example, because you do not have appropriate permissions. Portability POSIX.2, X/Open Portability Guide, UNIX systems. The –R and –r options are extensions of the POSIX standard. Related information cp, cpio, rm newgrp — Change to a new group Format newgrp [–l] [group] newgrp [–] [group] tcsh shell: newgrp [-] group Description newgrp lets you change to a new group. You stay logged in and your working directory does not change, but access permissions are calculated according to your new real and effective group IDs. If an error occurs, your session may be ended, and you must log in again. After the group IDs are changed, a new shell is initialized within the existing process, effectively overlaying the current shell from which newgrp was invoked. The new shell is determined from the initial program value of the OMVS segment of your user profile. newgrp does not change the value of exported shell variables, and all others are either set to their default or are unset. If you did not specify any arguments on the command line, newgrp changes to the default group specified for your user ID in the system user database. It also sets the list of supplementary groups to that set in the systems group database. If you specify a group, newgrp changes your real and effective group ID to that group. You are permitted to change to that group only if you are a member of that group, as specified in the system group database. Chapter 2. Shell command descriptions 467 newgrp group can be a group name from the security facility group database, or it can be a numeric group ID. If a numeric group exists as a group name in the group data base, the group ID number associated with that group is used. On systems where the supplementary group list also contains the new effective group ID or where the previous effective group ID was actually in the supplementary group list: v If the supplementary group list also contains the new effective group ID, newgrp changes the effective group ID. v If the supplementary group list does not contain the new effective group ID, newgrp adds it to the list (if there is room). On systems where the supplementary group list does not normally contain the effective group ID or where the old effective group ID was not in the supplementary group list: v If the supplementary group list contains the new effective group ID, newgrp removes it from the list. v If the supplementary group list does not contain the old effective group ID, newgrp adds it to the list (if there is room). newgrp in the tcsh shell newgrp in the tcsh shell, as in the z/OS shell, allows you to change to a new group. Options –l Starts the new shell session as a login session. This implies that it can run any shell profile code. – Is the obsolete version of –l. Localization newgrp uses the following localization environment variables: v LANG v LC_ALL v LC_CTYPE v LC_MESSAGES v NLSPATH See Appendix F, “Localization” for more information. Usage notes newgrp is not supported from an address space running multiple processes because it would cause all processes in the address space to have their security environment changed unexpectedly. If you are using the OMVS interface, you must be using the NOSHAREAS parameter before you issue the newgrp command. Also, if you are running in an environment with the _BPX_SHAREAS environment variable set to YES, you must unset it and start a new shell before issuing newgrp. For example: unset _BPX_SHAREAS; sh Exit values If newgrp succeeds, its exit status is that of the sh">
/
Завантажити
Просто дружнє нагадування. Ви можете переглянути документ прямо тут. Але найголовніше, наш штучний інтелект вже прочитав його. Він може пояснити складні речі простими словами, відповісти на ваші запитання будь-якою мовою та допомогти вам швидко орієнтуватися навіть у найдовших або найскладніших документах.
Публічне посилання оновлено
Публічне посилання на ваш чат було оновлено. You may view and manage your chat links after registration here.
Публічне посилання на документ
Реклама
