chiark
/
gitweb
/
~ianmdlvl
/
elogind.git
/ commitdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
| commitdiff |
tree
raw
|
patch
|
inline
| side by side (from parent 1:
f1a9ac3
)
volume_id: add function documentation
author
Kay Sievers
<kay.sievers@vrfy.org>
Mon, 14 May 2007 23:11:48 +0000
(
01:11
+0200)
committer
Kay Sievers
<kay.sievers@vrfy.org>
Mon, 14 May 2007 23:11:48 +0000
(
01:11
+0200)
extras/volume_id/lib/volume_id.c
patch
|
blob
|
history
diff --git
a/extras/volume_id/lib/volume_id.c
b/extras/volume_id/lib/volume_id.c
index f76742934772ed3cfb487cad2f4a114a7427d4ed..15e9cda4da57952f74af0bba6ab2ce36ee50221f 100644
(file)
--- a/
extras/volume_id/lib/volume_id.c
+++ b/
extras/volume_id/lib/volume_id.c
@@
-85,6
+85,14
@@
static void default_log(int priority, const char *file, int line, const char *fo
volume_id_log_fn_t volume_id_log_fn = default_log;
volume_id_log_fn_t volume_id_log_fn = default_log;
+/**
+ * volume_id_get_label:
+ * @type: Type string.
+ *
+ * Lookup the probing function for a specific type.
+ *
+ * Returns: The probing function for the given type, #NULL otherwise.
+ **/
const volume_id_probe_fn_t *volume_id_get_prober_by_type(const char *type)
{
unsigned int p, n;
const volume_id_probe_fn_t *volume_id_get_prober_by_type(const char *type)
{
unsigned int p, n;
@@
-103,12
+111,22
@@
const volume_id_probe_fn_t *volume_id_get_prober_by_type(const char *type)
return NULL;
}
return NULL;
}
+/**
+ * volume_id_get_label:
+ * @id: Probing context.
+ * @label: Label string. Must not be freed by the caller.
+ *
+ * Get the label string after a successful probe. Unicode
+ * is translated to UTF-8.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_label(struct volume_id *id, const char **label)
{
if (id == NULL)
int volume_id_get_label(struct volume_id *id, const char **label)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (label == NULL)
if (label == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-116,14
+134,25
@@
int volume_id_get_label(struct volume_id *id, const char **label)
return 1;
}
return 1;
}
+/**
+ * volume_id_get_label_raw:
+ * @id: Probing context.
+ * @label: Label byte array. Must not be freed by the caller.
+ * @len: Length of raw label byte array.
+ *
+ * Get the raw label byte array after a successful probe. It may
+ * contain undecoded multibyte character streams.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_label_raw(struct volume_id *id, const uint8_t **label, size_t *len)
{
if (id == NULL)
int volume_id_get_label_raw(struct volume_id *id, const uint8_t **label, size_t *len)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (label == NULL)
if (label == NULL)
- return
-EINVAL
;
+ return
0
;
if (len == NULL)
if (len == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-132,12
+161,21
@@
int volume_id_get_label_raw(struct volume_id *id, const uint8_t **label, size_t
return 1;
}
return 1;
}
+/**
+ * volume_id_get_uuid:
+ * @id: Probing context.
+ * @uuid: UUID string. Must not be freed by the caller.
+ *
+ * Get the raw UUID string after a successful probe.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_uuid(struct volume_id *id, const char **uuid)
{
if (id == NULL)
int volume_id_get_uuid(struct volume_id *id, const char **uuid)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (uuid == NULL)
if (uuid == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-145,14
+183,25
@@
int volume_id_get_uuid(struct volume_id *id, const char **uuid)
return 1;
}
return 1;
}
+/**
+ * volume_id_get_uuid_raw:
+ * @id: Probing context.
+ * @uuid: UUID byte array. Must not be freed by the caller.
+ * @len: Length of raw UUID byte array.
+ *
+ * Get the raw UUID byte array after a successful probe. It may
+ * contain unconverted endianes values.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_uuid_raw(struct volume_id *id, const uint8_t **uuid, size_t *len)
{
if (id == NULL)
int volume_id_get_uuid_raw(struct volume_id *id, const uint8_t **uuid, size_t *len)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (uuid == NULL)
if (uuid == NULL)
- return
-EINVAL
;
+ return
0
;
if (len == NULL)
if (len == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-161,12
+210,21
@@
int volume_id_get_uuid_raw(struct volume_id *id, const uint8_t **uuid, size_t *l
return 1;
}
return 1;
}
+/**
+ * volume_id_get_usage:
+ * @id: Probing context.
+ * @usage: Usage string. Must not be freed by the caller.
+ *
+ * Get the usage string after a successful probe.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_usage(struct volume_id *id, const char **usage)
{
if (id == NULL)
int volume_id_get_usage(struct volume_id *id, const char **usage)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (usage == NULL)
if (usage == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-174,12
+232,21
@@
int volume_id_get_usage(struct volume_id *id, const char **usage)
return 1;
}
return 1;
}
+/**
+ * volume_id_get_type:
+ * @id: Probing context
+ * @type: Type string. Must not be freed by the caller.
+ *
+ * Get the type string after a successful probe.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_type(struct volume_id *id, const char **type)
{
if (id == NULL)
int volume_id_get_type(struct volume_id *id, const char **type)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (type == NULL)
if (type == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-187,12
+254,21
@@
int volume_id_get_type(struct volume_id *id, const char **type)
return 1;
}
return 1;
}
+/**
+ * volume_id_get_type_version:
+ * @id: Probing context.
+ * @type_version: Type version string. Must not be freed by the caller.
+ *
+ * Get the Type version string after a successful probe.
+ *
+ * Returns: 1 if the value was set, 0 otherwise.
+ **/
int volume_id_get_type_version(struct volume_id *id, const char **type_version)
{
if (id == NULL)
int volume_id_get_type_version(struct volume_id *id, const char **type_version)
{
if (id == NULL)
- return
-EINVAL
;
+ return
0
;
if (type_version == NULL)
if (type_version == NULL)
- return
-EINVAL
;
+ return
0
;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
if (id->usage_id == VOLUME_ID_UNUSED)
return 0;
@@
-200,6
+276,16
@@
int volume_id_get_type_version(struct volume_id *id, const char **type_version)
return 1;
}
return 1;
}
+/**
+ * volume_id_probe_raid:
+ * @id: Probing context.
+ * @off: Probing offset relative to the start of the device.
+ * @size: Total size of the device.
+ *
+ * Probe device for all known raid signatures.
+ *
+ * Returns: 0 on successful probe, otherwise negative value.
+ **/
int volume_id_probe_raid(struct volume_id *id, uint64_t off, uint64_t size)
{
unsigned int i;
int volume_id_probe_raid(struct volume_id *id, uint64_t off, uint64_t size)
{
unsigned int i;
@@
-221,6
+307,16
@@
found:
return 0;
}
return 0;
}
+/**
+ * volume_id_probe_filesystem:
+ * @id: Probing context.
+ * @off: Probing offset relative to the start of the device.
+ * @size: Total size of the device.
+ *
+ * Probe device for all known filesystem signatures.
+ *
+ * Returns: 0 on successful probe, otherwise negative value.
+ **/
int volume_id_probe_filesystem(struct volume_id *id, uint64_t off, uint64_t size)
{
unsigned int i;
int volume_id_probe_filesystem(struct volume_id *id, uint64_t off, uint64_t size)
{
unsigned int i;
@@
-242,6
+338,16
@@
found:
return 0;
}
return 0;
}
+/**
+ * volume_id_probe_all:
+ * @id: Probing context.
+ * @off: Probing offset relative to the start of the device.
+ * @size: Total size of the device.
+ *
+ * Probe device for all known raid and filesystem signatures.
+ *
+ * Returns: 0 on successful probe, otherwise negative value.
+ **/
int volume_id_probe_all(struct volume_id *id, uint64_t off, uint64_t size)
{
if (id == NULL)
int volume_id_probe_all(struct volume_id *id, uint64_t off, uint64_t size)
{
if (id == NULL)
@@
-257,6
+363,16
@@
int volume_id_probe_all(struct volume_id *id, uint64_t off, uint64_t size)
return -1;
}
return -1;
}
+/**
+ * volume_id_probe_raid:
+ * @all_probers_fn: prober function to called for all known probing routines.
+ * @id: Context passed to prober function.
+ * @off: Offset value passed to prober function.
+ * @size: Size value passed to prober function.
+ * @data: Arbitrary data passed to the prober function.
+ *
+ * Run a custom function for all known probing routines.
+ **/
void volume_id_all_probers(all_probers_fn_t all_probers_fn,
struct volume_id *id, uint64_t off, uint64_t size,
void *data)
void volume_id_all_probers(all_probers_fn_t all_probers_fn,
struct volume_id *id, uint64_t off, uint64_t size,
void *data)
@@
-276,7
+392,15
@@
out:
return;
}
return;
}
-/* open volume by already open file descriptor */
+/**
+ * volume_id_open_fd:
+ * @id: Probing context.
+ * @fd: Open file descriptor of device to read from.
+ *
+ * Create the context for probing.
+ *
+ * Returns: Probing context, or #NULL on failure.
+ **/
struct volume_id *volume_id_open_fd(int fd)
{
struct volume_id *id;
struct volume_id *volume_id_open_fd(int fd)
{
struct volume_id *id;
@@
-291,7
+415,6
@@
struct volume_id *volume_id_open_fd(int fd)
return id;
}
return id;
}
-/* open volume by device node */
struct volume_id *volume_id_open_node(const char *path)
{
struct volume_id *id;
struct volume_id *volume_id_open_node(const char *path)
{
struct volume_id *id;
@@
-313,6
+436,12
@@
struct volume_id *volume_id_open_node(const char *path)
return id;
}
return id;
}
+/**
+ * volume_id_close:
+ * @id: Probing context.
+ *
+ * Release probing context and free all associated data.
+ */
void volume_id_close(struct volume_id *id)
{
if (id == NULL)
void volume_id_close(struct volume_id *id)
{
if (id == NULL)