libudev: update copyright headers

[elogind.git] / src / libudev / libudev-enumerate.c

diff --git a/src/libudev/libudev-enumerate.c b/src/libudev/libudev-enumerate.c
index 4725912c362add46dbe511f61c5afb69cb09f848..172965511b32cb6f366f9983d03449855d5c6f01 100644 (file)
--- a/src/libudev/libudev-enumerate.c
+++ b/src/libudev/libudev-enumerate.c
@@ -1,13 +1,21 @@
-/*
- * libudev - interface to udev device information
- *
- * 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
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- */
+/***
+  This file is part of systemd.
+
+  Copyright 2008-2012 Kay Sievers <kay@vrfy.org>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+***/
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -65,7 +73,9 @@ struct udev_enumerate {
  * udev_enumerate_new:
  * @udev: udev library context
  *
- * Returns: an enumeration context
+ * Create an enumeration context to scan /sys.
+ *
+ * Returns: an enumeration context.
  **/
 _public_ struct udev_enumerate *udev_enumerate_new(struct udev *udev)
 {
@@ -109,16 +119,18 @@ _public_ struct udev_enumerate *udev_enumerate_ref(struct udev_enumerate *udev_e
  *
  * Drop a reference of an enumeration context. If the refcount reaches zero,
  * all resources of the enumeration context will be released.
+ *
+ * Returns: the passed enumeration context if it has still an active reference, or #NULL otherwise.
  **/
-_public_ void udev_enumerate_unref(struct udev_enumerate *udev_enumerate)
+_public_ struct udev_enumerate *udev_enumerate_unref(struct udev_enumerate *udev_enumerate)
 {
         unsigned int i;
 
         if (udev_enumerate == NULL)
-                return;
+                return NULL;
         udev_enumerate->refcount--;
         if (udev_enumerate->refcount > 0)
-                return;
+                return udev_enumerate;
         udev_list_cleanup(&udev_enumerate->sysattr_match_list);
         udev_list_cleanup(&udev_enumerate->sysattr_nomatch_list);
         udev_list_cleanup(&udev_enumerate->subsystem_match_list);
@@ -132,13 +144,16 @@ _public_ void udev_enumerate_unref(struct udev_enumerate *udev_enumerate)
                 free(udev_enumerate->devices[i].syspath);
         free(udev_enumerate->devices);
         free(udev_enumerate);
+        return NULL;
 }
 
 /**
  * udev_enumerate_get_udev:
  * @udev_enumerate: context
  *
- * Returns: the udev library context.
+ * Get the udev library context.
+ *
+ * Returns: a pointer to the context.
  */
 _public_ struct udev *udev_enumerate_get_udev(struct udev_enumerate *udev_enumerate)
 {
@@ -243,7 +258,9 @@ static size_t devices_delay_later(struct udev *udev, const char *syspath)
  * udev_enumerate_get_list_entry:
  * @udev_enumerate: context
  *
- * Returns: the first entry of the sorted list of device paths.
+ * Get the first entry of the sorted list of device paths.
+ *
+ * Returns: a udev_list_entry.
  */
 _public_ struct udev_list_entry *udev_enumerate_get_list_entry(struct udev_enumerate *udev_enumerate)
 {
@@ -321,6 +338,8 @@ _public_ struct udev_list_entry *udev_enumerate_get_list_entry(struct udev_enume
  * @udev_enumerate: context
  * @subsystem: filter for a subsystem of the device to include in the list
  *
+ * Match only devices belonging to a certain kernel subsystem.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_match_subsystem(struct udev_enumerate *udev_enumerate, const char *subsystem)
@@ -339,6 +358,8 @@ _public_ int udev_enumerate_add_match_subsystem(struct udev_enumerate *udev_enum
  * @udev_enumerate: context
  * @subsystem: filter for a subsystem of the device to exclude from the list
  *
+ * Match only devices not belonging to a certain kernel subsystem.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate *udev_enumerate, const char *subsystem)
@@ -358,6 +379,8 @@ _public_ int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate *udev_en
  * @sysattr: filter for a sys attribute at the device to include in the list
  * @value: optional value of the sys attribute
  *
+ * Match only devices with a certain /sys device attribute.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_match_sysattr(struct udev_enumerate *udev_enumerate, const char *sysattr, const char *value)
@@ -377,6 +400,8 @@ _public_ int udev_enumerate_add_match_sysattr(struct udev_enumerate *udev_enumer
  * @sysattr: filter for a sys attribute at the device to exclude from the list
  * @value: optional value of the sys attribute
  *
+ * Match only devices not having a certain /sys device attribute.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_nomatch_sysattr(struct udev_enumerate *udev_enumerate, const char *sysattr, const char *value)
@@ -416,6 +441,8 @@ exit:
  * @property: filter for a property of the device to include in the list
  * @value: value of the property
  *
+ * Match only devices with a certain property.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_match_property(struct udev_enumerate *udev_enumerate, const char *property, const char *value)
@@ -434,6 +461,8 @@ _public_ int udev_enumerate_add_match_property(struct udev_enumerate *udev_enume
  * @udev_enumerate: context
  * @tag: filter for a tag of the device to include in the list
  *
+ * Match only devices with a certain tag.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_match_tag(struct udev_enumerate *udev_enumerate, const char *tag)
@@ -503,6 +532,8 @@ _public_ int udev_enumerate_add_match_is_initialized(struct udev_enumerate *udev
  * @udev_enumerate: context
  * @sysname: filter for the name of the device to include in the list
  *
+ * Match only devices with a given /sys device name.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  */
 _public_ int udev_enumerate_add_match_sysname(struct udev_enumerate *udev_enumerate, const char *sysname)
@@ -766,7 +797,7 @@ static int scan_devices_tags(struct udev_enumerate *udev_enumerate)
                         if (dent->d_name[0] == '.')
                                 continue;
 
-                        dev = udev_device_new_from_id_filename(udev_enumerate->udev, dent->d_name);
+                        dev = udev_device_new_from_device_id(udev_enumerate->udev, dent->d_name);
                         if (dev == NULL)
                                 continue;
 
@@ -867,6 +898,9 @@ static int scan_devices_all(struct udev_enumerate *udev_enumerate)
  * udev_enumerate_scan_devices:
  * @udev_enumerate: udev enumeration context
  *
+ * Scan /sys for all devices which match the given filters. No matches
+ * will return all currently available devices.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  **/
 _public_ int udev_enumerate_scan_devices(struct udev_enumerate *udev_enumerate)
@@ -890,6 +924,8 @@ _public_ int udev_enumerate_scan_devices(struct udev_enumerate *udev_enumerate)
  * udev_enumerate_scan_subsystems:
  * @udev_enumerate: udev enumeration context
  *
+ * Scan /sys for all kernel subsystems, including buses, classes, drivers.
+ *
  * Returns: 0 on success, otherwise a negative error value.
  **/
 _public_ int udev_enumerate_scan_subsystems(struct udev_enumerate *udev_enumerate)