'\" te

.\" Copyright (c) 1986-2006 AT&T Knowledge Ventures

.\" To view license terms, see http://www.opensource.org/licenses/cpl1.0.txt

.\" Portions Copyright (c) 2007, Sun Microsystems, Inc.

.TH msgcpp 1 "9 Oct 2007" "SunOS 5.11" "User Commands"

.SH NAME

msgcpp \- C language message catalog preprocessor

.SH SYNOPSIS

.LP

.nf

\fBmsgcpp\fR [\fB-ACEHMPVX\fR] [\fB-D\fR \fIname\fR[\fB=\fR\fIvalue\fR]] [\fB-I\fR \fIdirectory\fR] [\fB-U\fR \fIname\fR] 

 [\fB-T\fR[\fIlength\fR]] [\fB-Y\fR \fIdirectory\fR] [\fIinput\fR [\fIoutput\fR] ]

.fi

.SH DESCRIPTION

.sp

.LP

\fBmsgcpp\fR is a C language message catalog preprocessor. It accepts \fBcpp\fR(1) style options and arguments. \fBmsgcpp\fR preprocesses an input C source file and emits keyed lines to the output, usually for further processing by\fBmsgcc\fR(1). \fBmsgcc\fR output is in the \fBgencat\fR(1) syntax. Candidate message text is determined by arguments to the last \fB<error.h>\fR and \fB<option.h>\fR functions. The \fBmsgcpp\fR keyed output lines are:

.sp

.ne 2

.mk

.na

\fB\fBcmd\fR \fIcommand\fR\fR

.ad

.RS 19n

.rt  

