Document that the return value of get_name|uniq|phys is not permanent

It's a pointer to the copy libevdev has, but that copy may be freed by the
caller if someone calls e.g. libevdev_set_name()

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 24 insertions, 0 deletions

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index b3023cf..898e919 100644
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -742,6 +742,10 @@ int libevdev_has_event_pending(struct libevdev *dev);
 /**
  * @ingroup bits
  *
+ * Retrieve the device's name, either as set by the caller or as read from
+ * the kernel. The string returned is valid until libevdev_free() or until
+ * libevdev_set_name(), whichever comes earlier.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  *
  * @return The device name as read off the kernel device. The name is never
@@ -754,6 +758,10 @@ const char* libevdev_get_name(const struct libevdev *dev);
 /**
  * @ingroup kernel
  *
+ * Change the device's name as returned by libevdev_get_name(). This
+ * function destroys the string previously returned by libevdev_get_name(),
+ * a caller must take care that no references are kept.
+ *
  * @param dev The evdev device
  * @param name The new, non-NULL, name to assign to this device.
  *
@@ -765,6 +773,10 @@ void libevdev_set_name(struct libevdev *dev, const char *name);
 /**
  * @ingroup bits
  *
+ * Retrieve the device's physical location, either as set by the caller or
+ * as read from the kernel. The string returned is valid until
+ * libevdev_free() or until libevdev_set_phys(), whichever comes earlier.
+ *
  * Virtual devices such as uinput devices have no phys location.
  *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
@@ -778,6 +790,10 @@ const char * libevdev_get_phys(const struct libevdev *dev);
 /**
  * @ingroup kernel
  *
+ * Change the device's physical location as returned by libevdev_get_phys().
+ * This function destroys the string previously returned by
+ * libevdev_get_phys(), a caller must take care that no references are kept.
+ *
  * @param dev The evdev device
  * @param phys The new phys to assign to this device.
  *
@@ -789,6 +805,10 @@ void libevdev_set_phys(struct libevdev *dev, const char *phys);
 /**
  * @ingroup bits
  *
+ * Retrieve the device's unique identifier, either as set by the caller or
+ * as read from the kernel. The string returned is valid until
+ * libevdev_free() or until libevdev_set_uniq(), whichever comes earlier.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  *
  * @return The unique identifier for this device, or NULL if there is none
@@ -800,6 +820,10 @@ const char * libevdev_get_uniq(const struct libevdev *dev);
 /**
  * @ingroup kernel
  *
+ * Change the device's unique identifier as returned by libevdev_get_uniq().
+ * This function destroys the string previously returned by
+ * libevdev_get_uniq(), a caller must take care that no references are kept.
+ *
  * @param dev The evdev device
  * @param uniq The new uniq to assign to this device.
  *