mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
libudev: update documentation
This commit is contained in:
parent
26812f0a13
commit
1e5113228f
@ -23,6 +23,11 @@
|
||||
#include "libudev.h"
|
||||
#include "libudev-private.h"
|
||||
|
||||
/**
|
||||
* udev_device:
|
||||
*
|
||||
* Representation of a kernel sys device.
|
||||
*/
|
||||
struct udev_device {
|
||||
struct udev *udev;
|
||||
struct udev_device *parent_device;
|
||||
@ -341,6 +346,23 @@ struct udev_device *udev_device_new_from_syspath(struct udev *udev, const char *
|
||||
return udev_device;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_new_from_devnum:
|
||||
* @udev: udev library context
|
||||
* @type: char or block device
|
||||
* @devnum: device major/minor number
|
||||
*
|
||||
* Create new udev device, and fill in information from the sys
|
||||
* device and the udev database entry. The device is looked up
|
||||
* by its major/minor number. Character and block device numbers
|
||||
* are not unique across the two types, they do not share the same
|
||||
* range of numbers.
|
||||
*
|
||||
* The initial refcount is 1, and needs to be decremented to
|
||||
* release the resources of the udev device.
|
||||
*
|
||||
* Returns: a new udev device, or #NULL, if it does not exist
|
||||
**/
|
||||
struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, dev_t devnum)
|
||||
{
|
||||
char path[UTIL_PATH_SIZE];
|
||||
@ -392,6 +414,22 @@ struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, de
|
||||
return device;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_new_from_subsystem_sysname:
|
||||
* @udev: udev library context
|
||||
* @subsystem: the subsytem of the device
|
||||
* @sysname: the name of the device
|
||||
*
|
||||
* Create new udev device, and fill in information from the sys
|
||||
* device and the udev database entry. The device is looked up
|
||||
* by the subsytem and name string of the device, like "mem",
|
||||
* "zero", or "block", "sda".
|
||||
*
|
||||
* The initial refcount is 1, and needs to be decremented to
|
||||
* release the resources of the udev device.
|
||||
*
|
||||
* Returns: a new udev device, or #NULL, if it does not exist
|
||||
**/
|
||||
struct udev_device *udev_device_new_from_subsystem_sysname(struct udev *udev, const char *subsystem, const char *sysname)
|
||||
{
|
||||
char path_full[UTIL_PATH_SIZE];
|
||||
@ -495,6 +533,25 @@ static struct udev_device *device_new_from_parent(struct udev_device *udev_devic
|
||||
return NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_parent:
|
||||
* @udev_device: the device to start searching from
|
||||
*
|
||||
* Find the next parent device, and fill in information from the sys
|
||||
* device and the udev database entry.
|
||||
*
|
||||
* The returned the device is not referenced. It is attached to the
|
||||
* child device, and will be cleaned up when the child device
|
||||
* is cleaned up.
|
||||
*
|
||||
* It is not neccessarily just the upper level directory, empty or not
|
||||
* recognized sys directories are ignored.
|
||||
*
|
||||
* It can be called as many times as needed, without caring about
|
||||
* references.
|
||||
*
|
||||
* Returns: a new udev device, or #NULL, if it no parent exist.
|
||||
**/
|
||||
struct udev_device *udev_device_get_parent(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -508,6 +565,25 @@ struct udev_device *udev_device_get_parent(struct udev_device *udev_device)
|
||||
return udev_device->parent_device;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_parent_with_subsystem_devtype:
|
||||
* @udev_device: udev device to start searching from
|
||||
* @subsystem: the subsytem of the device
|
||||
* @devtype: the type (DEVTYPE) of the device
|
||||
*
|
||||
* Find the next parent device, with a matching subsystem and devtype
|
||||
* value, and fill in information from the sys device and the udev
|
||||
* database entry.
|
||||
*
|
||||
* The returned the device is not referenced. It is attached to the
|
||||
* child device, and will be cleaned up when the child device
|
||||
* is cleaned up.
|
||||
*
|
||||
* It can be called as many times as needed, without caring about
|
||||
* references.
|
||||
*
|
||||
* Returns: a new udev device, or #NULL, if no matching parent exists.
|
||||
**/
|
||||
struct udev_device *udev_device_get_parent_with_subsystem_devtype(struct udev_device *udev_device, const char *subsystem, const char *devtype)
|
||||
{
|
||||
struct udev_device *parent;
|
||||
@ -631,6 +707,12 @@ const char *udev_device_get_syspath(struct udev_device *udev_device)
|
||||
return udev_device->syspath;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_sysname:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* Returns: the sys name of the device device
|
||||
**/
|
||||
const char *udev_device_get_sysname(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -638,6 +720,12 @@ const char *udev_device_get_sysname(struct udev_device *udev_device)
|
||||
return udev_device->sysname;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_sysnum:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* Returns: the trailing number of of the device name
|
||||
**/
|
||||
const char *udev_device_get_sysnum(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -790,6 +878,12 @@ struct udev_list_entry *udev_device_get_properties_list_entry(struct udev_device
|
||||
return udev_list_get_entry(&udev_device->properties_list);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_driver:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* Returns: the driver string or #NULL, if ther is no driver attached.
|
||||
**/
|
||||
const char *udev_device_get_driver(struct udev_device *udev_device)
|
||||
{
|
||||
char driver[UTIL_NAME_SIZE];
|
||||
@ -804,6 +898,12 @@ const char *udev_device_get_driver(struct udev_device *udev_device)
|
||||
return udev_device->driver;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_devnum:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* Returns: the device major/minor number.
|
||||
**/
|
||||
dev_t udev_device_get_devnum(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -813,6 +913,16 @@ dev_t udev_device_get_devnum(struct udev_device *udev_device)
|
||||
return udev_device->devnum;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_action:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* This is only valid if the device was received through a monitor. Devices read from
|
||||
* sys do not have an action string. Usual actions are: add, remove, change, online,
|
||||
* offline.
|
||||
*
|
||||
* Returns: the kernel action value, or #NULL if there is no action value available.
|
||||
**/
|
||||
const char *udev_device_get_action(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -820,6 +930,15 @@ const char *udev_device_get_action(struct udev_device *udev_device)
|
||||
return udev_device->action;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_devnum:
|
||||
* @udev_device: udev device
|
||||
*
|
||||
* This is only valid if the device was received through a monitor. Devices read from
|
||||
* sys do not have a sequence number.
|
||||
*
|
||||
* Returns: the kernel event sequence number, or 0 if there is no sequence number available.
|
||||
**/
|
||||
unsigned long long int udev_device_get_seqnum(struct udev_device *udev_device)
|
||||
{
|
||||
if (udev_device == NULL)
|
||||
@ -827,6 +946,16 @@ unsigned long long int udev_device_get_seqnum(struct udev_device *udev_device)
|
||||
return udev_device->seqnum;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_sysattr_value:
|
||||
* @udev_device: udev device
|
||||
* @sysattr: attribute name
|
||||
*
|
||||
* The retrieved value is cached in the device. Repeated reads will return the same
|
||||
* value and not open the attribute again.
|
||||
*
|
||||
* Returns: the content of a sys attribute file, or #NULL if there is no sys attribute value.
|
||||
**/
|
||||
const char *udev_device_get_sysattr_value(struct udev_device *udev_device, const char *sysattr)
|
||||
{
|
||||
struct udev_list_entry *list_entry;
|
||||
@ -1025,6 +1154,13 @@ struct udev_list_entry *udev_device_add_property_from_string(struct udev_device
|
||||
return udev_device_add_property(udev_device, name, val);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_device_get_property_value:
|
||||
* @udev_device: udev device
|
||||
* @key: property name
|
||||
*
|
||||
* Returns: the value of a device property, or #NULL if there is no such property.
|
||||
**/
|
||||
const char *udev_device_get_property_value(struct udev_device *udev_device, const char *key)
|
||||
{
|
||||
struct udev_list_entry *list_entry;
|
||||
|
@ -19,6 +19,11 @@
|
||||
#include "libudev.h"
|
||||
#include "libudev-private.h"
|
||||
|
||||
/**
|
||||
* udev_list_entry:
|
||||
*
|
||||
* One entry in a list, containing a name and an optional value.
|
||||
*/
|
||||
struct udev_list_entry {
|
||||
struct udev_list_node node;
|
||||
struct udev *udev;
|
||||
@ -180,6 +185,12 @@ struct udev_list_entry *udev_list_get_entry(struct udev_list_node *list)
|
||||
return list_node_to_entry(list->next);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_list_entry_get_next:
|
||||
* @list_entry: current entry
|
||||
*
|
||||
* Returns: the next entry from the list, #NULL is no more entries are found.
|
||||
*/
|
||||
struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_entry)
|
||||
{
|
||||
struct udev_list_node *next;
|
||||
@ -193,6 +204,13 @@ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_en
|
||||
return list_node_to_entry(next);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_list_entry_get_by_name:
|
||||
* @list_entry: current entry
|
||||
* @name: name string to match
|
||||
*
|
||||
* Returns: the entry where @name matched, #NULL if no matching entry is found.
|
||||
*/
|
||||
struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list_entry, const char *name)
|
||||
{
|
||||
struct udev_list_entry *entry;
|
||||
@ -206,6 +224,12 @@ struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list
|
||||
return NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_list_entry_get_name:
|
||||
* @list_entry: current entry
|
||||
*
|
||||
* Returns: the name string of this entry.
|
||||
*/
|
||||
const char *udev_list_entry_get_name(struct udev_list_entry *list_entry)
|
||||
{
|
||||
if (list_entry == NULL)
|
||||
@ -213,6 +237,12 @@ const char *udev_list_entry_get_name(struct udev_list_entry *list_entry)
|
||||
return list_entry->name;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_list_entry_get_value:
|
||||
* @list_entry: current entry
|
||||
*
|
||||
* Returns: the value string of this entry.
|
||||
*/
|
||||
const char *udev_list_entry_get_value(struct udev_list_entry *list_entry)
|
||||
{
|
||||
if (list_entry == NULL)
|
||||
|
@ -21,6 +21,11 @@
|
||||
#include "libudev.h"
|
||||
#include "libudev-private.h"
|
||||
|
||||
/**
|
||||
* udev:
|
||||
*
|
||||
* Library context, passed to all operations.
|
||||
*/
|
||||
struct udev {
|
||||
int refcount;
|
||||
void (*log_fn)(struct udev *udev,
|
||||
@ -54,6 +59,15 @@ static void log_stderr(struct udev *udev,
|
||||
vfprintf(stderr, format, args);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_get_userdata:
|
||||
* @udev: udev library context
|
||||
*
|
||||
* Retrieve stored data pointer from library context. This might be useful
|
||||
* to access from callbacks.
|
||||
*
|
||||
* Returns: stored userdata
|
||||
**/
|
||||
void *udev_get_userdata(struct udev *udev)
|
||||
{
|
||||
if (udev == NULL)
|
||||
@ -61,6 +75,13 @@ void *udev_get_userdata(struct udev *udev)
|
||||
return udev->userdata;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_set_userdata:
|
||||
* @udev: udev library context
|
||||
* @userdata: data pointer
|
||||
*
|
||||
* Store custom @userdata in the library context.
|
||||
**/
|
||||
void udev_set_userdata(struct udev *udev, void *userdata)
|
||||
{
|
||||
if (udev == NULL)
|
||||
@ -71,7 +92,8 @@ void udev_set_userdata(struct udev *udev, void *userdata)
|
||||
/**
|
||||
* udev_new:
|
||||
*
|
||||
* Create udev library context.
|
||||
* Create udev library context. This reads the udev configuration
|
||||
* file, and fills in the default values.
|
||||
*
|
||||
* The initial refcount is 1, and needs to be decremented to
|
||||
* release the resources of the udev library context.
|
||||
@ -293,11 +315,28 @@ void udev_set_log_fn(struct udev *udev,
|
||||
info(udev, "custom logging function %p registered\n", udev);
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_get_log_priority:
|
||||
* @udev: udev library context
|
||||
*
|
||||
* The initial syslog priortity is read from the udev config file
|
||||
* at startup.
|
||||
*
|
||||
* Returns: the current syslog priority
|
||||
**/
|
||||
int udev_get_log_priority(struct udev *udev)
|
||||
{
|
||||
return udev->log_priority;
|
||||
}
|
||||
|
||||
/**
|
||||
* udev_set_log_priority:
|
||||
* @udev: udev library context
|
||||
* @priority: the new syslog priority
|
||||
*
|
||||
* Set the current syslog priority. The value controls which messages
|
||||
* are send to syslog.
|
||||
**/
|
||||
void udev_set_log_priority(struct udev *udev, int priority)
|
||||
{
|
||||
char num[32];
|
||||
|
@ -47,10 +47,17 @@ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_en
|
||||
struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list_entry, const char *name);
|
||||
const char *udev_list_entry_get_name(struct udev_list_entry *list_entry);
|
||||
const char *udev_list_entry_get_value(struct udev_list_entry *list_entry);
|
||||
#define udev_list_entry_foreach(entry, first) \
|
||||
for (entry = first; \
|
||||
entry != NULL; \
|
||||
entry = udev_list_entry_get_next(entry))
|
||||
/**
|
||||
* udev_list_entry_foreach:
|
||||
* @list_entry: entry to store the current position
|
||||
* @first_entry: first entry to start with
|
||||
*
|
||||
* Helper to iterate over all entries of a list.
|
||||
*/
|
||||
#define udev_list_entry_foreach(list_entry, first_entry) \
|
||||
for (list_entry = first_entry; \
|
||||
list_entry != NULL; \
|
||||
list_entry = udev_list_entry_get_next(list_entry))
|
||||
|
||||
/*
|
||||
* udev_device
|
||||
|
Loading…
Reference in New Issue
Block a user