Received-SPF: pass (google.com: best guess record for domain of linux-ext4-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Subject: Re: [PATCHv5 6/6] Documentation: Correct the description of
 FIEMAP_EXTENT_LAST
To:     Matthew Wilcox <willy@infradead.org>
Cc:     linux-ext4@vger.kernel.org, jack@suse.cz, tytso@mit.edu,
        adilger.kernel@dilger.ca, linux-fsdevel@vger.kernel.org,
        darrick.wong@oracle.com, hch@infradead.org, cmaiolino@redhat.com,
        david@fromorbit.com
References: <cover.1582880246.git.riteshh@linux.ibm.com>
 <5a00e8d4283d6849e0b8f408c8365b31fbc1d153.1582880246.git.riteshh@linux.ibm.com>
 <20200228153650.GG29971@bombadil.infradead.org>
From:   Ritesh Harjani <riteshh@linux.ibm.com>
Date:   Mon, 2 Mar 2020 13:40:06 +0530
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.7.2
MIME-Version: 1.0
In-Reply-To: <20200228153650.GG29971@bombadil.infradead.org>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Message-Id: <20200302081007.8B710A4070@d06av23.portsmouth.uk.ibm.com>
Sender: linux-ext4-owner@vger.kernel.org
Precedence: bulk


On 2/28/20 9:06 PM, Matthew Wilcox wrote:
> On Fri, Feb 28, 2020 at 02:56:59PM +0530, Ritesh Harjani wrote:
>> Currently FIEMAP_EXTENT_LAST is not working consistently across
>> different filesystem's fiemap implementations. So add more information
>> about how else this flag could set in other implementation.
>>
>> Also in general, user should not completely rely on this flag as
>> such since it could return false value for e.g.
>> when there is a delalloc extent which might get converted during
>> writeback, immediately after the fiemap calls return.
>>
>> Signed-off-by: Ritesh Harjani <riteshh@linux.ibm.com>
>> ---
>>   Documentation/filesystems/fiemap.txt | 10 +++++-----
>>   1 file changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/filesystems/fiemap.txt b/Documentation/filesystems/fiemap.txt
>> index f6d9c99103a4..fedfa9b9dde5 100644
>> --- a/Documentation/filesystems/fiemap.txt
>> +++ b/Documentation/filesystems/fiemap.txt
>> @@ -71,8 +71,7 @@ allocated is less than would be required to map the requested range,
>>   the maximum number of extents that can be mapped in the fm_extent[]
>>   array will be returned and fm_mapped_extents will be equal to
>>   fm_extent_count. In that case, the last extent in the array will not
>> -complete the requested range and will not have the FIEMAP_EXTENT_LAST
>> -flag set (see the next section on extent flags).
>> +complete the requested range.
> 
> This sentence still seems like it should be true.  If the filesystem knows
> there are more extents to come, it will definitely not set the LAST flag.
> 

sure.

>> @@ -96,7 +95,7 @@ block size of the file system.  With the exception of extents flagged as
>>   FIEMAP_EXTENT_MERGED, adjacent extents will not be merged.
>>   
>>   The fe_flags field contains flags which describe the extent returned.
>> -A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in
>> +A special flag, FIEMAP_EXTENT_LAST *may be* set on the last extent in
>>   the file so that the process making fiemap calls can determine when no
>>   more extents are available, without having to call the ioctl again.
> 
> I'm not sure I'd highlight 'may be' here.

Sure.

> 
>> @@ -115,8 +114,9 @@ data. Note that the opposite is not true - it would be valid for
>>   FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
>>   
>>   * FIEMAP_EXTENT_LAST
>> -This is the last extent in the file. A mapping attempt past this
>> -extent will return nothing.
>> +This is generally the last extent in the file. A mapping attempt past this
>> +extent may return nothing. In some implementations this flag is also set on
>> +the last dataset queried by the user (via fiemap->fm_length).
> 
> The word 'dataset' is used nowhere else in this document.  How about
> 
> "Some filesystems set this flag to indicate this extent is the last one in
> the range queried by the user"

Sure.

Thanks for the review.
Will make the suggested changes and send a v6.

-ritesh