add: documentation to new function

11 files changed, 75 insertions, 0 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index f827035..8816e97 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,6 +1,7 @@
 man_MANS = rb_clear.3 \
 		   rb_count.3 \
 		   rb_destroy.3 \
+		   rb_discard.3 \
 		   rb_new.3 \
 		   rb_overview.7 \
 		   rb_read.3 \
diff --git a/man/rb_clear.3 b/man/rb_clear.3
index 66d03b4..0df73a2 100644
--- a/man/rb_clear.3
+++ b/man/rb_clear.3
@@ -35,6 +35,7 @@ is invalid (null).
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_destroy.3 b/man/rb_destroy.3
index 58107b0..8876a1d 100644
--- a/man/rb_destroy.3
+++ b/man/rb_destroy.3
@@ -121,6 +121,7 @@ is invalid (null).
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_read (3),
+.BR rb_discard (3),
 .BR rb_recv (3),
 .BR rb_write (3),
 .BR rb_send (3),
diff --git a/man/rb_discard.3 b/man/rb_discard.3
new file mode 100644
index 0000000..040b6f7
--- /dev/null
+++ b/man/rb_discard.3
@@ -0,0 +1,64 @@
+.TH "rb_discard" "3" "25 January 2018 (v2.1.2)" "bofc.pl"
+.SH
+.PP
+.B rb_discard
+- allows to quickly discard part of buffer
+.SH SYNOPSIS
+.PP
+.BI "int rb_discard(struct rb *" rb ", size_t " count ");"
+.SH DESCRIPTION
+.PP
+Function
+.BR rb_discard(3)
+will remove
+.I count
+elements from
+.I rb
+buffer.
+This functions is very similar to calling
+.BR rb_read (3)
+and then discarding buffer, but this function is much better because when
+discarding with
+.BR rb_discard (3)
+there is no copying involved, so it's much faster.
+You can pass more
+.I count
+then there is in the buffer.
+Function never blocks calling thread.
+.PP
+Note, it is very difficult to discard data in multi-threaded environment with
+more than one reader per se.
+Thus it is inadvisible to use this function when there are two or more readers
+using same
+.I rb
+object.
+.SH RETURN VALUES
+.PP
+Function will return number of elements actually discarded fomr buffer. It is
+ok for function to return less elements than it was passed in
+.I count
+variable.
+This means there was less elements in
+.I rb
+than requested to be discarded.
+On errors -1 is returned.
+.SH ERRORS
+.PP
+.TP
+.B EINVAL
+.I rb
+is not a valid object.
+.SH SEE ALSO
+.PP
+.BR rb_overview (7),
+.BR rb_new (3),
+.BR rb_destroy (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_new.3 b/man/rb_new.3
index 2dc945d..c34df0f 100644
--- a/man/rb_new.3
+++ b/man/rb_new.3
@@ -99,6 +99,7 @@ and
 .PP
 .BR rb_overview (7),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_overview.7 b/man/rb_overview.7
index 2469616..f6581cd 100644
--- a/man/rb_overview.7
+++ b/man/rb_overview.7
@@ -122,6 +122,7 @@ Please note, that example is missing error handling for simplicity.
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_read.3 b/man/rb_read.3
index 3505599..0b701bd 100644
--- a/man/rb_read.3
+++ b/man/rb_read.3
@@ -165,6 +165,7 @@ Returned only if threads are enabled.
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_space.3 b/man/rb_space.3
index 71dab9f..7f8f113 100644
--- a/man/rb_space.3
+++ b/man/rb_space.3
@@ -26,6 +26,7 @@ you can put on the buffer.
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_version.3 b/man/rb_version.3
index ea4452a..d8f7e0d 100644
--- a/man/rb_version.3
+++ b/man/rb_version.3
@@ -37,6 +37,7 @@ Function returns pointer to statically allocated string with full version, like
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/man/rb_write.3 b/man/rb_write.3
index 05957da..cef1e19 100644
--- a/man/rb_write.3
+++ b/man/rb_write.3
@@ -109,6 +109,7 @@ Returned only if threads are enabled.
 .BR rb_overview (7),
 .BR rb_new (3),
 .BR rb_destroy (3),
+.BR rb_discard (3),
 .BR rb_stop (3),
 .BR rb_read (3),
 .BR rb_recv (3),
diff --git a/readme.md b/readme.md
index 048e89a..ab8b3fd 100644
--- a/readme.md
+++ b/readme.md
@@ -33,6 +33,8 @@ Additional functions are:
     returns number of free space for number of elements
   * [rb_stop](http://librb.kurwinet.pl/manuals/rb_stop.3.html) -
     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
 
 Dependencies
 ============