STANDARD INPUT

None.

INPUT FILES

The file grammar shall be a text file formatted as specified in A.3.7.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of yacc:

LANG

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

LC_ALL

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files).

LC_MESSAGES

This variable shall determine the language in which messages should be written. The LANG and LC_ ∗ variables shall affect the execution of the yacc utility as stated. The main() function defined in A.3.7.6 shall call

setlocale( LC_ALL, "") and thus, the program generated by yacc shall also be affected by the the contents of these variables at runtime.

ASYNCHRONOUS EVENTS

Default.

STANDARD OUTPUT

None.

STANDARD ERROR

If shift/reduce or reduce/reduce conflicts are detected in grammar, yacc writes a report of those conflicts to the standard error in an unspecified format. Standard error is also used for diagnostic messages.

OUTPUT FILES

The code file, the header file, and the description file shall be text files. All are described in the following subclauses.

CODE FILE

This file shall contain the C source code for the yyparse() routine. It shall contain code for the various semantic actions with macro substitution performed on them as described in A.3.7. It shall also contain a copy of the #define statements in the header file. If a %union declaration is used, the declaration for YYSTYPE shall be also included in this file.

The contents of the Program Section (see A.3.7.1.4) of the input file shall then be included.

HEADER FILE

The header file shall contain #define statements that associate the token numbers with the token names. This allows source files other than the code file to access the token codes. If a %union declaration is used, the declaration for YYS - TYPE and an extern YYSTYPE yylval declaration shall be also included in this file.

A C Language Development Utilities Option

DESCRIPTION FILE

The description file shall be a text file containing a description of the state machine corresponding to the parser, using an unspecified format. Limits for internal tables (see A.3.7.9) also shall be reported, in an implementation-defined manner.

INPUT LANGUAGE

Every specification file shall consist of three sections: declarations, grammar rules, and programs, separated by double percent-signs (%%). The declarations and programs sections can be empty. If the latter is empty, the preceding %% mark separating it from the rules section can be omitted. The input is free form text following the structure of the grammar defined below.

LEXICAL STRUCTURE OF THE GRAMMAR

The characters <blank>s, <newline>s, and <form-feed>s shall be ignored, except that they shall not appear in names or multicharacter reserved symbols. Comments shall be enclosed in /∗ . . . ∗/, and can appear wherever a name is valid.

Names are of arbitrary length, made up of letters, periods (.), underscores (_), and noninitial digits. Upper- and lowercase letters are distinct. Portable applications shall not use names beginning in yy or YY since the yacc parser uses such names. Many of the names appear in the final output of yacc, and thus they should be chosen to conform with any additional rules created by the C compiler to be used. In particular they will appear in #define statements. A literal shall consist of a single character enclosed in single-quotes (′). All of the escape sequences supported for character constants by the C Standard {7} (3.1.3.4) shall be supported by yacc. The relationship with the lexical analyzer is discussed in detail below. The NUL character shall not be used in grammar rules or literals.

DECLARATIONS SECTION

The declarations section is used to define the symbols used to define the target language and their relationship with each other. In particular, much of the additional information required to resolve ambiguities in the context-free grammar for the target language is provided here. Usually yacc assigns the relationship between the symbolic names it generates and their underlying numeric value. The declarations section makes it possible to control the assignment of these values. It is also possible to keep semantic information associated with the tokens currently on the parse stack in a user-defined C language union, if the members of the union are associated with the various names in the grammar. The declarations section provides for this as well. The first group of declarators below all take a list of names as arguments. That list can optionally be preceded by the name of a C union member (called a tag below) appearing within ‘‘<’’ and ‘‘>’’. (As an exception to the typographical conventions of the rest of this standard, in this case <tag> does not represent a metavariable, but the literal angle bracket characters surrounding a symbol.) The use of tag specifies that the tokens named on this line are to be of the same C type as the union member referenced by tag. This is discussed in more detail below. For lists used to define tokens, the first appearance of a given token can be followed by a positive integer (as a string of decimal digits). If this is done, the underlying value assigned to it for lexical purposes shall be taken to be that number. %token [<tag>] name [number] [name [number] ]. . . Declares name(s) to be a token. If tag is present, the C type for all tokens on this line shall be declared to be the type referenced by tag. If a positive integer, number, follows a name, that value shall be assigned to the token. %left [<tag>] name [number] [name [number] ]. . . %right [<tag>] name [number] [name [number] ]. . . Declares name to be a token, and assigns precedence to it. One or

A C Language Development Utilities Option

more lines, each beginning with one of these symbols can appear in this section. All tokens on the same line have the same precedence level and associativity; the lines are in order of increasing precedence or binding strength. %left denotes that the operators on that line are left associative, and %right similarly denotes right associative operators. If tag is present, it shall declare a C type for name(s) as described for %token. %nonassoc [<tag>] name [number] [name [number] ]. . . Declares name to be a token, and indicates that this cannot be used associatively. If the parser encounters associative use of this token it shall report an error. If tag is present, it shall declare a C type for name(s) as described for %token. %type <tag> name. . . Declares that union member name(s) are nonterminals, and thus it is required to have a tag field at its beginning. Because it deals with nonterminals only, assigning a token number or using a literal is also prohibited. If this construct is present, yacc shall perform type checking; if this construct is not present, the parse stack shall hold only the int type. Every name used in grammar undefined by a %token, %left, %right, or %nonassoc declaration is assumed to represent a nonterminal symbol. The yacc utility shall report an error for any nonterminal symbol that does not appear on the left side of at least one grammar rule. Once the type, precedence, or token number of a name is specified, it shall not be changed. If the first declaration of a token does not assign a token number, yacc shall assign a token number. Once this assignment is made, the token number shall not be changed by explicit assignment. The following declarators do not follow the previous pattern. %start name Declares the nonterminal name to be the start symbol, which represents the largest, most general structure described by the grammar rules. By default, it is the left-hand side of the first grammar rule; this default can be overridden with this declaration. %union { body of union (in C) } Declares the yacc value stack to be a union of the various types of values desired. By default, the values returned by actions (see below) and the lexical analyzer shall be integers. The yacc utility keeps track of types, and shall insert corresponding union member names in order to perform strict type checking of the resulting parser. Alternatively, given that at least one <tag> construct is used, the union can be declared in a header file (which shall be included in the declarations section by using an #include construct within

%{ and %}), and a typedef used to define the symbol YYSTYPE to represent this union. The effect of %union is to provide the declaration of YYSTYPE directly from the input. %{ . . . %} C language declarations and definitions can appear in the declarations section, enclosed by these marks. These statements shall be copied into the code file, and have global scope within it so that they can be used in the rules and program sections. The declarations section shall be terminated by the token %%.

GRAMMAR RULES

The rules section defines the context-free grammar to be accepted by the function yacc generates, and associates with those rules C language actions and additional precedence information. The grammar is described below, and a formal definition follows. The rules section is comprised of one or more grammar rules. A grammar rule has the form: A : BODY ;

The symbol A represents a nonterminal name, and BODY represents a sequence of zero or more names, literals, and semantic actions that can then be followed by optional precedence rules. Only the names and literals participate in the formation of the grammar; the semantic actions and precedence rules are used in other ways. The colon and the semicolon are yacc punctuation. If there are several successive grammar rules with the same left-hand side, the vertical bar | can be used to avoid rewriting the left-hand side; in this case the semicolon appears only after the last rule. The BODY part can be empty (or empty of names and literals) to indicate that the nonterminal symbol matches the empty string. The yacc utility assigns a unique number to each rule. Rules using the vertical bar notation are distinct rules. The number assigned to the rule appears in the description file. The elements comprising a BODY are: name literal These form the rules of the grammar: name is either a token or a nonterminal; literal stands for itself (less the lexically required quotation marks). semantic action With each grammar rule, the user can associate actions to be performed each time the rule is recognized in the input process. [Note that the word ‘‘action’’ can also refer to the actions of the parser (shift, reduce, etc.).] These actions can return values and can obtain the values returned by previous actions. These values shall be kept in objects of type YYSTYPE (see %union). The result value of the action shall be kept on the parse stack with the left-hand side of

A C Language Development Utilities Option

the rule, to be accessed by other reductions as part of their righthand side. By using the <tag> information provided in the declarations section, the code generated by yacc can be strictly type checked and contain arbitrary information. In addition, the lexical analyzer can provide the same kinds of values for tokens, if desired. An action is an arbitrary C statement, and as such can do input or output, call subprograms, and alter external variables. An action is one or more C statements enclosed in curly braces { and }. Certain pseudo-variables can be used in the action. These are macros for access to data structures known interally to yacc. $$ The value of the action can be set by assigning it to $$. If type checking is enabled and the type of the value to be assigned cannot be determined, a diagnostic message may be generated. $number This refers to the value returned by the component specified by the token number in the right side of a rule, reading from left to right; number can be zero or negative. If it is, it refers to the data associated with the name on the parser’s stack preceding the leftmost symbol of the current rule. (That is, $0 refers to the name immediately preceding the leftmost name in the current rule, to be found on the parser’s stack, and $-1 refers to the symbol to its left.) If number refers to an element past the current point in the rule, or beyond the bottom of the stack, the result is undefined. If type checking is enabled and the type of the value to be assigned cannot be determined, a diagnostic message may be generated. $<tag>number These correspond exactly to the corresponding symbols without the tag inclusion, but allow for strict type checking (and preclude unwanted type conversions). The effect is that the macro is expanded to use tag to select an element from the YYSTYPE union (using dataname.tag). This is particularly useful if number is not positive.

$<tag>$ This imposes on the reference the type of the union member referenced by tag. This construction is applicable when a reference to a left context value occurs in the grammar, and provides yacc with a means for selecting a type.

Actions can occur in the middle of a rule as well as at the end; an action can access values returned by actions to its left, and in turn the value it returns can be accessed by actions to its right. An action appearing in the middle of a rule shall be equivalent to replacing the action with a new nonterminal symbol and adding an empty rule with that nonterminal symbol on the left-hand side. The semantic action associated with the new rule shall be equivalent to the original action. The use of actions within rules might introduce conflicts that would not otherwise exist. By default, the value of a rule shall be the value of the first element in it. If the first element does not have a type (particularly in the case of a literal) and type checking is turned on by %type an error message shall result. precedence The keyword %prec can be used to change the precedence level associated with a particular grammar rule. Examples of this are in cases where a unary and binary operator have the same symbolic representation, but need to be given different precedences, or where the handling of an ambiguous if-else construction is necessary. The reserved symbol %prec can appear immediately after the body of the grammar rule and can be followed by a token name or a literal. It shall cause the precedence of the grammar rule to become that of the following token name or literal. The action for the rule as a whole can follow %prec. If a program section follows, the grammar rules shall be terminated by %%.

PROGRAMS SECTION

The programs section can include the definition of the lexical analyzer yylex(), and any other functions, for example those used in the actions specified in the grammar rules. This is C language code, and shall be included in the code file after the tables and code generated by yacc. It is unspecified whether the programs section precedes or follows the semantic actions in the output file; therefore, if the application contains any macro definitions and declarations intended to apply to the code in the semantic actions, it shall place them within %{ . . . %} in the declarations section.

INPUT GRAMMAR

The following input to yacc yields a parser for the input to yacc. This is to be taken as the formal specification of the grammar of yacc, notwithstanding conflicts that may appear elsewhere. The lexical structure is defined less precisely; the previous section on A.3.7.1.1 defines most terms. The correspondence between the previous terms and the tokens below is as follows. IDENTIFIER This corresponds to the concept of name, given previously. It also includes literals as defined previously.

A C Language Development Utilities Option

C_IDENTIFIER This is a name, and additionally it is known to be followed by a colon. A literal cannot yield this token. NUMBER A string of digits (a nonnegative decimal integer). TYPE LEFT MARK etc. These correspond directly to %type, %left, %%, etc. { ... } This indicates C language source code, with the possible inclusion of $ macros as discussed previously.

/∗ Grammar for the input to yacc ∗/ /∗ Basic entries ∗/ /∗ The following are recognized by the lexical analyzer ∗/ %token IDENTIFIER /∗ includes identifiers and literals ∗/ %token C_IDENTIFIER /∗ identifier (but not literal) followed by a : ∗/ %token NUMBER /∗ [0-9][0-9]∗ ∗/ /∗ Reserved words : %type=> TYPE %left=> LEFT, etc. ∗/ %token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION

%token MARK /∗ the %% mark ∗/ %token LCURL /∗ the %{ mark ∗/ %token RCURL /∗ the }% mark ∗/ /∗ 8-bit character literals stand for themselves; ∗/ /∗ tokens have to be defined for multibyte characters ∗/ %start spec

%% spec : defs MARK rules tail ; tail : MARK { /∗ In this action, set up the rest of the file ∗/ }

; defs : /∗ empty ∗/

