Merge 299097c into bf59bee

doc/man3/Makefile.am

@@ -103,6 +103,7 @@ MAN3_FILES_SECONDARY = \
 	flux_stat_watcher_get_rstat.3 \
 	flux_respond_raw.3 \
 	flux_respond_pack.3 \
+	flux_respond_error.3 \
 	flux_reactor_now_update.3 \
 	flux_request_unpack.3 \
 	flux_request_decode_raw.3 \
@@ -112,6 +113,7 @@ MAN3_FILES_SECONDARY = \
 	flux_event_encode_raw.3 \
 	flux_event_decode_raw.3 \
 	flux_response_decode_raw.3 \
+	flux_response_decode_error.3 \
 	flux_request_encode_raw.3 \
 	flux_content_load_get.3 \
 	flux_content_store.3 \
@@ -135,6 +137,7 @@ MAN3_FILES_SECONDARY = \
 	flux_rpc_get.3 \
 	flux_rpc_get_unpack.3 \
 	flux_rpc_get_raw.3 \
+	flux_rpc_get_error.3 \
 	flux_kvs_lookupat.3 \
 	flux_kvs_lookup_get.3 \
 	flux_kvs_lookup_get_unpack.3 \
@@ -231,6 +234,7 @@ flux_signal_watcher_get_signum.3: flux_signal_watcher_create.3
 flux_stat_watcher_get_rstat.3: flux_stat_watcher_create.3
 flux_respond_raw.3: flux_respond.3
 flux_respond_pack.3: flux_respond.3
+flux_respond_error.3: flux_respond.3
 flux_reactor_now_update.3: flux_reactor_now.3
 flux_request_unpack.3: flux_request_decode.3
 flux_request_decode_raw.3: flux_request_decode.3
@@ -240,6 +244,7 @@ flux_event_pack.3: flux_event_decode.3
 flux_event_encode_raw.3: flux_event_decode.3
 flux_event_decode_raw.3: flux_event_decode.3
 flux_response_decode_raw.3: flux_response_decode.3
+flux_response_decode_error.3: flux_response_decode.3
 flux_request_encode_raw.3: flux_request_encode.3
 flux_content_load_get.3: flux_content_load.3
 flux_content_store.3: flux_content_load.3
@@ -262,6 +267,7 @@ flux_rpc_raw.3: flux_rpc.3
 flux_rpc_get.3: flux_rpc.3
 flux_rpc_get_unpack.3: flux_rpc.3
 flux_rpc_get_raw.3: flux_rpc.3
+flux_rpc_get_error.3: flux_rpc.3
 flux_kvs_lookupat.3: flux_kvs_lookup.3
 flux_kvs_lookup_get.3: flux_kvs_lookup.3
 flux_kvs_lookup_get_unpack.3: flux_kvs_lookup.3

doc/man3/flux_event_decode.adoc

@@ -14,7 +14,7 @@ SYNOPSIS
 
  int flux_event_decode (const flux_msg_t *msg,
                         const char **topic,
-                        const char **json_str);
+                        const char **s);
 
  int flux_event_decode_raw (const flux_msg_t *msg,
                             const char **topic,
@@ -25,7 +25,7 @@ SYNOPSIS
                         const char *fmt, ...);
 
  flux_msg_t *flux_event_encode (const char *topic,
-                                const char *json_str);
+                                const char *s);
 
  flux_msg_t *flux_event_encode_raw (const char *topic,
                                     const void *data, int len);
@@ -42,9 +42,9 @@ DESCRIPTION
 _topic_, if non-NULL, will be set to the message's topic string. The storage
 for this string belongs to _msg_ and should not be freed.
 
-_json_str_, if non-NULL, will be set to the message's JSON payload. If
-no payload exists, _json_str_ is set to NULL.  The storage for this
-string belongs to _msg_ and should not be freed.
+_s_, if non-NULL, will be set to the message's NULL-terminated string payload.
+If no payload exists, it is set to NULL.  The storage for this string belongs
+to _msg_ and should not be freed.
 
 `flux_event_decode_raw()` decodes an event message with a raw payload,
 setting _data_ and _len_ to the payload data and length.  The storage for
@@ -56,8 +56,8 @@ in the style of jansson's `json_unpack()` (used internally). Decoding fails
 if the message doesn't have a JSON payload.
 
 `flux_event_encode()` encodes a Flux event message with topic string _topic_
