c89/cxx — Compile C/C++ source code and create an executable file

c89/cxx [-cEgOsV]
    [-D name[=value]]... [-U name]...
    [-W phase,option[,option]...]...
    [-o outfile]
    [-I directory]... [-L directory]...
    [file.c]... [file.a]...
    [file.o]...[file.x]...
    [-l libname]...

Purpose

The c89 and cxx commands compile and build C/C++ programs. They are the OpenExtensions interface to the IBM C/C++ compilers:
  • c89 can invoke the IBM XL C/C++ for z/VM compiler, the IBM C/C++ for z/VM compiler, or the IBM C for VM/ESA compiler. See usage note 1.
  • cxx invokes the IBM XL C/C++ for z/VM compiler or the IBM C/C++ for z/VM compiler (whichever is installed).
When you issue c89/cxx, the utility passes information about the application program and the compiler options to the compiler for processing. First, c89/cxx performs the compilation phase (including preprocessing) by compiling all operands of the file.c form. The result of each compile step is a file.o file. If all compilations are successful, or if only file.o and no file.c files are specified, c89/cxx proceeds to the module build phase:
  • c89 by default invokes the Program Management binder. However, the C prelinker can be invoked by specifying the -W b,p option.
  • cxx always invokes the Program Management binder.

In the module build phase, c89/cxx combines all file.o files from the compilation phase along with any file.o and file.x operands that were specified. Any file.a and -l libname operands that were specified are also used.

The output of the module build phase is an executable file. For c89/cxx to produce an executable file, you must specify at least one operand of the file.c or file.o form (or corresponding CMS native record file), or at least one operand of the file.a form.

c89/cxx can be invoked from the shell as a utility or from CMS as a CMS command.

For more information on how to manage your C source code, see z/VM: OpenExtensions Advanced Application Programming Tools.

Options

c89/cxx recognizes the following options.
-c
Specifies that only compilations be done. If the source file is a BFS file, the object file is written to the working directory. If the source file is a CMS record file, the object file is written to the A-disk with the name file TEXT.
-D name[=value]
Defines a C/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/cxx automatically defines, see usage note 6. Also, for related information, see usage note 10.
-E
Specifies that C/C++ source produced by the compiler preprocessor phase be copied to stdout. Compilation into object and link-edit are not done. If c89/cxx is invoked from CMS and the original C/C++ source resides in the byte file system, then the generated C/C++ source is placed in the directory in which the original C/C++ source resides. If c89/cxx is invoked from CMS and the original C/C++ source resides on an accessed file mode, then the generated C/C++ source is placed on the user's A-disk.
-g
Specifies that compilation is to produce an object file that includes symbolic information, which is required for source-level debugging.
-I directory
Specifies the directories to be used during compilation in searching for include files (also called header files).

Absolute path names 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 path names are not specified on #include directives, then the search order is as follows:
  • 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.
  • The include files are then searched for in all directories specified by the -I option, in the order specified.
  • Finally, the include files are searched for in the usual places. (See usage note 5 for a description of the usual places.)
CMS files can explicitly be specified on #include directives. You can indicate this by specifying a leading double slash (//). For example, to include the include file DEF H that is on a CMS minidisk, code your C/C++ source as follows: 
#include <//def.h>
CMS include files are handled according to C/C++ compiler conversion rules (see usage note 5). When specifying an #include directive with a leading double slash, the file search follows the CMS access search order. This means that when you explicitly specify a CMS file, any directory names specified on the -I option are ignored.
-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 a CMS file as an archive library directory.

For information on specifying C370LIB libraries, see the description of the -l libname operand. Also see usage note 7 for a description of the usual places.

-O
Specifies that compilation be done with the C/C++ compiler level 1 optimization and selective inlining techniques. The defaults are no optimization and no inlining. If you compile and build your C/C++ program using the -O option, you cannot take advantage of source-level debugging.

In addition to using optimization techniques, you may want to control writable strings by using the #pragma strings (readonly) directive.

-o outfile
Specifies where c89/cxx is to write the executable file. The file a.out is the default when the source file is a BFS file, and is written to the working directory. If the source file is a CMS record file, the default is to write the executable file to the A-disk with the name file MODULE.

Also see usage note 4 for related information.

