sharedmem.h: fix the docs.
The complaint was that the docs were vague. Unfortunately, the truth is
a bit of a mess, but that's all the more reason for us to document it
clearly.
Bug: https://github.com/android/ndk/issues/1127
Test: N/A
Change-Id: I3ba116d43bb99731e0bb0832118e0d58a6400ad0
diff --git a/include/android/sharedmem.h b/include/android/sharedmem.h
index 7f5177b..2aacf11 100644
--- a/include/android/sharedmem.h
+++ b/include/android/sharedmem.h
@@ -21,7 +21,7 @@
/**
* @file sharedmem.h
- * @brief Shared memory buffers that can be shared across process.
+ * @brief Shared memory buffers that can be shared between processes.
*/
#ifndef ANDROID_SHARED_MEMORY_H
@@ -61,11 +61,14 @@
*
* Use close() to release the shared memory region.
*
+ * Use {@link android.os.ParcelFileDescriptor} to pass the file descriptor to
+ * another process.
+ *
* Available since API level 26.
*
* \param name an optional name.
* \param size size of the shared memory region
- * \return file descriptor that denotes the shared memory; error code on failure.
+ * \return file descriptor that denotes the shared memory; -1 and sets errno on failure, or -EINVAL if the error is that size was 0.
*/
int ASharedMemory_create(const char *name, size_t size) __INTRODUCED_IN(26);
@@ -109,7 +112,7 @@
* \param fd file descriptor of the shared memory region.
* \param prot any bitwise-or'ed combination of PROT_READ, PROT_WRITE, PROT_EXEC denoting
* updated access. Note access can only be removed, but not added back.
- * \return 0 for success, error code on failure.
+ * \return 0 for success, -1 and sets errno on failure.
*/
int ASharedMemory_setProt(int fd, int prot) __INTRODUCED_IN(26);