libudev: update documentation

[elogind.git] / libudev / libudev-device.c

diff --git a/libudev/libudev-device.c b/libudev/libudev-device.c
index 5d1ad9f223acb307adc65c9dec6f0af681807a1d..410f75b3008d7054bc7d053403902ffb548526e2 100644 (file)
--- a/libudev/libudev-device.c
+++ b/libudev/libudev-device.c
@@ -1,7 +1,7 @@
 /*
  * libudev - interface to udev device information
  *
 /*
  * libudev - interface to udev device information
  *

- * Copyright (C) 2008-2009 Kay Sievers <kay.sievers@vrfy.org>
+ * Copyright (C) 2008-2010 Kay Sievers <kay.sievers@vrfy.org>

  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public


@@ -13,6 +13,7 @@
 #include <stdlib.h>
 #include <stddef.h>
 #include <unistd.h>
 #include <stdlib.h>
 #include <stddef.h>
 #include <unistd.h>

+#include <stdbool.h>

 #include <errno.h>
 #include <string.h>
 #include <dirent.h>
 #include <errno.h>
 #include <string.h>
 #include <dirent.h>


@@ -67,6 +68,7 @@ struct udev_device {
        int refcount;
        dev_t devnum;
        int watch_handle;
        int refcount;
        dev_t devnum;
        int watch_handle;

+       int maj, min;

        unsigned int parent_set:1;
        unsigned int subsystem_set:1;
        unsigned int devtype_set:1;
        unsigned int parent_set:1;
        unsigned int subsystem_set:1;
        unsigned int devtype_set:1;


@@ -77,6 +79,130 @@ struct udev_device {
        unsigned int ignore_remove:1;
 };
 
        unsigned int ignore_remove:1;
 };
 

+struct udev_list_entry *udev_device_add_property(struct udev_device *udev_device, const char *key, const char *value)
+{
+       udev_device->envp_uptodate = 0;
+       if (value == NULL) {
+               struct udev_list_entry *list_entry;
+
+               list_entry = udev_device_get_properties_list_entry(udev_device);
+               list_entry = udev_list_entry_get_by_name(list_entry, key);
+               if (list_entry != NULL)
+                       udev_list_entry_delete(list_entry);
+               return NULL;
+       }
+       return udev_list_entry_add(udev_device->udev, &udev_device->properties_list, key, value, 1, 0);
+}
+
+static struct udev_list_entry *udev_device_add_property_from_string(struct udev_device *udev_device, const char *property)
+{
+       char name[UTIL_LINE_SIZE];
+       char *val;
+
+       util_strscpy(name, sizeof(name), property);
+       val = strchr(name, '=');
+       if (val == NULL)
+               return NULL;
+       val[0] = '\0';
+       val = &val[1];
+       if (val[0] == '\0')
+               val = NULL;
+       return udev_device_add_property(udev_device, name, val);
+}
+
+/*
+ * parse property string, and if needed, update internal values accordingly
+ *
+ * udev_device_add_property_from_string_parse_finish() needs to be
+ * called after adding properties, and its return value checked
+ *
+ * udev_device_set_info_loaded() needs to be set, to avoid trying
+ * to use a device without a DEVPATH set
+ */
+void udev_device_add_property_from_string_parse(struct udev_device *udev_device, const char *property)
+{
+       if (strncmp(property, "DEVPATH=", 8) == 0) {
+               char path[UTIL_PATH_SIZE];
+
+               util_strscpyl(path, sizeof(path), udev_get_sys_path(udev_device->udev), &property[8], NULL);
+               udev_device_set_syspath(udev_device, path);
+       } else if (strncmp(property, "SUBSYSTEM=", 10) == 0) {
+               udev_device_set_subsystem(udev_device, &property[10]);
+       } else if (strncmp(property, "DEVTYPE=", 8) == 0) {
+               udev_device_set_devtype(udev_device, &property[8]);
+       } else if (strncmp(property, "DEVNAME=", 8) == 0) {
+               if (property[8] == '/')
+                       udev_device_set_devnode(udev_device, &property[8]);
+               else
+                       udev_device_set_knodename(udev_device, &property[8]);
+       } else if (strncmp(property, "DEVLINKS=", 9) == 0) {
+               char devlinks[UTIL_PATH_SIZE];
+               char *slink;
+               char *next;
+
+               util_strscpy(devlinks, sizeof(devlinks), &property[9]);
+               slink = devlinks;
+               next = strchr(slink, ' ');
+               while (next != NULL) {
+                       next[0] = '\0';
+                       udev_device_add_devlink(udev_device, slink, 0);
+                       slink = &next[1];
+                       next = strchr(slink, ' ');
+               }
+               if (slink[0] != '\0')
+                       udev_device_add_devlink(udev_device, slink, 0);
+       } else if (strncmp(property, "DRIVER=", 7) == 0) {
+               udev_device_set_driver(udev_device, &property[7]);
+       } else if (strncmp(property, "ACTION=", 7) == 0) {
+               udev_device_set_action(udev_device, &property[7]);
+       } else if (strncmp(property, "MAJOR=", 6) == 0) {
+               udev_device->maj = strtoull(&property[6], NULL, 10);
+       } else if (strncmp(property, "MINOR=", 6) == 0) {
+               udev_device->min = strtoull(&property[6], NULL, 10);
+       } else if (strncmp(property, "DEVPATH_OLD=", 12) == 0) {
+               udev_device_set_devpath_old(udev_device, &property[12]);
+       } else if (strncmp(property, "SEQNUM=", 7) == 0) {
+               udev_device_set_seqnum(udev_device, strtoull(&property[7], NULL, 10));
+       } else if (strncmp(property, "TIMEOUT=", 8) == 0) {
+               udev_device_set_timeout(udev_device, strtoull(&property[8], NULL, 10));
+       } else {
+               udev_device_add_property_from_string(udev_device, property);
+       }
+}
+
+int udev_device_add_property_from_string_parse_finish(struct udev_device *udev_device)
+{
+       if (udev_device->maj > 0)
+               udev_device_set_devnum(udev_device, makedev(udev_device->maj, udev_device->min));
+       udev_device->maj = 0;
+       udev_device->min = 0;
+
+       if (udev_device->devpath == NULL || udev_device->subsystem == NULL)
+               return -EINVAL;
+       return 0;
+}
+
+/**
+ * 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;
+
+       if (udev_device == NULL)
+               return NULL;
+       if (key == NULL)
+               return NULL;
+
+       list_entry = udev_device_get_properties_list_entry(udev_device);
+       list_entry =  udev_list_entry_get_by_name(list_entry, key);
+       return udev_list_entry_get_value(list_entry);
+}
+

 int udev_device_read_db(struct udev_device *udev_device)
 {
        struct stat stats;
 int udev_device_read_db(struct udev_device *udev_device)
 {
        struct stat stats;


@@ -303,25 +429,7 @@ struct udev_device *udev_device_new_from_syspath(struct udev *udev, const char *
        util_strscpy(path, sizeof(path), syspath);
        util_resolve_sys_link(udev, path, sizeof(path));
 
        util_strscpy(path, sizeof(path), syspath);
        util_resolve_sys_link(udev, path, sizeof(path));
 

-       /* try to resolve the silly block layout if needed */
-       if (strncmp(&path[len], "/block/", 7) == 0) {
-               char block[UTIL_PATH_SIZE];
-               char part[UTIL_PATH_SIZE];
-
-               util_strscpy(block, sizeof(block), path);
-               pos = strrchr(block, '/');
-               if (pos == NULL)
-                       return NULL;
-               util_strscpy(part, sizeof(part), pos);
-               pos[0] = '\0';
-               if (util_resolve_sys_link(udev, block, sizeof(block)) == 0)
-                       util_strscpyl(path, sizeof(path), block, part, NULL);
-       }
-
-       /* path exists in sys */
-       if (strncmp(&syspath[len], "/devices/", 9) == 0 ||
-           strncmp(&syspath[len], "/class/", 7) == 0 ||
-           strncmp(&syspath[len], "/block/", 7) == 0) {
+       if (strncmp(&syspath[len], "/devices/", 9) == 0) {

                char file[UTIL_PATH_SIZE];
 
                /* all "devices" require a "uevent" file */
                char file[UTIL_PATH_SIZE];
 
                /* all "devices" require a "uevent" file */


@@ -355,10 +463,9 @@ struct udev_device *udev_device_new_from_syspath(struct udev *udev, const char *
  * @devnum: device major/minor number
  *
  * Create new udev device, and fill in information from the sys
  * @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.
+ * device and the udev database entry. The device is looked-up
+ * by its major/minor number and type. Character and block device
+ * numbers are not unique across the two types.

  *
  * The initial refcount is 1, and needs to be decremented to
  * release the resources of the udev device.
  *
  * The initial refcount is 1, and needs to be decremented to
  * release the resources of the udev device.


@@ -369,9 +476,6 @@ struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, de
 {
        char path[UTIL_PATH_SIZE];
        const char *type_str;
 {
        char path[UTIL_PATH_SIZE];
        const char *type_str;

-       struct udev_enumerate *udev_enumerate;
-       struct udev_list_entry *list_entry;
-       struct udev_device *device = NULL;

 
        if (type == 'b')
                type_str = "block";
 
        if (type == 'b')
                type_str = "block";


@@ -380,40 +484,10 @@ struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, de
        else
                return NULL;
 
        else
                return NULL;
 

-       /* /sys/dev/{block,char}/<maj>:<min> link */
-       snprintf(path, sizeof(path), "%s/dev/%s/%u:%u", udev_get_sys_path(udev),
-                type_str, major(devnum), minor(devnum));
-       if (util_resolve_sys_link(udev, path, sizeof(path)) == 0)
-               return udev_device_new_from_syspath(udev, path);
-
-       udev_enumerate = udev_enumerate_new(udev);
-       if (udev_enumerate == NULL)
-               return NULL;
-
-       /* fallback to search sys devices for the major/minor */
-       if (type == 'b')
-               udev_enumerate_add_match_subsystem(udev_enumerate, "block");
-       else if (type == 'c')
-               udev_enumerate_add_nomatch_subsystem(udev_enumerate, "block");
-       udev_enumerate_scan_devices(udev_enumerate);
-       udev_list_entry_foreach(list_entry, udev_enumerate_get_list_entry(udev_enumerate)) {
-               struct udev_device *device_loop;
-
-               device_loop = udev_device_new_from_syspath(udev, udev_list_entry_get_name(list_entry));
-               if (device_loop != NULL) {
-                       if (udev_device_get_devnum(device_loop) == devnum) {
-                               if (type == 'b' && strcmp(udev_device_get_subsystem(device_loop), "block") != 0)
-                                       continue;
-                               if (type == 'c' && strcmp(udev_device_get_subsystem(device_loop), "block") == 0)
-                                       continue;
-                               device = device_loop;
-                               break;
-                       }
-                       udev_device_unref(device_loop);
-               }
-       }
-       udev_enumerate_unref(udev_enumerate);
-       return device;
+       /* use /sys/dev/{block,char}/<maj>:<min> link */
+       snprintf(path, sizeof(path), "%s/dev/%s/%u:%u",
+                udev_get_sys_path(udev), type_str, major(devnum), minor(devnum));
+       return udev_device_new_from_syspath(udev, path);

 }
 
 /**
 }
 
 /**


@@ -422,10 +496,9 @@ struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, de
  * @subsystem: the subsystem of the device
  * @sysname: the name of the device
  *
  * @subsystem: the subsystem 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 subsystem and name string of the device, like "mem",
- * "zero", or "block", "sda".
+ * Create new udev device, and fill in information from the sys device
+ * and the udev database entry. The device is looked up by the subsystem
+ * 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.
  *
  * The initial refcount is 1, and needs to be decremented to
  * release the resources of the udev device.


@@ -502,26 +575,51 @@ found:
        return udev_device_new_from_syspath(udev, path_full);
 }
 
        return udev_device_new_from_syspath(udev, path_full);
 }
 

+/**
+ * udev_device_new_from_environment
+ * @udev: udev library context
+ *
+ * Create new udev device, and fill in information from the
+ * current process environment. This only works reliable if
+ * the process is called from a udev rule. It is usually used
+ * for tools executed from IMPORT= rules.
+ *
+ * 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_environment(struct udev *udev)
+{
+       int i;
+       struct udev_device *udev_device;
+
+       udev_device = udev_device_new(udev);
+       if (udev_device == NULL)
+               return NULL;
+       udev_device_set_info_loaded(udev_device);
+
+       for (i = 0; environ[i] != NULL; i++)
+               udev_device_add_property_from_string_parse(udev_device, environ[i]);
+
+       if (udev_device_add_property_from_string_parse_finish(udev_device) < 0) {
+               info(udev, "missing values, invalid device\n");
+               udev_device_unref(udev_device);
+               udev_device = NULL;
+       }
+
+       return udev_device;
+}
+

 static struct udev_device *device_new_from_parent(struct udev_device *udev_device)
 {
        struct udev_device *udev_device_parent = NULL;
        char path[UTIL_PATH_SIZE];
        const char *subdir;
 
 static struct udev_device *device_new_from_parent(struct udev_device *udev_device)
 {
        struct udev_device *udev_device_parent = NULL;
        char path[UTIL_PATH_SIZE];
        const char *subdir;
 

-       /* follow "device" link in deprecated sys layout */
-       if (strncmp(udev_device->devpath, "/class/", 7) == 0 ||
-           strncmp(udev_device->devpath, "/block/", 7) == 0) {
-               util_strscpyl(path, sizeof(path), udev_device->syspath, "/device", NULL);
-               if (util_resolve_sys_link(udev_device->udev, path, sizeof(path)) == 0) {
-                       udev_device_parent = udev_device_new_from_syspath(udev_device->udev, path);
-                       if (udev_device_parent != NULL)
-                               return udev_device_parent;
-               }
-       }
-

        util_strscpy(path, sizeof(path), udev_device->syspath);
        subdir = &path[strlen(udev_get_sys_path(udev_device->udev))+1];
        util_strscpy(path, sizeof(path), udev_device->syspath);
        subdir = &path[strlen(udev_get_sys_path(udev_device->udev))+1];

-       while (1) {
+       for (;;) {

                char *pos;
 
                pos = strrchr(subdir, '/');
                char *pos;
 
                pos = strrchr(subdir, '/');


@@ -577,6 +675,9 @@ struct udev_device *udev_device_get_parent(struct udev_device *udev_device)
  * value, and fill in information from the sys device and the udev
  * database entry.
  *
  * value, and fill in information from the sys device and the udev
  * database entry.
  *

+ * If devtype is #NULL, only subsystem is checked, and any devtype will
+ * match.
+ *

  * 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.
  * 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.


@@ -1127,62 +1228,10 @@ int udev_device_add_devlink(struct udev_device *udev_device, const char *devlink
        if (list_entry == NULL)
                return -ENOMEM;
        if (unique)
        if (list_entry == NULL)
                return -ENOMEM;
        if (unique)

-               udev_list_entry_set_flag(list_entry, 1);
+               udev_list_entry_set_flags(list_entry, 1);

        return 0;
 }
 
        return 0;
 }
 

-struct udev_list_entry *udev_device_add_property(struct udev_device *udev_device, const char *key, const char *value)
-{
-       udev_device->envp_uptodate = 0;
-       if (value == NULL) {
-               struct udev_list_entry *list_entry;
-
-               list_entry = udev_device_get_properties_list_entry(udev_device);
-               list_entry = udev_list_entry_get_by_name(list_entry, key);
-               if (list_entry != NULL)
-                       udev_list_entry_delete(list_entry);
-               return NULL;
-       }
-       return udev_list_entry_add(udev_device->udev, &udev_device->properties_list, key, value, 1, 0);
-}
-
-struct udev_list_entry *udev_device_add_property_from_string(struct udev_device *udev_device, const char *property)
-{
-       char name[UTIL_PATH_SIZE];
-       char *val;
-
-       util_strscpy(name, sizeof(name), property);
-       val = strchr(name, '=');
-       if (val == NULL)
-               return NULL;
-       val[0] = '\0';
-       val = &val[1];
-       if (val[0] == '\0')
-               val = NULL;
-       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;
-
-       if (udev_device == NULL)
-               return NULL;
-       if (key == NULL)
-               return NULL;
-
-       list_entry = udev_device_get_properties_list_entry(udev_device);
-       list_entry =  udev_list_entry_get_by_name(list_entry, key);
-       return udev_list_entry_get_value(list_entry);
-}
-

 #define ENVP_SIZE                      128
 #define MONITOR_BUF_SIZE               4096
 static int update_envp_monitor_buf(struct udev_device *udev_device)
 #define ENVP_SIZE                      128
 #define MONITOR_BUF_SIZE               4096
 static int update_envp_monitor_buf(struct udev_device *udev_device)


@@ -1225,7 +1274,9 @@ static int update_envp_monitor_buf(struct udev_device *udev_device)
                l = util_strpcpyl(&s, l, key, "=", udev_list_entry_get_value(list_entry), NULL);
                if (l == 0)
                        return -EINVAL;
                l = util_strpcpyl(&s, l, key, "=", udev_list_entry_get_value(list_entry), NULL);
                if (l == 0)
                        return -EINVAL;

+               /* advance past the trailing '\0' that util_strpcpyl() guarantees */

                s++;
                s++;

+               l--;

        }
        udev_device->envp[i] = NULL;
        udev_device->monitor_buf_len = s - udev_device->monitor_buf;
        }
        udev_device->envp[i] = NULL;
        udev_device->monitor_buf_len = s - udev_device->monitor_buf;