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

.\"
.\" 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/.
.\"
.\" 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 are reprinted and reproduced in electronic form
.\" in the SunOS 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 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" 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.
.\" 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 the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH YACC 1 "Aug 24, 2009"
.SH NAME
yacc \- yet another compiler-compiler
.SH SYNOPSIS
.LP
.nf
\fByacc\fR [\fB-dltVv\fR] [\fB-b\fR \fIfile_prefix\fR] [\fB-Q\fR [y | n]]
      [\fB-P\fR \fIparser\fR] [\fB-p\fR \fIsym_prefix\fR] \fIfile\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fByacc\fR command converts a context-free grammar into a set of tables for
a simple automaton that executes an LALR(1) parsing algorithm. The grammar can
be ambiguous. Specified precedence rules are used to break ambiguities.
.sp
.LP
The output file, \fBy.tab.c\fR, must be compiled by the C compiler to produce a
function \fByyparse()\fR. This program must be loaded with the lexical analyzer
program, \fByylex()\fR, as well as \fBmain()\fR and \fByyerror()\fR, an error
handling routine. These routines must be supplied by the user. The \fBlex\fR(1)
command is useful for creating lexical analyzers usable by \fByacc\fR.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-b\fR \fIfile_prefix\fR\fR
.ad
.RS 18n
Uses \fIfile_prefix\fR instead of \fBy\fR as the prefix for all output files.
The code file \fBy.tab.c\fR, the header file \fBy.tab.h\fR (created when
\fB-d\fR is specified), and the description file \fBy.output\fR (created when
\fB-v\fR is specified), is changed to \fIfile_prefix\fR\fB\&.tab.c\fR,
\fIfile_prefix\fR\fB\&.tab.h\fR, and \fIfile_prefix\fR\fB\&.output\fR,
respectively.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 18n
Generates the file \fBy.tab.h\fR with the \fB#define\fR statements that
associate the \fByacc\fR user-assigned "token codes" with the user-declared
"token names". This association allows source files other than \fBy.tab.c\fR to
access the token codes.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 18n
Specifies that the code produced in \fBy.tab.c\fR does not contain any
\fB#line\fR constructs. This option should only be used after the grammar and
the associated actions are fully debugged.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIsym_prefix\fR\fR
.ad
.RS 18n
Uses \fIsym_prefix\fR instead of \fByy\fR as the prefix for all external names
produced by \fByacc\fR. The names affected include the functions
\fByyparse()\fR, \fByylex()\fR and \fByyerror()\fR, and the variables
\fIyylval\fR, \fIyychar\fR and \fIyydebug\fR. (In the remainder of this
section, the six symbols cited are referenced using their default names only as
a notational convenience.) Local names can also be affected by the \fB-p\fR
option. However, the \fB-p\fR option does not affect \fB#define\fR symbols
generated by \fByacc\fR.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIparser\fR\fR
.ad
.RS 18n
Allows you to specify the parser of your choice instead of
\fB/usr/share/lib/ccs/yaccpar\fR. For example, you can specify:
.sp
.in +2
.nf
example% \fByacc -P ~/myparser parser.y\fR
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-Q\fR[\fBy\fR|\fBn\fR]\fR
.ad
.RS 18n
The \fB-Qy\fR option puts the version stamping information in \fBy.tab.c\fR.
This allows you to know what version of \fByacc\fR built the file. The
\fB-Qn\fR option (the default) writes no version information.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 18n
Compiles runtime debugging code by default. Runtime debugging code is always
generated in \fBy.tab.c\fR under conditional compilation control. By default,
this code is not included when \fBy.tab.c\fR is compiled. Whether or not the
\fB-t\fR option is used, the runtime debugging code is under the control of
\fBYYDEBUG\fR , a preprocessor symbol. If \fBYYDEBUG\fR has a non-zero value,
then the debugging code is included. If its value is \fB0\fR, then the code is
not included. The size and execution time of a program produced without the
runtime debugging code is smaller and slightly faster.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 18n
Prepares the file \fBy.output\fR, which contains a description of the parsing
tables and a report on conflicts generated by ambiguities in the grammar.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 18n
Prints on the standard error output the version information for \fByacc\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operand is required:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
A path name of a file containing instructions for which a parser is to be
created.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAccessing the yacc Library
.sp
.LP
Access to the \fByacc\fR library is obtained with library search operands to
\fBcc\fR. To use the \fByacc\fR library \fBmain\fR:

.sp
.in +2
.nf
example% \fBcc y.tab.c -ly\fR
.fi
.in -2
.sp

.sp
.LP
Both the \fBlex\fR library and the \fByacc\fR library contain \fBmain\fR. To
access the \fByacc\fR \fBmain\fR:

.sp
.in +2
.nf
example% \fBcc y.tab.c lex.yy.c -ly -ll\fR
.fi
.in -2
.sp

.sp
.LP
This ensures that the \fByacc\fR library is searched first, so that its
\fBmain\fR is used.

.sp
.LP
The historical \fByacc\fR libraries have contained two simple functions that
are normally coded by the application programmer. These library functions are
similar to the following code:

.sp
.in +2
.nf
#include <locale.h>
int main(void)
{
        extern int yyparse();

        setlocale(LC_ALL, "");

        /* If the following parser is one created by lex, the
           application must be careful to ensure that LC_CTYPE
           and LC_COLLATE are set to the POSIX locale.  */
        (void) yyparse();
        return (0);
}

#include <stdio.h>

int yyerror(const char *msg)
{
        (void) fprintf(stderr, "%s\en", msg);
        return (0);
}
.fi
.in -2

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fByacc\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.LP
\fByacc\fR can handle characters from \fBEUC\fR primary and supplementary
codesets as one-token symbols. \fBEUC\fR codes can only be single character
quoted terminal symbols. \fByacc\fR expects \fByylex()\fR to return a wide
character (\fBwchar_t\fR) value for these one-token symbols.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.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 FILES
.sp
.ne 2
.na
\fB\fBy.output\fR\fR
.ad
.RS 14n
state transitions of the generated parser
.RE

.sp
.ne 2
.na
\fB\fBy.tab.c\fR\fR
.ad
.RS 14n
source code of the generated parser
.RE

.sp
.ne 2
.na
\fB\fBy.tab.h\fR\fR
.ad
.RS 14n
header file for the generated parser
.RE

.sp
.ne 2
.na
\fB\fByacc.acts\fR\fR
.ad
.RS 14n
temporary file
.RE

.sp
.ne 2
.na
\fB\fByacc.debug\fR\fR
.ad
.RS 14n
temporary file
.RE

.sp
.ne 2
.na
\fB\fByacc.tmp\fR\fR
.ad
.RS 14n
temporary file
.RE

.sp
.ne 2
.na
\fB\fByaccpar\fR\fR
.ad
.RS 14n
parser prototype for C programs
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBlex\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
.SH DIAGNOSTICS
.sp
.LP
The number of reduce-reduce and shift-reduce conflicts is reported on the
standard error output. A more detailed report is found in the \fBy.output\fR
file. Similarly, if some rules are not reachable from the start symbol, this
instance is also reported.
.SH NOTES
.sp
.LP
Because file names are fixed, at most one \fByacc\fR process can be active in a
given directory at a given time.
.sp
.LP
Users are encouraged to avoid using \fB$\fR as part of any identifier name.