path: root/usr/src/man/man1/msgcpp.1

'\" 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 "Oct 9, 2007"
.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
.na
\fB\fBcmd\fR \fIcommand\fR\fR
.ad
.RS 19n
\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
.na
\fB\fBdef\fR \fIname string\fR\fR
.ad
.RS 19n
\fIname\fR is a candidate variable with \fIstring\fR value string.
.RE

.sp
.ne 2
.na
\fB\fBstr\fR \fIstring\fR\fR
.ad
.RS 19n
\fIstring\fR should be entered into the catalog.
.RE

.sp
.ne 2
.na
\fB\fBvar\fR \fIname\fR\fR
.ad
.RS 19n
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
.na
\fB\fB-A\fR\fR
.ad
.br
.na
\fB\fB--assert=\fR\fIassertion\fR\fR
.ad
.RS 25n
Enter the assertion using \fB#assert\fR for system V compatibility.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.br
.na
\fB\fB--comments\fR\fR
.ad
.RS 25n
Pass comments to the output.
.sp
Comments are omitted by default.
.RE

.sp
.ne 2
.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
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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.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
.na
\fB\fB-E\fR\fR
.ad
.br
.na
\fB\fB--preprocess\fR\fR
.ad
.RS 25n
Ignored; for compatibility with very old compilers.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fR
.ad
.br
.na
\fB\fB--include-reference\fR\fR
.ad
.RS 25n
Emit \fB#include\fR file paths on the standard error, one per line, indented to
show nesting.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.br
.na
\fB\fB--include[=\fR\fIdirectory\fR\fB]\fR\fR
.ad
.RS 25n
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
.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

.sp
.ne 2
.na
\fB\fB-I-D[\fR\fIfile\fR]\fR
.ad
.sp .6
.RS 4n
Read the default \fBprobe\fR definitions from \fIfile\fR, or ignore the default
definitions if \fIfile\fR is omitted.
.RE

.sp
.ne 2
.na
\fB\fB-I-H\fR\fIdirectory\fR\fR
.ad
.br
.na
\fB\fBpp:hostdir\fR \fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
Mark directory as a hosted directory. Headers from hosted directories have
compatibility warnings disabled.
.RE

.sp
.ne 2
.na
\fB\fB-I-I\fR\fIheader\fR\fR
.ad
.br
.na
\fB\fBpp:ignore\fR \fIheader\fR\fR
.ad
.sp .6
.RS 4n
Add \fIheader\fR to the list of ignored headers.
.RE

.sp
.ne 2
.na
\fB\fB-I-M\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
\fIfile\fR contains a sequence of header \fB[= "map" ]\fR lines, where header
is either \fB<name>\fR or \fB"name"\fR, and \fB"map"\fR is an explicit binding
for header. header is ignored \fBif = "map"\fR is omitted.
.RE

.sp
.ne 2
.na
\fB\fB-I-R\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
Include \fIfile\fR but do not emit text or line syncs.
.RE

.sp
.ne 2
.na
\fB\fB-I-S\fR\fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
Add \fIdirectory\fR to the default standard include directory list.
.RE

.sp
.ne 2
.na
\fB\fB-I-T\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
Include \fIfile\fR and emit text to the output file. The option value can be
omitted.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.br
.na
\fB\fB--dependencies\fR\fR
.ad
.RS 25n
Generate \fBmake\fR(1S) dependencies. This option is not needed with
\fBnmake\fR.
.sp
The \fB-M\fR option can be followed by optional flags to change the dependency
output styles.
.sp
The following optional flags are supported:
.sp
.ne 2
.na
\fB\fBD\fR\fR
.ad
.RS 5n
Generate dependencies in a separate \fB\&.d\fR file. Preprocessed output is
still written to output, or the standard output if output is omitted.
.RE

.sp
.ne 2
.na
\fB\fBG\fR\fR
.ad
.RS 5n
Also generate missing dependencies.
.RE

.sp
.ne 2
.na
\fB\fBM\fR\fR
.ad
.RS 5n
Only generate local header dependencies. Hosted headers are omitted. Hosted
headers are determined by the \fB-I-H\fR option and the -\fB-pp:hosted\fR and
\fBpp:hostdir pragmas\fR. No special distinction is made between the \fB""\fR
and \fB<>\fR include styles.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.br
.na
\fB\fB--sync\fR\fR
.ad
.RS 25n
Emit line syncs.
.sp
Line sync is turned on by default. \fB-P\fR means \fB--nosync\fR.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fB[\fR\fIlength\fR\fB]\fR\fR
.ad
.RS 25n
If not \fBgcc\fR, truncate identifiers to \fIlength\fR characters for
compatibility with old AT&T compilers.
.RE

.sp
.ne 2
.na
\fB\fB-U\fR\fR
.ad
.br
.na
\fB\fB--undefine=\fR\fIname\fR\fR
.ad
.RS 25n
Remove the definition for the macro \fIname\fR.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.br
.na
\fB\fB--version\fR\fR
.ad
.RS 25n
Emit the \fBlibpp\fR version.
.RE

.sp
.ne 2
.na
\fB\fB-X\fR\fR
.ad
.br
.na
\fB\fB--argmode\fR\fR
.ad
.RS 25n
Enable \fIname\fR\fB=\fR\fIvalue\fR macro arguments for \fBeasel\fR
compatibility.
.RE

.sp
.ne 2
.na
\fB\fB-Y\fR\fR
.ad
.br
.na
\fB\fB--standard=\fR\fIdirectory\fR\fR
.ad
.RS 25n
Add \fIdirectory\fR to the list searched for \fB#include <...>\fR files.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIinput\fR\fR
.ad
.RS 10n
Specifies C source file to preprocess.
.RE

.sp
.ne 2
.na
\fB\fIoutput\fR\fR
.ad
.RS 10n
Specifies output file.
.RE

.SH EXIT STATUS
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBmsgcpp\fR to Extract Localizable Strings
.sp
.LP
The following example uses \fBmsgcpp\fR to extract localizable strings from the
file \fBhello.c\fR, marked using the \fBERROR_dictionary()\fR, and writes them
to the file \fBhello.mso\fR:

.sp
.in +2
.nf
example% cat hello.c


#include <stdio.h>
#include <stdlib.h>

/*
 * dummy macro to avoid including
 * libast headers
 */
#define ERROR_dictionary(x) x

int main(int ac, char *av[])
{
    puts( ERROR_dictionary("hello world") );
    puts( ERROR_dictionary("hello all") );
    return( EXIT_SUCCESS );
 }

example% msgcpp -D__STDC__ -D__i386 hello.c hello.mso

example% cat hello.mso
str "hello world"
str "hello all"
.fi
.in -2
.sp

.SH AUTHORS
.sp
.LP
Glenn Fowler, \fBgsf@research.att.com\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Volatile
.TE

.SH SEE ALSO
.sp
.LP
.BR cpp (1),
.BR gencat (1),
.BR msgcc (1),
.BR msgcvt (1),
.BR msggen (1),
.BR make (1S),
.BR attributes (7)
.sp
.LP
Kernighan, Brian W. and Ritchie, Dennis M., \fIThe C Programming Language\fR,
Prentice Hall, 1988.