-and optional JSON payload _json_str_.  The newly constructed message that
-is returned must be destroyed with `flux_msg_destroy()`.
+and optional NULL-terminated string payload _s_.  The newly constructed
+message that is returned must be destroyed with `flux_msg_destroy()`.
 
 `flux_event_encode_raw()` encodes a Flux event message with topic
 string _topic_.  If _data_ is non-NULL, its contents will be used as

doc/man3/flux_event_publish.adoc

@@ -14,24 +14,24 @@ SYNOPSIS
 
  flux_future_t *flux_event_publish (flux_t *h,
                                     const char *topic, int flags,
-                                    const char *json_str);
- 
+                                    const char *s);
+
  flux_future_t *flux_event_publish_pack (flux_t *h,
                                          const char *topic, int flags,
                                          const char *fmt, ...);
- 
+
  flux_future_t *flux_event_publish_raw (flux_t *h,
                                         const char *topic, int flags,
                                         const void *data, int len);
- 
+
  int flux_event_publish_get_seq (flux_future_t *f, int *seq);
 
 DESCRIPTION
 -----------
 
 `flux_event_publish()` sends an event message with topic string _topic_,
-_flags_ as described below, and optional payload _json_str_, a string-encoded
-JSON object or NULL indicating no payload.  The returned future is
+_flags_ as described below, and optional payload _s_, a NULL-terminated
+string, or NULL indicating no payload.  The returned future is
 fulfilled once the event is accepted by the broker and assigned a
 global sequence number.
 

doc/man3/flux_mrpc.adoc

@@ -12,13 +12,13 @@ SYNOPSIS
 --------
 #include <flux/core.h>
 
-flux_mrpc_t *flux_mrpc (flux_t *h, const char *topic, const char *json_str,
+flux_mrpc_t *flux_mrpc (flux_t *h, const char *topic, const char *s,
                         const char *nodeset, int flags);
 
 flux_mrpc_t *flux_mrpc_pack (flux_t *h, const char *topic, const char *nodeset,
                              int flags, const char *fmt, ...);
 
-int flux_mrpc_get (flux_mrpc_t *mrpc, const char **json_str);
+int flux_mrpc_get (flux_mrpc_t *mrpc, const char **s);
 
 int flux_mrpc_get_unpack (flux_mrpc_t *mrpc, const char *fmt, ...);
 

doc/man3/flux_request_decode.adoc

@@ -14,7 +14,7 @@ SYNOPSIS
 
  int flux_request_decode (const flux_msg_t *msg,
                           const char **topic,
-                          const char **json_str);
+                          const char **s);
 
  int flux_request_unpack (const flux_msg_t *msg,
                           const char **topic,
@@ -32,9 +32,9 @@ DESCRIPTION
 _topic_, if non-NULL, will be set the message's topic string. The storage
 for this string belongs to _msg_ and should not be freed.
 
-_json_str_, if non-NULL, will be set to the message's JSON payload.
-If no payload exists, _json_str_ is set to NULL.  The storage for this
-string belongs to _msg_ and should not be freed.
+_s_, if non-NULL, will be set to the message's NULL-terminated string payload.
+If no payload exists, it is set to NULL.  The storage for this string belongs
+to _msg_ and should not be freed.
 
 `flux_request_unpack()` decodes a request message with a JSON payload as
 above, parsing the payload using variable arguments with a format string

doc/man3/flux_request_encode.adoc

@@ -13,7 +13,7 @@ SYNOPSIS
  #include <flux/core.h>
 
  flux_msg_t *flux_request_encode (const char *topic,
-                                  const char *json_str);
+                                  const char *s);
 
  flux_msg_t *flux_request_encode_raw (const char *topic,
                                       void *data, int len);
@@ -22,7 +22,7 @@ DESCRIPTION
 -----------
 
 `flux_request_encode()` encodes a request message with topic string
-_topic_ and optional JSON payload _json_str_.  The newly constructed
+_topic_ and optional NULL terminated string payload _s_.  The newly constructed
 message that is returned must be destroyed with `flux_msg_destroy()`.
 
 `flux_request_encode_raw()` encodes a request message with topic
@@ -41,7 +41,7 @@ ERRORS
 ------
 
 EINVAL::
