| blob | d4f62f2b6ec9d902c99b9260268033135aa28e4c |
1 '\" te
2 .\" Copyright (c) 1986-2006 AT&T Knowledge Ventures
3 .\" To view license terms, see http://www.opensource.org/licenses/cpl1.0.txt
4 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc.
5 .TH MSGCPP 1 "Oct 9, 2007"
6 .SH NAME
7 msgcpp \- C language message catalog preprocessor
8 .SH SYNOPSIS
9 .LP
10 .nf
11 \fBmsgcpp\fR [\fB-ACEHMPVX\fR] [\fB-D\fR \fIname\fR[\fB=\fR\fIvalue\fR]] [\fB-I\fR \fIdirectory\fR] [\fB-U\fR \fIname\fR]
12 [\fB-T\fR[\fIlength\fR]] [\fB-Y\fR \fIdirectory\fR] [\fIinput\fR [\fIoutput\fR] ]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 \fBmsgcpp\fR is a C language message catalog preprocessor. It accepts
19 \fBcpp\fR(1) style options and arguments. \fBmsgcpp\fR preprocesses an input C
20 source file and emits keyed lines to the output, usually for further processing
21 by\fBmsgcc\fR(1). \fBmsgcc\fR output is in the \fBgencat\fR(1) syntax.
22 Candidate message text is determined by arguments to the last \fB<error.h>\fR
23 and \fB<option.h>\fR functions. The \fBmsgcpp\fR keyed output lines are:
24 .sp
25 .ne 2
26 .na
27 \fB\fBcmd\fR \fIcommand\fR\fR
28 .ad
29 .RS 19n
30 \fIcommand\fR is a candidate for \fB--??keys\fR option string generation. This
31 is triggered by \fBb_command(int argc\fR, in the input.
32 .RE
34 .sp
35 .ne 2
36 .na
37 \fB\fBdef\fR \fIname string\fR\fR
38 .ad
39 .RS 19n
40 \fIname\fR is a candidate variable with \fIstring\fR value string.
41 .RE
43 .sp
44 .ne 2
45 .na
46 \fB\fBstr\fR \fIstring\fR\fR
47 .ad
48 .RS 19n
49 \fIstring\fR should be entered into the catalog.
50 .RE
52 .sp
53 .ne 2
54 .na
55 \fB\fBvar\fR \fIname\fR\fR
56 .ad
57 .RS 19n
58 If \fBdef\fR \fIname\fR occurs then its string value should be entered into the
59 catalog.
60 .RE
62 .sp
63 .LP
64 The input source file is preprocessed with the \fBpp:allpossible\fR option on.
65 This enables non-C semantics. All source should first be compiled error-free
66 with a real compiler before running \fBmsgcpp\fR. The following changes are
67 enabled for the top level files. Included file behavior is not affected.
68 .RS +4
69 .TP
70 1.
71 All \fB#if\fR, \fB#ifdef\fR and \fB#ifndef\fR branches are enabled.
72 .RE
73 .RS +4
74 .TP
75 2.
76 The first definition for a macro is retained, even when subsequent
77 \fB#define\fR statements would normally redefine the macro. \fB#undef\fR must
78 be used to redefine a macro.
79 .RE
80 .RS +4
81 .TP
82 3.
83 Macro calls with an improper number of arguments are silently ignored.
84 .RE
85 .RS +4
86 .TP
87 4.
88 \fB#include\fR on non-existent headers are silently ignored.
89 .RE
90 .RS +4
91 .TP
92 5.
93 Invalid C source characters are silently ignored.
94 .RE
95 .sp
96 .LP
97 \fBmsgcat.h\fR is included if it exists. This file may contain macro
98 definitions for functions that translate string arguments. If \fBfoo\fR is a
99 function that translates its string arguments then include the line \fB#define
100 foo _TRANSLATE_\fR in \fBmsgcat.h\fR, or specify the option
101 \fB-Dfoo=_TRANSLATE_\fR. If \fBbar\fR is a function that translates string
102 arguments if the first argument is \fBstderr\fR, then use either \fB#define bar
103 _STDIO_\fR or \fB-Dbar=_STDIO_\fR.
104 .sp
105 .LP
106 The macro \fB_BLD_msgcat\fR is defined to be \fB1\fR. As an alternative to
107 \fBmsgcat.h\fR, \fB_TRANSLATE_\fR definitions could be placed inside \fB#ifdef
108 _BLD_msgcat ... #endif\fR.
109 .SH OPTIONS
110 .sp
111 .LP
112 The following options are supported:
113 .sp
114 .ne 2
115 .na
116 \fB\fB-A\fR\fR
117 .ad
118 .br
119 .na
120 \fB\fB--assert=\fR\fIassertion\fR\fR
121 .ad
122 .RS 25n
123 Enter the assertion using \fB#assert\fR for system V compatibility.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-C\fR\fR
130 .ad
131 .br
132 .na
133 \fB\fB--comments\fR\fR
134 .ad
135 .RS 25n
136 Pass comments to the output.
137 .sp
138 Comments are omitted by default.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-D\fR\fR
145 .ad
146 .br
147 .na
148 \fB\fB--define=\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR\fR
149 .ad
150 .RS 25n
151 Define the macro \fIname\fR to have \fIvalue\fR. This is the only portable way
152 to pass options through \fBcc\fR to \fBcpp\fR(1).
153 .RS +4
154 .TP
155 .ie t \(bu
156 .el o
157 If \fB=\fR\fIvalue\fR is omitted, \fIvalue\fR is assumed to be \fB1\fR .
158 .RE
159 .RS +4
160 .TP
161 .ie t \(bu
162 .el o
163 If \fIname\fR begins with \fB:\fR, then it is interpreted as a \fBlibpp\fR
164 \fB#pragma pp\fR: statement.
165 .RE
166 .RS +4
167 .TP
168 .ie t \(bu
169 .el o
170 If \fIname\fR begins with \fB%\fR, it is interpreted as a \fBlibpp\fR \fB#\fR
171 directive statement.
172 .RE
173 .RS +4
174 .TP
175 .ie t \(bu
176 .el o
177 If name begins with a \fB-\fR or a \fB+\fR, it is interpreted as a \fBlibpp\fR
178 option.
179 .sp
180 \fB-\fR turns the option on, \fB+\fR turns it off.
181 .RE
182 .RS +4
183 .TP
184 .ie t \(bu
185 .el o
186 Most options have a \fB#pragma\fR counterpart that is listed with the option
187 definition.
188 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-D-C\fR\fR
193 .ad
194 .br
195 .na
196 \fB\fBpp:compatibility\fR\fR
197 .ad
198 .sp .6
199 .RS 4n
200 Preprocess for K&R C compatibility.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fB-D-D\fR\fIlevel\fR\fR
207 .ad
208 .br
209 .na
210 \fB\fBpp:debug level\fR \fIlevel\fR\fR
211 .ad
212 .sp .6
213 .RS 4n
214 Set the debug trace level.
215 .sp
216 Specify \fIlevel\fR as a number greater than or equal to \fB0\fR. Higher levels
217 produce more output. Levels higher than \fB3\fR can only be enabled in the
218 \fB-g\fR compiled versions.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fB-D-F\fR\fIname\fR\fR
225 .ad
226 .sp .6
227 .RS 4n
228 Set the main input file name to \fIname\fR. This only affects the error
229 messages and the line sync output.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fB-D-H\fR\fR
236 .ad
237 .br
238 .na
239 \fB\fBpp:hosted\fR\fR
240 .ad
241 .sp .6
242 .RS 4n
243 All directories are hosted. Compatibility warning messages from the hosted
244 directory headers are suppressed.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fB-D-I\fR\fR
251 .ad
252 .br
253 .na
254 \fB\fBpp:cdir\fR\fR
255 .ad
256 .sp .6
257 .RS 4n
258 All directories contain C headers. This option is only used only with
259 \fB-D-+\fR.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-D-K\fR\fR
266 .ad
267 .br
268 .na
269 \fB\fBpp:keyargs\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 Enable the non-standard \fIname\fR\fB=\fR\fIvalue\fR macro argument mode.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fB-D-L\fR\fB[\fR\fIid\fR\fB]\fR\fR
280 .ad
281 .br
282 .na
283 \fB\fBpp:lineid [\fR\fIid\fR]\fR
284 .ad
285 .sp .6
286 .RS 4n
287 Set the line sync directive id to \fIid\fR. If \fIid\fR is not specified, set
288 to null.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fB-D-M\fR\fR
295 .ad
296 .br
297 .na
298 \fB\fBpp:nomultiple\fR\fR
299 .ad
300 .sp .6
301 .RS 4n
302 Disable multiple include detection.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fB-D-P\fR\fR
309 .ad
310 .br
311 .na
312 \fB\fBpp:passthrough\fR\fR
313 .ad
314 .sp .6
315 .RS 4n
316 Enable the non-standard passthrough mode. This can be useful for processing
317 non-C input.
318 .RE
320 .sp
321 .ne 2
322 .na
323 \fB\fB-D-Q\fR\fR
324 .ad
325 .br
326 .na
327 \fB\fBpp:dump\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 Dump macro definitions to the output so that the output may be passed through
332 \fBcpp\fR again. This is used for generating precompiled headers.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fB-D-R\fR\fR
339 .ad
340 .br
341 .na
342 \fB\fBpp:transition\fR\fR
343 .ad
344 .sp .6
345 .RS 4n
346 Enable the transition preprocessing mode. This is used for compilers that
347 cannot make up their semantics between K&R and ISO C.
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fB-D-S\fR\fR
354 .ad
355 .br
356 .na
357 \fB\fBpp:strict\fR\fR
358 .ad
359 .sp .6
360 .RS 4n
361 Enable strict preprocessing semantics and warnings. This works with any mode
362 (compatibility, transition, or the default ISO).
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fB-D-T\fR\fItest\fR\fR
369 .ad
370 .br
371 .na
372 \fB\fBpp:test\fR \fItest\fR\fR
373 .ad
374 .sp .6
375 .RS 4n
376 Enable implementation specific test code according to \fItest\fR.
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fB-D-W\fR\fR
383 .ad
384 .br
385 .na
386 \fB\fBpp:warn\fR\fR
387 .ad
388 .sp .6
389 .RS 4n
390 Enable pedantic warnings in non-hosted files.
391 .RE
393 .sp
394 .ne 2
395 .na
396 \fB\fB-D-X\fR\fB[cc]\fR\fR
397 .ad
398 .br
399 .na
400 \fB\fB\fR\fR
401 .ad
402 .sp .6
403 .RS 4n
404 Preprocess for the \fBcc\fR compiler, which must be an executable path or an
405 executable on \fB$PATH\fR.
406 .RE
408 .sp
409 .ne 2
410 .na
411 \fB\fB-D-Z\fR\fR
412 .ad
413 .br
414 .na
415 \fB\fBpp:pool\fR\fR
416 .ad
417 .sp .6
418 .RS 4n
419 Enable pool mode.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fB-D-d\fR\fR
426 .ad
427 .sp .6
428 .RS 4n
429 List canonicalized \fB#define\fR statements for non-predefined macros in the
430 output.
431 .RE
433 .sp
434 .ne 2
435 .na
436 \fB\fB-D-m\fR\fR
437 .ad
438 .sp .6
439 .RS 4n
440 List canonicalized \fB#define\fR statements for all macros. All other output is
441 disabled.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fB-D-+\fR\fR
448 .ad
449 .br
450 .na
451 \fB\fBpp:plusplus\fR\fR
452 .ad
453 .sp .6
454 .RS 4n
455 Preprocess for the C++ dialect.
456 .RE
458 .RE
460 .sp
461 .ne 2
462 .na
463 \fB\fB-E\fR\fR
464 .ad
465 .br
466 .na
467 \fB\fB--preprocess\fR\fR
468 .ad
469 .RS 25n
470 Ignored; for compatibility with very old compilers.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fB-H\fR\fR
477 .ad
478 .br
479 .na
480 \fB\fB--include-reference\fR\fR
481 .ad
482 .RS 25n
483 Emit \fB#include\fR file paths on the standard error, one per line, indented to
484 show nesting.
485 .RE
487 .sp
488 .ne 2
489 .na
490 \fB\fB-I\fR\fR
491 .ad
492 .br
493 .na
494 \fB\fB--include[=\fR\fIdirectory\fR\fB]\fR\fR
495 .ad
496 .RS 25n
497 Append directory to the list of directories searched for \fB#include\fR files.
498 .sp
499 If directory is \fB-\fR:
500 .RS +4
501 .TP
502 1.
503 \fB-I\fR directories before \fB-I-\fR are searched only for \fB"..."\fR
504 include files
505 .RE
506 .RS +4
507 .TP
508 2.
509 \fB-I\fR directories after \fB-I-\fR are searched for \fB"..."\fR and
510 \fB<"...">\fR include files
511 .RE
512 .RS +4
513 .TP
514 3.
515 the directory \fB\&.\fR is searched only if it is explicitly specified by an
516 \fB-I\fR option
517 .RE
518 .sp
519 .ne 2
520 .na
521 \fB\fB-I-C\fR\fIdirectory\fR\fR
522 .ad
523 .br
524 .na
525 \fB\fBpp:cdir directory\fR\fR
526 .ad
527 .sp .6
528 .RS 4n
529 Mark \fIdirectory\fR as a C header directory. This option is used with
530 \fBpp:plusplus\fR.
531 .RE
533 .sp
534 .ne 2
535 .na
536 \fB\fB-I-D[\fR\fIfile\fR]\fR
537 .ad
538 .sp .6
539 .RS 4n
540 Read the default \fBprobe\fR definitions from \fIfile\fR, or ignore the default
541 definitions if \fIfile\fR is omitted.
542 .RE
544 .sp
545 .ne 2
546 .na
547 \fB\fB-I-H\fR\fIdirectory\fR\fR
548 .ad
549 .br
550 .na
551 \fB\fBpp:hostdir\fR \fIdirectory\fR\fR
552 .ad
553 .sp .6
554 .RS 4n
555 Mark directory as a hosted directory. Headers from hosted directories have
556 compatibility warnings disabled.
557 .RE
559 .sp
560 .ne 2
561 .na
562 \fB\fB-I-I\fR\fIheader\fR\fR
563 .ad
564 .br
565 .na
566 \fB\fBpp:ignore\fR \fIheader\fR\fR
567 .ad
568 .sp .6
569 .RS 4n
570 Add \fIheader\fR to the list of ignored headers.
571 .RE
573 .sp
574 .ne 2
575 .na
576 \fB\fB-I-M\fR\fIfile\fR\fR
577 .ad
578 .sp .6
579 .RS 4n
580 \fIfile\fR contains a sequence of header \fB[= "map" ]\fR lines, where header
581 is either \fB<name>\fR or \fB"name"\fR, and \fB"map"\fR is an explicit binding
582 for header. header is ignored \fBif = "map"\fR is omitted.
583 .RE
585 .sp
586 .ne 2
587 .na
588 \fB\fB-I-R\fR\fIfile\fR\fR
589 .ad
590 .sp .6
591 .RS 4n
592 Include \fIfile\fR but do not emit text or line syncs.
593 .RE
595 .sp
596 .ne 2
597 .na
598 \fB\fB-I-S\fR\fIdirectory\fR\fR
599 .ad
600 .sp .6
601 .RS 4n
602 Add \fIdirectory\fR to the default standard include directory list.
603 .RE
605 .sp
606 .ne 2
607 .na
608 \fB\fB-I-T\fR\fIfile\fR\fR
609 .ad
610 .sp .6
611 .RS 4n
612 Include \fIfile\fR and emit text to the output file. The option value can be
613 omitted.
614 .RE
616 .RE
618 .sp
619 .ne 2
620 .na
621 \fB\fB-M\fR\fR
622 .ad
623 .br
624 .na
625 \fB\fB--dependencies\fR\fR
626 .ad
627 .RS 25n
628 Generate \fBmake\fR(1S) dependencies. This option is not needed with
629 \fBnmake\fR.
630 .sp
631 The \fB-M\fR option can be followed by optional flags to change the dependency
632 output styles.
633 .sp
634 The following optional flags are supported:
635 .sp
636 .ne 2
637 .na
638 \fB\fBD\fR\fR
639 .ad
640 .RS 5n
641 Generate dependencies in a separate \fB\&.d\fR file. Preprocessed output is
642 still written to output, or the standard output if output is omitted.
643 .RE
645 .sp
646 .ne 2
647 .na
648 \fB\fBG\fR\fR
649 .ad
650 .RS 5n
651 Also generate missing dependencies.
652 .RE
654 .sp
655 .ne 2
656 .na
657 \fB\fBM\fR\fR
658 .ad
659 .RS 5n
660 Only generate local header dependencies. Hosted headers are omitted. Hosted
661 headers are determined by the \fB-I-H\fR option and the -\fB-pp:hosted\fR and
662 \fBpp:hostdir pragmas\fR. No special distinction is made between the \fB""\fR
663 and \fB<>\fR include styles.
664 .RE
666 .RE
668 .sp
669 .ne 2
670 .na
671 \fB\fB-P\fR\fR
672 .ad
673 .br
674 .na
675 \fB\fB--sync\fR\fR
676 .ad
677 .RS 25n
678 Emit line syncs.
679 .sp
680 Line sync is turned on by default. \fB-P\fR means \fB--nosync\fR.
681 .RE
683 .sp
684 .ne 2
685 .na
686 \fB\fB-T\fR\fB[\fR\fIlength\fR\fB]\fR\fR
687 .ad
688 .RS 25n
689 If not \fBgcc\fR, truncate identifiers to \fIlength\fR characters for
690 compatibility with old AT&T compilers.
691 .RE
693 .sp
694 .ne 2
695 .na
696 \fB\fB-U\fR\fR
697 .ad
698 .br
699 .na
700 \fB\fB--undefine=\fR\fIname\fR\fR
701 .ad
702 .RS 25n
703 Remove the definition for the macro \fIname\fR.
704 .RE
706 .sp
707 .ne 2
708 .na
709 \fB\fB-V\fR\fR
710 .ad
711 .br
712 .na
713 \fB\fB--version\fR\fR
714 .ad
715 .RS 25n
716 Emit the \fBlibpp\fR version.
717 .RE
719 .sp
720 .ne 2
721 .na
722 \fB\fB-X\fR\fR
723 .ad
724 .br
725 .na
726 \fB\fB--argmode\fR\fR
727 .ad
728 .RS 25n
729 Enable \fIname\fR\fB=\fR\fIvalue\fR macro arguments for \fBeasel\fR
730 compatibility.
731 .RE
733 .sp
734 .ne 2
735 .na
736 \fB\fB-Y\fR\fR
737 .ad
738 .br
739 .na
740 \fB\fB--standard=\fR\fIdirectory\fR\fR
741 .ad
742 .RS 25n
743 Add \fIdirectory\fR to the list searched for \fB#include <...>\fR files.
744 .RE
746 .SH OPERANDS
747 .sp
748 .LP
749 The following operands are supported:
750 .sp
751 .ne 2
752 .na
753 \fB\fIinput\fR\fR
754 .ad
755 .RS 10n
756 Specifies C source file to preprocess.
757 .RE
759 .sp
760 .ne 2
761 .na
762 \fB\fIoutput\fR\fR
763 .ad
764 .RS 10n
765 Specifies output file.
766 .RE
768 .SH EXIT STATUS
769 .sp
770 .ne 2
771 .na
772 \fB\fB0\fR\fR
773 .ad
774 .RS 6n
775 Successful completion.
776 .RE
778 .sp
779 .ne 2
780 .na
781 \fB\fB>0\fR\fR
782 .ad
783 .RS 6n
784 An error occurred.
785 .RE
787 .SH EXAMPLES
788 .LP
789 \fBExample 1 \fRUsing \fBmsgcpp\fR to Extract Localizable Strings
790 .sp
791 .LP
792 The following example uses \fBmsgcpp\fR to extract localizable strings from the
793 file \fBhello.c\fR, marked using the \fBERROR_dictionary()\fR, and writes them
794 to the file \fBhello.mso\fR:
796 .sp
797 .in +2
798 .nf
799 example% cat hello.c
802 #include <stdio.h>
803 #include <stdlib.h>
805 /*
806 * dummy macro to avoid including
807 * libast headers
808 */
809 #define ERROR_dictionary(x) x
811 int main(int ac, char *av[])
812 {
813 puts( ERROR_dictionary("hello world") );
814 puts( ERROR_dictionary("hello all") );
815 return( EXIT_SUCCESS );
816 }
818 example% msgcpp -D__STDC__ -D__i386 hello.c hello.mso
820 example% cat hello.mso
821 str "hello world"
822 str "hello all"
823 .fi
824 .in -2
825 .sp
827 .SH AUTHORS
828 .sp
829 .LP
830 Glenn Fowler, \fBgsf@research.att.com\fR
831 .SH ATTRIBUTES
832 .sp
833 .LP
834 See \fBattributes\fR(5) for descriptions of the following attributes:
835 .sp
837 .sp
838 .TS
839 box;
840 c | c
841 l | l .
842 ATTRIBUTE TYPE ATTRIBUTE VALUE
843 _
844 Interface Stability Volatile
845 .TE
847 .SH SEE ALSO
848 .sp
849 .LP
850 \fBcpp\fR(1), \fBgencat\fR(1), \fBmsgcc\fR(1), \fBmsgcvt\fR(1),
851 \fBmsggen\fR(1), \fBmake\fR(1S), \fBattributes\fR(5)
852 .sp
853 .LP
854 Kernighan, Brian W. and Ritchie, Dennis M., \fIThe C Programming Language\fR,
855 Prentice Hall, 1988.