update: manual pages

13 files changed, 160 insertions, 6 deletions

diff --git a/man/rb_cleanup.3 b/man/rb_cleanup.3
new file mode 100644
index 0000000..1888bf1
--- /dev/null
+++ b/man/rb_cleanup.3
@@ -0,0 +1 @@
+.so man3/rb_destroy.3
diff --git a/man/rb_clear.3 b/man/rb_clear.3
index 8fbad09..7dba95a 100644
--- a/man/rb_clear.3
+++ b/man/rb_clear.3
@@ -34,7 +34,9 @@ is invalid (null).
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -43,4 +45,5 @@ is invalid (null).
 .BR rb_send (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_destroy.3 b/man/rb_destroy.3
index e88d499..87021ac 100644
--- a/man/rb_destroy.3
+++ b/man/rb_destroy.3
@@ -1,8 +1,9 @@
 .TH "rb_destroy" "3" " 9 February 2018 (v1.0.0)" "bofc.pl"
 .SH NAME
 .PP
-.B rb_destroy,
-.B rb_stop
+.BR rb_stop ,
+.BR rb_destroy ,
+.B rb_cleanup
 - functions to stop any locked threads in rb functions and free resources
 allocated by
 .BR rb_new (3)
@@ -11,6 +12,8 @@ allocated by
 .BI "int rb_stop(struct rb *" rb ");"
 .br
 .BI "int rb_destroy(struct rb *" rb ");"
+.br
+.BI "int rb_cleanup(struct rb *" rb ");"
 .SH DESCRIPTION
 .PP
 Function
@@ -40,13 +43,23 @@ first.
 Passing same
 .I rb
 object twice, will result in segmentation fault.
+.PP
+Function
+.BR rb_cleanup (3)
+works same as
+.BR rb_destroy (3)
+but should be called only on object initialized with
+.BR rb_init (3)
+function.
 .SH NOTES
 .PP
 Due to nature of pthread, you must be sure that no threads are calling
 any functions from
 .B librb
 before calling
-.BR rb_destroy (3).
+.BR rb_destroy (3)
+or
+.BR rb_cleanup (3).
 Failing to do so, will lead to deadlocks or crashes sooner or later.
 .PP
 If you cannot stop threads by yourself before calling
@@ -120,6 +133,7 @@ is invalid (null).
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_read (3),
 .BR rb_discard (3),
 .BR rb_recv (3),
@@ -128,4 +142,5 @@ is invalid (null).
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_discard.3 b/man/rb_discard.3
index fa5772a..d05daf3 100644
--- a/man/rb_discard.3
+++ b/man/rb_discard.3
@@ -52,7 +52,9 @@ is not a valid object.
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
@@ -61,4 +63,5 @@ is not a valid object.
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_header_size.3 b/man/rb_header_size.3
new file mode 100644
index 0000000..0ce4e26
--- /dev/null
+++ b/man/rb_header_size.3
@@ -0,0 +1,33 @@
+.TH "rb_header_size" "3" " 9 February 2018 (v1.0.0)" "bofc.pl"
+.SH NAME
+.PP
+.B rb_header_size
+- read size of
+.B rb
+header in bytes.
+.SH SYNOPSIS
+.PP
+.B "#include <librb.h>"
+.PP
+.B size_t rb_header_size(void);
+.SH RETURN VALUE
+.PP
+Function returns size of iternal struct with information about buffer.
+Size of the buffer with data is not included.
+.SH SEE ALSO
+.PP
+.BR rb_overview (7),
+.BR rb_new (3),
+.BR rb_init (3),
+.BR rb_destroy (3),
+.BR rb_cleanup (3),
+.BR rb_discard (3),
+.BR rb_stop (3),
+.BR rb_read (3),
+.BR rb_recv (3),
+.BR rb_write (3),
+.BR rb_send (3),
+.BR rb_clear (3),
+.BR rb_count (3),
+.BR rb_space (3),
+.BR rb_version (3)
diff --git a/man/rb_init.3 b/man/rb_init.3
new file mode 100644
index 0000000..8012883
--- /dev/null
+++ b/man/rb_init.3
@@ -0,0 +1 @@
+.so man3/rb_new.3
diff --git a/man/rb_new.3 b/man/rb_new.3
index f69c366..1952fe1 100644
--- a/man/rb_new.3
+++ b/man/rb_new.3
@@ -1,14 +1,17 @@
 .TH "rb_new" "3" " 9 February 2018 (v1.0.0)" "bofc.pl"
 .SH NAME
 .PP
-.B rb_new
-- create new ring buffer
+.B rb_new, rb_init
+- initializes new ring buffer
 .SH SYNOPSIS
 .PP
 .BI "#include <librb.h>"
 .PP
 .BI "struct rb *rb_new(size_t " count ", size_t " object_size ", \
 unsigned long " flags ");"
+.br
+.BI "struct rb *rb_init(size_t " count ", size_t " object_size ", \
+unsigned long " flags ", void *" mem ");"
 .SH DESCRIPTION
 .PP
 .BR rb_new (3)
@@ -49,7 +52,26 @@ should be a size of an object, ring buffer will hold.
 You should not write nor read objects of different size than created one, as
 this will lead to undefined behaviour or even crashes.
 .PP
-Function can accept following
+.BR rb_init (3)
+can be used if dynamic allocation is not supported or it needs to be avoided.
+Functions works same as
+.BR rb_new (3)
+but does not perform any allocation and user is responsible to pass pointer to
+.I mem
+that is big enough to hold
+.B rb
+header and any data that could be inserted into buffer.
+Information about header size can be read from
+.BR rb_header_size (3)
+function, and data length can be calculated with formula
+.RI ( count
+*
+.IR object_size ).
+.I mem
+can be whatever continous memory like array on stack, or some custom allocation.
+Check example to see how to use it in practice.
+.PP
+Functions can accept following
 .I flags
 .TP
 .B O_NONBLOCK
@@ -95,10 +117,50 @@ couldn't allocate memory for given
 .I count
 and
 .I object_size
+.SH EXAMPLES
+.PP
+.EX
+.PP
+    #include <rb.h>
+    #include <stdio.h>
+
+    struct msg
+    {
+        int a;
+        int b;
+    };
+
+    int main(void)
+    {
+        struct msg msg;
+        struct rb *rb;
+        /* allocate memory on stack for rb header and 8 elements of msg */
+        unsigned char buf[rb_header_size() + 8 * sizeof(msg)];
+
+        /* initialize ring buffer with custom allocated memory */
+        rb = rb_init(8, sizeof(msg), 0, buf);
+
+        /* rb can be now accessed as usuall */
+
+        /* when work on rb is done, it needs to be cleaned up */
+        rb_cleanup(rb);
+
+        return 0;
+    }
+.EE
+.SH NOTES
+.PP
+Algorithm used in this buffer requires one element to be always empty to
+distinguish situations when buffer is full or empty and as such,
+.B rb
+object can effectively hold
+.I count
+- 1 elements in the buffer.
 .SH SEE ALSO
 .PP
 .BR rb_overview (7),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -108,4 +170,5 @@ and
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_overview.7 b/man/rb_overview.7
index 4dddea7..20f9415 100644
--- a/man/rb_overview.7
+++ b/man/rb_overview.7
@@ -25,11 +25,17 @@ size_t " count ");"
 .PP
 Additinal functions are provided for better control over buffer
 .PP