-The _topic_ argument was NULL or _json_str_ is not a json object.
+The _topic_ argument was NULL or _s_ is not NULL terminated.
 
 ENOMEM::
 Memory was unavailable.

doc/man3/flux_respond.adoc

@@ -5,42 +5,51 @@ flux_respond(3)
 
 NAME
 ----
-flux_respond, flux_respond_pack, flux_respond_raw - respond to a request
+flux_respond, flux_respond_pack, flux_respond_raw, flux_respond_error - respond to a request
 
 
 SYNOPSIS
 --------
  #include <flux/core.h>
 
  int flux_respond (flux_t *h, const flux_msg_t *request,
-                   int errnum, const char *json_str);
+                   int errnum, const char *s);
 
  int flux_respond_pack (flux_t *h, const flux_msg_t *request,
                         const char *fmt, ...);
 
  int flux_respond_raw (flux_t *h, const flux_msg_t *request,
                        int errnum, const void *data, int length);
 
+ int flux_respond_error (flux_t *h, const flux_msg_t *request,
+                         int errnum, const char *fmt, ...);
 
 DESCRIPTION
 -----------
 
-`flux_respond()`, `flux_respond_pack()`, and `flux_respond_raw()` encode
-and send a response message on handle _h_, deriving topic string,
-matchtag, and route stack from the provided _request_.
+`flux_respond()`, `flux_respond_pack()`, `flux_respond_raw()`, and
+`flux_respond_error()`  encode and send a response message on handle _h_,
+deriving topic string, matchtag, and route stack from the provided
+_request_.
 
-If _errnum_ is non-zero, an error is returned to the sender such that
-`flux_rpc_get(3)` or `flux_rpc_get_raw(3)` will fail, with the system
-errno set to _errnum_.  Any payload arguments are ignored in this case.
+`flux_respond()` can operate in two modes.  If _errnum_ is non-zero,
+an error is returned to the sender such that `flux_rpc_get(3)` or
+variants will fail, with the system errno set to _errnum_.  Any payload
+arguments are ignored in this case.
 
-If _json_str_ is non-NULL, `flux_respond()` will send it as the response
+If _s_ is non-NULL, `flux_respond()` will send it as the response
 payload, otherwise there will be no payload.  Similarly, if _data_ is
 non-NULL, `flux_respond_raw()` will send it as the response payload.
 
 `flux_respond_pack()` encodes a response message with a JSON payload,
 building the payload using variable arguments with a format string in
 the style of jansson's `json_pack()` (used internally).
 
+`flux_respond_error()` returns an error response to the sender.
+_errnum_ must be non-zero.  If _fmt_ is non-NULL, an error string
+payload is included in the response, constructed using printf(3)-style
+arguments.  The error string may be used to provide a more
+detailed error message than can be conveyed via _errnum_.
 
 include::JSON_PACK.adoc[]
 

doc/man3/flux_response_decode.adoc

@@ -5,7 +5,7 @@ flux_response_decode(3)
 
 NAME
 ----
-flux_response_decode, flux_response_decode_raw - decode a Flux response message
+flux_response_decode, flux_response_decode_raw, flux_response_decode_error - decode a Flux response message
 
 
 SYNOPSIS
@@ -14,12 +14,16 @@ SYNOPSIS
 
  int flux_response_decode (const flux_msg_t *msg,
                            const char **topic,
-                           const char **json_str);
+                           const char **s);
 
  int flux_response_decode_raw (const flux_msg_t *msg,
                                const char **topic,
                                const void **data, int *len);
 
+ int flux_response_decode_error (const flux_msg_t *msg,
+                                 const char *errstr);
+
+
 DESCRIPTION
 -----------
 
@@ -28,14 +32,18 @@ DESCRIPTION
 _topic_, if non-NULL, will be set to the message's topic string. The
 storage for this string belongs to _msg_ and should not be freed.
 
-_json_str_, if non-NULL, will be set to the message's JSON payload.
-If no payload exists, _json_str_ is set to NULL.  The storage for this
+_s_, if non-NULL, will be set to the message's NULL-terminated string payload.
+If no payload exists, it is set to NULL.  The storage for this
 string belongs to _msg_ and should not be freed.
 
 `flux_response_decode_raw()` decodes a response message with a raw payload,
 setting _data_ and _len_ to the payload data and length. The storage for
 the raw payload belongs to _msg_ and should not be freed.
 
