1 files changed, 931 insertions, 0 deletions
diff --git a/usr/src/man/man1/msgcpp.1 b/usr/src/man/man1/msgcpp.1
new file mode 100644
index 0000000000..f6716d780d
--- /dev/null
+++ b/usr/src/man/man1/msgcpp.1
@@ -0,0 +1,931 @@
+'\" 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
+
+.sp
+.ne 2
+.mk
+.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
+.mk
+.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
+.mk
+.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
+.mk
+.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
+.mk
+.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
+.mk
+.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
+.mk
+.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
+.mk
+.na
+\fB\fB-M\fR\fR
+.ad
+.br
+.na
+\fB\fB--dependencies\fR\fR
+.ad
+.RS 25n
+.rt  
+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
+.mk
+.na
+\fB\fBD\fR\fR
+.ad
+.RS 5n
+.rt  
+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
+.mk
+.na
+\fB\fBG\fR\fR
+.ad
+.RS 5n
+.rt  
+Also generate missing dependencies.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBM\fR\fR
+.ad
+.RS 5n
+.rt  
+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
+.mk
+.na
+\fB\fB-P\fR\fR
+.ad
+.br
+.na
+\fB\fB--sync\fR\fR
+.ad
+.RS 25n
+.rt  
+Emit line syncs.
+.sp
+Line sync is turned on by default. \fB-P\fR means \fB--nosync\fR.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB-T\fR\fB[\fR\fIlength\fR\fB]\fR\fR
+.ad
+.RS 25n
+.rt  
+If not \fBgcc\fR, truncate identifiers to \fIlength\fR characters for
+compatibility with old AT&T compilers.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB-U\fR\fR
+.ad
+.br
+.na
+\fB\fB--undefine=\fR\fIname\fR\fR
+.ad
+.RS 25n
+.rt  
+Remove the definition for the macro \fIname\fR.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB-V\fR\fR
+.ad
+.br
+.na
+\fB\fB--version\fR\fR
+.ad
+.RS 25n
+.rt  
+Emit the \fBlibpp\fR version.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB-X\fR\fR
+.ad
+.br
+.na
+\fB\fB--argmode\fR\fR
+.ad
+.RS 25n
+.rt  
+Enable \fIname\fR\fB=\fR\fIvalue\fR macro arguments for \fBeasel\fR
+compatibility.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB-Y\fR\fR
+.ad
+.br
+.na
+\fB\fB--standard=\fR\fIdirectory\fR\fR
+.ad
+.RS 25n
+.rt  
+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
+.mk
+.na
+\fB\fIinput\fR\fR
+.ad
+.RS 10n
+.rt  
+Specifies C source file to preprocess.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIoutput\fR\fR
+.ad
+.RS 10n
+.rt  
+Specifies output file.
+.RE
+
+.SH EXIT STATUS
+.sp
+.ne 2
+.mk
+.na
+\fB\fB0\fR\fR
+.ad
+.RS 6n
+.rt  
+Successful completion.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB>0\fR\fR
+.ad
+.RS 6n
+.rt  
+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(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+Interface StabilityVolatile 
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBcpp\fR(1), \fBgencat\fR(1), \fBmsgcc\fR(1), \fBmsgcvt\fR(1),
+\fBmsggen\fR(1), \fBmake\fR(1S), \fBattributes\fR(5)
+.sp
+.LP
+Kernighan, Brian W. and Ritchie, Dennis M., \fIThe C Programming Language\fR,
+Prentice Hall, 1988.