Low-level probing

Low-level probing — low-level prober initialization

Synopsis

typedef             blkid_probe;
void                blkid_free_probe                    (blkid_probe pr);
blkid_probe         blkid_new_probe                     (void);
blkid_probe         blkid_new_probe_from_filename       (const char *filename);
dev_t               blkid_probe_get_devno               (blkid_probe pr);
int                 blkid_probe_get_fd                  (blkid_probe pr);
blkid_loff_t        blkid_probe_get_offset              (blkid_probe pr);
blkid_loff_t        blkid_probe_get_sectors             (blkid_probe pr);
unsigned int        blkid_probe_get_sectorsize          (blkid_probe pr);
blkid_loff_t        blkid_probe_get_size                (blkid_probe pr);
dev_t               blkid_probe_get_wholedisk_devno     (blkid_probe pr);
int                 blkid_probe_is_wholedisk            (blkid_probe pr);
int                 blkid_probe_set_device              (blkid_probe pr,
                                                         int fd,
                                                         blkid_loff_t off,
                                                         blkid_loff_t size);
int                 blkid_probe_step_back               (blkid_probe pr);
void                blkid_reset_probe                   (blkid_probe pr);

Description

The low-level probing routines always and directly read information from the selected (see blkid_probe_set_device()) device.

The probing routines are grouped together into separate chains. Currently, the library provides superblocks, partitions and topology chains.

The probing routines is possible to filter (enable/disable) by type (e.g. fstype "vfat" or partype "gpt") or by usage flags (e.g. BLKID_USAGE_RAID). These filters are per-chain. Note that always when you touch the chain filter the current probing position is reset and probing starts from scratch. It means that the chain filter should not be modified during probing, for example in loop where you call blkid_do_probe().

For more details see the chain specific documentation.

The low-level API provides two ways how access to probing results.

1. The NAME=value (tag) interface. This interface is older and returns all data as strings. This interface is generic for all chains.

2. The binary interfaces. These interfaces return data in the native formats. The interface is always specific to the probing chain.

Note that the previous probing result (binary or NAME=value) is always zeroized when a chain probing function is called. For example: 

1
2
3
4
 
blkid_probe_enable_partitions(pr, TRUE);
blkid_probe_enable_superblocks(pr, FALSE);

blkid_do_safeprobe(pr);

overwrites the previous probing result for the partitions chain, the superblocks result is not modified.

Details

blkid_probe

typedef struct blkid_struct_probe *blkid_probe;

low-level probing setting

blkid_free_probe ()

void                blkid_free_probe                    (blkid_probe pr);

Deallocates the probe struct, buffers and all allocated data that are associated with this probing control struct.

pr :

 probe

blkid_new_probe ()

blkid_probe         blkid_new_probe                     (void);

Returns :

 a pointer to the newly allocated probe struct or NULL in case of error.

blkid_new_probe_from_filename ()

blkid_probe         blkid_new_probe_from_filename       (const char *filename);

This function is same as call open(filename), blkid_new_probe() and blkid_probe_set_device(pr, fd, 0, 0).

The filename is closed by blkid_free_probe() or by the blkid_probe_set_device() call.

filename :

 device or regular file

Returns :

 a pointer to the newly allocated probe struct or NULL in case of error.

blkid_probe_get_devno ()

dev_t               blkid_probe_get_devno               (blkid_probe pr);

pr :

 probe

Returns :

 block device number, or 0 for regular files.

blkid_probe_get_fd ()

int                 blkid_probe_get_fd                  (blkid_probe pr);

pr :

 probe

Returns :

 file descriptor for assigned device/file or -1 in case of error.

blkid_probe_get_offset ()

blkid_loff_t        blkid_probe_get_offset              (blkid_probe pr);

This function returns offset of probing area as defined by blkid_probe_set_device().

pr :

 probe

Returns :

 offset in bytes or -1 in case of error.

blkid_probe_get_sectors ()

blkid_loff_t        blkid_probe_get_sectors             (blkid_probe pr);

pr :

 probe

Returns :

 512-byte sector count or -1 in case of error.

blkid_probe_get_sectorsize ()

unsigned int        blkid_probe_get_sectorsize          (blkid_probe pr);

pr :

 probe or NULL (for NULL returns 512)

Returns :

 block device logical sector size (BLKSSZGET ioctl, default 512).

blkid_probe_get_size ()

blkid_loff_t        blkid_probe_get_size                (blkid_probe pr);

This function returns size of probing area as defined by blkid_probe_set_device(). If the size of the probing area is unrestricted then this function returns the real size of device. See also blkid_get_dev_size().

pr :

 probe

Returns :

 size in bytes or -1 in case of error.

blkid_probe_get_wholedisk_devno ()

dev_t               blkid_probe_get_wholedisk_devno     (blkid_probe pr);

pr :

 probe

Returns :

 device number of the wholedisk, or 0 for regular files.

blkid_probe_is_wholedisk ()

int                 blkid_probe_is_wholedisk            (blkid_probe pr);

pr :

 probe

Returns :

 1 if the device is whole-disk or 0.

blkid_probe_set_device ()

int                 blkid_probe_set_device              (blkid_probe pr,
                                                         int fd,
                                                         blkid_loff_t off,
                                                         blkid_loff_t size);

Assigns the device to probe control struct, resets internal buffers and resets the current probing.

pr :

 probe

fd :

 device file descriptor

off :

 begin of probing area

size :

 size of probing area (zero means whole device/file)

Returns :

 -1 in case of failure, or 0 on success.

blkid_probe_step_back ()

int                 blkid_probe_step_back               (blkid_probe pr);

This function move pointer to the probing chain one step back -- it means that the previously used probing function will be called again in the next blkid_do_probe() call.

This is necessary for example if you erase or modify on-disk superblock according to the current libblkid probing result.

Example 1. wipe all superblock, but use libblkid only for probing

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
pr = blkid_new_probe_from_filename(devname);

blkid_probe_enable_superblocks(pr, 1);
blkid_probe_set_superblocks_flags(pr, BLKID_SUBLKS_MAGIC);

blkid_probe_enable_partitions(pr, 1);
blkid_probe_set_partitions_flags(pr, BLKID_PARTS_MAGIC);

while (blkid_do_probe(pr) == 0) {
    const char *ostr = NULL;
    size_t len = 0;

    // superblocks
    if (blkid_probe_lookup_value(pr, "SBMAGIC_OFFSET", &ostr, NULL) == 0)
        blkid_probe_lookup_value(pr, "SBMAGIC", NULL, &len);

    // partition tables
    if (len == 0 && blkid_probe_lookup_value(pr, "PTMAGIC_OFFSET", &ostr, NULL) == 0)
        blkid_probe_lookup_value(pr, "PTMAGIC", NULL, &len);

    if (!len || !str)
        continue;

    // convert ostr to the real offset by off = strtoll(ostr, NULL, 10);
        // use your stuff to errase @len bytes at the @off
        ....

    // retry the last probing to check for backup superblocks ..etc.
        blkid_probe_step_back(pr);
}


pr :

 prober

Returns :

 0 on success, and -1 in case of error.

blkid_reset_probe ()

void                blkid_reset_probe                   (blkid_probe pr);

Zeroize probing results and resets the current probing (this has impact to blkid_do_probe() only). This function does not touch probing filters and keeps assigned device.

pr :

 probe
Generated by GTK-Doc V1.18