+`flux_response_decode_error()` decodes an optional error string included
+with an error response.  This fails if the response is not an error,
+or does not include an error string payload.
+
 
 RETURN VALUE
 ------------
@@ -54,6 +62,10 @@ EPROTO::
 Message decoding failed, such as due to incorrect message type,
 missing topic string, etc..
 
+ENOENT::
+`flux_response_decode_error()` was called on a message with no
+error response payload.
+
 
 AUTHOR
 ------

doc/man3/flux_rpc.adoc

@@ -5,15 +5,15 @@ flux_rpc(3)
 
 NAME
 ----
-flux_rpc, flux_rpc_pack, flux_rpc_raw, flux_rpc_get, flux_rpc_get_unpack, flux_rpc_get_raw - perform a remote procedure call to a Flux service
+flux_rpc, flux_rpc_pack, flux_rpc_raw, flux_rpc_get, flux_rpc_get_unpack, flux_rpc_get_raw, flux_rpc_get_error - perform a remote procedure call to a Flux service
 
 
 SYNOPSIS
 --------
  #include <flux/core.h>
 
  flux_future_t *flux_rpc (flux_t *h, const char *topic,
-                          const char *json_str,
+                          const char *s,
                           uint32_t nodeid, int flags);
 
  flux_future_t *flux_rpc_pack (flux_t *h, const char *topic,
@@ -24,13 +24,14 @@ SYNOPSIS
                               const void *data, int len,
                               uint32_t nodeid, int flags);
 
- int flux_rpc_get (flux_future_t *f, const char **json_str);
+ int flux_rpc_get (flux_future_t *f, const char **s);
 
  int flux_rpc_get_unpack (flux_future_t *f, const char *fmt, ...);
 
  int flux_rpc_get_raw (flux_future_t *f,
                        const void **data, int *len);
 
+ const char *flux_rpc_get_error (flux_future_t *f);
 
 DESCRIPTION
 -----------
@@ -54,18 +55,24 @@ to access the response message stored in the future.  If the response
 message has not yet been received, these functions block until it is,
 or an error occurs.
 
+`flux_rpc_get_error()` returns an error string explaining the reason
+for a failure.  Its return value is never NULL.  If the remote service
+included a textual error string in the response, that is returned.
+Otherwise flux_strerror(3) provides the string based on the error
+number received in the response.
+
 
 REQUEST OPTIONS
 ---------------
 
 The request message is encoded and sent with or without a payload
 using one of the three `flux_rpc()` variants.
 
-`flux_rpc()` attaches _json_str_, a serialized JSON string, as request
+`flux_rpc()` attaches _s_, a NULL terminated string, as request
 payload.  If NULL, the request is encoded without a payload.
 
-`flux_rpc_pack()` attaches a JSON payload encoded using Jansson
-`json_pack()` style arguments (see below).
+`flux_rpc_pack()` attaches a JSON payload encoded as a NULL terminated
+string using Jansson `json_pack()` style arguments (see below).
 
 `flux_rpc_raw()` attaches a raw payload _data_ of length _len_, in bytes.
 If _data_ is NULL, the request is encoded without a payload.
@@ -100,13 +107,13 @@ with an error.  Otherwise it is fulfilled with the response message.
 If there was an error, `flux_future_get()` or the `flux_rpc_get()` variants
 return an error.
 
-`flux_rpc_get()` sets _json_str_ (if non-NULL) to the serialized JSON
-payload contained in the RPC response.  If there was no payload, _json_str_
+`flux_rpc_get()` sets _s_ (if non-NULL) to the NULL-terminated string
+payload contained in the RPC response.  If there was no payload, _s_
 is set to NULL.
 
-`flux_rpc_get_unpack()` decodes the JSON payload using Jansson `json_unpack()`
-style arguments (see below).  It is an error if there is no payload, or if
-the payload is not JSON.
+`flux_rpc_get_unpack()` decodes the NULL-terminated string payload as JSON
+using Jansson `json_unpack()` style arguments (see below).  It is an error
+if there is no payload, or if the payload is not JSON.
 
 `flux_rpc_get_raw()` assigns the raw payload of the RPC response message
 to _data_ and its length to _len_.  If there is no payload, this function

doc/test/spell.en.pws

@@ -424,3 +424,4 @@ hostlist
 hostnames
 unfulfills
 MSGFLAG
+errstr