aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMichał Łyszczek <michal.lyszczek@bofc.pl>2021-05-20 21:50:17 +0200
committerMichał Łyszczek <michal.lyszczek@bofc.pl>2021-05-21 02:33:54 +0200
commite6fbeea04948ee1a86c298d9227cbad1946ee9dd (patch)
treee913f17f44abdfb6c3f4d1c0ab693111836c8db3
parentd4d3a8efc50023c42ea623b0377d49c446ac25df (diff)
downloadpsmq-e6fbeea04948ee1a86c298d9227cbad1946ee9dd.tar.gz
psmq-e6fbeea04948ee1a86c298d9227cbad1946ee9dd.tar.bz2
psmq-e6fbeea04948ee1a86c298d9227cbad1946ee9dd.zip
man: add documentation for ioctl
Signed-off-by: Michał Łyszczek <michal.lyszczek@bofc.pl>
-rw-r--r--man/psmq_ioctl.3118
-rw-r--r--man/psmq_ioctl_reply_timeout.3134
-rw-r--r--man/psmq_receive.316
3 files changed, 268 insertions, 0 deletions
diff --git a/man/psmq_ioctl.3 b/man/psmq_ioctl.3
new file mode 100644
index 0000000..ef7dc41
--- /dev/null
+++ b/man/psmq_ioctl.3
@@ -0,0 +1,118 @@
+.TH "psmq_ioctl" "3" "19 May 2021 (v0.2.0)" "bofc.pl"
+.SH NAME
+.PP
+.B psmq_ioctl
+- control broker behaviour for client.
+.SH SYNOPSIS
+.PP
+.BI "#include <psmq.h>"
+.PP
+.BI "int psmq_ioctl(struct psmq *" psmq ", int " req ", " ... ")"
+.SH DESCRIPTION
+.PP
+Controls broker behaviour for client
+.IR psmq .
+All ioctls can be called using
+.BR psmq_ioctl (3)
+function or function specific for ioctl - effects will be the same, just
+the call will be different.
+This page only shows all possible ioctls and its respective functions with
+very short overview.
+After successfull ioctl, broker will send
+.B PSMQ_CTRL_CMD_IOCTL
+message to
+.I psmq
+queue, with reply, be that success confirmation or error.
+Check proper ioctl function's man page for details.
+.TP
+.B PSMQ_IOCTL_REPLY_TIMEOUT
+.BR psmq_ioctl_reply_timeout (3)
+- Sets time in ms, how long broker will wait for
+.I psmq
+queue until it starts dropping messages in case queue is full.
+.SH "RETURN VALUE"
+.PP
+0 on success. -1 on errors with appropriate errno set.
+.SH ERRORS
+.TP
+.B EINVAL
+.I psmq
+is
+.B NULL
+.TP
+.B EBADF
+.I psmq
+has not yet been initialized
+.PP
+Additional errno can be returned by specific ioctl.
+.SH EXAMPLE
+Set reply timeout.
+.PP
+.nf
+ #include <psmq.h>
+
+ static int on_receive(struct psmq_msg *msg, char *topic,
+ unsigned char *payload, unsigned short paylen)
+ {
+ unsigned short timeout;
+
+ switch (msg->ctrl.cmd)
+ {
+ case PSMQ_CTRL_CMD_IOCTL:
+ /* payload[0] contains IOCTL number used in request,
+ * so you can perform different actions depending
+ * on response for different IOCTL */
+ switch (payload[0])
+ {
+ case PSMQ_IOCTL_REPLY_TIMEOUT:
+ memcpy(&timeout, payload + 1, sizeof(timeout));
+ fprintf(stder, "timeout set to %hu\\n", timeout);
+ return 0;
+ }
+ }
+ }
+
+ int main(void)
+ {
+ struct psmq psmq;
+ struct psmq_msg msg;
+
+ /* initialize psmq object that will create /sub mqueue for
+ * receiving data, and will connect to broker of name /brok.
+ * Max items in queue is set to 10 */
+ psmq_init(&psmq, "/brok", "/sub", 10);
+
+ /* set reply timeout with psmq_ioctl() function */
+ psmq_ioctl(&psmq, PSMQ_IOCTL_REPLY_TIMEOUT, 100);
+
+ /* every ioctl can also be called with dedicated function */
+ /* psmq_ioctl_reply_timeout(&psmq, 100); */
+
+ /* we will receive reply from broker for each ioctl sent */
+ psmq_receive(&psmq, &msg, NULL);
+ on_receive(&msg, PSMQ_TOPIC(msg), PSMQ_PAYLOAD(msg), msg.paylen);
+
+ /* after work is finished, we need to deregister from broker to
+ * make space in broker for another client */
+ psmq_cleanup(&psmq);
+ return 0;
+ }
+.nf
+.SH "BUG REPORTING"
+.PP
+Please, report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"
+.SH "SEE ALSO"
+.PP
+.BR psmqd (1),
+.BR psmq-pub (1),
+.BR psmq-sub (1),
+.BR psmq_cleanup (3),
+.BR psmq_init (3),
+.BR psmq_publish (3),
+.BR psmq_receive (3),
+.BR psmq_subscribe (3),
+.BR psmq_timedreceive (3),
+.BR psmq_timedreceive_ms (3),
+.BR psmq_unsubscribe (3),
+.BR psmq_building (7),
+.BR psmq_overview (7).
diff --git a/man/psmq_ioctl_reply_timeout.3 b/man/psmq_ioctl_reply_timeout.3
new file mode 100644
index 0000000..cda8ec7
--- /dev/null
+++ b/man/psmq_ioctl_reply_timeout.3
@@ -0,0 +1,134 @@
+.TH "psmq_ioctl_reply_timeout" "3" "19 May 2021 (v0.2.0)" "bofc.pl"
+.SH NAME
+.PP
+.B psmq_ioctl_reply_timeout
+- Sets time in ms, how long broker will wait for
+.I psmq
+queue until it starts dropping messages in case queue is full.
+.SH SYNOPSIS
+.PP
+.BI "#include <psmq.h>"
+.PP
+.BI "int psmq_ioctl_reply_timeout(struct psmq *" psmq ", unsigned short " val ")"
+.SH DESCRIPTION
+.PP
+When clients queue is full and broker is about to put a message on it, such
+message will be dropped immediately without hesitation.
+If you expect that incoming data will be received faster than you can
+process it, you can set how long broker shall wait for you to free up
+space on your queue.
+This time is specified in milliseconds.
+.PP
+Be advised though!
+If you set this to high value, broker will be stuck waiting for your client,
+other messages will not be processed by broker util it can deliver message
+for you!
+This can lead to situations where other clients won't be able to send data
+to broker as its queue can get full too when messages are not being processed.
+.SH "BROKER RESPONSE"
+.PP
+Response frame is
+.PP
+.nf
+ 0 1 3
+ +-----+---------+
+ | req | timeout |
+ +-----+---------+
+.fi
+.TP
+.I req
+This will always be
+.BR PSMQ_CTRL_CMD_IOCTL .
+.TP
+.I timeout
+timeout set in broker stored as unsigned short.
+.SH "RETURN VALUE"
+.PP
+Library function will return 0 on success and -1 on errors.
+On broker side this ioctl cannot fail,
+msg.data[0] will have PSMQ_IOCTL_REPLY_TIMEOUT value and
+msg.data[1:2] will contain set timeout.
+.SH ERRORS
+.TP
+.B EINVAL
+.I psmq
+is
+.B NULL
+or
+.I val
+is bigger than 65535.
+.TP
+.B EBADF
+.I psmq
+has not yet been initialized
+.SH EXAMPLE
+Set reply timeout.
+.PP
+.nf
+ #include <psmq.h>
+
+ static int on_receive(struct psmq_msg *msg, char *topic,
+ unsigned char *payload, unsigned short paylen)
+ {
+ unsigned short timeout;
+
+ switch (msg->ctrl.cmd)
+ {
+ case PSMQ_CTRL_CMD_IOCTL:
+ /* payload[0] contains IOCTL number used in request,
+ * so you can perform different actions depending
+ * on response for different IOCTL */
+ switch (payload[0])
+ {
+ case PSMQ_IOCTL_REPLY_TIMEOUT:
+ memcpy(&timeout, payload + 1, sizeof(timeout));
+ fprintf(stder, "timeout set to %hu\\n", timeout);
+ return 0;
+ }
+ }
+ }
+
+ int main(void)
+ {
+ struct psmq psmq;
+ struct psmq_msg msg;
+
+ /* initialize psmq object that will create /sub mqueue for
+ * receiving data, and will connect to broker of name /brok.
+ * Max items in queue is set to 10 */
+ psmq_init(&psmq, "/brok", "/sub", 10);
+
+ /* set reply timeout with psmq_ioctl() function */
+ psmq_ioctl(&psmq, PSMQ_IOCTL_REPLY_TIMEOUT, 100);
+
+ /* every ioctl can also be called with dedicated function */
+ /* psmq_ioctl_reply_timeout(&psmq, 100); */
+
+ /* we will receive reply from broker for each ioctl sent */
+ psmq_receive(&psmq, &msg, NULL);
+ on_receive(&msg, PSMQ_TOPIC(msg), PSMQ_PAYLOAD(msg), msg.paylen);
+
+ /* after work is finished, we need to deregister from broker to
+ * make space in broker for another client */
+ psmq_cleanup(&psmq);
+ return 0;
+ }
+.fi
+.SH "BUG REPORTING"
+.PP
+Please, report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"
+.SH "SEE ALSO"
+.PP
+.BR psmqd (1),
+.BR psmq-pub (1),
+.BR psmq-sub (1),
+.BR psmq_cleanup (3),
+.BR psmq_init (3),
+.BR psmq_publish (3),
+.BR psmq_receive (3),
+.BR psmq_subscribe (3),
+.BR psmq_timedreceive (3),
+.BR psmq_timedreceive_ms (3),
+.BR psmq_unsubscribe (3),
+.BR psmq_building (7),
+.BR psmq_overview (7).
diff --git a/man/psmq_receive.3 b/man/psmq_receive.3
index f400b7d..d1da445 100644
--- a/man/psmq_receive.3
+++ b/man/psmq_receive.3
@@ -56,6 +56,9 @@ Unsubscribe confirmation has been received.
.TP
.B PSMQ_CTRL_CMD_CLOSE
Broker closed connection with the client.
+.TP
+.B PSMQ_CTRL_CMD_IOCTL
+Response from the broker for ioctl request.
.PP
.IR ctrl . data
is a response status of received message.
@@ -96,6 +99,19 @@ is bigger than 0, otherwise you risk getting
.B SIGSEGV
from OS.
.PP
+When
+.IR ctrl . data
+is
+.B PSMQ_CTRL_CMD_IOCTL
+then
+.I data
+will not contain topic but first byte will be ioctl request number
+and all of the following bytes are ioctl specific.
+In general all of reponses from ioctl will require custom parsing.
+Check
+.BR psmq_ioctl (3)
+for all possible ioctls.
+.PP
.I paylen
Length of payload part in
.IR data .