; def : START IDENTIFIER

{ /∗ Copy union definition to output ∗/

}

{ /∗ Copy C code to output file ∗/ } RCURL

; rword : TOKEN

; tag : /∗ empty: union tag id optional ∗/

; nlist : nmno

; nmno : IDENTIFIER /∗ Note: literal invalid with % type ∗/

; /∗ rule section ∗/ rules : C_IDENTIFIER rbody prec

; rule : C_IDENTIFIER rbody prec

; rbody : /∗ empty ∗/

; act : ’{’ { /∗ Copy action, translate $$, etc. ∗/ } ’}’ ; prec : /∗ empty ∗/

;

A C Language Development Utilities Option

CONFLICTS

The parser produced for an input grammar may contain states in which conflicts occur. The conflicts occur because the grammar is not LALR (1). An ambiguous grammar always contains at least one LALR (1) conflict. The yacc utility shall resolve all conflicts, using either default rules or user-specified precedence rules. Conflicts are either ‘‘shift/reduce conflicts’’ or ‘‘reduce/reduce conflicts.’’ A shift/reduce conflict is where, for a given state and lookahead symbol, both a shift action and a reduce action are possible. A reduce/reduce conflict is where, for a given state and lookahead symbol, reductions by two different rules are possible. The rules below describe how to specify what actions to take when a conflict occurs. Not all shift/reduce conflicts can be successfully resolved this way because the conflict may be due to something other than ambiguity, so incautious use of these facilities can cause the language accepted by the parser to be much different than was intended. The description file shall contain sufficient information to understand the cause of the conflict. Where ambiguity is the reason either the default or explicit rules should be adequate to produce a working parser. The declared precedences and associativities (see A.3.7.1.2) are used to resolve parsing conflicts as follows:

1. A precedence and associativity is associated with each grammar rule; it is the precedence and associativity of the last token or literal in the body of the rule. If the %prec keyword is used, it overrides this default. Some grammar rules might not have both precedence and associativity.
2. If there is a shift/reduce conflict, and both the grammar rule and the input symbol have precedence and associativity associated with them, then the conflict is resolved in favor of the action (shift or reduce) associated with the higher precedence. If the precedences are the same, then the associativity is used; left associative implies reduce, right associative implies shift, and nonassociative implies an error in the string being parsed.
3. When there is a shift/reduce conflict that cannot be resolved by rule (2), the shift is done. Conflicts resolved this way are counted in the diagnostic output described in A.3.7.3.
4. When there is a reduce/reduce conflict, a reduction is done by the grammar rule that occurs earlier in the input sequence. Conflicts resolved this way are counted in the diagnostic output described in A.3.7.3.

Conflicts resolved by precedence or associativity shall not be counted in the shift/reduce and reduce/reduce conflicts reported by yacc on either standard error or in the description file.

ERROR HANDLING

The token error shall be reserved for error handling. The name error can be used in grammar rules. It indicates places where the parser can recover from a syntax error. The default value of error shall be 256. Its value can be changed using a %token declaration. The lexical analyzer should not return the value of error. The parser shall detect a syntax error when it is in a state where the action associated with the lookahead symbol is error. A semantic action can cause the parser to initiate error handling by executing the macro YYERROR. When YYER - ROR is executed, the semantic action shall pass control back to the parser. YYER - ROR cannot be used outside of semantic actions. When the parser detects a syntax error, it normally calls yyerror with the character string "syntax error" as its argument. The call shall not be made if the parser is still recovering from a previous error when the error is detected. The parser is considered to be recovering from a previous error until the parser has shifted over at least three normal input symbols since the last error was detected or a semantic action has executed the macro yyerrok. The parser shall not call yyerror when YYERROR is executed. The macro function YYRECOVERING() shall return 1 if a syntax error has been detected and the parser has not yet fully recovered from it. Otherwise, zero shall be returned. When a syntax error is detected by the parser, the parser shall check if a previous syntax error has been detected. If a previous error was detected, and if no normal input symbols have been shifted since the preceding error was detected, the parser checks if the lookahead symbol is an endmarker (see A.3.7.4). If it is, the parser shall return with a nonzero value. Otherwise, the lookahead symbol shall be discarded and normal parsing shall resume. When YYERROR is executed or when the parser detects a syntax error and no previous error has been detected, or at least one normal input symbol has been shifted since the previous error was detected, the parser shall pop back one state at a time until the parse stack is empty or the current state allows a shift over error. If the parser empties the parse stack, it shall return with a nonzero value. Otherwise, it shall shift over error and then resume normal parsing. If the parser reads a lookahead symbol before the error was detected, that symbol shall still be the lookahead symbol when parsing is resumed. The macro yyerrok in a semantic action shall cause the parser to act as if it has fully recovered from any previous errors. The macro yyclearin shall cause the parser to discard the current lookahead token. If the current lookahead token has not yet been read, yyclearin shall have no effect. The macro YYACCEPT shall cause the parser to return with the value zero. The macro YYABORT shall cause the parser to return with a nonzero value.

A C Language Development Utilities Option

INTERFACE TO THE LEXICAL ANALYZER

The yylex() function is an integer-valued function that returns a token number representing the kind of token read. If there is a value associated with the token returned by yylex() (see the discussion of tag above), it shall be assigned to the external variable yylval. If the parser and yylex() do not agree on these token numbers, reliable communication between them cannot occur. For (one character) literals, the token is simply the numeric value of the character in the current character set. The numbers for other tokens can either be chosen by yacc, or chosen by the user. In either case, the #define construct of C is used to allow yylex() to return these numbers symbolically. The #define statements are put into the code file, and the header file if that file is requested. The set of characters permitted by yacc in an identifier is larger than that permitted by C. Token names found to contain such characters shall not be included in the #define declarations. If the token numbers are chosen by yacc, the tokens other than literals shall be assigned numbers greater than 256, although no order is implied. A token can be explicitly assigned a number by following its first appearance in the declarations section with a number. Names and literals not defined this way retain their default definition. All assigned token numbers shall be unique and distinct from the token numbers used for literals. If duplicate token numbers cause conflicts in parser generation, yacc shall report an error; otherwise, it is unspecified whether the token assignment is accepted or an error is reported. The end of the input is marked by a special token called the endmarker, which has a token number that is zero or negative. (These values are invalid for any other token.) All lexical analyzers shall return zero or negative as a token number upon reaching the end of their input. If the tokens up to, but excluding, the endmarker form a structure that matches the start symbol, the parser shall accept the input. If the endmarker is seen in any other context, it shall be considered an error.

COMPLETING THE PROGRAM

In addition to yyparse() and yylex(), the functions yyerror() and main() are required to make a complete program. The application can supply main() and yyerror(), or those routines can be obtained from the yacc library.

YACC LIBRARY

The following functions appear only in the yacc library accessible through the −l y operand to c89; they can therefore be redefined by a portable application: int main(void) This function shall call yyparse() and exit with an unspecified value. Other actions within this function are unspecified. int yyerror(const char ∗s) This function shall write the NUL -terminated argument to

standard error, followed by a <newline>. The order of the −l y and −l l operands given to c89 is significant; the application shall either provide its own main() function or ensure that −l y precedes −l l.

DEBUGGING THE PARSER

The parser generated by yacc shall have diagnostic facilities in it that can be optionally enabled at either compile time or at run time (if enabled at compile time). The compilation of the runtime debugging code is under the control of YYDEBUG, a preprocessor symbol. If YYDEBUG has a nonzero value, the debugging code shall be included. If its value is zero, the code shall not be included. In parsers where the debugging code has been included, the external int yydebug can be used to turn debugging on (with a nonzero value) and off (zero value) at run time. The initial value of yydebug shall be zero. When −t is specified, the code file shall be built such that, if YYDEBUG is not already defined at compilation time (using the c89 -D YYDEBUG option, for example), YYDEBUG shall be set explicitly to 1. When −t is not specified, the code file shall be built such that, if YYDEBUG is not already defined, it shall be set explicitly to zero. The format of the debugging output is unspecified but includes at least enough information to determine the shift and reduce actions, and the input symbols. It also provides information about error recovery.

ALGORITHMS

The parser constructed by yacc implements an LALR (1) parsing algorithm as documented in the literature. It is unspecified whether the parser is table-driven or direct-coded. A parser generated by yacc shall never request an input symbol from yylex() while in a state where the only actions other than the error action are reductions by a single rule. The literature of parsing theory defines these concepts.

LIMITS

The yacc utility may have several internal tables. The minimum maximums for these tables are shown in Table A-4. The exact meaning of these values is implementation defined. The implementation shall define the relationship between these values and between them and any error messages that the implementation may generate should it run out of space for any internal structure. An implementation may combine groups of these resources into a single pool as long as the total available to the user does not fall below the sum of the sizes specified by this subclause.

A C Language Development Utilities Option

Table A-4 − yacc Internal Limits

Minimum Limit Description Maximum

NTERMS 126 Number of tokens. NNONTERM 200 Number of nonterminals. NPROD 300 Number of rules. NSTATES 600 Number of states. MEMSIZE 5200 Length of rules. The total length, in names (tokens and nonterminals), of all the rules of the grammar. The left-hand side is counted for each rule, even if it is not explicitly repeated, as specified in A.3.7.1.3. ACTSIZE 4000 Number of actions. ‘‘Actions’’ here (and in the description file) refer to parser actions (shift, reduce, etc.) not to semantic actions defined in A.3.7.1.3.

EXAMPLES

Access to the yacc library is obtained with library search operands to c89. To use the yacc library main(), c89 y.tab.c -l y Both the lex library and the yacc library contain main(). To access the yacc main(), c89 y.tab.c lex.yy.c -l y -l l This ensures that the yacc library is searched first, so that its main() is used. The historical yacc libraries have contained two simple functions that are normally coded by the application programmer. These library functions are similar to the following code:

A C Language Development Utilities Option

#include locale.h(7) 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(7)

int yyerror(const char ∗msg) { (void) fprintf(stderr, "%s\n", msg); return (0); } Historical implementations experience name conflicts on the names yacc. tmp, yacc. acts, yacc. debug, y.tab.c, y.tab.h, and y.output if more than one copy of yacc is running in a single directory at one time. The −b option was added to overcome this problem. The related problem of allowing multiple yacc parsers to be placed in the same file was addressed by adding a −p option to override the previously hardcoded yy variable prefix. (The −p option name was selected from a historical implementation.) Implementations will also have to be cognizant of 2.11.6.3, which requires that any temporary files used by yacc also be named to avoid collisions. The description of the −p option specifies the minimal set of function and variable names that cause conflict when multiple parsers are linked together. YYSTYPE does not need to be changed. Instead, the programmer can use −b to give the header files for different parsers different names, and then the file with the yylex() for a given parser can include the header for that parser. Names such as yyclearerr don’t need to be changed because they are used only in the actions; they do not have linkage. It is possible that an implementation will have other names, either internal ones for implementing things such as yyclearerr, or providing nonstandard features, that it wants to change with −p. The −b option was added to provide a portable method for permitting yacc to work on multiple separate parsers in the same directory. If a directory contains more than one yacc grammar, and both grammars are constructed at the same time (by, say, a parallel make program), conflict results. While the solution is not historical practice, it corrects a known deficiency in historical implementations. Corresponding changes were made to all sections that referenced the filenames y.tab.c (now ‘‘the code file’’), y.tab.h (now ‘‘the header file’’), and y.output (now ‘‘the description file’’).

The grammar for yacc input is based on System V documentation. The textual description shows there that the ; is required at the end of the rule. The grammar and the implementation do not require this. (The use of C_IDENTIFIER causes a reduce to occur in the right place.) Also, in that implementation, the constructs such as %token can be terminated by a semicolon, but this is not permitted by the grammar. The keywords such as %token can also appear in uppercase, which is again not discussed. In most places where % is used, \ can be substituted, and there are alternate spellings for some of the symbols (e.g. % LEFT can be %< or even \<). Multibyte characters should be recognized by the lexical analyzer and returned as tokens. They should not be returned as multibyte character literals. The token error that is used for error recovery is normally assigned the value 256 in the historical implementation. Thus, the token value 256, which used in many multibyte character sets, is not available for use as the value of a user-defined token.

