usr/src/man/man1/yacc.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved  Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
   4 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
   5 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
   6 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   9 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
  10 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  11 .TH YACC 1 "Aug 24, 2009"
  12 .SH NAME
  13 yacc \- yet another compiler-compiler
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 \fByacc\fR [\fB-dltVv\fR] [\fB-b\fR \fIfile_prefix\fR] [\fB-Q\fR [y | n]]
  18       [\fB-P\fR \fIparser\fR] [\fB-p\fR \fIsym_prefix\fR] \fIfile\fR
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fByacc\fR command converts a context-free grammar into a set of tables for
  25 a simple automaton that executes an LALR(1) parsing algorithm. The grammar can
  26 be ambiguous. Specified precedence rules are used to break ambiguities.
  27 .sp
  28 .LP
  29 The output file, \fBy.tab.c\fR, must be compiled by the C compiler to produce a
  30 function \fByyparse()\fR. This program must be loaded with the lexical analyzer
  31 program, \fByylex()\fR, as well as \fBmain()\fR and \fByyerror()\fR, an error
  32 handling routine. These routines must be supplied by the user. The \fBlex\fR(1)
  33 command is useful for creating lexical analyzers usable by \fByacc\fR.
  34 .SH OPTIONS
  35 .sp
  36 .LP
  37 The following options are supported:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB-b\fR \fIfile_prefix\fR\fR
  42 .ad
  43 .RS 18n
  44 Uses \fIfile_prefix\fR instead of \fBy\fR as the prefix for all output files.
  45 The code file \fBy.tab.c\fR, the header file \fBy.tab.h\fR (created when
  46 \fB-d\fR is specified), and the description file \fBy.output\fR (created when
  47 \fB-v\fR is specified), is changed to \fIfile_prefix\fR\fB\&.tab.c\fR,
  48 \fIfile_prefix\fR\fB\&.tab.h\fR, and \fIfile_prefix\fR\fB\&.output\fR,
  49 respectively.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fB-d\fR\fR
  56 .ad
  57 .RS 18n
  58 Generates the file \fBy.tab.h\fR with the \fB#define\fR statements that
  59 associate the \fByacc\fR user-assigned "token codes" with the user-declared
  60 "token names". This association allows source files other than \fBy.tab.c\fR to
  61 access the token codes.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fB-l\fR\fR
  68 .ad
  69 .RS 18n
  70 Specifies that the code produced in \fBy.tab.c\fR does not contain any
  71 \fB#line\fR constructs. This option should only be used after the grammar and
  72 the associated actions are fully debugged.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fB-p\fR \fIsym_prefix\fR\fR
  79 .ad
  80 .RS 18n
  81 Uses \fIsym_prefix\fR instead of \fByy\fR as the prefix for all external names
  82 produced by \fByacc\fR. The names affected include the functions
  83 \fByyparse()\fR, \fByylex()\fR and \fByyerror()\fR, and the variables
  84 \fIyylval\fR, \fIyychar\fR and \fIyydebug\fR. (In the remainder of this
  85 section, the six symbols cited are referenced using their default names only as
  86 a notational convenience.) Local names can also be affected by the \fB-p\fR
  87 option. However, the \fB-p\fR option does not affect \fB#define\fR symbols
  88 generated by \fByacc\fR.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fB-P\fR \fIparser\fR\fR
  95 .ad
  96 .RS 18n
  97 Allows you to specify the parser of your choice instead of
  98 \fB/usr/share/lib/ccs/yaccpar\fR. For example, you can specify:
  99 .sp
 100 .in +2
 101 .nf
 102 example% \fByacc -P ~/myparser parser.y\fR
 103 .fi
 104 .in -2
 105 .sp
 106
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB-Q\fR[\fBy\fR|\fBn\fR]\fR
 113 .ad
 114 .RS 18n
 115 The \fB-Qy\fR option puts the version stamping information in \fBy.tab.c\fR.
 116 This allows you to know what version of \fByacc\fR built the file. The
 117 \fB-Qn\fR option (the default) writes no version information.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB-t\fR\fR
 124 .ad
 125 .RS 18n
 126 Compiles runtime debugging code by default. Runtime debugging code is always
 127 generated in \fBy.tab.c\fR under conditional compilation control. By default,
 128 this code is not included when \fBy.tab.c\fR is compiled. Whether or not the
 129 \fB-t\fR option is used, the runtime debugging code is under the control of
 130 \fBYYDEBUG\fR , a preprocessor symbol. If \fBYYDEBUG\fR has a non-zero value,
 131 then the debugging code is included. If its value is \fB0\fR, then the code is
 132 not included. The size and execution time of a program produced without the
 133 runtime debugging code is smaller and slightly faster.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fB-v\fR\fR
 140 .ad
 141 .RS 18n
 142 Prepares the file \fBy.output\fR, which contains a description of the parsing
 143 tables and a report on conflicts generated by ambiguities in the grammar.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fB-V\fR\fR
 150 .ad
 151 .RS 18n
 152 Prints on the standard error output the version information for \fByacc\fR.
 153 .RE
 154
 155 .SH OPERANDS
 156 .sp
 157 .LP
 158 The following operand is required:
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fIfile\fR\fR
 163 .ad
 164 .RS 8n
 165 A path name of a file containing instructions for which a parser is to be
 166 created.
 167 .RE
 168
 169 .SH EXAMPLES
 170 .LP
 171 \fBExample 1 \fRAccessing the yacc Library
 172 .sp
 173 .LP
 174 Access to the \fByacc\fR library is obtained with library search operands to
 175 \fBcc\fR. To use the \fByacc\fR library \fBmain\fR:
 176
 177 .sp
 178 .in +2
 179 .nf
 180 example% \fBcc y.tab.c -ly\fR
 181 .fi
 182 .in -2
 183 .sp
 184
 185 .sp
 186 .LP
 187 Both the \fBlex\fR library and the \fByacc\fR library contain \fBmain\fR. To
 188 access the \fByacc\fR \fBmain\fR:
 189
 190 .sp
 191 .in +2
 192 .nf
 193 example% \fBcc y.tab.c lex.yy.c -ly -ll\fR
 194 .fi
 195 .in -2
 196 .sp
 197
 198 .sp
 199 .LP
 200 This ensures that the \fByacc\fR library is searched first, so that its
 201 \fBmain\fR is used.
 202
 203 .sp
 204 .LP
 205 The historical \fByacc\fR libraries have contained two simple functions that
 206 are normally coded by the application programmer. These library functions are
 207 similar to the following code:
 208
 209 .sp
 210 .in +2
 211 .nf
 212 #include <locale.h>
 213 int main(void)
 214 {
 215         extern int yyparse();
 216
 217         setlocale(LC_ALL, "");
 218
 219         /* If the following parser is one created by lex, the
 220            application must be careful to ensure that LC_CTYPE
 221            and LC_COLLATE are set to the POSIX locale.  */
 222         (void) yyparse();
 223         return (0);
 224 }
 225
 226 #include <stdio.h>
 227
 228 int yyerror(const char *msg)
 229 {
 230         (void) fprintf(stderr, "%s\en", msg);
 231         return (0);
 232 }
 233 .fi
 234 .in -2
 235
 236 .SH ENVIRONMENT VARIABLES
 237 .sp
 238 .LP
 239 See \fBenviron\fR(5) for descriptions of the following environment variables
 240 that affect the execution of \fByacc\fR: \fBLANG\fR, \fBLC_ALL\fR,
 241 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 242 .sp
 243 .LP
 244 \fByacc\fR can handle characters from \fBEUC\fR primary and supplementary
 245 codesets as one-token symbols. \fBEUC\fR codes can only be single character
 246 quoted terminal symbols. \fByacc\fR expects \fByylex()\fR to return a wide
 247 character (\fBwchar_t\fR) value for these one-token symbols.
 248 .SH EXIT STATUS
 249 .sp
 250 .LP
 251 The following exit values are returned:
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fB0\fR\fR
 256 .ad
 257 .RS 6n
 258 Successful completion.
 259 .RE
 260
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fB>0\fR\fR
 265 .ad
 266 .RS 6n
 267 An error occurred.
 268 .RE
 269
 270 .SH FILES
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBy.output\fR\fR
 275 .ad
 276 .RS 14n
 277 state transitions of the generated parser
 278 .RE
 279
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBy.tab.c\fR\fR
 284 .ad
 285 .RS 14n
 286 source code of the generated parser
 287 .RE
 288
 289 .sp
 290 .ne 2
 291 .na
 292 \fB\fBy.tab.h\fR\fR
 293 .ad
 294 .RS 14n
 295 header file for the generated parser
 296 .RE
 297
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fByacc.acts\fR\fR
 302 .ad
 303 .RS 14n
 304 temporary file
 305 .RE
 306
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fByacc.debug\fR\fR
 311 .ad
 312 .RS 14n
 313 temporary file
 314 .RE
 315
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fByacc.tmp\fR\fR
 320 .ad
 321 .RS 14n
 322 temporary file
 323 .RE
 324
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fByaccpar\fR\fR
 329 .ad
 330 .RS 14n
 331 parser prototype for C programs
 332 .RE
 333
 334 .SH ATTRIBUTES
 335 .sp
 336 .LP
 337 See \fBattributes\fR(5) for descriptions of the following attributes:
 338 .sp
 339
 340 .sp
 341 .TS
 342 box;
 343 c | c
 344 l | l .
 345 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 346 _
 347 Interface Stability     Committed
 348 _
 349 Standard        See \fBstandards\fR(5).
 350 .TE
 351
 352 .SH SEE ALSO
 353 .sp
 354 .LP
 355 \fBlex\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
 356 .SH DIAGNOSTICS
 357 .sp
 358 .LP
 359 The number of reduce-reduce and shift-reduce conflicts is reported on the
 360 standard error output. A more detailed report is found in the \fBy.output\fR
 361 file. Similarly, if some rules are not reachable from the start symbol, this
 362 instance is also reported.
 363 .SH NOTES
 364 .sp
 365 .LP
 366 Because file names are fixed, at most one \fByacc\fR process can be active in a
 367 given directory at a given time.
 368 .sp
 369 .LP
 370 Users are encouraged to avoid using \fB$\fR as part of any identifier name.