select.c: Clarify osmo_fd_(un)register() API expectations of registered fd
Those restrictions were implicitly required for a while and most of the
users of this API already followed them, but just a few didn't. All
known users have now been fixed. Let's explicitly document the
restrictions imposed by the API to ease avoiding similar issues in the
future.
Change-Id: I53d95aad15b33dd66aa5c7dd11745a35c4481f33
diff --git a/src/core/select.c b/src/core/select.c
index f983601..584de24 100644
--- a/src/core/select.c
+++ b/src/core/select.c
@@ -151,6 +151,9 @@
/*! Register a new file descriptor with select loop abstraction
* \param[in] fd osmocom file descriptor to be registered
* \returns 0 on success; negative in case of error
+ *
+ * The API expects fd field of the struct osmo_fd to remain unchanged while
+ * registered, ie until osmo_fd_unregister() is called on it.
*/
int osmo_fd_register(struct osmo_fd *fd)
{
@@ -208,6 +211,9 @@
/*! Unregister a file descriptor from select loop abstraction
* \param[in] fd osmocom file descriptor to be unregistered
+ *
+ * This function must be called before changing the value of the fd field in
+ * the struct osmo_fd.
*/
void osmo_fd_unregister(struct osmo_fd *fd)
{