Historically, <tag> can contain any characters except >, including white space, in the implementation. However, since the tag must reference a Standard C union member, in practice conforming implementations need only support the set of characters for Standard C identifiers in this context. Some historical implementations are known to accept actions that are terminated by a period. Historical implementations often allow $ in names. A conforming implementation need support neither of these behaviors. Unary operators that are the same token as a binary operator in general need their precedence adjusted. This is handled by the %prec advisory symbol associated with the particular grammar rule defining that unary operator. See A. Applications are not required to use this operator for unary operators, but the grammars that do not require it are rare. Deciding when to use %prec illustrates the difficulty in specifying the behavior of yacc. There may be situations in which the grammar is not strictly speaking in error, and yet yacc cannot interpret it unambiguously. The resolution of ambiguities in the grammar can in many instances be resolved by providing additional information, such as using %type or %union declarations. It is often easier and it usually yields a smaller parser to take this alternative when it is appropriate. The size and execution time of a program produced without the runtime debugging code is usually smaller and slightly faster in historical implementations. There is a fair amount of material in this that appears tutorial in nature; some of it has been moved to the Rationale in Draft 9 to simplify the specification. It is hard to avoid because of the need to define terms at least informally. The alternative is to bring in one of the parser generator texts and use its terminology directly, but since there is some variation in that terminology, it was felt that informal definitions of the terms so that someone who understood the concepts would be sure to understand the terms would make the standard stand alone from any specific text. Statistics messages from several historical implementations include the following types of information:

A C Language Development Utilities Option

n/512 terminals, n/300 nonterminals n/600 grammar rules, n/1500 states n shift/reduce, n reduce/reduce conflicts reported n/350 working sets used memory: states,etc. n/15000, parser n/15000 n/600 distinct lookahead sets n extra closures n shift entries, n exceptions n goto entries n entries saved by goto default Optimizer space used: input n/15000, output n/15000 n table entries, n zero maximum spread: n, maximum offset: n The report of internal tables in the description file is left implementation defined because all aspects of these limits are also implementation defined. Some implementations may use dynamic allocation techniques and have no specific limit values to report.

HISTORY OF DECISIONS MADE

