usr/src/man/man1/yacc.1

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