+.BI "struct rb *rb_init(size_t " count ", size_t " object_size ", \
+unsigned long " flags ", void *" mem ");"
+.br
+.BI "int rb_cleanup(struct rb *" rb ");"
+.br
 .BI "long rb_recv(struct rb *" rb ", void *" buffer ", size_t " count ", \
 unsigned long " flags ");"
 .br
 .BI "long rb_send(struct rb *" rb ", const void *" buffer ", \
 size_t " count ", unsigned long " flags ");"
+.br
 .BI "int rb_clear(struct rb *" rb ", int " clear ");"
 .br
 .BI "long rb_count(struct rb *" rb ");"
@@ -38,6 +44,8 @@ size_t " count ", unsigned long " flags ");"
 .br
 .BI "int rb_stop(struct rb *" rb ");"
 .br
+.B size_t rb_header_size(void);
+.br
 .BI "const char *rb_version(char *" major ", char *" minor ", char *" patch ");"
 .SH DESCRIPTION
 .PP
@@ -63,6 +71,10 @@ available.
 This behaviour can be altered to work in non-blocking mode, so calls from
 read and write will return immediately when there are not enough resources.
 malloc and free are called only in new and destory functions.
+You can also use buffer and provide own
+.I mem
+pointer to memory that buffer should work on (like so array on stack), in such
+case there will be no dynamic allocations performed by library.
 .PP
 As this library is focused on speed, user can create buffer with only power of
 two count (n^2).