The format of the y.output file is not given because specification of the format was not seen to enhance application portability. The listing is primarily intended to help human users understand and debug the parser; use of y.output by a portable application script is far-fetched. Furthermore, implementations have not produced consistent output and no clear winner was apparent. The format selected by the implementation should be human-readable, in addition to the requirement that it be a text file. Standard error reports are not specifically described because they are seldom of use to portable applications and there was no reason to restrict implementations. Some implementations recognize ={ as equivalent to {, because it appears in historical documentation. This construction was recognized and documented as obsolete as long ago as 1978, in the original paper Yacc: Yet Another Compiler- Compiler by Stephen C. Johnson. POSIX. 2 chose to leave it as obsolete and omit it.

Annex B (normative) C Language Bindings Option

This annex describes the C language bindings to the language-independent services described in Section 7. The interfaces described in this annex may be provided by the conforming system; however, any system claiming conformance to the Language-Independent System Services C Language Bindings Option shall provide all of the interfaces described here.

B.0.1 C Language Bindings Option Rationale. (This subclause is not a part of P1003. 2)

In this version of POSIX. 2, the language-independent descriptions in Section 7 have not been developed. The language-independent syntax is being created in parallel by the POSIX. 1 working group. Therefore, the C language bindings described in this annex are actually the full functional specifications. It is the intention of the POSIX. 2 working group to rectify this situation in a revision to this standard, by moving the majority of the functional specifications back into Section 7, leaving Annex B with only brief descriptions of the C bindings to those services.

Annex B C Language Bindings Option 771

B.1 C Language Definitions

B.1.1 POSIX Symbols

Certain symbols in this annex are defined in headers. Some of those headers could also define symbols other than those defined by this standard, potentially conflicting with symbols used by the application. Also, this standard defines symbols that other standards do not permit to appear in those headers without some control on the visibility of those symbols. Symbols called feature test macros are used to control the visibility of symbols that might be included in a header. Implementations, future versions of this standard, and other standards may define additional feature test macros. The #defines for feature test macros shall appear in the application source code before any #include of a header where a symbol should be visible to some, but not all, applications. If the definition of the macro does not precede the #include, the result is undefined. Feature test macros shall begin with the underscore character (_) and an uppercase letter, or with two underscore characters.

Implementations may add symbols to the headers shown in Table B-1, provided the identifiers for those symbols begin with the corresponding reserved prefixes in Table B-1. Similarly, implementations may add symbols to the headers in Table B-1 that end in the string indicated as a reserved suffix as long as the reserved suffix is in that part of the name considered significant by the implementation. This shall be in addition to any reservations made in the C Standard {7}.

After the last inclusion of a given header, an application may use any of the symbol classes reserved in Table B-1 for its own purposes, as long as the requirements in the note to Table B-1 are satisfied, noting that the symbol declared in the header may become inaccessible.

Future revisions of this standard, and other POSIX standards, are likely to use symbols in these same reserved spaces.

In addition, implementations may add members to a structure or union without controlling the visibility of those members with a feature test macro, as long as a user-defined macro with the same name cannot interfere with the correct interpretation of the program.

A conforming POSIX. 2 application shall define the feature test macro in Table B-2. When an application includes a header and the _POSIX_C_SOURCE feature test macro is defined to be the value 1 or 2, the effect shall be the same as if _POSIX_SOURCE was defined as described in POSIX. 1 {8}. In addition, when the application includes any of the headers defined in this standard, and _POSIX_C_SOURCE is defined to be the value 2:

1. All symbols defined in POSIX. 2 to appear when the header is included shall be made visible.

B C Language Bindings Option

Table B-1 − POSIX. 2 Reserved Header Symbols

Reserved Reserved Header Key Prefix Suffix 1

fnmatch.h(7) 2 FNM_ glob.h(7) 1 gl_ 2 GLOB_ limits.h(7) 1 _MAX regex.h(7) 1 re_ 1 rm_ 2 REG_ wordexp.h(7) 1 we_ 2 WRDE_

NOTE: The Key values are:

1. Prefixes and suffixes of symbols that shall not be declared or #defined by the application.

1. Prefixes and suffixes of symbols that shall be preceded in the application with a #undef of that symbol before any other use.

Table B-2 − _POSIX_C_SOURCE

Name Description

_POSIX_C_SOURCE Enable POSIX. 1 {8} and POSIX. 2 symbols; see text.

1. Symbols that are explicitly permitted, but not required, by POSIX. 2 to appear in the header (including those in reserved name spaces) may be made visible.
2. Additional symbols shall not be made visible, unless controlled by another feature test macro.

The effect of defining the _POSIX_C_SOURCE macro to any other value is unspecified. If there are no feature test macros present in a program, only the set of symbols defined by the C Standard {7} shall be present. For each feature test macro present, only the symbols specified by that feature test macro plus those of the C Standard {7} shall be defined when the header is included.

B.1 C Language Definitions 773

B.1.1.1 POSIX Symbols Rationale. (This subclause is not a part of P1003. 2)

When the application defines the _POSIX_C_SOURCE feature test macro with value 2, it must be aware that all of the name space from POSIX. 1 {8} and POSIX. 2 has been reserved. This does not imply that a POSIX. 2 implementation must support POSIX. 1 {8}, just that the application must not conflict with an implementation that does. The application can check _POSIX_VERSION and _POSIX2_C_VERSION at compile time to see which standards are supported, if that is necessary. This is primarily an issue for the headers stdio.h(7), limits.h(7), locale.h(7), and unistd.h(7), since other POSIX. 1 {8} names appear in other headers not mentioned in POSIX. 2. It is expected that C bindings to future POSIX standards and revisions will define new values for _POSIX_C_SOURCE, with each new value reserving the name space for that new standard or revision, plus all earlier POSIX standards. Using a single feature test macro for all standards rather than a separate macro for each standard furthers the goal of eventually combining all of the C bindings into one standard, which will be included in an international standard that refers to a language-independent ISO / IEC 9945-1 {8}.

B.1.2 Headers and Function Prototypes

Implementations shall declare function prototypes for all functions. Each function prototype shall appear in the header included in the synopsis of the function.

B.1.3 Error Numbers

Some of the functions in this annex use the variable errno to report errors. Such usage is documented in Errors in each specification. The usage of errno and the meanings of the symbolic names shall be as defined in POSIX. 1 {8} B.1.3.

B.1.4 C Language Definitions Rationale. (This subclause is not a part of P1003. 2)

This clause clarifies the interface to the C Standard {7}. The description was taken from POSIX. 1, with one important modification. Since POSIX. 1 {8} and the C Standard {7} were being developed and approved at about the same time, POSIX. 1 {8} allowed ‘‘Common Usage C’’ implementations to give system vendors time to develop Standard C interfaces. Since Standard C compilers are now commonly available, POSIX. 2 does not explicitly describe the binding to Common Usage C. However, such a binding would be straightforward, as long as the rules for Common Usage C in POSIX. 1 are followed.

B C Language Bindings Option

B.2 C Numerical Limits The following subclauses list the names of macros that C language applications can use to obtain minimum and current values for limits defined in 2.13.1.

B.2.0.1 C Numerical Limits Rationale. (This subclause is not a part of P1003. 2)

This subclause was added in Draft 9 to give C applications access to limits at compile time. Applications can use the values from the macros without resorting to sysconf(). The descriptions very closely follow the descriptions of macros and limits in POSIX. 1 {8}. This definition of the limits is specific to the C language. Other language bindings might use different interfaces or names to provide equivalent information to the application. Note that there are no C bindings or interfaces that change based on the macros in Table B-5. These macro only advertise the availability of the associated utilities.

B.2.1 C Macros for Symbolic Limits

The macros in Table B-3 shall be defined in the header limits.h(7). They specify values for the symbolic limits defined in 2.13.1.

Table B-3 − C Macros for Symbolic Limits

Minimum Allowed Minimum for this Symbolic Limit by 2 Implementation

POSIX.

BC_BASE_MAX _POSIX2_BC_BASE_MAX BC_BASE_MAX BC_DIM_MAX _POSIX2_BC_DIM_MAX BC_DIM_MAX BC_SCALE_MAX _POSIX2_BC_SCALE_MAX BC_SCALE_MAX BC_STRING_MAX _POSIX2_BC_STRING_MAX BC_STRING_MAX COLL_WEIGHTS_MAX _POSIX2_COLL_WEIGHTS_MAX COLL_WEIGHTS_MAX EXPR_NEST_MAX _POSIX2_EXPR_NEST_MAX EXPR_NEST_MAX LINE_MAX _POSIX2_LINE_MAX LINE_MAX RE_DUP_MAX _POSIX2_RE_DUP_MAX RE_DUP_MAX

The names in the first column of Table B-3 are symbolic limits as defined in 2.13.1. The names in the second column are C macros that define the smallest values permitted for the symbolic limits on any POSIX. 2 implementation; they shall be defined as constant expressions with the most restrictive values specified in 2.13.1. The names in the third column are C macros that define less restrictive values provided by the implementation; each shall be defined as a constant that

• is not smaller than the associated macro in column 2, and
• is not larger than the smallest value that will be returned by sysconf() when the application is executed.

B.2 C Numerical Limits 775

B.2.1.1 C Macros for Symbolic Limits Rationale. (This subclause is not a part of P1003. 2)

The macros in column 3 of Table B-3 are required to be constant expressions. If the C binding is to be used with POSIX. 2 implementations over which the implementor of the binding has no control, the column-3 values must be the same as column-2. If the implementation of the C binding is intended to be used with a POSIX. 2 implementation that always supports a larger value than one in column 2, that implementation of the binding may use the larger value for the column-3 macro. If an application compiled with that binding is then used with a different POSIX. 2 implementation, it is the user’s fault that the application is being run in an environment in which it was not intended. The application can assume, for example, that the stream created by popen("mailx user","w") will accept lines of length LINE_MAX, even if this is larger than _POSIX2_LINE_MAX. However, if the application is creating a data file that might be processed on another implementation, it should use the values in column 2.

B.2.2 Compile-Time Symbolic Constants for Portability Specifications

The macros in Table B-4 shall be defined in the header unistd.h(7). These macros can be used by the application, at compile time, to determine which optional facilities are present and what actions shall be taken by the implementation.

Table B-4 − C Compile-Time Symbolic Constants

Macro Name Description

_POSIX2_C_VERSION The integer value 199???L. This value indicates the version of the interfaces in this annex that are provided by the implementation. It will change with each published version of this standard to indicate the 4-digit year and 2-digit month that the standard was approved by the IEEE Standards Board.

B.2.2.1 Compile-Time Symbolic Constants for Portability Specifications Rationale. (This subclause is not a part of P1003. 2)

The symbolic constant _POSIX2_C_VERSION is analogous to _POSIX_VERSION, defined in POSIX. 1 {8}. It indicates the version of the C interfaces that are supplied by the compiler and runtime library.

The version of the utilities is given by the POSIX2_VERSION limit (see 2.13.1), whose value can be obtained at runtime using sysconf() (see B.10.2).

B C Language Bindings Option

B.2.3 Execution-Time Symbolic Constants for Portability Specifications

The macros in Table B-5 can be used by the application at execution time to determine which optional facilities are present. If a macro is defined to have the value −1 in the header unistd.h(7), the implementation shall never provide that feature when the application runs under that implementation. If a macro is defined to have a value other than −1, the implementation shall always provide that feature. If the macro is undefined, then the sysconf() function (see B.10.2) can be used to determine if the feature is provided for a particular invocation of the application.

Table B-5 − C Execution-Time Symbolic Constants

Macro Name Description

_POSIX2_C_DEV The system supports the C Language Development Utilities Option (see _POSIX2_FORT_DEV The system supports the FORTRAN Development Utilities Option (see _POSIX2_FORT_RUN The system supports the FORTRAN Runtime Utilities Option (see Annex C) _POSIX2_LOCALEDEF The system supports the creation of locales as described in localedef(1) . _POSIX2_SW_DEV The system supports the Software Development Utilities Option (see Section 6)

B.2.4 POSIX. 1 C Numerical Limits

The macros specified in POSIX. 1 {8} to provide compile-time values for the configurable variables in Table 7-1 (see 7.8.2) shall also be visible in a POSIX. 2 system. Other macros required by POSIX. 1 {8} 2.9 (Numerical Limits) and 2.10 (Symbolic Constants) may also be visible in a POSIX. 2 system.

B.2.4.1 POSIX. 1 C Numerical Limits Rationale. (This subclause is not a part of P1003. 2)

Subclause 7.8.2 requires that certain POSIX. 1 {8} configurable variables be visible in POSIX. 2. Subclause B.2.4 ensures that POSIX. 2 C applications can obtain these variables using the same macros as POSIX. 1 {8} C applications. It also allows an implementation to make all of the POSIX. 1 {8} macros available even if _POSIX_SOURCE is not set. It also allows an implementation to make all of the POSIX. 1 {8} symbols available even if it does not support all of POSIX. 1 {8}.

B.2 C Numerical Limits 777

B.3 C Binding for Shell Command Interface

B.3.0.1 C Binding for Shell Command Interface Rationale. (This subclause is not a part of P1003. 2)

The system() and popen() functions should not be used by programs that have set user (or group) ID privileges, as defined in POSIX. 1 {8}. The fork() and exec family of functions [except execlp() and execvp() ], also defined in POSIX. 1 {8}, should be used instead. This prevents any unforeseen manipulation of the user’s environment that could cause execution of commands not anticipated by the calling program. If the original and ‘‘ popen() ed’’ processes both intend to read or write or read and write a common file, and either will be using FILE -type C functions [ fread(), fwrite(), etc.], the rules in POSIX. 1 {8} 8.2.3 must be observed.

B.3.1 C Binding for Execute Command

Function: system()

B.3.1.1 Synopsis

#include stdlib.h(7) int system(const char ∗command);

B.3.1.2 Description

This standard requires the system() function as described in the C Standard {7}. The system() function shall execute the command specified by the string pointed to by command. The environment of the executed command shall be as if a child process were created using the POSIX. 1 {8} fork() function, and the child process invoked the sh utility (see sh(1) ) using the POSIX. 1 {8} execl() function as follows: execl(<shell path>, "sh", "-c", command, (char ∗)0); where <shell path> is an unspecified pathname for the sh utility. The system() function shall ignore the SIGINT and SIGQUIT signals, and block the SIGCHLD signal, while waiting for the command to terminate. If this might cause the application to miss a signal that would have killed it, then the application should examine the return value from system() and take whatever action is appropriate to the application if the command terminated due to receipt of a signal. The system() function shall not affect the termination status of any child of the calling processes other than the process(es) it itself creates. The system() function shall not return until the child process has terminated.

B C Language Bindings Option

B.3.1.3 Returns

If command is NULL, the system() function shall return nonzero. If command is not NULL, the system() function shall return the termination status of the command language interpreter in the format specified by the waitpid() function in POSIX. 1 {8}. The termination status of the command language interpreter is as specified for the sh utility, except that if some error prevents the command language interpreter from executing after the child process is created, the return value from system() shall be as if the command language interpreter had terminated using exit(127) or _exit(127). If a child process cannot be created, or if the termination status for the command language interpreter cannot be obtained, system() shall return −1 and set errno to indicate the error.

B.3.1.4 Errors

The system() function may set errno values as described by fork() in POSIX. 1 {8}.

B.3.1.5 Rationale. (This subclause is not a part of P1003. 2)

The C Standard {7} specifies that when command is NULL, system() returns nonzero if there is a command interpreter available and zero if one is not available. At first reading, it might appear that POSIX. 2 conflicts with this, since it requires system( NULL ) to always return nonzero. There is no conflict, however. A POSIX. 2 implementation must always have a command interpreter available, and is nonconforming if none is present. It is therefore permissible for the system() function on a POSIX. 2 system to implement the behavior specified by the C Standard {7} as long as it is understood that the implementation is not POSIX. 2 conforming if system( NULL ) returns zero.

Note that, while system() must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting for the child to terminate, the handling of signals in the executed command is as specified by fork() and exec. For example, if SIGINT is being caught or is set to SIG_DFL when system() is called, then the child will be started with SIGINT handling set to SIG_DFL. Ignoring SIGINT and SIGQUIT in the parent process prevents coordination problems (two processes reading from the same terminal, for example) when the executed command ignores or catches one of the signals. It is also usually the correct action when the user has given a command to the application to be executed synchronously (as in the ‘‘!’’ command in many interactive applications). In either case, the signal should be delivered only to the child process, not to the application itself. There is one situation where ignoring the signals might have less than the desired effect. This is when the application uses system() to perform some task invisible to the user. If the user typed the interrupt character (ˆC for example) while system() is being used in this way, one would expect the application to be killed, but only the executed command will be killed. Applications that use system() in this way should carefully check the return status from system() to see if the executed command was successful, and should take appropriate action when the command fails.

B.3 C Binding for Shell Command Interface 779

Blocking SIGCHLD while waiting for the child to terminate prevents the application from catching the signal and obtaining status from system() ’s child process before system() can get the status itself.

EXAMPLES

The context in which the utility is ultimately executed may differ from that in which the system() function was called. For example, file descriptors that have the FD_CLOEXEC flag set will be closed, and the process ID and parent process ID will be different. Also, if the executed utility changes its environment variables or its current working directory, that change will not be reflected in the caller’s context. Earlier drafts of this standard required, or allowed, system() to return with errno

EINTR

if it was interrupted with a signal. This error return was removed, and a

requirement that system() not return until the child has terminated was added. This means that if a waitpid() call in system() exits with errno EINTR, system() must re-issue the waitpid(). This change was made for two reasons:

1. There is no way for an application to clean up if system() returns EINTR, short of calling wait(3), and that could have the undesirable effect of returning status of children other than the one started by system().
2. While it might require a change in some historical implementations, those implementations already have to be changed because they use wait(3) instead of waitpid().

Note that if the application is catching SIGCHLD signals, it will receive such a signal before a successful system() call returns.

HISTORY OF DECISIONS MADE

The C Standard {7} requires that a call to system() with a NULL will return a nonzero value, indicating the presence of a command language interpreter available to the system. It was explicitly decided that when command is NULL, system() should not be required to check to make sure that the command language interpreter actually exists with the correct mode, that there are enough processes to execute it, etc. The call system( NULL ) could, theoretically, check for such problems as too many existing child processes, and return zero. However, it would be inappropriate to return zero due to such a (presumably) transient condition. If some condition exists that is not under the control of this application and that would cause any system() call to fail, that system has been rendered nonconformant. Modified in Draft 6 to reflect the availability of the waitpid() function in POSIX. 1 {8}. To conform to this standard, system() must use waitpid(), or some similar function, instead of wait(3). Figure B-1 illustrates how system() might be implemented on a POSIX. 1 {8} implementation.

B C Language Bindings Option

#include signal.h(7) int system(const char ∗cmd) { int stat; pid_t pid; struct sigaction sa, savintr, savequit; sigset_t saveblock; if (cmd == NULL ) return(1); sa.sa_handler = SIG_IGN; sigemptyset(&sa.sa_mask); sa.sa_flags = 0; sigemptyset(&savintr.sa_mask); sigemptyset(&savequit.sa_mask); sigaction( SIGINT, &sa, &savintr); sigaction( SIGQUIT, &sa, &savequit); sigaddset(&sa.sa_mask, SIGCHLD ); sigprocmask( SIG_BLOCK, &sa.sa_mask, &saveblock); if ((pid = fork() ) == 0) { sigaction( SIGINT, &savintr, ( struct sigaction ∗)0); sigaction( SIGQUIT, &savequit, ( struct sigaction ∗)0); sigprocmask( SIG_SETMASK, &saveblock, ( sigset_t ∗)0); execl("/bin/sh", "sh", "-c", cmd, (char ∗)0); _exit(127); } if (pid == -1) { stat = -1; /∗ errno comes from fork() ∗/ } else { while (waitpid(pid, &stat, 0) == -1) { if (errno != EINTR ) { stat = -1; break; } } } sigaction( SIGINT, &savintr, ( struct sigaction ∗)0); sigaction( SIGQUIT, &savequit, ( struct sigaction ∗)0); sigprocmask( SIG_SETMASK, &saveblock, ( sigset_t ∗)0); return(stat); }

Figure B-1 − Sample system() Implementation

Note that, while a particular implementation of system() (such as the one above) can assume a particular path for the shell, such a path is not necessarily valid on another system. The above example is not portable, and is not intended to be. There is no defined way for an application to find the specific path for the shell. However, confstr() can provide a value for PATH that is guaranteed to find the sh

B.3 C Binding for Shell Command Interface 781

utility. One reviewer suggested that an implementation of system() might want to use an environment variable such as SHELL to determine which command interpreter to use. The supposed implementation would use the default command interpreter if the one specified by the environment variable was not available. This would allow a user, when using an application that prompts for command lines to be processed using system(), to specify a different command interpreter. Such an implementation is discouraged. If the alternate command interpreter did not follow the command line syntax specified in POSIX. 2, then changing SHELL would render system() nonconformant. This would affect applications that expected the specified behavior from system(), and since this standard does not mention that SHELL affects system(), the application would not know that it needed to unset SHELL.

B.3.2 C Binding for Pipe Communications with Programs

Functions: popen(), pclose()

B.3.2.1 Synopsis

#include stdio.h(7) FILE ∗popen(const char ∗command, const char ∗mode);

int pclose( FILE ∗stream);

B.3.2.2 Description

The popen() function shall execute the command specified by the string command. It shall create a pipe between the calling program and the executed command, and return a pointer to a C Standard {7} stream that can be used to either read from or write to the pipe. The pclose() function shall close the stream, wait for the command to terminate, and return the termination status from the command language interpreter. The environment of the executed command shall be as if a child process were created within the popen() call using the fork() function, and the child invoked the sh utility using the call: execl(<shell path>, "sh", "-c", command, (char ∗)0); where <shell path> is an unspecified pathname for the sh utility. However, popen() shall ensure that any streams from previous popen() calls that remain open in the parent process are closed in the new child process.

The mode argument to popen() is a string that specifies I/O mode:

1. If mode is "r", when the child process is started its file descriptor STDOUT_FILENO shall be the writable end of the pipe, and the file descriptor fileno(stream) in the calling process, where stream is the stream pointer returned by popen(), shall be the readable end of the pipe.

B C Language Bindings Option

1. If mode is "w", when the child process is started its file descriptor STDIN_FILENO shall be the readable end of the pipe, and the file descriptor fileno(stream) in the calling process, where stream is the stream pointer returned by popen(), shall be the writable end of the pipe.
2. If mode is any other value, the result is undefined.

A stream opened by popen() should be closed by pclose(). As stated above, pclose() shall return the termination status from the command language interpreter. However, if the application has called any of the following:

1. wait(3),
2. waitpid() with a pid argument less than or equal to zero or equal to the process ID of the command line interpreter, or
3. any other function not defined in POSIX. 1 {8} or POSIX. 2 that could do one of the above

and one of those calls caused the termination status to be unavailable to pclose(), then pclose() shall return −1 with errno set to ECHILD to report this situation. In any case, pclose() shall not return before the child process created by popen() has terminated. If the command language interpreter cannot be executed, the child termination status returned by pclose() shall be as if the command language interpreter terminated using exit(127) or _exit(127). If it can be executed, the exit(3) value shall be as described for the sh utility. The pclose() function shall not affect the termination status of any child of the calling process other than the one created by popen() for the associated stream. If the argument stream to pclose() is not a pointer to a stream created by popen(), the result of pclose() is undefined. After popen(), both the parent and the child process shall be capable of executing independently before either terminates. See 2.9.1.2.

B.3.2.3 Returns

The popen() function shall return a NULL pointer if the pipe or subprocess cannot be created. Otherwise, it shall return a stream pointer as described above. Upon successful return, pclose() shall return the termination status of the command language interpreter. Otherwise, pclose() shall return −1 and set errno to indicate the error.

B.3.2.4 Errors

If any of the following conditions are detected, the popen() function shall return NULL and set errno to the corresponding value:

EINVAL

The mode argument is invalid.

B.3 C Binding for Shell Command Interface 783

The popen() function may also set errno values as described by the POSIX. 1 {8} fork() or pipe() functions. If any of the following conditions are detected, the pclose() function shall return −1 and set errno to the corresponding value:

ECHILD

The status of the child process could not be obtained, as described

above.

B.3.2.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

Because open files are shared, a mode "r" command can be used as an input filter and a mode "w" command as an output filter. The behavior of popen() is specified for modes of "r" and "w". Other modes such as "rb" and "wb" might be supported by specific implementations, but these would not be portable features. Note that historical implementations of popen() only check to see if the first character of mode is r. Thus, a mode of "robert the robot" would be treated as mode "r", and a mode of "anything else" would be treated as mode "w". If the application calls waitpid() with a pid argument greater than zero, and it still has a popen() ed stream open, it must ensure that pid does not refer to the process started by popen().

HISTORY OF DECISIONS MADE

There is a requirement that pclose() not return before the child process terminates. This is intended to disallow implementations that return EINTR if a signal is received while waiting. If pclose() returned before the child terminated, there would be no way for the application to discover which child used to be associated with the stream, and it could not do the cleanup itself. If the stream pointed to by stream was not created by popen(), historical implementations of pclose() return −1 without setting errno. To avoid requiring pclose() to set errno in this case, this standard makes the behavior undefined. An application should not use pclose() to close any stream that wasn’t created by popen(). Wording was added in Draft 10 requiring that the parent and child processes be able to execute independently. This behavior has been the intent all along, and the specific words were taken from the current draft of the POSIX. 1a revision to POSIX. 1 {8}. Rationale about this wording appears in B.3.1.1 of POSIX. 1a. Some historical implementations either block or ignore the signals SIGINT, SIGQUIT, and SIGHUP while waiting for the child process to terminate. Since this behavior is not described in POSIX. 2, such implementations are not conforming. Also, some historical implementations return EINTR if a signal is received, even though the child process has not terminated. Such implementations are also considered nonconforming.

B C Language Bindings Option

Consider, for example, an application that uses popen("command", "r") to start command, which is part of the same application. The parent writes a prompt to its standard output (presumably the terminal) and then reads from the popened stream. The child reads the response from the user, does some transformation on the response (pathname expansion, perhaps) and writes the result to its standard output. The parent process reads the result from the pipe, does something with it, and prints another prompt. The cycle repeats. Assuming that both processes do appropriate buffer flushing, this would be expected to work. Modified in Draft 6 to reflect the availability of the waitpid() function in POSIX. 1 {8}. To conform to this standard, pclose() must use waitpid(), or some similar function, instead of wait(3). Figure B-2 illustrates how the pclose() function might be implemented on a POSIX. 1 {8} system.

int pclose( FILE ∗stream) { int stat; pid_t pid; pid = <pid for process created for stream by popen() > (void) fclose(stream); while (waitpid(pid, &stat, 0) == -1) { if (errno != EINTR ) { stat = -1; break; } } return(stat); }

Figure B-2 − Sample pclose() Implementation

B.3 C Binding for Shell Command Interface 785

B.4 C Binding for Access Environment Variables Function: getenv() The C language binding to the service described in 7.2 shall be the POSIX. 1 {8} getenv() function.

B.5 C Binding for Regular Expression Matching Functions: regcomp(), regexec(), regfree(), regerror()

B.5.1 Synopsis

#include sys-types.h(7) #include regex.h(7) int regcomp( regex_t ∗preg, const char ∗pattern, int cflags); int regexec(const regex_t ∗preg, const char ∗string, size_t nmatch, regmatch_t pmatch[ ], int eflags); size_t regerror(int errcode, const regex_t ∗preg, char ∗errbuf, size_t errbuf_size); void regfree( regex_t ∗preg);

B.5.2 Description

These functions shall interpret basic and extended regular expressions, as described in 2.8. The header regex.h(7) shall define the structure types regex_t and regmatch_t. The structure type regex_t shall include at least the member shown in Table B-6. The structure type regmatch_t shall contain at least the members shown in Table B-7. The type regoff_t, which shall be defined in regex.h(7), shall be a signed arithmetic type that can hold the largest value that can be stored in either an off_t or a ssize_t.

The regcomp() function shall compile the regular expression contained in the string pointed to by the pattern argument and place the results in the structure pointed to by preg. The cflags argument shall be the bitwise inclusive OR of zero or more of the flags shown in Table B-8, which shall be defined in the header regex.h(7). The default regular expression type for pattern shall be a Basic Regular Expression. The application can specify Extended Regular Expressions using the REG_EXTENDED cflags flag. If the function regcomp() succeeds, it shall return zero; otherwise it shall return nonzero, and the content of preg shall be undefined.

B C Language Bindings Option

Table B-6 − Structure Type regex_t

Member Member Description Type Name

size_t re_nsub Number of parenthesized subexpressions.

Table B-7 − Structure Type regmatch_t

Member Member Description Type Name

regoff_t rm_so Byte offset from start of string to start of substring. regoff_t rm_eo Byte offset from start of string of the first character after the end of substring.

Table B-8 − regcomp() cflags Argument

flag Description

REG_EXTENDED Use Extended Regular Expressions. REG_ICASE Ignore case in match. See 2.8.2. REG_NOSUB Report only success/fail in regexec() .REG_NEWLINE Change the handling of <newline>, as described in the text.

Table B-9 − regexec() eflags Argument

flag Description

REG_NOTBOL The first character of the string pointed to by string is not the beginning of the line. Therefore, the circumflex character (ˆ), when taken as a special character, shall not match the beginning of string. REG_NOTEOL The last character of the string pointed to by string is not the end of the line. Therefore, the dollar sign ($), when taken as a special character, shall not match the end of string.

If the REG_NOSUB flag was not set in cflags, then regcomp() shall set re_nsub to the number of parenthesized subexpressions [delimited by \( \) in basic regular expressions or ( ) in extended regular expressions] found in pattern. The regexec() function shall compare the null-terminated string specified by string against the compiled regular expression preg initialized by a previous call to regcomp(). If it finds a match, regexec() shall return zero; otherwise it shall return nonzero indicating either no match or an error. The eflags argument shall be the bitwise inclusive OR of zero or more of the flags shown in Table B-9, which shall be defined in the header regex.h(7).

B.5 C Binding for Regular Expression Matching 787

If nmatch is zero or REG_NOSUB was set in the cflags argument to regcomp(), then regexec() shall ignore the pmatch argument. Otherwise, the pmatch argument shall point to an array with at least nmatch elements, and regexec() shall fill in the elements of that array with offsets of the substrings of string that correspond to the parenthesized subexpressions of pattern: pmatch[i].rm_so shall be the byte offset of the beginning and pmatch[i].rm_eo shall be one greater than the byte offset of the end of substring i. (Subexpression i begins at the ith matched open parenthesis, counting from 1.) Offsets in pmatch[0] shall identify the substring that corresponds to the entire regular expression. Unused elements of pmatch up to pmatch[nmatch−1] shall be filled with −1. If there are more than nmatch subexpressions in pattern (pattern itself counts as a subexpression), then regexec() shall still do the match, but shall record only the first nmatch substrings. When matching a basic or extended regular expression, any given parenthesized subexpression of pattern might participate in the match of several different substrings of string, or it might not match any substring even though the pattern as a whole did match. The following rules shall be used to determine which substrings to report in pmatch when matching regular expressions:

1. If subexpression i in a regular expression is not contained within another subexpression, and it participated in the match several times, then the byte offsets in pmatch[i] shall delimit the last such match.
2. If subexpression i is not contained within another subexpression, and it did not participate in an otherwise successful match, then the byte offsets in pmatch[i] shall be −1. A subexpression shall not participate in the match when:

(a) ∗ or \{ \} appears immediately after the subexpression in a basic regular expression, or ∗, ?, or { } appears immediately after the subexpression in an extended regular expression, and the subexpression did not match (matched zero times), or

(b) | is used in an extended regular expression to select this subexpression or another, and the other subexpression matched.

1. If subexpression i is contained within another subexpression j, and i is not contained within any other subexpression that is contained within j, and a match of subexpression j is reported in pmatch[j], then the match or nonmatch of subexpression i reported in pmatch[i] shall be as described in (1) and (2) above, but within the substring reported in pmatch[j] rather than the whole string.

1. If subexpression i is contained in subexpression j, and the byte offsets in pmatch[j] are −1, then the byte offsets in pmatch[i] also shall be −1.

1. If subexpression i matched a zero-length string, then both byte offsets in pmatch[i] shall be the byte offset of the character or null terminator immediately following the zero-length string.

If, when regexec() is called, the locale is different than when the regular expression was compiled, the result is undefined.

B C Language Bindings Option

If REG_NEWLINE is not set in cflags, then a <newline> character in pattern or string shall be treated as an ordinary character. If REG_NEWLINE is set, then <newline> shall be treated as an ordinary character except as follows:

1. A <newline> in string shall not be matched by a period outside of a bracket expression (see 2.8.3.1.3) or by any form of a nonmatching list (see 2.8.3.2).
2. A circumflex (ˆ) in pattern, when used to specify expression anchoring (see 2.8.4.4 and 2.8.4.6), shall match the zero-length string immediately after a <newline> in string, regardless of the setting of REG_NOTBOL.
3. A dollar-sign ($) in pattern, when used to specify expression anchoring, shall match the zero-length string immediately before a <newline> in string, regardless of the setting of REG_NOTEOL.

The regfree() function shall free any memory allocated by regcomp() associated with preg. The regerror() function provides a mapping from error codes returned by regcomp() and regexec() to unspecified printable strings. It shall generate a string corresponding to the value of the errcode argument, which shall be the last nonzero value returned by regcomp() or regexec() with the given value of preg. If errcode is not such a value, the content of the generated string is unspecified. If preg is ( regexec_t )0, but errcode is a value returned by a previous call to regexec() or regcomp(), then regerror() still shall generate an error string corresponding to the value of errcode, but it might not be as detailed under some implementations.

If the errbuf_size argument is not zero, regerror() shall place the generated string into the errbuf_size-byte buffer pointed to by errbuf. If the string (including the terminating null) cannot fit in the buffer, regerror() shall truncate the string and null-terminate the result. If errbuf_size is zero, regerror() shall ignore the errbuf argument, but shall return the integer value described below. If the preg argument to regexec() or regfree() is not a compiled regular expression returned by regcomp(), the result is undefined. A preg shall no longer be treated as a compiled regular expression after it is given to regfree().

B.5.3 Returns

On successful completion, the regcomp() function shall return zero. On successful completion, the regexec() function shall return zero to indicate that string matched pattern, or REG_NOMATCH (which shall be defined in regex.h(7) ) to indicate no match. The regerror() function shall return the size of the buffer needed to hold the entire generated string, including the null termination. If the return value is greater than errbuf_size, the string returned in the buffer pointed to by errbuf has been truncated.

B.5 C Binding for Regular Expression Matching 789

Table B-10 − regcomp(), regexec() Return Values

Error Code Description

REG_NOMATCH regexec() failed to match REG_BADPAT Invalid regular expression REG_ECOLLATE Invalid collating element referenced REG_ECTYPE Invalid character class type referenced REG_EESCAPE Trailing \ in pattern REG_ESUBREG Number in \digit invalid or in error REG_EBRACK [ ] imbalance REG_EPAREN \( \) or ( ) imbalance REG_EBRACE \{ \} imbalance REG_BADBR Content of \{ \} invalid: Not a number, number too large, more than two numbers, first larger than second REG_ERANGE Invalid endpoint in range expression REG_ESPACE Out of memory REG_BADRPT ?, ∗, or + not preceded by valid regular expression

B.5.4 Errors

If regcomp() or regexec() fails, it shall return a nonzero value indicating the type of failure. Table B-10 contains the names of macros for error codes that may be returned. If a code is returned, the interpretation shall be as given in the table. The implementation shall define the macros in Table B-10 in regex.h(7), and may define additional macros beginning with ‘‘ REG_ ’’ for other error codes. If regcomp() detects an illegal regular expression, it may return REG_BADPAT, or it may return one of the error codes that more precisely describes the error.

B.5.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

An example of using the functions is shown in Figure B-3 The following demonstrates how the REG_NOTBOL flag could be used with regexec() to find all substrings in a line that match a pattern supplied by a user. (For simplicity of the example, very little error checking is done.) (void) regcomp (&re, pattern, 0); /∗ this call to regexec() finds the first match on the line ∗/ error = regexec (&re, &buffer[0], 1, &pm, 0); while (error == 0) { /∗ while matches found ∗/ <substring found between pm.rm_sp and pm.rm_ep> /∗ This call to regexec() finds the next match ∗/ error = regexec (&re, pm.rm_ep, 1, &pm, REG_NOTBOL ); }

B C Language Bindings Option

#include regex.h(7)

/∗ ∗ Match string against the extended regular expression in ∗ pattern, treating errors as no match. ∗ ∗ Return 1 for match, 0 for no match. ∗/

int match(const char ∗string, const char ∗pattern) { int status; regex_t re;

if (regcomp(&re, pattern, REG_EXTENDED | REG_NOSUB ) != 0) { return(0); /∗ report error ∗/ } status = regexec(&re, string, ( size_t ) 0, NULL, 0); regfree(&re); if (status != 0) { return(0); /∗ report error ∗/ } return status == 0; }

Figure B-3 − Example Regular Expression Matching

An application could use regerror(code,preg, NULL, ( size_t )0) to find out how big a buffer is needed for the generated string, malloc() a buffer to hold the string, and then call regerror() again to get the string. Alternately, it could allocate a fixed, static buffer that is big enough to hold most strings (perhaps 128 bytes), and then malloc() a larger buffer if it finds that this is too small. The regmatch() function must fill in all nmatch elements of pmatch, where nmatch and pmatch are supplied by the application, even if some elements of pmatch do not correspond to subexpressions in pattern. The application writer should note that there is probably no reason for using a value of nmatch that is larger than preg->re_nsub.

HISTORY OF DECISIONS MADE

The REG_ICASE flag supports the operations taken by the grep −i option and the historical implementations of ex and vi. Including this flag will make it easier for application code to be written that does the same thing as these utilities. The substrings reported in pmatch[] are defined using offsets from the start of the string rather than pointers. Since this is a new interface, there should be no impact on historical implementations or applications, and offsets should be just as

B.5 C Binding for Regular Expression Matching 791

easy to use as pointers. The change to offsets was made to facilitate future extensions in which the string to be searched is presented to regexec() in blocks, allowing a string to be searched that is not all in memory at once. A new type regoff_t is used for the elements of pmatch[] to ensure that the application can represent either the largest possible array in memory (important for a POSIX. 2-conforming application) or the largest possible file (important for an application using the extension where a file is searched in chunks).

The working group has rejected, at least for now, the inclusion of a regsub() function that would be used to do substitutions for a matched regular expression. While such a routine would be useful to some applications, its utility would be much more limited than the matching function described here. Both regular expression parsing and substitution are possible to implement without support other than that required by the C Standard {7}, but matching is much more complex than substituting. The only ‘‘difficult’’ part of substitution, given the information supplied by regexec(), is finding the next character in a string when there can be multibyte characters. That is a much wider issue, and one that needs a more general solution. The errno variable has not been used for error returns to avoid cluttering up the errno namespace for this feature. In Draft 9, the interface was modified so that the matched substrings rm_sp and rm_ep are in a separate regmatch_t structure instead of in regex_t. This allows a single compiled regular expression to be used simultaneously in several contexts; in main() and a signal handler, perhaps, or in multiple threads of lightweight processes. (The preg argument to regexec() is declared with type const, so the implementation is not permitted to use the structure to store intermediate results.) It also allows an application to request an arbitrary number of substrings from a regular expression. (Previous versions reported only ten substrings.) The number of subexpressions in the regular expression is reported in re_nsub in preg. With this change to regexec(), consideration was given to dropping the REG_NOSUB flag, since the user can now specify this with a zero nmatch argument to regexec(). However, keeping REG_NOSUB allows an implementation to use a different (perhaps more efficient) algorithm if it knows in regcomp() that no subexpressions need be reported. The implementation is only required to fill in pmatch if nmatch is not zero and if REG_NOSUB is not specified. Note that the size_t type, as defined in the C Standard {7}, is unsigned, so the description of regexec() does not need to address negative values of nmatch. The rules for reporting substrings of extended regular expressions are consistent with those used by Henry Spencer’s ‘‘almost public domain’’ version of regexec(). The REG_NOTBOL and REG_NOTEOL flags were added to regexec() in Draft 9. REG_NOTBOL was added to allow an application to do repeated searches for the same pattern in a line. If the pattern contains a circumflex character that should match the beginning of a line, then the pattern should only match when matched against the beginning of the line. Without the REG_NOTBOL flag, the application could rewrite the expression for subsequent matches, but in the general case this would require parsing the expression. The need for REG_NOTEOL is not as clear;

B C Language Bindings Option

it was added for symmetry. The addition of the regerror() function addresses the historical need for portable application programs to have access to error information more than ‘‘Function failed to compile/match your regular expression for unknown reasons.’’

This interface provides for two different methods of dealing with error conditions. The specific error codes ( REG_EBRACE, for example), defined in regex.h(7), allow an application to recover from an error if it is so able. Many applications, especially those that use patterns supplied by a user, will not try to deal with specific error cases, but will just use regerror() to obtain a human-readable error message to present to the user. The regerror() function uses a scheme similar to confstr() to deal with the problem of allocating memory to hold the generated string. The scheme used by strerror() in the C Standard {7} was considered unacceptable since it creates difficulties for multithreaded applications. ( POSIX. 4a, a standard for threads, started balloting in January 1991.) A different scheme used by regerror() in one draft of this standard was eliminated to improve internal consistency, and because the current interface produced greater consensus than the other. The preg argument is provided to regerror() to allow an implementation to generate a more descriptive message than would be possible with errcode alone. An implementation might, for example, save the character offset of the offending character of the pattern in a field of preg, and then include that in the generated message string. The implementation may also ignore preg. A REG_FILENAME flag was considered, but omitted. This flag caused regexec() to match patterns as described in 3.13 instead of regular expressions. This service is now provided by the fnmatch() function [see B.6].

B.5 C Binding for Regular Expression Matching 793

B.6 C Binding for Match Filename or Pathname Function: fnmatch()

B. ar(1)
Synopsis

#include fnmatch.h(7) int fnmatch(const char ∗pattern, const char ∗string, int flags);

B. make(1)
Description

The fnmatch() function shall match patterns as described in 3.13.1 and 3.13.2. It checks the string specified by the string argument to see if it matches the pattern specified by the pattern argument. The flags argument modifies the interpretation of pattern and string. It is the bitwise inclusive OR of zero or more of the flags shown in Table B-11, which are defined in the header fnmatch.h(7). If the FNM_PATHNAME flag is set in flags, then a slash character in string shall be explicitly matched by a slash in pattern; it shall not be matched by either the asterisk or question-mark special characters, nor by a bracket expression. If the FNM_PATHNAME flag is not set, the slash character shall be treated as an ordinary character.

Table B-11 − fnmatch() flags Argument

flags Description

FNM_NOESCAPE Disable backslash escaping FNM_PATHNAME Slash in string only matches slash in pattern FNM_PERIOD Leading period in string must be exactly matched by period in pattern

If FNM_NOESCAPE is not set in flags, a backslash character (\) in pattern followed by any other character shall match that second character in string. In particular, ’\\’ shall match a backslash in string. If FNM_NOESCAPE is set, a backslash character shall be treated as an ordinary character. If FNM_PERIOD is set in flags, then a leading period in string shall match a period in pattern as described by rule (2) in 3.13.2, where the location of ‘‘leading’’ is indicated by the value of FNM_PATHNAME:

• If FNM_PATHNAME is set, a period is ‘‘leading’’ if it is the first character in string or if it immediately follows a slash.
• If FNM_PATHNAME is not set, a period is ‘‘leading’’ only if it is the first character of string.

If FNM_PERIOD is not set, then no special restrictions shall be placed on matching a period.

B C Language Bindings Option

B. strip(1)
Returns

If string matches the pattern specified by pattern, then fnmatch() shall return zero. If there is no match, fnmatch() shall return FNM_NOMATCH, which shall be defined in the header fnmatch.h(7). If an error occurs, fnmatch() shall return another nonzero value.

B.6.4 Errors

This standard does not specify any error conditions that are required to be detected by the fnmatch() function. Some errors may be detected under unspecified conditions.

B.6.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

The fnmatch() function has two major uses. It could be used by an application or utility that needs to read a directory and apply a pattern against each entry. The find utility is an example of this. It can also be used by the pax utility to process its pattern operands, or by applications that need to match strings in a similar manner.

HISTORY OF DECISIONS MADE

This function replaces the REG_FILENAME flag of regcomp() in early drafts. It provides virtually the same functionality as the regcomp() and regexec() functions using the REG_FILENAME and REG_FSLASH flags [the REG_FSLASH flag was proposed for regcomp(), and would have had the opposite effect from FMN_PATHNAME ], but with a simpler interface and less overhead. The name fnmatch() is intended to imply filename match, rather than pathname match. The default action of this function is to match filenames, rather than pathnames, since it gives no special significance to the slash character. With the FNM_PATHNAME flag, fnmatch() does match pathnames, but without tilde expansion, parameter expansion, or special treatment for period at the beginning of a filename.

B.6 C Binding for Match Filename or Pathname 795

B.7 C Binding for Command Option Parsing Function: getopt()

B.7.1 Synopsis

#include unistd.h(7) int getopt(int argc, char ∗ const argv[ ], const char ∗optstring);

extern char ∗optarg; extern int optind, opterr, optopt;

B.7.2 Description

The getopt() function is a command-line parser that can be used by applications that follow Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in 2.10.2. The remaining guidelines are not addressed by getopt() and are the responsibility of the application. The parameters argc and argv are the argument count and argument array as passed to main(). The argument optstring is a string of recognized option characters; if a character is followed by a colon, the option takes an argument. All option characters allowed by Utility Syntax Guideline 3 are allowed in optstring. The implementation may accept other characters as an extension. The variable optind is the index of the next element of the argv[] vector to be processed. It is initialized to 1 by the system, and getopt() updates it when it finishes with each element of argv[]. When an element of argv[] contains multiple option characters, it is unspecified how getopt() determines which options have already been processed. The getopt() function shall return the next option character from argv that matches a character in optstring, if there is one that matches. If the option takes an argument, getopt() shall set the variable optarg to point to the optionargument as follows:

1. If the option was the last character in the string pointed to by an element of argv, then optarg contains the next element of argv, and optind shall be incremented by 2. If the resulting value of optind is not less than argc, this indicates a missing option argument, and getopt() shall return an error indication.
2. Otherwise, optarg points to the string following the option character in that element of argv, and optind shall be incremented by 1.

If, when getopt() is called, argv[optind] is NULL, ∗argv[optind] is not the character −, or argv[optind] points to the string "−", getopt() shall return −1 without changing optind. If argv[optind] points to the string "−−", getopt() shall return −1 after incrementing optind.

B C Language Bindings Option

If getopt() encounters an option character that is not contained in optstring, it shall return the question-mark (?) character. If it detects a missing option argument, it shall return the colon character (:) if the first character of optstring was a colon, or a question-mark character otherwise. In either case, getopt() shall set the variable optopt to the option character that caused the error. If the application has not set the variable opterr to zero and the first character of optstring is not a colon, getopt() shall also print a diagnostic message to standard error using the formatting rules specified for the getopts utility (see getopts(1) ).

B.7.3 Returns

The getopt() function shall return the next option character specified on the command line. The value −1 shall be returned when all command line options have been parsed.

B.7.4 Errors

If an invalid option is encountered, getopt() shall return a question-mark character. If an option with a missing option argument is encountered, getopt() shall return either a question-mark or a colon, as described previously.

B.7.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

The getopt() function is only required to support option characters included in Guideline 3. Many historical implementations of getopt() support other characters as options. This is an allowed extension, but applications that use extensions are not maximally portable. Note that support for multibyte option characters is only possible when such characters can be represented as type int. The code fragment in Figure B-4 shows how one might process the arguments for a utility that can take the mutually exclusive options a and b and the options f and o, both of which require arguments. The code in Figure B-4 accepts any of the following as equivalent: cmd −ao arg path path cmd −a −o arg path path cmd −o arg −a path path cmd −a −o arg −− path path cmd −a −oarg path path cmd −aoarg path path

HISTORY OF DECISIONS MADE

Support for the optopt variable was added in Draft 9. This documents historical practice, and allows the application to obtain the identity of the invalid option.

B.7 C Binding for Command Option Parsing 797

#include unistd.h(7) int main (int argc, char ∗argv[ ]) { int c, bflg, aflg, errflg = 0; char ∗ifile, ∗ofile; extern char ∗optarg; extern int optind, optopt; . . . while ((c = getopt(argc, argv, ":abf:o:")) != -1) { switch (c) { case ’a’: if (bflg) errflg = 1; else aflg = 1; break; case ’b’: if (aflg) errflg = 1; else bflg = 1; bproc( ); break; case ’f’: ifile = optarg; break; case ’o’: ofile = optarg; break; case ’:’: /∗ -f or -o without option-arg ∗/ fprintf (stderr, "Option -%c requires an option-argument\n", optopt); errflg = 1; break; case ’?’: fprintf (stderr, "Unrecognized option: -%c\n", optopt); errflg = 1; break; } } if (errflg) { fprintf(stderr, "usage: . . . "); exit(2); } for ( ; optind < argc; optind++) { if (access(argv[optind], R_OK )) { . . . }

Figure B-4 − Argument Processing with getopt()

B C Language Bindings Option

The description was extensively rewritten in Draft 9 to be more explicit about how optarg and optind are set, and to recognize that this routine deals with a vector of string pointers, not directly with a shell command line. The description was modified in Draft 9 to make it clear that getopt(), like the getopts utility, shall deal with option-arguments whether separated from the option by <blank>s or not. Note that the requirements on getopt() and getopts are more stringent than the Utility Syntax Guidelines. The getopt() function has been changed to return −1, rather than EOF, so that stdio.h(7) is not required. The special significance of a colon as the first character of optstring was added in Draft 11 to make getopt() consistent with the getopts utility. It allows an application to make a distinction between a missing argument and an incorrect option letter without having to examine the option letter. It is true that a missing argument can only be detected in one case, but that is a case that has to be considered.

B.8 C Binding for Generate Pathnames Matching a Pattern Functions: glob(), globfree()

B.8.1 Synopsis

#include glob.h(7) int glob(const char ∗pattern, int flags, int (∗errfunc)(const char ∗epath, int eerrno), glob_t ∗pglob); void globfree( glob_t ∗pglob);

B.8.2 Description

The glob() function is a pathname generator that implements the rules defined in 3.13, with optional support for rule (3) in 3.13.3. The header glob.h(7) defines the structure type glob_t, which includes at least the members shown in Table B-12. The argument pattern is a pointer to a pathname pattern to be expanded. The glob() function shall match all accessible pathnames against this pattern and develop a list of all pathnames that match. In order to have access to a pathname, glob() requires search permission on every component of a path except the last and read permission on each directory of any filename component of pattern that contains any of the special characters ∗, ? or [. The glob() function stores the number of matched pathnames into pglob->gl_pathc and a pointer to a list of pointers to pathnames into pglob->gl_pathv. The pathnames are in sort order as defined by 2.2.2.30. The first pointer after the last pathname shall be NULL. If the pattern does not match any pathnames, the returned number of matched paths is set to zero.

B.8 C Binding for Generate Pathnames Matching a Pattern 799

Table B-12 − Structure Type glob_t

Member Member Description Type Name

size_t gl_pathc Count of paths matched by pattern. char ∗∗ gl_pathv Pointer to a list of matched pathnames. size_t gl_offs Slots to reserve at the beginning of gl_pathv.

It is the caller’s responsibility to create the structure pointed to by pglob. The glob() function shall allocate other space as needed, including the memory pointed to by gl_pathv. The globfree() function shall free any space associated with pglob from a previous call to glob(). The argument flags is used to control the behavior of glob(). The value of flags is the bitwise inclusive OR of any of the constants shown in Table B-13, which are defined in glob.h(7).

Table B-13 − glob() flags Argument

Name Description

GLOB_APPEND Append pathnames generated to the ones from a previous call to glob() .GLOB_DOOFFS Make use of pglob->gl_offs. If this flag is set, pglob->gl_offs is used to specify how many NULL pointers to add to the beginning of pglob->gl_pathv. In other words, pglob->gl_pathv shall point to pglob->gl_offs NULL pointers, followed by pglob->gl_pathc pathname pointers, followed by a NULL pointer. GLOB_ERR Causes glob() to return when it encounters a directory that it cannot open or read. Ordinarily, glob() continues to find matches. GLOB_MARK Each pathname that is a directory that matches pattern has a slash appended. GLOB_NOCHECK Support rule (3) in 3.13.3. If pattern does not match any pathname, then glob() shall return a list consisting of only pattern, and the number of matched pathnames is 1. GLOB_NOESCAPE Disable backslash escaping. GLOB_NOSORT Ordinarily, glob() sorts the matching pathnames according to the definition of collation sequence in 2.2.2.30. When this flag is used the order of pathnames returned is unspecified.

The GLOB_APPEND flag can be used to append a new set of words to those generated by a previous call to glob(). The following rules apply when two or more calls to glob() are made with the same value of pglob and without intervening calls to globfree():

1. The first such call shall not set GLOB_APPEND. All subsequent calls shall set it.

B C Language Bindings Option

1. All of the calls shall set GLOB_DOOFFS, or all shall not set it.

1. After the second call, pglob->gl_pathv shall point to a list containing the following: (a) Zero or more NULLs, as specified by GLOB_DOOFFS and pglob->gl_offs. (b) Pointers to the pathnames that were in the pglob->gl_pathv list before the call, in the same order as before. (c) Pointers to the new pathnames generated by the second call, in the specified order.
2. The count returned in pglob->gl_pathc shall be the total number of pathnames from the two calls.

The application can change any of the fields in Table B-12 after a call to glob(), but if it does it shall reset them to the original value before a subsequent call, using the same pglob value, to globfree() or glob() with the GLOB_APPEND flag.

If, during the search, a directory is encountered that cannot be opened or read and errfunc is not NULL, glob() shall call (∗errfunc)() with two arguments:

1. The epath argument is a pointer to the path that failed.
2. The eerrno argument is the value of errno from the failure, as set by the POSIX. 1 {8} opendir(), readdir(), or stat() functions. (Other values may be used to report other errors not explicitly documented for those functions.)

If (∗errfunc)() is called and returns nonzero, or if the GLOB_ERR flag is set in flags, glob() shall stop the scan and return GLOB_ABORTED after setting gl_pathc and gl_pathv in pglob to reflect the paths already scanned. If GLOB_ERR is not set and either errfunc is NULL or (∗errfunc)() returns zero, the error shall be ignored.

B.8.3 Returns

On successful completion, glob() shall return zero. The argument pglob->gl_pathc shall return the number of matched pathnames and the argument pglob->gl_pathv shall contain a pointer to a null-terminated list of matched and sorted pathnames. However, if pglob->gl_pathc is zero, the content of pglob->gl_pathv is undefined.

B.8.4 Errors

If glob() terminates due to an error, it shall return one of the nonzero constants shown in Table B-14, which are defined in glob.h(7). The arguments pglob->gl_pathc and pglob->gl_pathv are still set as defined above in Returns.

B.8 C Binding for Generate Pathnames Matching a Pattern 801

Table B-14 − glob() Error Return Values

Name Description

GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (∗errfunc)() returned nonzero. GLOB_NOMATCH The pattern does not match any exiting pathname, and GLOB_NOCHECK was not set in flags. GLOB_NOSPACE An attempt to allocate memory failed.

B.8.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

This function is not provided for the purpose of enabling utilities to perform pathname expansion on their arguments, as this operation is performed by the shell, and utilities are explicitly not expected to redo this. Instead, it is provided for applications that need to do pathname expansion on strings obtained from other sources, such as a pattern typed by a user or read from a file. If a utility needs to see if a pathname matches a given pattern, it can use fnmatch(). Note that gl_pathc and gl_pathv have meaning even if glob() fails. This allows glob() to report partial results in the event of an error. However, if gl_pathc is zero, gl_pathv is unspecified even if glob() did not return an error. The GLOB_NOCHECK option could be used when an application wants to expand a pathname if wildcards are specified, but wants to treat the pattern as just a string otherwise. The sh utility might use this for option-arguments, for example. One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with the POSIX. 1 {8} execv(), execve(), or execvp() functions. Suppose, for example, that an application wants to do the equivalent of ls −l ∗.c, but for some reason system("ls −l ∗.c") is not acceptable. The application could obtain (approximately) the same result using the sequence: globbuf.gl_offs = 2; glob ("∗.c", GLOB_DOOFFS, NULL, &globbuf); globbuf.gl_pathv[0] = "ls"; globbuf.gl_pathv[1] = "-l"; execvp ("ls", &globbuf.gl_pathv[0]); Using the same example, ls −l ∗.c ∗.h could be approximately simulated using GLOB_APPEND as follows: globbuf.gl_offs = 2; glob ("∗.c", GLOB_DOOFFS, NULL, &globbuf); glob ("∗.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); ... etc. ...

B C Language Bindings Option

The new pathnames generated by a subsequent call with GLOB_APPEND are not sorted together with the previous pathnames. This mirrors the way that the shell handles pathname expansion when multiple expansions are done on a command line.

HISTORY OF DECISIONS MADE

The interface was simplified to a useful, but less complex, subset. The errfunc argument was added to allow errors to be reported. A reviewer claimed that the GLOB_DOOFFS flag is unnecessary because it could be simulated using: new = (char ∗∗)malloc((n + pglob->gl_pathc + 1) ∗ sizeof (char ∗)); (void) memcpy (new+n, pglob->gl_pathv, pglob->gl_pathc ∗ sizeof(char ∗)); (void) memset (new, 0, n ∗ sizeof (char ∗)); free (pglob->gl_pathv); pglob->gl_pathv = new; However, this assumes that the memory pointed to by gl_pathv is a block that was separately created using malloc(). This is not necessarily the case. An application should make no assumptions about how the memory referenced by fields in pglob was allocated. It might have been obtained from malloc() in a large chunk, and then carved up within glob(), or it might have been created using a different memory allocator. It is not the intent of this standard to specify or imply how the memory used by glob() is managed. The structure elements gl_pathc and gl_pathv were renamed from gl_argc and gl_argv in Draft 9. The old names implied an association with the parameters to main() that does not necessarily exist. The GLOB_APPEND flag was added in Draft 9 at the request of a reviewer. This flag would be used when an application wants to expand several different patterns into a single list. Tilde and parameter expansion were removed from glob() in Draft 9. Applications that need these expansions should use the wordexp() function [see B.9].

B.8 C Binding for Generate Pathnames Matching a Pattern 803

B.9 C Binding for Perform Word Expansions Functions: wordexp(), wordfree()

B.9.1 Synopsis

#include wordexp.h(7) int wordexp(const char ∗words, wordexp_t ∗pwordexp, int flags); void wordfree( wordexp_t ∗pwordexp);

B.9.2 Description

The wordexp() function shall perform word expansions as described in 3.6, subject to quoting as in 3.2, and place the list of expanded words into pwordexp. The expansions shall be the same as would be performed by the shell if words were the part of a command line representing the arguments to a utility. Therefore, words shall not contain an unquoted <newline> or any of the unquoted shell special characters |, &, ;, <, or >, except in the context of command substitution as specified in 3.6.3. It also shall not contain unquoted parentheses or braces, except in the context of command or variable substitution. If words contains an unquoted comment character (number sign) that is the beginning of a token, wordexp() may treat the comment character as a regular character, or may interpret it as a comment indicator and ignore the remainder of words. The header wordexp.h(7) defines the structure type wordexp_t, which includes at least the members shown in Table B-15.

Table B-15 − Structure Type wordexp_t

Member Member Description Type Name

size_t we_wordc Count of words matched by words. char ∗∗ we_wordv Pointer to list of expanded words. size_t we_offs Slots to reserve at the beginning of we_wordv.

The argument words is a pointer to a string containing one or more words to be expanded. The wordexp() function shall store the number of generated words into we_wordc and a pointer to a list of pointers to words in we_wordv. Each individual field created during field splitting (see 3.6.5) or pathname expansion (see 3.6.6) is a separate word in the we_wordv list. The words are in order as described in 3.6. The first pointer after the last word pointer shall be NULL. The expansion of special parameters described in 3.5.2 is unspecified. It is the caller’s responsibility to create the structure pointed to by pwordexp. The wordexp() function allocates other space as needed, including memory pointed to

B C Language Bindings Option

by we_wordv. The wordfree() function shall free any memory associated with pwordexp from a previous call to wordexp(). The argument flags is used to control the behavior of wordexp(). The value of flags is the bitwise inclusive OR of any of the constants in Table B-16, which are defined in wordexp.h(7).

Table B-16 − wordexp() flags Argument

Name Description

WRDE_APPEND Append words generated to the ones from a previous call to wordexp() .WRDE_DOOFFS Make use of we_offs. If this flag is set, we_offs is used to specify how many NULL pointers to add to the beginning of we_wordv. In other words, we_wordv shall point to we_offs NULL pointers, followed by we_wordc word pointers, followed by a NULL pointer. WRDE_NOCMD Fail if command substitution, as specified in 3.6.3, is requested. WRDE_REUSE The pwordexp argument was passed to a previous successful call to wordexp(), and has not been passed to wordfree(). The result shall be the same as if the application had called wordfree() and then called wordexp() without WRDE_REUSE .WRDE_SHOWERR Do not redirect standard error to /dev/null. WRDE_UNDEF Report error on an attempt to expand an undefined shell variable.

The WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to wordexp(). The following rules apply when two or more calls to wordexp() are made with the same value of pwordexp and without intervening calls to wordfree():

1. The first such call shall not set WRDE_APPEND. All subsequent calls shall set it.
2. All of the calls shall set WRDE_DOOFFS, or all shall not set it.
3. After the second and each subsequent call, we_wordv shall point to a list containing the following: (a) Zero or more NULLs, as specified by WRDE_DOOFFS and we_offs. (b) Pointers to the words that were in the we_wordv list before the call, in the same order as before. (c) Pointers to the new words generated by the latest call, in the specified order.
4. The count returned in we_wordc shall be the total number of words from all of the calls.

The application can change any of the fields in Table B-15 after a call to wordexp(), but if it does it shall reset them to the original value before a subsequent call, using the same pwordexp value, to wordfree() or wordexp() with the WRDE_APPEND or WRDE_REUSE flag.

B.9 C Binding for Perform Word Expansions 805

If words contains an unquoted <newline>, |, &, ;, <, >, parenthesis, or brace in an inappropriate context, wordexp() shall fail, and the number of expanded words shall be zero. Unless WRDE_SHOWERR is set in flags, wordexp() shall redirect standard error to /dev/null for any utilities executed as a result of command substitution while expanding words. If WRDE_SHOWERR is set, wordexp() may write messages to standard error if syntax errors are detected while expanding words. If WRDE_DOOFFS is set, then we_offs shall have the same value for each wordexp() call and the wordfree() call using a given pglob.

B.9.3 Returns

If no errors are encountered while expanding words, wordexp() shall return zero. Otherwise it shall return a nonzero value.

B.9.4 Errors

Table B-17 − wordexp() Return Values

Name Description

WRDE_BADCHAR One of the unquoted characters |, &, ;, <, >, parentheses, or braces appears in words in an inappropriate context. WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags. WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. WRDE_NOSPACE Attempt to allocate memory failed WRDE_SYNTAX Shell syntax error, such as unbalanced parentheses or unterminated string.

If wordexp() terminates due to an error, it shall return one of the nonzero constants shown in Table B-17, which shall be defined in wordexp.h(7). The implementation may define additional error returns beginning with WRDE_. If wordexp() returns the error value WRDE_NOSPACE, then pwordexp->we_wordc and pwordexp->we_wordv shall be updated to reflect any words that were successfully expanded. In other cases, they shall not be modified.

B C Language Bindings Option

B.9.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

This function is intended to be used by an application that wants to do all of the shell’s expansions on a word or words obtained from a user. For example, if the application prompts for a file name (or list of file names) and then used wordexp() to process the input, the user could respond with anything that would be valid as input to the shell. The WRDE_NOCMD flag is provided for applications that, for security or other reasons, want to prevent a user from executing shell commands. Disallowing unquoted shell special characters also prevents unwanted side effects such as executing a command or writing a file.

HISTORY OF DECISIONS MADE

This function was added in Draft 9 as an alternative to glob(). There has been continuing controversy over exactly what features should be included in glob(). It is hoped that providing wordexp() (which provides all of the shell’s word expansions, but will probably be slow to execute), and glob() (which is faster but does only expansion of pathnames, without tilde or parameter expansion), will satisfy the majority of reviewers. While wordexp() could be implemented entirely as a library routine, it is expected that most implementations will run a shell in a subprocess to do the expansion. Two different approaches have been proposed for how the required information might be presented to the shell and the results returned. They are presented here as examples. One proposal is to extend the echo utility by adding a −q option. This option would cause echo to add a backslash before each backslash and each <blank> that occurs within an argument. The wordexp() function could then invoke the shell as follows: (void) strcpy (buffer, "echo -q "); (void) strcat (buffer, words); if ((flags & WRDE_SHOWERR ) == 0) (void) strcat (buffer, " 2>/dev/null"); f = popen (buffer, "r"); The wordexp() function would read the resulting output, remove unquoted backslashes, and break into words at unquoted <blank>s. If the WRDE_NOCMD flag was set, wordexp() would have to scan words before starting the subshell to make sure that there would be no command substitution. In any case, it would have to scan words for unquoted special characters. Another proposal is to add the following options to sh:

B.9 C Binding for Perform Word Expansions 807

−w wordlist This option provides a wordlist expansion service to applications. The words in wordlist are expanded, and the following is written to standard output:

1. The count of the number of words after expansion, in decimal, followed by a null byte.
2. The number of bytes needed to represent the expanded words (not including null separators), in decimal, followed by a null byte.
3. The expanded words, each terminated by a null byte. If an error is encountered during word expansion, sh exits with a nonzero status after writing the above to report any words successfully expanded −P Run in ‘‘protected’’ mode. If specified with the −w option, no command substitution is performed.

With these options, wordexp() could be implemented fairly simply by creating a subprocess using fork(), and executing sh using the line: execl(<shell path>, "sh", "-P", "-w", words, (char ∗)0); after directing standard error to /dev/null. It seemed objectionable for a library routine to write messages to standard error, unless explicitly requested, so wordexp() is required to redirect standard error to /dev/null to ensure that no messages are generated, even for commands executed for command substitution. The new WRDE_SHOWERR flag can be specified to request that error messages be written. The WRDE_REUSE flag allows the implementation to avoid the expense of freeing and reallocating memory, if that is possible. A minimal implementation can just call wordfree() when WRDE_REUSE is set.

B C Language Bindings Option

B.10 C Binding for Get POSIX Configurable Variables

B.10.1 C Binding for Get String-Valued Configurable Variables

Function: confstr()

B.10.1.1 Synopsis

#include unistd.h(7) size_t confstr(int name, char ∗buf, size_t len);

B.10.1.2 Description

The confstr() function provides a method for applications to get configurationdefined string values. Its use and purpose are similar to the sysconf() function defined in POSIX. 1 {8}, but it is used where string values rather than numeric values are returned. The name argument represents the system variable to be queried. The implementation shall support all of the name values shown in Table B-18, which are defined in unistd.h(7). It may support others.

Table B-18 − confstr() name Values

name Value String returned by confstr()

_CS_PATH A value for the PATH environment variable that finds all standard utilities.

If len is not zero, and if name has a configuration-defined value, confstr() shall copy that value into the len-byte buffer pointed to by buf. If the string to be returned is longer than len bytes, including the terminating null, then confstr() shall truncate the string to len−1 bytes and null-terminate the result. The application can detect that the string was truncated by comparing the value returned by confstr() with len. If len is zero and buf is NULL, then confstr() still shall return the integer value as defined below, but shall not return a string. If len is zero but buf is not NULL, the result is unspecified.

B.10.1.3 Returns

If name does not have a configuration-defined value, confstr() shall return zero and leave errno unchanged. If name has a configuration-defined value, the confstr() function shall return the size of buffer that would be needed to hold the entire configuration-defined value.

B.10 C Binding for Get POSIX Configurable Variables 809

If this return value is greater than len, the string returned in buf has been truncated.

B.10.1.4 Errors

If any of the following conditions occur, confstr() shall return zero and set errno to the corresponding value:

EINVAL

The value of the name argument is invalid.

B.10.1.5 Rationale. (This subclause is not a part of P1003. 2)

EXAMPLES

An application can distinguish between an invalid name parameter value and one that corresponds to a configurable variable that has no configuration-defined value by checking if errno has been modified. This mirrors the behavior of sysconf() in POSIX. 1 {8}. The original need for this function was to provide a way of finding the configuration-defined default value for the environment variable PATH. Since PATH can be modified by the user to include directories that could contain utilities replacing POSIX. 2 standard utilities, applications need a way to determine the system-supplied PATH environment variable value that contains the correct search path for the POSIX. 2 standard utilities. An application could use confstr(name, NULL, ( size_t ) 0) to find out how big a buffer is needed for the string value, malloc() a buffer to hold the string, and call confstr() again to get the string. Alternately, it could allocate a fixed, static buffer that is big enough to hold most answers (512 bytes, maybe, or 1024), but then malloc() a larger buffer if it finds that this is too small.

HISTORY OF DECISIONS MADE

In Draft 7, these values and sysconf() values defined in POSIX. 1 {8} were obtained using a function named posixconf(). However, that routine was dropped in favor of csysconf(). There did not seem to be any reason to provide the redundant interface to POSIX. 1 {8} functions, nor to return values as strings when numeric values are really what are needed. csysconf() could be extended to return strings for other related standards or features. In Draft 9, csysconf() has been replaced by confstr(). The name was changed because too many people were confused by the name; they thought that the ‘c’ referred to the C language, rather than characters (as distinct from integers). The confstr() function also copies the returned string into a buffer supplied by the application instead of returning a pointer to a string. This allows a cleaner interface in some implementations (lightweight processes were mentioned), and resolves questions about when the application must copy the string returned.

B C Language Bindings Option

B.10.2 C Binding for Get Numeric-Valued Configurable Variables

Functions: sysconf(), pathconf(), fpathconf() A system that supports the C Language Bindings Option shall support the C language bindings defined in POSIX. 1 {8} for the sysconf(), pathconf(), and fpathconf() functions. Of the name values defined in POSIX. 1 {8}, only those that correspond to numeric-valued configuration values listed in Table 7-1, are required by POSIX. 2. In addition, the sysconf() function shall support the name values in Table B-19, defined in unistd.h(7), to provide values for values in 2.13.1.

Table B-19 − C Bindings for Numeric-Valued Configurable Variables

Symbolic Limit name Value

BC_BASE_MAX _SC_BC_BASE_MAX BC_DIM_MAX _SC_BC_DIM_MAX BC_SCALE_MAX _SC_BC_SCALE_MAX BC_STRING_MAX _SC_BC_STRING_MAX COLL_WEIGHTS_MAX _SC_COLL_WEIGHTS_MAX EXPR_NEST_MAX _SC_EXPR_NEST_MAX LINE_MAX _SC_LINE_MAX RE_DUP_MAX _SC_RE_DUP_MAX POSIX2_VERSION _SC_2_VERSION POSIX2_C_DEV _SC_2_C_DEV POSIX2_FORT_DEV _SC_2_FORT_DEV POSIX2_FORT_RUN _SC_2_FORT_RUN POSIX2_LOCALEDEF _SC_2_LOCALEDEF POSIX2_SW_DEV _SC_2_SW_DEV

B.10.3 Rationale. (This subclause is not a part of P1003. 2)

In Draft 9, the name values corresponding to the _POSIX2_∗ symbolic limits were changed to more closely follow the convention used in POSIX. 1 {8}. In POSIX. 1 {8}, for example, the name value for _POSIX_VERSION is _SC_VERSION. The POSIX. 2 name value for _POSIX2_C_DEV (actually, it was _POSIX_C_DEV in Draft 8) was _SC_POSIX_C_DEV, and is now _SC_2_C_DEV. If sysconf(_SC_2_VERSION) is not equal to the value of the _POSIX2_VERSION symbolic constant (see B.2.2), the utilities available via system() or popen() might not behave as described in this standard. This would mean that the application is not running in an environment that conforms to POSIX. 2. Some applications might be able to deal with this, others might not. However, the interfaces defined in Annex B shall continue to operate as specified, even if sysconf(_SC_2_VERSION) reports that the utilities no longer perform as specified.

B.10 C Binding for Get POSIX Configurable Variables 811

B.11 C Binding for Locale Control The C binding to the services described in 7.9 shall be the setlocale() function defined in POSIX. 1 {8} 8.1.2. In addition to the category values defined in POSIX. 1 {8}, setlocale() shall also accept the value LC_MESSAGES, which shall be defined in locale.h(7).

B.11.1 C Binding for Locale Control Rationale. (This subclause is not a part of P1003. 2)

The order in which the various locale categories are processed by setlocale() is not specified by POSIX. 1 {8}, so the place for LC_MESSAGES in that order is also unspecified.

B C Language Bindings Option

Annex C (normative) FORTRAN Development and Runtime Utilities Options

This annex describes utilities used for the development of FORTRAN language applications, including compilation or translation of FORTRAN source code, and the execution of certain FORTRAN applications at runtime. The utilities described in this annex may be provided by the conforming system; however, any system claiming conformance to the FORTRAN Development Utilities Option shall provide the fort77 utility and any system claiming conformance to the FORTRAN Runtime Utilities Option shall provide the asa utility.

C.0.1 FORTRAN Development and Runtime Utilities Options Rationale. (This subclause is not a part of P1003. 2)

This clause is included in this standard as a temporary measure to accommodate existing FORTRAN developers. It is the intention of the POSIX. 2 working group that this annex be moved from this standard to the emerging standard being developed by the POSIX. 9 working group, which will specify FORTRAN -specific interfaces to the basic services provided by this standard and POSIX. 1. The movement of this annex should occur in a later version of this standard. See the rationale for asa for a description of the FORTRAN Runtime Utilities Option and why it was split off from the FORTRAN Development Utilities Option.