[components]对POSIX函数中mqueue.c的mq_unlink函数注释 (#7543)

1 files changed, 34 insertions, 0 deletions

diff --git a/components/libc/posix/ipc/mqueue.c b/components/libc/posix/ipc/mqueue.c
index 6f04945962..b2e7b7b6c4 100644
--- a/components/libc/posix/ipc/mqueue.c
+++ b/components/libc/posix/ipc/mqueue.c
@@ -355,6 +355,40 @@ int mq_close(mqd_t id)
 }
 RTM_EXPORT(mq_close);
 
+/**
+ * @brief    This function will remove a message queue (REALTIME).
+ *
+ * @note    The mq_unlink() function shall remove the message queue named by the string name. 
+ *          If one or more processes have the message queue open when mq_unlink() is called, 
+ *          destruction of the message queue shall be postponed until all references to the message queue have been closed. 
+ *          However, the mq_unlink() call need not block until all references have been closed; it may return immediately.
+ * 
+ *          After a successful call to mq_unlink(), reuse of the name shall subsequently cause mq_open() to behave as if 
+ *          no message queue of this name exists (that is, mq_open() will fail if O_CREAT is not set, 
+ *          or will create a new message queue if O_CREAT is set).
+ * 
+ * @param    name  is the name of the message queue.
+ *
+ * @return   Upon successful completion, the function shall return a value of zero. 
+ *           Otherwise, the named message queue shall be unchanged by this function call, 
+ *           and the function shall return a value of -1 and set errno to indicate the error.
+ *
+ * @warning  This function can ONLY be called in the thread context, you can use RT_DEBUG_IN_THREAD_CONTEXT to
+ *           check the context.
+ *           The mq_unlink() function shall fail if:
+ *              [EACCES]
+ *              Permission is denied to unlink the named message queue.
+ *              [EINTR]
+ *              The call to mq_unlink() blocked waiting for all references to the named message queue to be closed and a signal interrupted the call.
+ *              [ENOENT]
+ *              The named message queue does not exist.
+ *           The mq_unlink() function may fail if:
+ *              [ENAMETOOLONG]
+ *              The length of the name argument exceeds {_POSIX_PATH_MAX} on systems that do not support the XSI option 
+ *              or exceeds {_XOPEN_PATH_MAX} on XSI systems,or has a pathname component that is longer than {_POSIX_NAME_MAX} on systems that do 
+ *              not support the XSI option or longer than {_XOPEN_NAME_MAX} on XSI systems.A call to mq_unlink() with a name argument that contains 
+ *              the same message queue name as was previously used in a successful mq_open() call shall not give an [ENAMETOOLONG] error.
+ */
 int mq_unlink(const char *name)
 {
     mqdes_t pmq;