@@ -121,7 +133,9 @@ Please note, that example is missing error handling for simplicity.
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -131,4 +145,5 @@ Please note, that example is missing error handling for simplicity.
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_read.3 b/man/rb_read.3
index f098c20..194e542 100644
--- a/man/rb_read.3
+++ b/man/rb_read.3
@@ -164,7 +164,9 @@ Returned only if threads are enabled.
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -174,4 +176,5 @@ Returned only if threads are enabled.
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_space.3 b/man/rb_space.3
index 8d41990..852cca3 100644
--- a/man/rb_space.3
+++ b/man/rb_space.3
@@ -32,7 +32,9 @@ object is invalid.
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -40,4 +42,5 @@ object is invalid.
 .BR rb_write (3),
 .BR rb_send (3),
 .BR rb_clear (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/man/rb_version.3 b/man/rb_version.3
index 37a7a4a..08213ae 100644
--- a/man/rb_version.3
+++ b/man/rb_version.3
@@ -36,7 +36,9 @@ Function returns pointer to statically allocated string with full version, like
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -45,4 +47,5 @@ Function returns pointer to statically allocated string with full version, like
 .BR rb_send (3),
 .BR rb_clear (3),
 .BR rb_count (3),
+.BR rb_header_size (3),
 .BR rb_space (3),
diff --git a/man/rb_write.3 b/man/rb_write.3
index c580315..71315a9 100644
--- a/man/rb_write.3
+++ b/man/rb_write.3
@@ -108,7 +108,9 @@ Returned only if threads are enabled.
 .PP
 .BR rb_overview (7),
 .BR rb_new (3),
+.BR rb_init (3),
 .BR rb_destroy (3),
+.BR rb_cleanup (3),
 .BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
@@ -116,4 +118,5 @@ Returned only if threads are enabled.
 .BR rb_clear (3),
 .BR rb_count (3),
 .BR rb_space (3),
+.BR rb_header_size (3),
 .BR rb_version (3)
diff --git a/readme.md b/readme.md
index b5ff23c..cb714a2 100644
--- a/readme.md
+++ b/readme.md
@@ -21,6 +21,10 @@ some more functions, it can be operated using 4 basic functions
 
 Additional functions are:
 
+  * [rb_init](http://librb.kurwinet.pl/manuals/rb_init.3.html) -
+    initializes new ring buffer but does not use dynamic allocation
+  * [rb_cleanup](http://librb.kurwinet.pl/manuals/rb_cleanup.3.html) -
+    cleans up whatever has been initialized with rb_init
   * [rb_recv](http://librb.kurwinet.pl/manuals/rb_recv.3.html) -
     reads from the ring buffer but also accepts flags
   * [rb_send](http://librb.kurwinet.pl/manuals/rb_send.3.html) -
@@ -35,6 +39,10 @@ Additional functions are:
     forces all threads to exit **rb_write** and **rb_read** functions
   * [rb_discard](http://librb.kurwinet.pl/manuals/rb_discard.3.html) -
     allows to quickly discard part of buffers data
+  * [rb_header_size](http://librb.kurwinet.pl/manuals/rb_header_size.3.html) -
+    get size of internal struct with buffer information
+  * [rb_version](http://librb.kurwinet.pl/manuals/rb_version.3.html) -
+    get version of library that is used
 
 Dependencies
 ============