Low-level probing

Low-level probing — low-level prober initialization

Functions

Types and Values

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.

Functions

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.

Parameters

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.

Parameters

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);

Parameters

pr

probe

 

Returns

block device number, or 0 for regular files.


blkid_probe_get_fd ()

int
blkid_probe_get_fd (blkid_probe pr);

Parameters

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().

Parameters

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);

Parameters

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);

Parameters

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().

Parameters

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);

Parameters

pr

probe

 

Returns

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


blkid_probe_hide_range ()

int
blkid_probe_hide_range (blkid_probe pr,
                        uint64_t off,
                        uint64_t len);

This function modifies in-memory cached data from the device. The specified range is zeroized. This is usable together with blkid_probe_step_back(). The next blkid_do_probe() will not see specified area.

Note that this is usable for already (by library) read data, and this function is not a way how to hide any large areas on your device.

The function blkid_probe_reset_buffers() reverts all.

Parameters

pr

prober

 

off

start of the range

 

len

size of the range

 

Returns

<0 in case of failure, or 0 on success.

Since: 2.31


blkid_probe_is_wholedisk ()

int
blkid_probe_is_wholedisk (blkid_probe pr);

Parameters

pr

probe

 

Returns

1 if the device is whole-disk or 0.


blkid_probe_reset_buffers ()

int
blkid_probe_reset_buffers (blkid_probe pr);

libblkid reuse all already read buffers from the device. The buffers may be modified by blkid_probe_hide_range(). This function reset and free all cached buffers. The next blkid_do_probe() will read all data from the device.

Parameters

pr

prober

 

Returns

<0 in case of failure, or 0 on success.

Since: 2.31


blkid_probe_reset_hints ()

void
blkid_probe_reset_hints (blkid_probe pr);

Removes all previously defined probinig hints. See also blkid_probe_set_hint().

Parameters

pr

probe

 

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, resets the current probing, and close previously associated device (if open by libblkid).

If fd is < 0 than only resets the prober and returns 1. Note that blkid_reset_probe() keeps the device associated with the prober, but blkid_probe_set_device() does complete reset.

Parameters

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, 0 on success and 1 on reset.


blkid_probe_set_hint ()

int
blkid_probe_set_hint (blkid_probe pr,
                      const char *name,
                      uint64_t value);

Sets extra hint for low-level prober. If the hint is set by NAME=value notation than value is ignored. The functions blkid_probe_set_device() and blkid_reset_probe() resets all hints.

The hints are optional way how to force libblkid probing functions to check for example another location.

Parameters

pr

probe

 

name

hint name or NAME=value

 

value

offset or another number

 

Returns

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


blkid_probe_set_sectorsize ()

int
blkid_probe_set_sectorsize (blkid_probe pr,
                            unsigned int sz);

Note that blkid_probe_set_device() resets this setting. Use it after blkid_probe_set_device() and before any probing call.

Parameters

pr

probe

 

sz

new size (to overwrite system default)

 

Returns

0 or <0 in case of error

Since: 2.30


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.

Note that blkid_probe_hide_range() changes semantic of this function and cached buffers are not reset, but library uses in-memory modified buffers to call the next probing function.

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) == BLKID_PROBE_OK) {
	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 erase @len bytes at the @off
        ....

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

Parameters

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.

Parameters

pr

probe

 

Types and Values

blkid_probe

typedef struct blkid_struct_probe *blkid_probe;

low-level probing setting


BLKID_PROBE_OK

#define BLKID_PROBE_OK 0

probing return value; superblock (RAID, partiton table, ...) succesfully detected


BLKID_PROBE_NONE

#define BLKID_PROBE_NONE 1

probing return value; found nothing


BLKID_PROBE_ERROR

#define BLKID_PROBE_ERROR -1

probing return value; probing ends with en error (see errno for more details)


BLKID_PROBE_AMBIGUOUS

#define BLKID_PROBE_AMBIGUOUS -2

probing return value; more than one probing result, in this case, it's not safe to use the device automaticaly and user intervention is recommended