Add man pages for memmem and memrmem

Signed-off-by: Mattias Andrée <maandree@kth.se>

3 files changed, 183 insertions, 4 deletions

diff --git a/libsimple/mem.h b/libsimple/mem.h
index 8fb85fa..cf5a866 100644
--- a/libsimple/mem.h
+++ b/libsimple/mem.h
@@ -11,7 +11,8 @@
  * 
  * @param   s  The array of bytes to search
  * @param   c  The byte value to search for
- * @return     `s` with a miminal offset such that `*s == c`
+ * @return     `s` with a miminal offset such that `*r == c`,
+ *             where `r` is the returned pointer
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__pure__, __nonnull__, __warn_unused_result__)))
 void *libsimple_rawmemchr(const void *, int);
@@ -26,8 +27,9 @@ void *libsimple_rawmemchr(const void *, int);
  * @param   s  The array of bytes to search
  * @param   c  The byte value to search for
  * @param   n  The number of bytes in the byte array
- * @return     `s` with a maximal offset such that `*s == c`,
- *             `NULL` if no such offset exists within [0, n)
+ * @return     `s` with a maximal offset such that `*r == c`,
+ *             where `r` is the returned pointer `NULL` if no
+ *             such offset exists within [s, &s[n])
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__pure__, __nonnull__, __warn_unused_result__)))
 void *libsimple_memrchr(const void *, int, size_t);
@@ -47,7 +49,8 @@ void *libsimple_memrchr(const void *, int, size_t);
  * @param   s  The array of bytes to search
  * @param   c  The byte value to search for
  * @param   n  The number of bytes in the byte array
- * @return     `s` with a maximal offset such that `*s == c`
+ * @return     `s` with a maximal offset such that `*r == c`,
+ *             where `r` is the returned pointer
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__pure__, __nonnull__, __warn_unused_result__)))
 void *libsimple_rawmemrchr(const void *, int, size_t);
@@ -56,6 +59,17 @@ void *libsimple_rawmemrchr(const void *, int, size_t);
 #endif
 
 
+/**
+ * Finds the first substring in an array of bytes
+ * 
+ * @param   haystack   The array of bytes to search
+ * @param   nhaystack  The length of `haystack`
+ * @param   needle     The substring to search for
+ * @param   nneedle    The length of `needle`
+ * @return             `haystack` with a minimal offset such that,
+ *                     `!memcmp(r, needle, nneedle)` where `r` is the
+ *                     returned pointer, `NULL` if no such offset exists
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__pure__, __warn_unused_result__)))
 void *libsimple_memmem(const void *, size_t, const void *, size_t);
 #ifndef memmem
@@ -63,6 +77,17 @@ void *libsimple_memmem(const void *, size_t, const void *, size_t);
 #endif
 
 
+/**
+ * Finds the last substring in an array of bytes
+ * 
+ * @param   haystack   The array of bytes to search
+ * @param   nhaystack  The length of `haystack`
+ * @param   needle     The substring to search for
+ * @param   nneedle    The length of `needle`
+ * @return             `haystack` with a maximal offset such that,
+ *                     `!memcmp(r, needle, nneedle)` where `r` is the
+ *                     returned pointer, `NULL` if no such offset exists
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__pure__, __warn_unused_result__)))
 void *libsimple_memrmem(const void *, size_t, const void *, size_t);
 #ifndef memrmem
diff --git a/man/libsimple_memmem.3 b/man/libsimple_memmem.3
new file mode 100644
index 0000000..f084de9
--- /dev/null
+++ b/man/libsimple_memmem.3
@@ -0,0 +1,77 @@
+.TH LIBSIMPLE_MEMMEM 3 2018-10-20 libsimple
+.SH NAME
+libsimple_memmem \- find byte string in memory
+.SH SYNOPSIS
+.nf
+#include <libsimple.h>
+
+void *libsimple_memmem(const void *haystack, size_t nhaystack, const void *needle, size_t nneedle);
+
+#ifndef memmem
+# define memmem libsimple_memmem
+#endif
+.fi
+
+Link with
+.IR \-lsimple .
+.SH DESCRIPTION
+The
+.BR libsimple_memmem ()
+function scans the memory segment
+.IR haystack ,
+with the size
+.IR nhaystack ,
+for the first occurence of the byte string
+.I needle
+with the size
+.IR nneedle .
+.SH RETURN VALUE
+The
+.BR libsimple_memmem ()
+function returns the pointer
+.I s
+with a minimal offset such that
+.IR !memcmp(r,needle,nneedle) ,
+where
+.I r
+is the returned pointer.
+If no such offset exists,
+.B NULL
+is returned.
+.SH ERRORS
+The
+.BR libsimple_memmem ()
+function cannot fail.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR libsimple_memmem ()
+T}	Thread safety	MT-Safe
+T{
+.BR libsimple_memmem ()
+T}	Async-signal safety	AS-Safe
+T{
+.BR libsimple_memmem ()
+T}	Async-cancel safety	AC-Safe
+.TE
+.SH EXAMPLES
+None.
+.SH APPLICATION USAGE
+None.
+.SH RATIONALE
+None.
+.SH FUTURE DIRECTIONS
+None.
+.SH NOTES
+None.
+.SH BUGS
+None.
+.SH SEE ALSO
+.BR libsimple_memrmem (3),
+.BR memchr (3)
diff --git a/man/libsimple_memrmem.3 b/man/libsimple_memrmem.3
new file mode 100644
index 0000000..71bf251
--- /dev/null
+++ b/man/libsimple_memrmem.3
@@ -0,0 +1,77 @@
+.TH LIBSIMPLE_MEMRMEM 3 2018-10-20 libsimple
+.SH NAME
+libsimple_memrmem \- find byte string in memory
+.SH SYNOPSIS
+.nf
+#include <libsimple.h>
+
+void *libsimple_memrmem(const void *haystack, size_t nhaystack, const void *needle, size_t nneedle);
+
+#ifndef memrmem
+# define memrmem libsimple_memrmem
+#endif
+.fi
+
+Link with
+.IR \-lsimple .
+.SH DESCRIPTION
+The
+.BR libsimple_memrmem ()
+function scans the memory segment
+.IR haystack ,
+with the size
+.IR nhaystack ,
+for the last occurence of the byte string
+.I needle
+with the size
+.IR nneedle .
+.SH RETURN VALUE
+The
+.BR libsimple_memrmem ()
+function returns the pointer
+.I s
+with a maximal offset such that
+.IR !memcmp(r,needle,nneedle) ,
+where
+.I r
+is the returned pointer.
+If no such offset exists,
+.B NULL
+is returned.
+.SH ERRORS
+The
+.BR libsimple_memrmem ()
+function cannot fail.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR libsimple_memrmem ()
+T}	Thread safety	MT-Safe
+T{
+.BR libsimple_memrmem ()
+T}	Async-signal safety	AS-Safe
+T{
+.BR libsimple_memrmem ()
+T}	Async-cancel safety	AC-Safe
+.TE
+.SH EXAMPLES
+None.
+.SH APPLICATION USAGE
+None.
+.SH RATIONALE
+None.
+.SH FUTURE DIRECTIONS
+None.
+.SH NOTES
+None.
+.SH BUGS
+None.
+.SH SEE ALSO
+.BR libsimple_memmem (3),
+.BR libsimple_memrchr (3)