On Tue, Jun 06, 2017 at 12:20:32AM +0200, Hans van Kranenburg wrote: > A programmer who is trying to implement calling the btrfs SEARCH > or SEARCH_V2 ioctl will probably soon end up reading this struct > definition. > > Properly document the input fields to prevent common misconceptions: > 1. The search space is linear, not 3 dimensional. The invidual min/max > values for objectid, type and offset cannot be used to filter the > result, they only define the endpoints of an interval. > 2. The transaction id (a.k.a. generation) filter applies only on > transaction id of the last COW operation on a whole metadata page, not > on individual items. > > Ad 1. The first misunderstanding was helped by the previous misleading > comments on min/max type and offset: > "keys returned will be >= min and <= max". > > Ad 2. For example, running btrfs balance will happily cause rewriting of > metadata pages that contain a filesystem tree of a read only subvolume, > causing transids to be increased. > > Also, improve descriptions of tree_id and nr_items and add in/out > annotations. > > Signed-off-by: Hans van Kranenburg <hans.van.kranenburg@xxxxxxxxxx> Looks good to me, thanks. I've realigned the comments so they don't overflow 80 columns and aligned the /* in */ hints. > Most interesting changes since v1: > - mention the special tree_id input value 0 > - rewrite the part about min_key and max_key, trying to be more concise I find the description instructive enough so the expanded expression to describe the whole range is not IMHO needed. -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
