IEEE P1003.2a Draft 8 - December 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] P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX 5.7 ctags - Create a tags file This utility shall be provided on systems that support the User 7 Portability Utilities Option, the Software Development Utilities Option, 7 and either or both of the C Language Development Utilities Option and 7 FORTRAN Development Utilities Option. On other systems it is optional. 7 5.7.1 Synopsis ctags [-ax] [-f _t_a_g_s_f_i_l_e] _p_a_t_h_n_a_m_e ... 5.7.2 Description The ctags utility shall create a _t_a_g_s file from C-language or FORTRAN source file(s) specified by the _p_a_t_h_n_a_m_e operands. The tags file shall list the locators of language-specific objects within the source files. A locator consists of a name, pathname, and either basic regular expression or a line number that can be used in searching for the object definition. The objects that shall be recognized are specified in 5.7.7. 5.7.3 Options The ctags utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -a Append to tags file. -f _t_a_g_s_f_i_l_e Write the object locator lists into _t_a_g_s_f_i_l_e instead of the default file named tags in the current directory. -x Produce a list of object names, the line number and file name in which each is defined, as well as the text of that line, and write this to the standard output. 5.7.4 Operands The following _p_a_t_h_n_a_m_e operands shall be supported by the implementation: _f_i_l_e._c Files with basenames ending with the .c suffix shall be treated as C-language source code. Such files that are 7 not valid input to c89 produce unspecified results. 7 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 118 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 _f_i_l_e._h Files with basenames ending with the .h suffix shall be treated as C-language source code. Such files that are 7 not valid input to c89 produce unspecified results. 7 _f_i_l_e._f Files with basenames ending with the .f suffix shall be treated as FORTRAN language source code. Such files that 7 are not valid input to fort77 produce unspecified results. 7 The handling of other files is implementation defined. 5.7.5 External Influences 5.7.5.1 Standard Input See Input Files. 5.7.5.2 Input Files The input files shall be text files containing source code in the language indicated by the operand filename suffixes. 5.7.5.3 Environment Variables The following environment variables shall affect the execution of ctags: 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_COLLATE This variable shall determine the order in which output is sorted for the -x option. The POSIX 8 Locale shall determine the order in which the tags 8 file is written. 8 LC_CTYPE This variable shall determine the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters within arguments and input files). When processing C- 7 language source code, if the locale is not 7 compatible with the C locale described by the 7 C Standard {7}, the results are unspecified. 7 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.7 ctags - Create a tags file 119 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX LC_MESSAGES This variable shall determine the language in which messages should be written. 5.7.5.4 Asynchronous Events Default. 5.7.6 External Effects 5.7.6.1 Standard Output The list of object name information produced by the -x option shall be written to standard output in the following format: "%s %d %s %s", <_o_b_j_e_c_t-_n_a_m_e>, <_l_i_n_e-_n_u_m_b_e_r>, <_f_i_l_e_n_a_m_e>, <_t_e_x_t> 8 where <_t_e_x_t> is the text of line <_l_i_n_e-_n_u_m_b_e_r> of file <_f_i_l_e_n_a_m_e>. 5.7.6.2 Standard Error Used only for diagnostic messages. 5.7.6.3 Output Files The format of the output file shall be: "%s\t%s\t/%s/\n", <_i_d_e_n_t_i_f_i_e_r>, <_f_i_l_e_n_a_m_e>, <_r_e_x_p> where <_r_e_x_p> is a basic regular expression (see 2.8.3) that could be used 7 by an editor to find the defining instance of <_i_d_e_n_t_i_f_i_e_r> in <_f_i_l_e_n_a_m_e> 8 (where ``defining instance'' is indicated by the declarations listed in 8 5.7.7). 8 An alternative format is: 8 "%s\t%s\t%d\n", <_i_d_e_n_t_i_f_i_e_r>, <_f_i_l_e_n_a_m_e>, <_l_i_n_e_n_o> 8 where <_l_i_n_e_n_o> is a decimal line number that could be used by an editor 7 to find <_i_d_e_n_t_i_f_i_e_r> in <_f_i_l_e_n_a_m_e>. This alternative format shall not be 7 produced by ctags when it is used as described by this standard, but the 7 standard utilities that process tags files shall be able to process this 7 format as well as the preceding one. 7 In either format, the file shall be sorted by identifier, based on the 8 collation sequence in the POSIX Locale. 8 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 120 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.7.7 Extended Description If the operand identifies C-language source, the ctags utility shall 7 attempt to produce an output line for each of the following objects: 7 - Function definitions 7 - Typedefs 7 - Macros with arguments 7 It may also produce output for any of the following objects: 7 - Function prototypes 7 - Structures 7 - Unions 7 - Global variable definitions 7 - Enums 7 - Macros without arguments 7 - #define statements 7 - #line statements 7 Any #if and #ifdef statements shall produce no output. The tag main is treated specially in C programs. The tag formed shall be created by prefixing M to the name of the file, with the trailing .c, and leading pathname components (if any) removed. On systems that do not support the 7 C Language Development Utilities Option in Annex A, ctags produces 7 unspecified results for C-language source code files. It should write to 7 standard error a message identifying this condition and cause a nonzero 7 exit status to be produced. 7 If the operand identifies FORTRAN source, the ctags utility shall produce an output line for each function definition. It may also produce output for any of the following objects: - Subroutine definitions - COMMON statements - PARAMETER statements Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.7 ctags - Create a tags file 121 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX - DATA and BLOCK DATA statements - Statement numbers On systems that do not support the FORTRAN Development Utilities Option 7 in Annex C, ctags produces unspecified results for FORTRAN source code 7 files. It should write to standard error a message identifying this 7 condition and cause a nonzero exit status to be produced. 7 It is implementation defined what other objects (including duplicate identifiers) produce output. 5.7.8 Exit Status The ctags utility shall exit with one of the following values: 0 Successful completion. >0 An error occurred. 5.7.9 Consequences of Errors Default. BEGIN_RATIONALE 5.7.10 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_a) _U_s_a_g_e_,__E_x_a_m_p_l_e_s The special treatment of the tag main makes the use of ctags practical in directories with more than one program. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The option list was significantly reduced from that provided by historical implementations. The -F option was omitted as redundant, since it is the default. The -B option was omitted as being of very limited usefulness. The -t option was omitted since the recognition of typedefs is now required for C source files. The -u option was omitted because the update function was judged to be not only inefficient but also rarely needed. An earlier draft included a -w option to suppress warning diagnostics. Since the types of such diagnostics could not be described, the option Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 122 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 was omitted as being not useful. The output with -x is meant to be a simple index that can be written out as an off-line readable function index. If the input files to ctags (such as .c files) were not created using the same locales as those in effect when ctags -x is run, results might not be as expected. 8 The description of C-language processing says ``shall attempt to'' 7 because the C language can be greatly obfuscated, especially through the 7 use of #defines, and this utility would be of no use if the real C 7 preprocessor were run to identify them. The output from ctags may be 7 fooled and incorrect for various constructs. 7 The text for LC_CTYPE about compatibility with the C locale acknowledges 7 that the C Standard {7} imposes requirements on the locale used to 7 process C source. This could easily be a superset of that known as ``the 7 C locale'' by way of implementation extensions, or one of a few 7 alternative locales for systems supporting different code sets. No 7 statement is made for FORTRAN because ISO 1539 {2} (FORTRAN 77) does not 7 (yet) define a similar locale concept. However, a general rule in 7 POSIX.2 is that any time locales do not match (preparing a file for one 7 locale and processing it in another), results are suspect. 7 The collation sequence of the tags file is not affected by LC_COLLATE 8 because it is typically not used by human readers, but only by programs 8 such as vi to locate the tag within the source files. Using the POSIX 8 Locale eliminates some of the problems of coordinating locales between 8 the ctags file creator and the vi file reader. 8 Historically, the tags file has been used only by ex and vi. However, the format of the tags file has been published to encourage other programs to use the tags in new ways. The format allows either regular 7 expressions or line numbers to find the identifiers because the 7 historical vi recognizes either. The ctags utility does not produce the 7 format using line numbers because it are not useful following any source 7 file changes that add or delete lines. 7 Historical implementations also understand the objects used by the languages Pascal and sometimes LISP, and understand the C source output by lex and yacc. The ctags utility is not required to accommodate these languages, although implementors are encouraged to do so. The following historical option was not specified, as vgrind is not included in this standard. -v If the -v flag is given, an index of the form expected by vgrind is produced on the standard output. This listing contains the function name, file name, and page number (assuming 64 line pages). Since the output will be sorted into lexicographic Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.7 ctags - Create a tags file 123 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX order, it may be desired to run the output through sort -f. Sample use: ctags -v files | sort -f > index vgrind -x index END_RATIONALE 5.8 df - Report free disk space 5.8.1 Synopsis df [-kP] [_f_i_l_e ...] 5.8.2 Description The df utility shall write the amount of available space for file systems on which the invoking user has appropriate read access. File systems shall be specified by the _f_i_l_e operands; when none are specified, information shall be written for all file systems. The format of the default output from df is unspecified, but all space figures shall be reported in 512-byte units, unless the -k option is specified. This output shall contain at least the file system names and amount of available space on each of these file systems. 5.8.3 Options The df utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -k Use 1024-byte units, instead of the default 512-byte units, when writing space figures. -P Produce output in the format described in 5.8.6.1. 5.8.4 Operands The following operand shall be supported by the implementation: Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 124 5 User Portability Utilities Option