Subject: ls(1) new command line options '-/' and '-%': CIFS system attributes support [PSARC/2007/394 FastTrack timeout 07/11/2007] To: PSARC-ext@Sun.Com Cc: Basabi.Bhattacharya@sun.com Bcc: one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay Template Version: @(#)sac_nextcase 1.63 06/14/07 SMI This information is Copyright 2007 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: ls(1) new command line options '-/' and '-%': CIFS system attributes support 1.2. Name of Document Author/Supplier: Author: Basabi Bhattacharya 1.3 Date of This Document: 29 June, 2007 4. Technical Description This case adds two new command line options '-/' and '-%' to ls(1) to support the extended system attributes added in PSARC case 2007/315. I.Overview The Extensible Attribute Interfaces (PSARC/2007/315) project introduced a number of extended system file attributes. The system utilities need to be able to display and manipulate these new attributes. This fasttrack case adds two new options ("-/ flag" and "-% timestamp") to the ls utility to display the new system attributes and to allow the file creation timestamp attribute to be used (as well as the atime, ctime, and mtime timestamps) for sorting the list of files displayed. The option names '/' and '%' were chosen because all of the alphabetic characters are already in use by the set of utilities that need to be updated to support extended system attributes and the numeric options didn't seem appropriate this use. The project team, therefore, asks for a waiver to CLIP Guideline #3 ("Each option name should be a single alphanumeric character (the alnum character classification) from the portable character set. ...") so the use of these option names can be consistent across all of the affected utilities. II. Release Binding The project team requests a minor release binding. III. Details When "-/ verbosity_flag" is specified, a single line of output will follow the normal -l output using the format: "\t{%s}\n", list of attributes If the verbosity_flag option argument is 'v' (verbose), the state of each boolean system attribute associated with the file will be displayed in a comma separated list using the attribute name. For each boolean extended system attribute, if the attribute is set, the attribute name will be in the list; if the attribute is not set, "no" immediately followed by the attribute name will be in the list. With the attributes listed in PSARC/2007/315 on a ZFS filesystem, an example second line of output would be: {archive,hidden,readonly,system,appendonly,nonodump,immutable,noav_modified,opaque,noav_quarantined,settable,nounlink} If the verbosity_flag option argument is 'c' (compact), the state of each boolean system attribute associated with the file will be displayed as a single character (a unique alphabetic character if the attribute is set, or '-' if the attribute is not set). With the attributes listed in PSARC/2007/315 on a ZFS filesystem, an example second line of output (corresponding to the same attribute settings shown in the verbose form above) would be: {AHRSa-i-o-tu} If there are no extended system attributes associated with a file, the list of attributes will be an empty string: {} If the user doesn't have permission to access extended attributes for a file, a dignostic message will be written to stderr and the list of attributes will be replaced with a single '?' character: {?} When "-% timestamp" is specified, the corresponding timestamp from the file is displayed (in long listing formats) or used to determine sort order of files listed. A timestamp operand is specifed even though only one new timestamp (file creation time) was added by PSARC/2007/315 for two reasons. First, the project team has had requests to have ls provide a way to display all time stamps associated with a file. And, second, because it is likely that other new timestamps will be added later. (A retention [file can't be deleted until] timestamp and a deletion [file will be removed by the system at this time] timestamp have already been suggested as possible future timestamp attributes.) Given the shortage of available option characters for ls now, we want to be able to use this one option character for all future timestamp requests. To make this easier (and with a minor hope that -c and -u could be reclaimed for other uses in a few decades ;-} ), timestamp strings are also specified to allow the last file access timestamp (atime) (currently specified by -u), last file modification timestamp (mtime) (the default), and last file status modification time (ctime) (currently specified by -c) to be specified as well as the new file creation timestamp (crtime). If any of these are specified, the timestamp specified will be used for sorting (such as when -t is specified) or displayed as the timestamp on long format listings. If the timestamp option argument is "all", all timestamps associated with each file listed will be displayed on separate lines following the line containing the file's name. Specifying "-% all" will not affect which timestamp is used for sorting nor for display on the first line in long format listing. By default, the format of all of these time stamps will match the output used on long listing format timestamps when -e is specified. If -E is specified on the command line, the format including nanosecond timestamp resolution will be used for all of the timestamps displayed. See the diff-marked, updated ls(1) man page in this case's materials directory for a detailed description of these options including the boolean extended system attribute names and their single character abbreviations. IV. Interfaces IV.1 Exported Interfaces ______________________________________ | Interface |Classification| |_____________________|______________| |/usr/bin/ls | | |/usr/xpg4/bin/ls | Committed | |/usr/xpg6/bin/ls | | |_____________________|______________| IV.2 Imported Interfaces _________________________________________________________________ | Interface | Classification | Comments | |================================================================| | _PC_SATTR_ENABLED | Consolidation | [f]pathconf() variables | | _PC_SATTR_EXISTS | Private | from PSARC/2007/315. | |_____________________+________________+_________________________| | fgetattr() | Consolidation | From PSARC/2007/315. | | | Private | | |_____________________+________________+_________________________| | | | From the project team | | | | that is implementing | | | | PSARC/2007/315. Used | | | | to get the system | | attr_to_option() | Consolidation | attribute names, their | | name_to_attr() | Private | single character | | | | abbreviations, and the | | | | order in which they | | | | should be displayed. | |_____________________+________________+_________________________| All of these are mentioned here only to register use of these interfaces. Note, however, that PSARC/2007/315 case materials don't make clear the interface taxonomy for fgetattr() and other functions listed on the fgetattr(3C) man page. (The last specification (spec.final.txt) says that all of the functions listed on the fgetattr(3C) man page including fgetattr() are consolidation private; fgetattr.3c (in the same directory) says that all of the functions described there are Evolving). 5. References PSARC/1999/645 Command Line Interface (CLIP) PSARC/2006/715 CIFS Service PSARC/2007/315 Extensible Attribute Interfaces CR 6565581 The command ls(1) needs to support additional file system attributes proposed in PSARC/2007/315. 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open