Btrfs: btrfs_ioctl_search_key documentation
authorHans van Kranenburg <hans.van.kranenburg@mendix.com>
Mon, 5 Jun 2017 22:20:32 +0000 (00:20 +0200)
committerDavid Sterba <dsterba@suse.com>
Mon, 19 Jun 2017 16:26:03 +0000 (18:26 +0200)
commit1a63143dc18b2c6a2233d1c5afce95205d2676f4
tree5c7194f6ba07aacef4cc5a22b8c0fa9c34176a6f
parentef7cdac101602844a4179f7d2d9e26bd20a0edf9
Btrfs: btrfs_ioctl_search_key documentation

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@mendix.com>
Signed-off-by: David Sterba <dsterba@suse.com>
include/uapi/linux/btrfs.h