2 * Low-level libblkid probing API
4 * Copyright (C) 2008-2009 Karel Zak <kzak@redhat.com>
6 * This file may be redistributed under the terms of the
7 * GNU Lesser General Public License.
12 * @title: Low-level probing
13 * @short_description: low-level prober initialization
15 * The low-level probing routines always and directly read information from
16 * the selected (see blkid_probe_set_device()) device.
18 * The probing routines are grouped together into separate chains. Currently,
19 * the librray provides superblocks, partitions and topology chains.
21 * The probing routines is possible to filter (enable/disable) by type (e.g.
22 * fstype "vfat" or partype "gpt") or by usage flags (e.g. BLKID_USAGE_RAID).
23 * These filters are per-chain. Note that always when you touch the chain
24 * filter the current probing position is reseted and probing starts from
25 * scratch. It means that the chain filter should not be modified during
26 * probing, for example in loop where you call blkid_do_probe().
28 * For more details see the chain specific documentation.
30 * The low-level API provides two ways how access to probing results.
32 * 1. The NAME=value (tag) interface. This interface is older and returns all data
33 * as strings. This interface is generic for all chains.
35 * 2. The binary interfaces. These interfaces return data in the native formats.
36 * The interface is always specific to the probing chain.
41 * SECTION: lowprobe-tags
42 * @title: Low-level tags
43 * @short_description: generic NAME=value interface.
45 * The probing routines inside the chain are mutually exclusive by default --
46 * only few probing routines are marked as "tolerant". The "tolerant" probing
47 * routines are used for filesystem which can share the same device with any
48 * other filesystem. The blkid_do_safeprobe() checks for the "tolerant" flag.
50 * The SUPERBLOCKS chain is enabled by default. The all others chains is
51 * necessary to enable by blkid_probe_enable_'CHAINNAME'(). See chains specific
54 * The blkid_do_probe() function returns a result from only one probing
55 * routine, and the next call from the next probing routine. It means you need
56 * to call the function in loop, for example:
60 * while((blkid_do_probe(pr) == 0)
65 * The blkid_do_safeprobe() is the same as blkid_do_probe(), but returns only
66 * first probing result for every enabled chain. This function checks for
67 * ambivalent results (e.g. more "intolerant" filesystems superblocks on the
70 * The probing result is set of NAME=value pairs (the NAME is always unique).
79 #include <sys/types.h>
80 #ifdef HAVE_SYS_STAT_H
83 #ifdef HAVE_SYS_MKDEV_H
84 #include <sys/mkdev.h>
93 # ifdef HAVE_UUID_UUID_H
94 # include <uuid/uuid.h>
104 extern const struct blkid_chaindrv superblocks_drv
;
105 extern const struct blkid_chaindrv topology_drv
;
106 extern const struct blkid_chaindrv partitions_drv
;
109 * All supported chains
111 static const struct blkid_chaindrv
*chains_drvs
[] = {
112 [BLKID_CHAIN_SUBLKS
] = &superblocks_drv
,
113 [BLKID_CHAIN_TOPLGY
] = &topology_drv
,
114 [BLKID_CHAIN_PARTS
] = &partitions_drv
117 static void blkid_probe_reset_vals(blkid_probe pr
);
122 * Returns: a pointer to the newly allocated probe struct.
124 blkid_probe
blkid_new_probe(void)
130 pr
= calloc(1, sizeof(struct blkid_struct_probe
));
134 /* initialize chains */
135 for (i
= 0; i
< BLKID_NCHAINS
; i
++) {
136 pr
->chains
[i
].driver
= chains_drvs
[i
];
137 pr
->chains
[i
].flags
= chains_drvs
[i
]->dflt_flags
;
138 pr
->chains
[i
].enabled
= chains_drvs
[i
]->dflt_enabled
;
147 * Deallocates the probe struct, buffers and all allocated
148 * data that are associated with this probing control struct.
150 void blkid_free_probe(blkid_probe pr
)
157 for (i
= 0; i
< BLKID_NCHAINS
; i
++) {
158 struct blkid_chain
*ch
= &pr
->chains
[i
];
160 if (ch
->driver
->free_data
)
161 ch
->driver
->free_data(pr
, ch
->data
);
169 static void blkid_probe_reset_buffer(blkid_probe pr
)
171 DBG(DEBUG_LOWPROBE
, printf("reseting blkid probe buffer\n"));
173 memset(pr
->buf
, 0, pr
->buf_max
);
177 memset(pr
->sbbuf
, 0, BLKID_SB_BUFSIZ
);
183 * Removes chain values from probing result.
185 void blkid_probe_chain_reset_vals(blkid_probe pr
, struct blkid_chain
*chn
)
187 int nvals
= pr
->nvals
;
190 for (x
= 0, i
= 0; i
< pr
->nvals
; i
++) {
191 struct blkid_prval
*v
= &pr
->vals
[i
];
193 if (v
->chain
!= chn
&& x
== i
) {
197 if (v
->chain
== chn
) {
201 memcpy(&pr
->vals
[x
++], v
, sizeof(struct blkid_prval
));
207 * Copies chain values from probing result to @vals, the max size of @vals is
208 * @nvals and returns real number of values.
210 int blkid_probe_chain_copy_vals(blkid_probe pr
, struct blkid_chain
*chn
,
211 struct blkid_prval
*vals
, int nvals
)
215 for (x
= 0, i
= 0; i
< pr
->nvals
&& x
< nvals
; i
++) {
216 struct blkid_prval
*v
= &pr
->vals
[i
];
220 memcpy(&vals
[x
++], v
, sizeof(struct blkid_prval
));
226 * Appends values from @vals to the probing result
228 void blkid_probe_append_vals(blkid_probe pr
, struct blkid_prval
*vals
, int nvals
)
232 while (i
< nvals
&& pr
->nvals
< BLKID_NVALS
) {
233 memcpy(&pr
->vals
[pr
->nvals
++], &vals
[i
++],
234 sizeof(struct blkid_prval
));
238 static void blkid_probe_reset_vals(blkid_probe pr
)
240 memset(pr
->vals
, 0, sizeof(pr
->vals
));
244 struct blkid_chain
*blkid_probe_get_chain(blkid_probe pr
)
246 return pr
->cur_chain
;
249 void *blkid_probe_get_binary_data(blkid_probe pr
, struct blkid_chain
*chn
)
259 rc
= chn
->driver
->probe(pr
, chn
);
262 pr
->cur_chain
= NULL
;
268 printf("returning %s binary data\n", chn
->driver
->name
));
277 * Cleanup probing result. This function does not touch probing filters
278 * and keeps assigned device.
280 void blkid_reset_probe(blkid_probe pr
)
287 blkid_probe_reset_buffer(pr
);
288 blkid_probe_reset_vals(pr
);
290 for (i
= 0; i
< BLKID_NCHAINS
; i
++)
291 pr
->chains
[i
].idx
= -1;
295 static int blkid_probe_dump_filter(blkid_probe pr, int chain)
297 struct blkid_chain *chn;
300 if (!pr || chain < 0 || chain >= BLKID_NCHAINS)
303 chn = &pr->chains[chain];
308 for (i = 0; i < chn->driver->nidinfos; i++) {
309 const struct blkid_idinfo *id = chn->driver->idinfos[i];
311 DBG(DEBUG_LOWPROBE, printf("%d: %s: %s\n",
314 blkid_bmp_get_item(chn->fltr, i)
315 ? "disabled" : "enabled <--"));
322 * Returns properly initialized chain filter
324 unsigned long *blkid_probe_get_filter(blkid_probe pr
, int chain
, int create
)
326 struct blkid_chain
*chn
;
328 if (!pr
|| chain
< 0 || chain
>= BLKID_NCHAINS
)
331 chn
= &pr
->chains
[chain
];
333 /* always when you touch the chain filter all indexes are reseted and
334 * probing starts from scratch
337 pr
->cur_chain
= NULL
;
339 if (!chn
->driver
->has_fltr
|| (!chn
->fltr
&& !create
))
343 chn
->fltr
= calloc(1, blkid_bmp_nbytes(chn
->driver
->nidinfos
));
345 memset(chn
->fltr
, 0, blkid_bmp_nbytes(chn
->driver
->nidinfos
));
347 /* blkid_probe_dump_filter(pr, chain); */
352 * Generic private functions for filter setting
354 int __blkid_probe_invert_filter(blkid_probe pr
, int chain
)
357 struct blkid_chain
*chn
;
360 fltr
= blkid_probe_get_filter(pr
, chain
, FALSE
);
364 chn
= &pr
->chains
[chain
];
366 for (i
= 0; i
< blkid_bmp_nwords(chn
->driver
->nidinfos
); i
++)
369 DBG(DEBUG_LOWPROBE
, printf("probing filter inverted\n"));
370 /* blkid_probe_dump_filter(pr, chain); */
374 int __blkid_probe_reset_filter(blkid_probe pr
, int chain
)
376 return blkid_probe_get_filter(pr
, chain
, FALSE
) ? 0 : -1;
379 int __blkid_probe_filter_types(blkid_probe pr
, int chain
, int flag
, char *names
[])
382 struct blkid_chain
*chn
;
385 fltr
= blkid_probe_get_filter(pr
, chain
, TRUE
);
389 chn
= &pr
->chains
[chain
];
391 for (i
= 0; i
< chn
->driver
->nidinfos
; i
++) {
393 const struct blkid_idinfo
*id
= chn
->driver
->idinfos
[i
];
396 for (n
= names
; *n
; n
++) {
397 if (!strcmp(id
->name
, *n
)) {
402 if (flag
& BLKID_FLTR_ONLYIN
) {
404 blkid_bmp_set_item(fltr
, i
);
405 } else if (flag
& BLKID_FLTR_NOTIN
) {
407 blkid_bmp_set_item(fltr
, i
);
412 printf("%s: a new probing type-filter initialized\n",
414 /* blkid_probe_dump_filter(pr, chain); */
419 * Note that we have two offsets:
421 * 1/ general device offset (pr->off), that's useful for example when we
422 * probe a partition from whole disk image:
423 * blkid-low --offset <partition_position> disk.img
425 * 2/ buffer offset (the 'off' argument), that useful for offsets in
428 * That means never use lseek(fd, 0, SEEK_SET), the zero position is always
429 * pr->off, so lseek(fd, pr->off, SEEK_SET).
432 unsigned char *blkid_probe_get_buffer(blkid_probe pr
,
433 blkid_loff_t off
, blkid_loff_t len
)
435 ssize_t ret_read
= 0;
437 if (off
< 0 || len
< 0) {
439 printf("unexpected offset or length of buffer requested\n"));
442 if (off
+ len
<= BLKID_SB_BUFSIZ
) {
444 pr
->sbbuf
= malloc(BLKID_SB_BUFSIZ
);
448 if (!pr
->sbbuf_len
) {
449 if (lseek(pr
->fd
, pr
->off
, SEEK_SET
) < 0)
451 ret_read
= read(pr
->fd
, pr
->sbbuf
, BLKID_SB_BUFSIZ
);
454 pr
->sbbuf_len
= ret_read
;
456 if (off
+ len
> pr
->sbbuf_len
)
458 return pr
->sbbuf
+ off
;
460 unsigned char *newbuf
= NULL
;
462 if (len
> pr
->buf_max
) {
463 newbuf
= realloc(pr
->buf
, len
);
471 if (newbuf
|| off
< pr
->buf_off
||
472 off
+ len
> pr
->buf_off
+ pr
->buf_len
) {
474 if (blkid_llseek(pr
->fd
, pr
->off
+ off
, SEEK_SET
) < 0)
477 ret_read
= read(pr
->fd
, pr
->buf
, len
);
478 if (ret_read
!= (ssize_t
) len
)
483 return off
? pr
->buf
+ (off
- pr
->buf_off
) : pr
->buf
;
488 * blkid_probe_set_device:
490 * @fd: device file descriptor
491 * @off: begin of probing area
492 * @size: size of probing area
494 * Assigns the device to probe control struct, resets internal buffers and
495 * reads 512 bytes from device to the buffers.
497 * Returns: -1 in case of failure, or 0 on success.
499 int blkid_probe_set_device(blkid_probe pr
, int fd
,
500 blkid_loff_t off
, blkid_loff_t size
)
505 blkid_reset_probe(pr
);
522 pr
->mode
= sb
.st_mode
;
524 if (S_ISBLK(sb
.st_mode
)) {
525 blkdev_get_size(fd
, (unsigned long long *) &pr
->size
);
526 pr
->devno
= sb
.st_rdev
;
528 pr
->size
= sb
.st_size
;
533 /* read SB to test if the device is readable */
534 if (!blkid_probe_get_buffer(pr
, 0, 0x200)) {
536 printf("failed to prepare a device for low-probing\n"));
540 DBG(DEBUG_LOWPROBE
, printf("ready for low-probing, offset=%zd, size=%zd\n",
545 int blkid_probe_get_dimension(blkid_probe pr
,
546 blkid_loff_t
*off
, blkid_loff_t
*size
)
556 int blkid_probe_set_dimension(blkid_probe pr
,
557 blkid_loff_t off
, blkid_loff_t size
)
562 DBG(DEBUG_LOWPROBE
, printf(
563 "changing probing area: size=%llu, off=%llu "
564 "-to-> size=%llu, off=%llu\n",
565 (unsigned long long) pr
->size
,
566 (unsigned long long) pr
->off
,
567 (unsigned long long) size
,
568 (unsigned long long) off
));
573 blkid_probe_reset_buffer(pr
);
582 * Calls probing functions in all enabled chains. The superblocks chain is
583 * enabled by default. The blkid_do_probe() stores result from only one
584 * probing function. It's necessary to call this routine in a loop to get
585 * resuluts from all probing functions in all chains.
587 * This is string-based NAME=value interface only.
590 * <title>basic case - use the first result only</title>
593 * if (blkid_do_probe(pr) == 0) {
594 * int nvals = blkid_probe_numof_values(pr);
595 * for (n = 0; n < nvals; n++) {
596 * if (blkid_probe_get_value(pr, n, &name, &data, &len) == 0)
597 * printf("%s = %s\n", name, data);
604 * <title>advanced case - probe for all signatures</title>
607 * while (blkid_do_probe(pr) == 0) {
608 * int nvals = blkid_probe_numof_values(pr);
614 * See also blkid_reset_probe().
616 * Returns: 0 on success, 1 when probing is done and -1 in case of error.
618 int blkid_do_probe(blkid_probe pr
)
626 struct blkid_chain
*chn
;
629 pr
->cur_chain
= &pr
->chains
[0];
630 else if (pr
->cur_chain
< &pr
->chains
[BLKID_NCHAINS
- 1])
631 pr
->cur_chain
+= sizeof(struct blkid_chain
);
633 return 1; /* all chains already probed */
636 chn
->binary
= FALSE
; /* for sure... */
638 DBG(DEBUG_LOWPROBE
, printf("chain probe %s %s\n",
640 chn
->enabled
? "ENABLED" : "DISABLED"));
645 /* rc: -1 = error, 0 = success, 1 = no result */
646 rc
= chn
->driver
->probe(pr
, chn
);
654 * blkid_do_safeprobe:
657 * This function gathers probing results from all enabled chains and checks
658 * for ambivalent results (e.g. more filesystems on the device).
660 * This is string-based NAME=value interface only.
662 * Note about suberblocks chain -- the function does not check for filesystems
663 * when a RAID signature is detected. The function also does not check for
664 * collision between RAIDs. The first detected RAID is returned.
666 * Returns: 0 on success, 1 if nothing is detected, -2 if ambivalen result is
667 * detected and -1 on case of error.
669 int blkid_do_safeprobe(blkid_probe pr
)
671 int i
, count
= 0, rc
= 0;
676 for (i
= 0; i
< BLKID_NCHAINS
; i
++) {
677 struct blkid_chain
*chn
;
679 chn
= pr
->cur_chain
= &pr
->chains
[i
];
680 chn
->binary
= FALSE
; /* for sure... */
682 DBG(DEBUG_LOWPROBE
, printf("chain safeprobe %s %s\n",
684 chn
->enabled
? "ENABLED" : "DISABLED"));
691 /* rc: -2 ambivalent, -1 = error, 0 = success, 1 = no result */
692 rc
= chn
->driver
->safeprobe(pr
, chn
);
694 goto done
; /* error */
696 count
++; /* success */
700 pr
->cur_chain
= NULL
;
703 return count
? 0 : 1;
707 * blkid_do_fullprobe:
710 * This function gathers probing results from all enabled chains. Same as
711 * blkid_so_safeprobe() but does not check for collision between probing
714 * This is string-based NAME=value interface only.
716 * Returns: 0 on success, 1 if nothing is detected or -1 on case of error.
718 int blkid_do_fullprobe(blkid_probe pr
)
720 int i
, count
= 0, rc
= 0;
725 for (i
= 0; i
< BLKID_NCHAINS
; i
++) {
727 struct blkid_chain
*chn
;
729 chn
= pr
->cur_chain
= &pr
->chains
[i
];
730 chn
->binary
= FALSE
; /* for sure... */
732 DBG(DEBUG_LOWPROBE
, printf("chain fullprobe %s: %s\n",
734 chn
->enabled
? "ENABLED" : "DISABLED"));
741 /* rc: -1 = error, 0 = success, 1 = no result */
742 rc
= chn
->driver
->probe(pr
, chn
);
744 goto done
; /* error */
746 count
++; /* success */
750 pr
->cur_chain
= NULL
;
753 return count
? 0 : 1;
756 /* same sa blkid_probe_get_buffer() but works with 512-sectors */
757 unsigned char *blkid_probe_get_sector(blkid_probe pr
, unsigned int sector
)
759 return pr
? blkid_probe_get_buffer(pr
,
760 ((blkid_loff_t
) sector
) << 9, 0x200) : NULL
;
763 struct blkid_prval
*blkid_probe_assign_value(
764 blkid_probe pr
, const char *name
)
766 struct blkid_prval
*v
;
770 if (pr
->nvals
>= BLKID_NVALS
)
773 v
= &pr
->vals
[pr
->nvals
];
775 v
->chain
= pr
->cur_chain
;
779 printf("assigning %s [%s]\n", name
, v
->chain
->driver
->name
));
783 int blkid_probe_set_value(blkid_probe pr
, const char *name
,
784 unsigned char *data
, size_t len
)
786 struct blkid_prval
*v
;
788 if (len
> BLKID_PROBVAL_BUFSIZ
)
789 len
= BLKID_PROBVAL_BUFSIZ
;
791 v
= blkid_probe_assign_value(pr
, name
);
795 memcpy(v
->data
, data
, len
);
800 int blkid_probe_vsprintf_value(blkid_probe pr
, const char *name
,
801 const char *fmt
, va_list ap
)
803 struct blkid_prval
*v
;
806 v
= blkid_probe_assign_value(pr
, name
);
810 len
= vsnprintf((char *) v
->data
, sizeof(v
->data
), fmt
, ap
);
813 pr
->nvals
--; /* reset the latest assigned value */
820 int blkid_probe_sprintf_value(blkid_probe pr
, const char *name
,
821 const char *fmt
, ...)
827 rc
= blkid_probe_vsprintf_value(pr
, name
, fmt
, ap
);
834 * blkid_probe_get_devno:
837 * Returns: block device number, or 0 for regilar files.
839 dev_t
blkid_probe_get_devno(blkid_probe pr
)
844 if (fstat(pr
->fd
, &sb
) == 0 && S_ISBLK(sb
.st_mode
))
845 pr
->devno
= sb
.st_rdev
;
851 * blkid_probe_get_size:
854 * Returns: block device (or file) size in bytes or -1 in case of error.
856 blkid_loff_t
blkid_probe_get_size(blkid_probe pr
)
858 return pr
? pr
->size
: -1;
862 * blkid_probe_get_sectorsize:
865 * Returns: block device hardware sector size (BLKSSZGET ioctl, default 512).
867 unsigned int blkid_probe_get_sectorsize(blkid_probe pr
)
870 return DEFAULT_SECTOR_SIZE
; /*... and good luck! */
876 if (fstat(pr
->fd
, &st
))
878 pr
->mode
= st
.st_mode
;
880 if (S_ISBLK(pr
->mode
)) {
881 if (blkdev_get_sector_size(pr
->fd
, (int *) &pr
->blkssz
))
888 pr
->blkssz
= DEFAULT_SECTOR_SIZE
;
893 * blkid_probe_numof_values:
896 * Returns: number of values in probing result or -1 in case of error.
898 int blkid_probe_numof_values(blkid_probe pr
)
906 * blkid_probe_get_value:
908 * @num: wanted value in range 0..N, where N is blkid_probe_numof_values() - 1
909 * @name: pointer to return value name or NULL
910 * @data: pointer to return value data or NULL
911 * @len: pointer to return value length or NULL
913 * Returns: 0 on success, or -1 in case of error.
915 int blkid_probe_get_value(blkid_probe pr
, int num
, const char **name
,
916 const char **data
, size_t *len
)
918 struct blkid_prval
*v
= __blkid_probe_get_value(pr
, num
);
925 *data
= (char *) v
->data
;
929 DBG(DEBUG_LOWPROBE
, printf("returning %s value\n", v
->name
));
934 * blkid_probe_lookup_value:
936 * @name: name of value
937 * @data: pointer to return value data or NULL
938 * @len: pointer to return value length or NULL
940 * Returns: 0 on success, or -1 in case of error.
942 int blkid_probe_lookup_value(blkid_probe pr
, const char *name
,
943 const char **data
, size_t *len
)
945 struct blkid_prval
*v
= __blkid_probe_lookup_value(pr
, name
);
950 *data
= (char *) v
->data
;
953 DBG(DEBUG_LOWPROBE
, printf("returning %s value\n", v
->name
));
958 * blkid_probe_has_value:
960 * @name: name of value
962 * Returns: 1 if value exist in probing result, otherwise 0.
964 int blkid_probe_has_value(blkid_probe pr
, const char *name
)
966 if (blkid_probe_lookup_value(pr
, name
, NULL
, NULL
) == 0)
971 struct blkid_prval
*__blkid_probe_get_value(blkid_probe pr
, int num
)
973 if (pr
== NULL
|| num
< 0 || num
>= pr
->nvals
)
976 return &pr
->vals
[num
];
979 struct blkid_prval
*__blkid_probe_lookup_value(blkid_probe pr
, const char *name
)
983 if (pr
== NULL
|| pr
->nvals
== 0 || name
== NULL
)
986 for (i
= 0; i
< pr
->nvals
; i
++) {
987 struct blkid_prval
*v
= &pr
->vals
[i
];
989 if (v
->name
&& strcmp(name
, v
->name
) == 0) {
990 DBG(DEBUG_LOWPROBE
, printf("returning %s value\n", v
->name
));
998 /* converts DCE UUID (uuid[16]) to human readable string
999 * - the @len should be always 37 */
1000 void blkid_unparse_uuid(const unsigned char *uuid
, char *str
, size_t len
)
1003 uuid_unparse(uuid
, str
);
1006 "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x",
1007 uuid
[0], uuid
[1], uuid
[2], uuid
[3],
1011 uuid
[10], uuid
[11], uuid
[12], uuid
[13], uuid
[14],uuid
[15]);