-s
Specifies that compilation produces a file.o file that does not include symbolic information. This is the default behavior for c89/cxx.
-U name
Undefines a C/C++ macro specified with name. This option affects only macros defined by the -D option, including those automatically specified by c89/cxx. For information about macros that c89/cxx automatically defines, see usage note 6. Also, for related information, see usage note 10.
-V
This verbose option produces and directs output to stdout as compiler listings and (for c89 only) prelinker listings. Error output continues to be directed to stderr. If c89/cxx is invoked from CMS, and if the source resides in a byte file system directory, then the output is placed in the directory where the source was found. If c89/cxx is invoked from CMS, and if the source resides on an accessed file mode, then the output is placed on the user's A-disk.
-W phase,option[,option]...
Specifies options to be passed to the compile or module build phases of c89/cxx. Phase 0 or c specifies the compile phase, and phase b specifies the module build phase.
  • When using c89 to invoke the IBM XL C/C++ for z/VM compiler or the IBM C/C++ for z/VM compiler, or when using cxx, the module build phase always uses the Program Management binder. To pass options to the binder, the first module build phase option must be b.
  • When using c89 to invoke the IBM C for VM/ESA compiler, the module build phase includes prelinker processing, the loading of the resulting CMS TEXT file using the CMS LOAD command, and the creation of the module file by the CMS GENMOD command.
    To pass options to the prelinker, the first module build phase option must be p. For example, to write the prelink map to stdout, specify: 
    c89 -W b,p,map file.c

    To pass options to the LOAD command, the first module build phase option must be l.

    To pass options to the GENMOD command, the first module build phase option must be g.

    To use the Program Management binder (instead of the prelinker, LOAD, and GENMOD) and pass options to it, the first module build phase option must be b. For example: 
    c89 -W b,b,NOTERM file.c

You cannot use -W to override the compiler options that correspond to c89/cxx options, with the exception of the listing options (corresponding to -V) and inlining options (corresponding to -O).

For the prelinker, c89 uses the following options, all of which can be overridden using the -W option with the exception of OE. 
DUP                    NONCAL
OE                     NOMAP
NER                    NOUPCASE
NOMEMORY               NOLIB

For the CMS LOAD command, c89 uses the default options except for RLDSAVE, NOAUTO, and NOMAP.

For the CMS GENMOD command, c89 uses the default options except for NOMAP.

For the Program Management binder (CMS BIND command), c89/cxx uses the default options except for CASE MIXED.

Notes:
  1. Most compiler and prelinker options have a positive and negative form. The negative form is the positive with a NO added before (as in XREF and NOXREF). The same is true for LOAD and GENMOD.
  2. The IBM XL C/C++ for z/VM compiler is described in XL C/C++ for z/VM: User's Guide. The IBM C/C++ for z/VM compiler is described in C/C++ for z/VM: User's Guide, SC09-7625-00. The IBM C for VM/ESA compiler is described in C for VM/ESA: User's Guide, SC09-2152-00.
  3. The Program Management binder is described in z/VM: Program Management Binder for CMS.
  4. The prelinker is described in z/VM: Language Environment User's Guide.
  5. The CMS module build process is described in z/VM: CMS Application Development Guide.

Operands

