IEEE P1003.2 Draft 11.2 - September 1991 Copyright (c) 1991 by the Institute of Electrical and Electronics Engineers, Inc. 345 East 47th Street New York, NY 10017, USA All rights reserved as an unpublished work. This is an unapproved and unpublished IEEE Standards Draft, subject to change. The publication, distribution, or copying of this draft, as well as all derivative works based on this draft, is expressly prohibited except as set forth below. Permission is hereby granted for IEEE Standards Committee participants to reproduce this document for purposes of IEEE standardization activities only, and subject to the restrictions contained herein. Permission is hereby also granted for member bodies and technical committees of ISO and IEC to reproduce this document for purposes of developing a national position, subject to the restrictions contained herein. Permission is hereby also granted to the preceding entities to make limited copies of this document in an electronic form only for the stated activities. The following restrictions apply to reproducing or transmitting the document in any form: 1) all copies or portions thereof must identify the document's IEEE project number and draft number, and must be accompanied by this entire notice in a prominent location; 2) no portion of this document may be redistributed in any modified or abridged form without the prior approval of the IEEE Standards Department. Other entities seeking permission to reproduce this document, or any portion thereof, for standardization or other activities, must contact the IEEE Standards Department for the appropriate license. Use of information contained in this unapproved draft is at your own risk. IEEE Standards Department Copyright and Permissions 445 Hoes Lane, P.O. Box 1331 Piscataway, NJ 08855-1331, USA +1 (908) 562-3800 +1 (908) 562-1571 [FAX] Part 2: SHELL AND UTILITIES P1003.2/D11.2 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 _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e Support for the _o_p_t_o_p_t variable was added in Draft 9. This documents historical practice, and allows the application to obtain the identity of the invalid option. The description was extensively rewritten in Draft 9 to be more explicit about how _o_p_t_a_r_g and _o_p_t_i_n_d 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 _g_e_t_o_p_t(), like the getopts utility, shall deal with option-arguments whether separated from the option by _s or not. Note that the requirements on _g_e_t_o_p_t() and getopts are more stringent than the Utility Syntax Guidelines. The _g_e_t_o_p_t() function has been changed to return -1, rather than EOF, so that <_s_t_d_i_o._h> is not required. The special significance of a colon as the first character of _o_p_t_s_t_r_i_n_g 1 was added in Draft 11 to make _g_e_t_o_p_t() consistent with the getopts 1 utility. It allows an application to make a distinction between a 1 missing argument and an incorrect option letter without having to examine 1 the option letter. It is true that a missing argument can only be 1 detected in one case, but that is a case that has to be considered. 1 END_RATIONALE 1 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.7 C Binding for Command Option Parsing 941 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX B.8 C Binding for Generate Pathnames Matching a Pattern Functions: _g_l_o_b(), _g_l_o_b_f_r_e_e() B.8.1 Synopsis #include int glob(const char *_p_a_t_t_e_r_n, int _f_l_a_g_s, int (*_e_r_r_f_u_n_c)(const char *_e_p_a_t_h, int _e_e_r_r_n_o), glob_t *_p_g_l_o_b); void globfree(glob_t *_p_g_l_o_b); B.8.2 Description The _g_l_o_b() 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 defines the structure type _g_l_o_b__t, which includes at least the members shown in Table B-12. Table B-12 - Structure Type _gggg_llll_oooo_bbbb______tttt __________________________________________________________________________________________________________________________________________________ Member Member Type Name Description _________________________________________________________________________ _s_i_z_e__t _g_l__p_a_t_h_c Count of paths matched by _p_a_t_t_e_r_n. 11 _c_h_a_r ** _g_l__p_a_t_h_v Pointer to a list of matched pathnames. _s_i_z_e__t _g_l__o_f_f_s Slots to reserve at the beginning of 11 _g_l__p_a_t_h_v. 1 __________________________________________________________________________________________________________________________________________________ The argument _p_a_t_t_e_r_n is a pointer to a pathname pattern to be expanded. The _g_l_o_b() 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, _g_l_o_b() requires search permission on every component of a path except the last and read permission on each directory of any filename component of _p_a_t_t_e_r_n that contains any of the special characters *, ? or [. The _g_l_o_b() function stores the number of matched pathnames into _p_g_l_o_b->_g_l__p_a_t_h_c and a pointer to a list of pointers to pathnames into _p_g_l_o_b->_g_l__p_a_t_h_v. 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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 942 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 It is the caller's responsibility to create the structure pointed to by _p_g_l_o_b. The _g_l_o_b() function shall allocate other space as needed, including the memory pointed to by _g_l__p_a_t_h_v. The _g_l_o_b_f_r_e_e() function shall free any space associated with _p_g_l_o_b from a previous call to _g_l_o_b(). The argument _f_l_a_g_s is used to control the behavior of _g_l_o_b(). The value of _f_l_a_g_s is the bitwise inclusive OR of any of the constants shown in Table B-13, which are defined in . Table B-13 - _gggg_llll_oooo_bbbb() _ffff_llll_aaaa_gggg_ssss Argument __________________________________________________________________________________________________________________________________________________ Name Description _________________________________________________________________________ GLOB_APPEND Append pathnames generated to the ones from a previous call to _g_l_o_b(). GLOB_DOOFFS Make use of _p_g_l_o_b->_g_l__o_f_f_s. If this flag is set, _p_g_l_o_b->_g_l__o_f_f_s is used to specify how many NULL pointers to add to the beginning of _p_g_l_o_b->_g_l__p_a_t_h_v. In other words, _p_g_l_o_b->_g_l__p_a_t_h_v shall point to _p_g_l_o_b->_g_l__o_f_f_s NULL pointers, followed by _p_g_l_o_b->_g_l__p_a_t_h_c pathname pointers, followed by a NULL pointer. GLOB_ERR Causes _g_l_o_b() to return when it encounters a directory that it cannot open or read. Ordinarily, _g_l_o_b() continues to find matches. GLOB_MARK Each pathname that is a directory that matches _p_a_t_t_e_r_n has a slash appended. GLOB_NOCHECK Support rule (3) in 3.13.3. If _p_a_t_t_e_r_n does not match any pathname, then _g_l_o_b() shall return a list consisting of only _p_a_t_t_e_r_n, and the number of matched pathnames is 1. GLOB_NOESCAPE Disable backslash escaping. 1 GLOB_NOSORT Ordinarily, _g_l_o_b() sorts the matching pathnames according to the definition of _c_o_l_l_a_t_i_o_n _s_e_q_u_e_n_c_e 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 _g_l_o_b(). The following rules apply when 1 two or more calls to _g_l_o_b() are made with the same value of _p_g_l_o_b and 1 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.8 C Binding for Generate Pathnames Matching a Pattern 943 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX without intervening calls to _g_l_o_b_f_r_e_e(): 1 (1) The first such call shall not set GLOB_APPEND. All subsequent 1 calls shall set it. 1 (2) All of the calls shall set GLOB_DOOFFS, or all shall not set it. 1 (3) After the second call, _p_g_l_o_b->_g_l__p_a_t_h_v shall point to a list containing the following: (a) Zero or more NULLs, as specified by GLOB_DOOFFS and _p_g_l_o_b->_g_l__o_f_f_s. (b) Pointers to the pathnames that were in the _p_g_l_o_b->_g_l__p_a_t_h_v 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. (4) The count returned in _p_g_l_o_b->_g_l__p_a_t_h_c 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 1 to _g_l_o_b(), but if it does it shall reset them to the original value 1 before a subsequent call, using the same _p_g_l_o_b value, to _g_l_o_b_f_r_e_e() or 1 _g_l_o_b() with the GLOB_APPEND flag. 1 If, during the search, a directory is encountered that cannot be opened or read and _e_r_r_f_u_n_c is not NULL, _g_l_o_b() shall call (*_e_r_r_f_u_n_c)() with two arguments: (1) The _e_p_a_t_h argument is a pointer to the path that failed. (2) The _e_e_r_r_n_o argument is the value of _e_r_r_n_o from the failure, as set by the POSIX.1 {8} _o_p_e_n_d_i_r(), _r_e_a_d_d_i_r(), or _s_t_a_t() functions. (Other values may be used to report other errors not explicitly documented for those functions.) If (*_e_r_r_f_u_n_c)() is called and returns nonzero, or if the GLOB_ERR flag is set in _f_l_a_g_s, _g_l_o_b() shall stop the scan and return GLOB_ABORTED after setting _g_l__p_a_t_h_c and _g_l__p_a_t_h_v in _p_g_l_o_b to reflect the paths already scanned. If GLOB_ERR is not set and either _e_r_r_f_u_n_c is NULL or (*_e_r_r_f_u_n_c)() returns zero, the error shall be ignored. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 944 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 B.8.3 Returns On successful completion, _g_l_o_b() shall return zero. The argument _p_g_l_o_b->_g_l__p_a_t_h_c shall return the number of matched pathnames and the argument _p_g_l_o_b->_g_l__p_a_t_h_v shall contain a pointer to a null-terminated list of matched and sorted pathnames. However, if _p_g_l_o_b->_g_l__p_a_t_h_c is zero, the content of _p_g_l_o_b->_g_l__p_a_t_h_v is undefined. Table B-14 - _gggg_llll_oooo_bbbb() Error Return Values __________________________________________________________________________________________________________________________________________________ Name Description _________________________________________________________________________ GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*_e_r_r_f_u_n_c)() returned nonzero. GLOB_NOMATCH The _p_a_t_t_e_r_n does not match any exiting 11 pathname, and GLOB_NOCHECK was not set in 1 _f_l_a_g_s. 1 GLOB_NOSPACE An attempt to allocate memory failed. __________________________________________________________________________________________________________________________________________________ B.8.4 Errors If _g_l_o_b() terminates due to an error, it shall return one of the nonzero constants shown in Table B-14, which are defined in . The arguments _p_g_l_o_b->_g_l__p_a_t_h_c and _p_g_l_o_b->_g_l__p_a_t_h_v are still set as defined above in Returns. BEGIN_RATIONALE B.8.5 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e 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 _f_n_m_a_t_c_h(). Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.8 C Binding for Generate Pathnames Matching a Pattern 945 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX Note that _g_l__p_a_t_h_c and _g_l__p_a_t_h_v have meaning even if _g_l_o_b() fails. This allows _g_l_o_b() to report partial results in the event of an error. However, if _g_l__p_a_t_h_c is zero, _g_l__p_a_t_h_v is unspecified even if _g_l_o_b() 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} _e_x_e_c_v(), _e_x_e_c_v_e(), or _e_x_e_c_v_p() 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 (_a_p_p_r_o_x_i_m_a_t_e_l_y) 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. ... 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. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The interface was simplified to a useful, but less complex, subset. The _e_r_r_f_u_n_c 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: Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 946 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 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 _g_l__p_a_t_h_v is a block that was separately created using _m_a_l_l_o_c(). This is not necessarily the case. An application should make no assumptions about how the memory referenced by fields in _p_g_l_o_b was allocated. It might have been obtained from _m_a_l_l_o_c() in a large chunk, and then carved up within _g_l_o_b(), 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 _g_l_o_b() is managed. The structure elements _g_l__p_a_t_h_c and _g_l__p_a_t_h_v were renamed from _g_l__a_r_g_c and _g_l__a_r_g_v in Draft 9. The old names implied an association with the parameters to _m_a_i_n() 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 _g_l_o_b() in Draft 9. Applications that need these expansions should use the _w_o_r_d_e_x_p() function [see B.9]. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.8 C Binding for Generate Pathnames Matching a Pattern 947 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX B.9 C Binding for Perform Word Expansions Functions: _w_o_r_d_e_x_p(), _w_o_r_d_f_r_e_e() B.9.1 Synopsis #include int wordexp(const char *_w_o_r_d_s, wordexp_t *_p_w_o_r_d_e_x_p, int _f_l_a_g_s); void wordfree(wordexp_t *_p_w_o_r_d_e_x_p); B.9.2 Description The _w_o_r_d_e_x_p() 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 _p_w_o_r_d_e_x_p. The expansions shall be the same as would be performed by the shell if _w_o_r_d_s were the part of a command line representing the arguments to a utility. Therefore, _w_o_r_d_s shall not contain an unquoted 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 _w_o_r_d_s contains an unquoted comment character (number sign) that is the beginning of a token, _w_o_r_d_e_x_p() may treat the comment character as a regular character, or may interpret it as a comment indicator and ignore the remainder of _w_o_r_d_s. The header defines the structure type _w_o_r_d_e_x_p__t, which includes at least the members shown in Table B-15. Table B-15 - Structure Type _wwww_oooo_rrrr_dddd_eeee_xxxx_pppp______tttt __________________________________________________________________________________________________________________________________________________ Member Member Type Name Description _________________________________________________________________________ _s_i_z_e__t _w_e__w_o_r_d_c Count of words matched by _w_o_r_d_s. 11 _c_h_a_r ** _w_e__w_o_r_d_v Pointer to list of expanded words. _s_i_z_e__t _w_e__o_f_f_s Slots to reserve at the beginning of 11 _w_e__w_o_r_d_v. 1 __________________________________________________________________________________________________________________________________________________ The argument _w_o_r_d_s is a pointer to a string containing one or more words to be expanded. The _w_o_r_d_e_x_p() function shall store the number of generated words into _w_e__w_o_r_d_c and a pointer to a list of pointers to Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 948 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 words in _w_e__w_o_r_d_v. Each individual field created during field splitting (see 3.6.5) or pathname expansion (see 3.6.6) is a separate word in the _w_e__w_o_r_d_v 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 _p_w_o_r_d_e_x_p. The _w_o_r_d_e_x_p() function allocates other space as needed, including memory pointed to by _w_e__w_o_r_d_v. The _w_o_r_d_f_r_e_e() function shall free any memory associated with _p_w_o_r_d_e_x_p from a previous call to _w_o_r_d_e_x_p(). The argument _f_l_a_g_s is used to control the behavior of _w_o_r_d_e_x_p(). The value of _f_l_a_g_s is the bitwise inclusive OR of any of the constants in Table B-16, which are defined in . Table B-16 - _wwww_oooo_rrrr_dddd_eeee_xxxx_pppp() _ffff_llll_aaaa_gggg_ssss Argument __________________________________________________________________________________________________________________________________________________ Name Description _________________________________________________________________________ WRDE_APPEND Append words generated to the ones from a previous call to _w_o_r_d_e_x_p(). WRDE_DOOFFS Make use of _w_e__o_f_f_s. If this flag is set, _w_e__o_f_f_s is used to specify how many NULL pointers to add to the beginning of _w_e__w_o_r_d_v. In other words, _w_e__w_o_r_d_v shall point to _w_e__o_f_f_s NULL pointers, followed by _w_e__w_o_r_d_c word pointers, followed by a NULL pointer. WRDE_NOCMD Fail if command substitution, as specified in 3.6.3, is requested. WRDE_REUSE The _p_w_o_r_d_e_x_p argument was passed to a previous successful call to _w_o_r_d_e_x_p(), and has not been passed to _w_o_r_d_f_r_e_e(). The result shall be the same as if the application had called _w_o_r_d_f_r_e_e() and then called _w_o_r_d_e_x_p() 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 _w_o_r_d_e_x_p(). The following rules apply when two or more calls to _w_o_r_d_e_x_p() are made with the same value of Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.9 C Binding for Perform Word Expansions 949 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX _p_w_o_r_d_e_x_p and without intervening calls to _w_o_r_d_f_r_e_e(): (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, _w_e__w_o_r_d_v shall point to a list containing the following: (a) Zero or more NULLs, as specified by WRDE_DOOFFS and _w_e__o_f_f_s. (b) Pointers to the words that were in the _w_e__w_o_r_d_v 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 _w_e__w_o_r_d_c 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 1 to _w_o_r_d_e_x_p(), but if it does it shall reset them to the original value 1 before a subsequent call, using the same _p_w_o_r_d_e_x_p value, to _w_o_r_d_f_r_e_e() or 1 _w_o_r_d_e_x_p() with the WRDE_APPEND or WRDE_REUSE flag. 1 If _w_o_r_d_s contains an unquoted , |, &, ;, <, >, parenthesis, or brace in an inappropriate context, _w_o_r_d_e_x_p() shall fail, and the number of expanded words shall be zero. Unless WRDE_SHOWERR is set in _f_l_a_g_s, _w_o_r_d_e_x_p() shall redirect standard error to /dev/null for any utilities executed as a result of command substitution while expanding _w_o_r_d_s. If WRDE_SHOWERR is set, _w_o_r_d_e_x_p() may write messages to standard error if syntax errors are detected while expanding _w_o_r_d_s. If WRDE_DOOFFS is set, then _w_e__o_f_f_s shall have the same value for each 1 _w_o_r_d_e_x_p() call and the _w_o_r_d_f_r_e_e() call using a given _p_g_l_o_b. 1 B.9.3 Returns If no errors are encountered while expanding _w_o_r_d_s, _w_o_r_d_e_x_p() shall return zero. Otherwise it shall return a nonzero value. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 950 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 B.9.4 Errors Table B-17 - _wwww_oooo_rrrr_dddd_eeee_xxxx_pppp() Return Values __________________________________________________________________________________________________________________________________________________ Name Description _________________________________________________________________________ WRDE_BADCHAR One of the unquoted characters |, &, ;, <, >, parentheses, or braces appears in _w_o_r_d_s in an inappropriate context. WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in _f_l_a_g_s. 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 _w_o_r_d_e_x_p() terminates due to an error, it shall return one of the nonzero constants shown in Table B-17, which shall be defined in . The implementation may define additional error returns beginning with WRDE_. If _w_o_r_d_e_x_p() returns the error value WRDE_NOSPACE, then _p_w_o_r_d_e_x_p->_w_e__w_o_r_d_c and _p_w_o_r_d_e_x_p->_w_e__w_o_r_d_v shall be updated to reflect any words that were successfully expanded. In other cases, they shall not be modified. BEGIN_RATIONALE B.9.5 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e 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 _w_o_r_d_e_x_p() 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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.9 C Binding for Perform Word Expansions 951 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e This function was added in Draft 9 as an alternative to _g_l_o_b(). There has been continuing controversy over exactly what features should be included in _g_l_o_b(). It is hoped that providing _w_o_r_d_e_x_p() (which provides all of the shell's word expansions, but will probably be slow to execute), and _g_l_o_b() (which is faster but does only expansion of pathnames, without tilde or parameter expansion), will satisfy the majority of reviewers. While _w_o_r_d_e_x_p() could be implemented entirely as a library routine, it is 1 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 that occurs within an argument. The _w_o_r_d_e_x_p() function could then invoke the shell as follows: (void) strcpy (buffer, "echo -q "); (void) strcat (buffer, _w_o_r_d_s); if ((flags & WRDE_SHOWERR) == 0) (void) strcat (buffer, " 2>/dev/null"); f = popen (buffer, "r"); The _w_o_r_d_e_x_p() function would read the resulting output, remove unquoted backslashes, and break into words at unquoted _s. If the WRDE_NOCMD flag was set, _w_o_r_d_e_x_p() would have to scan _w_o_r_d_s before starting the subshell to make sure that there would be no command substitution. In any case, it would have to scan _w_o_r_d_s for unquoted special characters. Another proposal is to add the following options to sh: -w _w_o_r_d_l_i_s_t This option provides a wordlist expansion service to applications. The words in _w_o_r_d_l_i_s_t 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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 952 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 (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, _w_o_r_d_e_x_p() could be implemented fairly simply by creating a subprocess using _f_o_r_k(), and executing sh using the line: execl(<_s_h_e_l_l _p_a_t_h>, "_s_h", "-_P", "-_w", _w_o_r_d_s, (_c_h_a_r *)_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 _w_o_r_d_e_x_p() 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 _w_o_r_d_f_r_e_e() when WRDE_REUSE is set. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.9 C Binding for Perform Word Expansions 953 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX B.10 C Binding for Get POSIX Configurable Variables B.10.1 C Binding for Get String-Valued Configurable Variables Function: _c_o_n_f_s_t_r() B.10.1.1 Synopsis #include size_t confstr(int _n_a_m_e, char *_b_u_f, size_t _l_e_n); B.10.1.2 Description The _c_o_n_f_s_t_r() function provides a method for applications to get configuration-defined string values. Its use and purpose are similar to the _s_y_s_c_o_n_f() function defined in POSIX.1 {8}, but it is used where string values rather than numeric values are returned. The _n_a_m_e argument represents the system variable to be queried. The implementation shall support all of the _n_a_m_e values shown in Table B-18, which are defined in . It may support others. Table B-18 - confstr() _nnnn_aaaa_mmmm_eeee Values __________________________________________________________________________________________________________________________________________________ _nnnn_aaaa_mmmm_eeee Value String returned by confstr() _________________________________________________________________________ _CS_PATH A value for the PATH environment variable that finds all standard utilities. __________________________________________________________________________________________________________________________________________________ If _l_e_n is not zero, and if _n_a_m_e has a configuration-defined value, _c_o_n_f_s_t_r() shall copy that value into the _l_e_n-byte buffer pointed to by _b_u_f. If the string to be returned is longer than _l_e_n bytes, including the terminating null, then _c_o_n_f_s_t_r() shall truncate the string to _l_e_n-1 bytes and null-terminate the result. The application can detect that the string was truncated by comparing the value returned by _c_o_n_f_s_t_r() with _l_e_n. If _l_e_n is zero and _b_u_f is NULL, then _c_o_n_f_s_t_r() still shall return the integer value as defined below, but shall not return a string. If _l_e_n is zero but _b_u_f is not NULL, the result is unspecified. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 954 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 B.10.1.3 Returns If _n_a_m_e does not have a configuration-defined value, _c_o_n_f_s_t_r() shall return zero and leave _e_r_r_n_o unchanged. If _n_a_m_e has a configuration-defined value, the _c_o_n_f_s_t_r() function shall return the size of buffer that would be needed to hold the entire configuration-defined value. If this return value is greater than _l_e_n, the string returned in _b_u_f has been truncated. B.10.1.4 Errors If any of the following conditions occur, _c_o_n_f_s_t_r() shall return zero and set _e_r_r_n_o to the corresponding value: [EINVAL] The value of the _n_a_m_e argument is invalid. BEGIN_RATIONALE B.10.1.5 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e An application can distinguish between an invalid _n_a_m_e parameter value and one that corresponds to a configurable variable that has no configuration-defined value by checking if _e_r_r_n_o has been modified. This mirrors the behavior of _s_y_s_c_o_n_f() 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, _m_a_l_l_o_c() a buffer to hold the string, and call _c_o_n_f_s_t_r() 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 _m_a_l_l_o_c() a larger buffer if it finds that this is too small. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e In Draft 7, these values and _s_y_s_c_o_n_f() values defined in POSIX.1 {8} were obtained using a function named _p_o_s_i_x_c_o_n_f(). However, that routine was dropped in favor of _c_s_y_s_c_o_n_f(). 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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.10 C Binding for Get POSIX Configurable Variables 955 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX _c_s_y_s_c_o_n_f() could be extended to return strings for other related standards or features. In Draft 9, _c_s_y_s_c_o_n_f() has been replaced by _c_o_n_f_s_t_r(). 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 _c_o_n_f_s_t_r() 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. END_RATIONALE B.10.2 C Binding for Get Numeric-Valued Configurable Variables Functions: _s_y_s_c_o_n_f(), _p_a_t_h_c_o_n_f(), _f_p_a_t_h_c_o_n_f() A system that supports the C Language Bindings Option shall support the C language bindings defined in POSIX.1 {8} for the _s_y_s_c_o_n_f(), _p_a_t_h_c_o_n_f(), and _f_p_a_t_h_c_o_n_f() functions. Of the _n_a_m_e 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 _s_y_s_c_o_n_f() function shall support the _n_a_m_e values in Table B-19, defined in , to provide values for values in 2.13.1. BEGIN_RATIONALE B.10.3 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) In Draft 9, the _n_a_m_e 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 _n_a_m_e value for {_POSIX_VERSION} is _SC_VERSION. The POSIX.2 _n_a_m_e 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 _s_y_s_t_e_m() or _p_o_p_e_n() 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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 956 B C Language Bindings Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 Table B-19 - C Bindings for Numeric-Valued Configurable Variables __________________________________________________________________________________________________________________________________________________ Symbolic Limit _n_a_m_e 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 __________________________________________________________________________________________________________________________________________________ END_RATIONALE B.11 C Binding for Locale Control The C binding to the services described in 7.9 shall be the _s_e_t_l_o_c_a_l_e() function defined in POSIX.1 {8} 8.1.2. In addition to the category values defined in POSIX.1 {8}, _s_e_t_l_o_c_a_l_e() shall also accept the value LC_MESSAGES, which shall be defined in . BEGIN_RATIONALE B.11.1 C Binding for Locale Control Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) The order in which the various locale categories are processed by _s_e_t_l_o_c_a_l_e() is not specified by POSIX.1 {8}, so the place for LC_MESSAGES in that order is also unspecified. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. B.11 C Binding for Locale Control 957 P1003.2/D11.2 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. BEGIN_RATIONALE C.0.1 FORTRAN Development and Runtime Utilities Options Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._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. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. Annex C FORTRAN Development and Runtime Utilities Options 959 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX C.1 asa - Interpret carriage-control characters This utility is optional. It shall be provided on systems that support the FORTRAN Runtime Utilities Option. C.1.1 Synopsis asa [_f_i_l_e ...] C.1.2 Description The asa utility shall write its input files to standard output, mapping carriage-control characters from the text files to line-printer control sequences in an implementation-defined manner. The first character of every line shall be removed from the input, and the following actions shall be performed: If the character removed is: The rest of the line shall be output without change. 0 A shall be output, then the rest of the input line. 1 One or more implementation-defined characters that causes an advance to the next page shall be output, followed by the rest of the input line. + The of the previous line shall be replaced with one or more implementation-defined characters that causes printing to return to column position 1, followed by the rest of the input line. If the + is the first character in the input, it shall have the same effect as . The action of the asa utility is unspecified upon encountering any character other than those listed above as the first character in a line. C.1.3 Options None. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 960 C FORTRAN Development and Runtime Utilities Options