psmq_subscribe(3)
bofc manual pages
psmq_subscribe(3)
NAME
psmq_subscribe, psmq_unsubscribe - control subscriptions for the client.
SYNOPSIS
#include <psmq.h>
int psmq_subscribe(struct psmq *psmq, const char *topic)
int psmq_unsubscribe(struct psmq *psmq, const char *topic)
DESCRIPTION
Once you connected to the broker you still won't be able to receive messages until you subscribe to something, as broker will send only messages that are interesting to you.
psmq_subscribe(3) allows you to tell the broker, you want to receive all messages that matches passed topic. You can read more about topics page psmq_overview(7) page. When subscribing, you can use wildcards.
psmq_unsubscribe(3) simply removes your client from given topic so you won't receive messages, that matches this topic anymore. This must be exact topic that was used in subscribe message, including wildcard. If you subscribed to "/can/engine/*", you have to use exacly same string to unsubsribe, you cannot unsubscribe from "/can/engine/rpm". If you need to receive all "/can/engine/*" messages except for "/can/engine/rpm", you need to either subscribe to all other topics one by one, or simply ignore "rpm" topic in you application.
EMBEDDED SYSTEM NOTES
Both psmq_subscribe(3) and psmq_unsubscribe(3) will cause broker to call malloc() and free(), respectively. Belive it or not, it's to save a lots of memory. Remember, it's not malloc() you should be afraid of, it's free(), so if you only subscribe at the beginning of program (and bootup in general) and then never unsubscribe, you don't have anything to worry about.
RETURN VALUE
0 on success. -1 on errors with appropriate errno set.
ERRORS
- EINVAL
- psmq or topic is NULL
- EBADF
- psmq object has no yet been initialized.
- EINVAL
- topic does not start from '/' character.
- ENOBUFS
- topic is too long and doesn't fit into transmit buffer. You need to recompile psmq with bigger PSMQ_MSG_MAX.
BUG REPORTING
Please, report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"
SEE ALSO
psmqd(1), psmq-pub(1), psmq-sub(1), psmq_cleanup(3), psmq_init(3), psmq_publish(3), psmq_receive(3), psmq_subscribe(3), psmq_timedreceive(3), psmq_timedreceive_ms(3), psmq_unsubscribe(3), psmq_building(7), psmq_overview(7).
19 May 2021 (v9999)
psmq_subscribe(3)