diff --git a/doc/man1/Makefile.am b/doc/man1/Makefile.am index dc4661ca696a..0ab587f1d1c1 100644 --- a/doc/man1/Makefile.am +++ b/doc/man1/Makefile.am @@ -22,7 +22,8 @@ MAN1_FILES_PRIMARY = \ flux-hwloc.1 \ flux-proxy.1 \ flux-cron.1 \ - flux-user.1 + flux-user.1 \ + flux-event.1 # These files are generated as roff .so includes of a primary page. # A2X handles this automatically if mentioned in NAME section diff --git a/doc/man1/flux-event.adoc b/doc/man1/flux-event.adoc new file mode 100644 index 000000000000..94f9218da907 --- /dev/null +++ b/doc/man1/flux-event.adoc @@ -0,0 +1,60 @@ +// flux-help-include: true +FLUX-EVENT(1) +============= +:doctype: manpage + + +NAME +---- +flux-event - Send and receive Flux events + + +SYNOPSIS +-------- +*flux* *event* 'COMMAND' ['OPTIONS'] + + +DESCRIPTION +----------- +Flux events are messages that are broadcast throughout the Flux instance +with publish/subscribe semantics. Each event message has a _topic string_ +and an optional _payload_. + +Subscriptions are by topic string. A subscription topic of length _N_ +matches an event if the first _N_ characters of the event topic +are identical to that of the subscription. For example the event topic +'a.b.c' is matched by the subscription topic 'a.b.c', 'a.b', or 'a'. +A subscription to the empty string matches all events. + +COMMANDS +-------- +*pub* [-r] [-l] 'topic' ['payload']:: +Publish an event with optional payload. If payload is specified, +it is interpreted as raw if the '-r' option is used, otherwise it is +interpreted as JSON. If the payload spans multiple arguments, +the arguments are concatenated with one space between them. +If '-l' is specified, subscribe to the published event and wait for +it to be received before exiting. + +*sub* '[-c N]' ['topic'] ['topic'...]:: +Subscribe to events matching the topic string(s) provided on the +command line. If none are specified, subscribe to all events. +If '-c N' is specified, print the first 'N' events on stdout and exit; +otherwise continue printing events until a signal is received. +Events are displayed one per line: the topic string, followed by a tab, +followed by the payload, if any. + + +AUTHOR +------ +This page is maintained by the Flux community. + + +RESOURCES +--------- +Github: + + +COPYRIGHT +--------- +include::COPYRIGHT.adoc[]