\fIcommand\fR is a candidate for \fB--??keys\fR option string generation. This is triggered by \fBb_command(int argc\fR, in the input.

.RE

.sp

.ne 2

.mk

.na

\fB\fBdef\fR \fIname string\fR\fR

.ad

.RS 19n

.rt  

\fIname\fR is a candidate variable with \fIstring\fR value string.

.RE

.sp

.ne 2

.mk

.na

\fB\fBstr\fR \fIstring\fR\fR

.ad

.RS 19n

.rt  

\fIstring\fR should be entered into the catalog.

.RE

.sp

.ne 2

.mk

.na

\fB\fBvar\fR \fIname\fR\fR

.ad

.RS 19n

.rt  

If \fBdef\fR \fIname\fR occurs then its string value should be entered into the catalog.

.RE

.sp

.LP

The input source file is preprocessed with the \fBpp:allpossible\fR option on. This enables non-C semantics. All source should first be compiled error-free with a real compiler before running \fBmsgcpp\fR. The following changes are enabled for the top level files. Included file behavior is not affected.

.RS +4

.TP

1.

All \fB#if\fR, \fB#ifdef\fR and \fB#ifndef\fR branches are enabled.

.RE

.RS +4

.TP

2.

The first definition for a macro is retained, even when subsequent \fB#define\fR statements would normally redefine the macro. \fB#undef\fR must be used to redefine a macro.

.RE

.RS +4

.TP

3.

Macro calls with an improper number of arguments are silently ignored.

.RE

.RS +4

.TP

4.

\fB#include\fR on non-existent headers are silently ignored.

.RE

.RS +4

.TP

5.

Invalid C source characters are silently ignored.

.RE

.sp

.LP

\fBmsgcat.h\fR is included if it exists. This file may contain macro definitions for functions that translate string arguments. If \fBfoo\fR is a function that translates its string arguments then include the line \fB#define foo _TRANSLATE_\fR in \fBmsgcat.h\fR, or specify the option \fB-Dfoo=_TRANSLATE_\fR. If \fBbar\fR is a function that translates string arguments if the first argument is \fBstderr\fR, then use either \fB#define bar _STDIO_\fR or \fB-Dbar=_STDIO_\fR. 

.sp

.LP

The macro \fB_BLD_msgcat\fR is defined to be \fB1\fR. As an alternative to \fBmsgcat.h\fR, \fB_TRANSLATE_\fR definitions could be placed inside \fB#ifdef _BLD_msgcat ... #endif\fR. 

.SH OPTIONS

.sp

.LP

The following options are supported:

.sp

.ne 2

.mk

.na

\fB\fB-A\fR\fR

.ad

.br

.na

\fB\fB--assert=\fR\fIassertion\fR\fR

.ad

.RS 25n

.rt  

Enter the assertion using \fB#assert\fR for system V compatibility.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-C\fR\fR

.ad

.br

.na

\fB\fB--comments\fR\fR

.ad

.RS 25n

.rt  

Pass comments to the output. 

.sp

Comments are omitted by default.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D\fR\fR

.ad

.br

.na

\fB\fB--define=\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR\fR

.ad

.RS 25n

.rt  

Define the macro \fIname\fR to have \fIvalue\fR. This is the only portable way to pass options through \fBcc\fR to \fBcpp\fR(1). 

.RS +4

.TP

.ie t \(bu

.el o

If \fB=\fR\fIvalue\fR is omitted, \fIvalue\fR is assumed to be \fB1\fR .

.RE

.RS +4

.TP

.ie t \(bu

.el o

If \fIname\fR begins with \fB:\fR, then it is interpreted as a \fBlibpp\fR \fB#pragma pp\fR: statement.

.RE

.RS +4

.TP

.ie t \(bu

.el o

If \fIname\fR begins with \fB%\fR, it is interpreted as a \fBlibpp\fR \fB#\fR directive statement.

.RE

.RS +4

.TP

.ie t \(bu

.el o

If name begins with a \fB-\fR or a \fB+\fR, it is interpreted as a \fBlibpp\fR option.

.sp

\fB-\fR turns the option on, \fB+\fR turns it off.

.RE

.RS +4

.TP

.ie t \(bu

.el o

Most options have a \fB#pragma\fR counterpart that is listed with the option definition.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-C\fR\fR

.ad

.br

.na

\fB\fBpp:compatibility\fR\fR

.ad

.sp .6

.RS 4n

Preprocess for K&R C compatibility.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-D\fR\fIlevel\fR\fR

.ad

.br

.na

\fB\fBpp:debug level\fR \fIlevel\fR\fR

.ad

.sp .6

.RS 4n

Set the debug trace level. 

.sp

Specify \fIlevel\fR as a number greater than or equal to \fB0\fR. Higher levels produce more output. Levels higher than \fB3\fR can only be enabled in the \fB-g\fR compiled versions.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-F\fR\fIname\fR\fR

.ad

.sp .6

.RS 4n

Set the main input file name to \fIname\fR. This only affects the error messages and the line sync output.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-H\fR\fR

.ad

.br

.na

\fB\fBpp:hosted\fR\fR

.ad

.sp .6

.RS 4n

All directories are hosted. Compatibility warning messages from the hosted directory headers are suppressed.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-I\fR\fR

.ad

.br

.na

\fB\fBpp:cdir\fR\fR

.ad

.sp .6

.RS 4n

All directories contain C headers. This option is only used only with \fB-D-+\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-K\fR\fR

.ad

.br

.na

\fB\fBpp:keyargs\fR\fR

.ad

.sp .6

.RS 4n

Enable the non-standard \fIname\fR\fB=\fR\fIvalue\fR macro argument mode.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-L\fR\fB[\fR\fIid\fR\fB]\fR\fR

.ad

.br

.na

\fB\fBpp:lineid [\fR\fIid\fR]\fR

.ad

.sp .6

.RS 4n

Set the line sync directive id to \fIid\fR. If \fIid\fR is not specified, set to null.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-M\fR\fR

.ad

.br

.na

\fB\fBpp:nomultiple\fR\fR

.ad

.sp .6

.RS 4n

Disable multiple include detection.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-P\fR\fR

.ad

.br

.na

\fB\fBpp:passthrough\fR\fR

.ad

.sp .6

.RS 4n

Enable the non-standard passthrough mode. This can be useful for processing non-C input.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-Q\fR\fR

.ad

.br

.na

\fB\fBpp:dump\fR\fR

.ad

.sp .6

.RS 4n

Dump macro definitions to the output so that the output may be passed through \fBcpp\fR again. This is used for generating precompiled headers.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-R\fR\fR

.ad

.br

.na

\fB\fBpp:transition\fR\fR

.ad

.sp .6

.RS 4n

Enable the transition preprocessing mode. This is used for compilers that cannot make up their semantics between K&R and ISO C.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-S\fR\fR

.ad

.br

.na

\fB\fBpp:strict\fR\fR

.ad

.sp .6

.RS 4n

Enable strict preprocessing semantics and warnings. This works with any mode (compatibility, transition, or the default ISO).

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-T\fR\fItest\fR\fR

.ad

.br

.na

\fB\fBpp:test\fR \fItest\fR\fR

.ad

.sp .6

.RS 4n

Enable implementation specific test code according to \fItest\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-W\fR\fR

.ad

.br

.na

\fB\fBpp:warn\fR\fR

.ad

.sp .6

.RS 4n

Enable pedantic warnings in non-hosted files.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-X\fR\fB[cc]\fR\fR

.ad

.br

.na

\fB\fB\fR\fR

.ad

.sp .6

.RS 4n

Preprocess for the \fBcc\fR compiler, which must be an executable path or an executable on \fB$PATH\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-Z\fR\fR

.ad

.br

.na

\fB\fBpp:pool\fR\fR

.ad

.sp .6

.RS 4n

Enable pool mode.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-d\fR\fR

.ad

.sp .6

.RS 4n

List canonicalized \fB#define\fR statements for non-predefined macros in the output.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-m\fR\fR

.ad

.sp .6

.RS 4n

List canonicalized \fB#define\fR statements for all macros. All other output is disabled.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-D-+\fR\fR

.ad

.br

.na

\fB\fBpp:plusplus\fR\fR

.ad

.sp .6

.RS 4n

Preprocess for the C++ dialect.

.RE

.RE

.sp

.ne 2

.mk

.na

\fB\fB-E\fR\fR

.ad

.br

.na

\fB\fB--preprocess\fR\fR

.ad

.RS 25n

.rt  

Ignored; for compatibility with very old compilers.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-H\fR\fR

.ad

.br

.na

\fB\fB--include-reference\fR\fR

.ad

.RS 25n

.rt  

Emit \fB#include\fR file paths on the standard error, one per line, indented to show nesting.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-I\fR\fR

.ad

.br

.na

\fB\fB--include[=\fR\fIdirectory\fR\fB]\fR\fR

.ad

.RS 25n

.rt  

Append directory to the list of directories searched for \fB#include\fR files. 

.sp

If directory is \fB-\fR: 

.RS +4

.TP

1.

\fB-I\fR directories before \fB-I-\fR are searched only for \fB"..."\fR include files

.RE

.RS +4

.TP

2.

\fB-I\fR directories after \fB-I-\fR are searched for \fB"..."\fR and \fB<"...">\fR include files

.RE

.RS +4

.TP

3.

the directory \fB\&.\fR is searched only if it is explicitly specified by an \fB-I\fR option

.RE

.sp

.ne 2

.mk

.na

\fB\fB-I-C\fR\fIdirectory\fR\fR

.ad

.br

.na

\fB\fBpp:cdir directory\fR\fR

.ad

.sp .6

.RS 4n

Mark \fIdirectory\fR as a C header directory. This option is used with \fBpp:plusplus\fR.

.RE