Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2010 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Windows Sparse Attribute
1.2. Name of Document Author/Supplier:
Author: Alan Wright
1.3 Date of This Document:
14 January, 2010
4. Technical Description
4.1. Details:
This case proposes a new system attribute to support sparse files
over the SMB protocol.
The system attribute interface is described in:
PSARC/2007/315 Extensible Attribute Interfaces
Associated changes to chmod(1) and ls(1) are described in:
PSARC/2007/410 Add system attribute to chmod
PSARC/2007/394 ls(1) '-/' and '-%' options for system attributes
The sparse attribute (XAT_SPARSE) will be added to the read-write
system attributes defined in PSARC/2007/315 and will be generally
available to applications to indicate sparse treatment of objects:
a boolean value of true indicates that the object may be treated
as sparse. Note that the sparse attribute does not indicate whether
or not the file is actually sparse. Sparse-aware applications may
interpret the sparse attribute as an indicator to use SEEK_DATA and
SEEK_HOLE (see lseek(2)) to optimize the reading of file content.
In order to set or clear the sparse attribute the consumer must have
the ACE_WRITE_ATTRIBUTES permission or the PRIV_FILE_OWNER privilege.
In the kernel, it will be accessible via VOP_GETATTR() and
VOP_SETATTR(). In user space, it will be accessible via chmod(1),
ls(1) and fgetattr(3C). No changes are required to the VOP or
the function prototypes described in fgetattr(3C).
From an SMB protocol perspective, there are two sparse indicators:
FILE_SUPPORTS_SPARSE_FILES and FILE_ATTRIBUTE_SPARSE_FILE.
FILE_SUPPORTS_SPARSE_FILES
An SMB server can indicate support for sparse files by setting the
FILE_SUPPORTS_SPARSE_FILES flag in the SmbTrans2QueryFsInformation
response. SMB clients will then expect support for requests such as
FSCTL_SET_SPARSE and FSCTL_SET_ZERO_DATA [MS-FSCC].
FILE_ATTRIBUTE_SPARSE_FILE
Users and applications on an SMB client can change the sparse setting
of a file by setting or clearing FILE_ATTRIBUTE_SPARSE_FILE via the
FSCTL_SET_SPARSE control. When an SMB server that supports sparse
files receives an FSCTL_SET_SPARSE request on a file, it should set
or clear FILE_ATTRIBUTE_SPARSE_FILE on the file as appropriate.
Note that there is no requirement to make the file sparse nor for the
file to be sparse nor for the file system to take any action to avoid
writing zeroes during file writes based on the value of the sparse
attribute. If the file is truncated to zero length or superseded
[MS-SMB], the sparse flag is cleared.
SMB client applications can query sparse files to identify allocated
ranges via FSCTL_QUERY_ALLOCATED_RANGES [MS-FSCC], which returns
zero or more FILE_ALLOCATED_RANGE_BUFFER elements. Each element
corresponds to an allocated range and contains a file offset and a
length. Thus applications need only read non-zeroed ranges in a
sparse file. When allocated ranges are copied to a sparse file, the
file system will take care of the sparse regions. Note that if an
application simply reads a sparse file without explicitly reading
allocated ranges, the file system will fill-in the zeroed ranges and,
in a copy operation, the destination will not be sparse.
4.5 Exported Interface Table
|Proposed |Specified |
|Stability |in what |
Interface Name |Classification |Document? | Comments
===============================================================================
| |This |
| |Document |
| | |
A_SPARSE |Committed | | Added to read-write
| | | view of extended
| | | attribute namespace
| | |
| | |
XAT_SPARSE |Consolidation | | Value for sparse
|Private | | system attribute
4.6. Doc Impact:
Modifications to the chmod(1) man page:
Table 1: Attribute Names and Abbreviation Characters
Attribute Name Attribute Abbreviation Character
-------------- --------------------------------
+ sparse s
Modifications to the ls(1) man page:
-/ c | v
+ sparse This attribute is available to users and applications
to indicate that a file can be interpreted as sparse.
It does not indicate whether or not the file is actually
sparse and it has no special semantics on the Solaris
operating system. The sparse attribute will be cleared
if the file is truncated to zero length.
The display characters used in compact mode (-/ c) are as follows:
Attribute Name Display
+ sparse s
The display positions are as follows:
! {|||||||||||}
+ |||||||||||+- s (sparse)
! ||||||||||+-- O (offline)
! |||||||||+--- u (nounlink)
! ||||||||+---- q (av_quarantined)
! |||||||+----- m (av_modified)
! ||||||+------ i (immutable)
! |||||+------- d (nodump)
! ||||+-------- a (appendonly)
! |||+--------- S (system)
! ||+---------- R (readonly)
! |+----------- H (hidden)
! +------------ A (archive)
Modifications to the fgetattr(3C) man page:
View Attribute Data type
_______________________________________________________________
XATTR_VIEW_READWRITE ...
+ A_SPARSE boolean_value
5. References
[MS-FSCC]: File System Control Codes
http://msdn.microsoft.com/en-us/library/cc231987%28PROT.13%29.aspx
[MS-SMB]: Server Message Block (SMB) Protocol Specification
http://msdn.microsoft.com/en-us/library/cc246231%28PROT.10%29.aspx
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