c89/cxx recognizes the following operands:
Note: You can specify a CMS record file system file identifier by preceding the file name with a double slash (//).
file.c
Specifies the name of a C/C++ source file to be compiled. The form for a C source file is file.c; the form for a C++ source file is file.cpp or file.cxx. You can specify a CMS file, but it must have a file type of C, CPP, or CXX.

The object file is written in the working directory and is named file.o. If a CMS native record file name is specified, the object file is named file MODULE A. See usage note 4 for related information.

file.a
Specifies the name of an archive file, as produced by the ar command, to be used during the module build phase.
file.o
Specifies the name of a C/C++ object file, produced by c89/cxx, to be used in the module build phase. You can specify a CMS file, but it must have a file type of TEXT.
file.x
Specifies the name of a definition side-deck produced during the c89 link-editing phase when creating a Dynamic Link Library (DLL). You can specify a CMS file, but it must have a file type of EXP. For additional information, see usage note 12.
-l libname
Specifies the name of an archive library. c89/cxx searches for the file liblibname.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.

You can specify a CMS file, but it must have a file type of TXTLIB. libname is used directly without prefixing it with lib. If only //libname is specified, the file type txtlib is assumed. The CMS native record file specified must be a C370LIB object library. For more information about the Object Library Utility, see XL C/C++ for z/VM: User's Guide.

Files

libc.a
C/C++ function library (see usage note 7).
libm.a
C/C++ math function library (see usage note 7).
libl.a
lex function library.
liby.a
yacc function library.
/usr/include
The usual place to search for include files (see usage note 5).
/lib
The usual place to search for library functions (see usage note 7).
/usr/lib
The usual place to search for library functions (see usage note 7).

Usage Notes

  1. By default, the c89 command invokes the IBM XL C/C++ for z/VM compiler or the IBM C/C++ for z/VM compiler (whichever is installed) to compile C or C++ source. If you had previously set c89 to invoke the IBM C for VM/ESA compiler and want to change to the IBM XL C/C++ for z/VM compiler or the IBM C/C++ for z/VM compiler, you can issue the following command to specify the C/C++ compiler module (CBXFINIT) on the _CNAME environment variable: 
    globalv select cenv setlp_cname cbxfinit
    To use the IBM C for VM/ESA compiler, you can specify the C compiler module (CBC310) by issuing the following command: 
    globalv select cenv setlp_cname cbc310
    The cxx command always invokes CBXFINIT MODULE and does not look at the _CNAME environment variable.
  2. 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.
  3. When invoking c89/cxx 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.

    To escape these special characters, either enclose the option-argument or operand in double quotation marks, or precede each character with a backslash.

  4. Some c89/cxx behavior applies only to files (and not to CMS native record files).
    • The -o option does not allow a file of the form file.c to be specified.
    • If the compilation is not successful, the corresponding file.o file is always removed.
  5. Minidisks and SFS directories in the CMS file system search order are used as the usual place to resolve compiler include files during compilation. Searching here for include files is automatic.

    Because the include files are CMS files, the C/C++ compiler uses conversion rules to transform the #include preprocessor directive specification into a CMS file name. This transformation strips any directory name on the #include directive, and then takes the first 8 or less characters up to the first dot (.).

    Therefore, if an application programmer specifies an #include directive with a relative path name having the same file name as a system include file (CMS file) and the user include file cannot be found, the system include file is found instead.

    For consistency with other implementations, c89/cxx searches the directory /usr/include as the usual place, just prior to searching the CMS minidisks or SFS directories.

  6. c89/cxx automatically defines the following POSIX feature test macros:
    • errno=(*__errno())
    • _OPEN_DEFAULT=1
    • __OPEN_VM=1

    c89/cxx adds the macro definition only after processing the c89/cxx command string. You can override the macro by specifying -D or -U options for it on the c89/cxx command string.

    The __OPEN_VM macro is used internally in the compiler and does not change any of the standard feature macros. The _OPEN_DEFAULT macro defines the level of POSIX feature test macros used in FEATURES H.

  7. The usual place for the -L option search is the /lib directory followed by the /usr/lib directory. For consistency with other implementations, the archive libraries libc.a and libm.a exist as files in the /usr/lib directory. However, the library functions are not contained in them. Instead, CMS files installed with Language Environment® are used as the usual place to resolve library functions in the final step of the link-editing phase.
  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 c89/cxx command string, if subsequent specification of file.o files requires that additional symbols be resolved from that library.
  9. 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 and -s). However, some c89/cxx 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:
    -E
    Overrides -O and -V, -c, -g and -s.
    -g
    Overrides -O and and -s.
    -s
    Overrides -g (the last one specified is honored).
    -O -V, -c
    All are honored if not overridden.
  10. 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.
    -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.
    -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.
    -W
    All specifications are used. All options specified for a phase are passed to it, as if they were concatenated together in the order specified.
    -o
    The output file used will be the one specified on the last -o option.
  11. The C/C++ runtime library supports a file naming convention of // (the file name can begin with exactly two slashes). c89/cxx indicates that the file naming convention of // can be used.

    However, OpenExtensions does not support this convention. Do not use this convention (//) unless it is specifically indicated (as here in c89/cxx). OpenExtensions 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.

  12. A file.x definition side-deck contains link-editing phase IMPORT control statements naming symbols that are exported by a DLL. The definition side-deck is subsequently used during the link-editing phase of an application that is to use the DLL.
    To create a definition side-deck, you must specify the dll option as a linkage editor option during the c89 link-editing phase when creating the DLL. Also, you must use either the C compiler option exportall or the C compiler directive #pragma export. For example: 
    c89 -o outdll -W c,expo,dll -W b,p,dll file.c

    The definition side-deck is written to the working directory and is named [var][outdll.x/var]. If a file identifier of //outdll is specified, the definition side-deck is named //outdll.EXP. If the output file specified already has a suffix, that suffix is replaced.

    To subsequently use file.x definition side-decks, specify them along with any other file.o object files specified for the c89 link-editing phase. For example: 
    c89  -omyappl myappl.o outdll.x

    To run an application that is link-edited with a definition side-deck, the DLL that was created along with the definition side-deck must be made available. When the DLL resides in the BFS, it must be in either the working directory or a directory named on the LIBPATH environment variable. Otherwise, it must be a file residing on a minidisk or SFS directory accessed in the current CMS search order.

    For more information about DLLs, see the z/VM: CMS Application Development Guide.

Localization

c89/cxx uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_CTYPE
  • LC_MESSAGES
See Localization for more information.

Exit Values

0
Successful completion.
1
Failure due to incorrect specification of the arguments passed to c89/cxx.
2
Failure processing archive libraries:
  • Archive library was not in any of the library directories specified.
  • Archive library was incorrectly specified, or was not specified, following the -l operand.
3
Compilation, prelink, or build step was unsuccessful.
4
Error when preparing to call the compiler, prelinker, or module build commands for one of the following reasons:
  • The file or CMS native record file name specified is incorrect.
  • The file or CMS native record file name cannot be opened.
5
Dynamic allocation error, when preparing to call the compiler, prelinker, or module build commands due to an error being detected in the allocation information.
6
Error copying the file from a temporary CMS file to a BFS file.
8
Error creating a temporary input CMS file for the compiler, prelinker, or module build commands.

Portability

POSIX.2.

The -V option is an extension of the POSIX standard.

Related Commands

ar, lex, make, strip, yacc