NAME

       remctl_output - Retrieve the results of a remctl command

SYNOPSIS

       #include <remctl.h>

       struct remctl_output *remctl_output(struct remctl *r);

DESCRIPTION

       remctl_output() retrieves the next output token from the remote remctl server.  r is a
       remctl client object created with remctl_new(), which should have previously been used as
       the argument to remctl_open() and then either remctl_command() or remctl_commandv().

       The returned remctl_output struct has the following members:

           struct remctl_output {
               enum remctl_output_type type;
               char *data;
               size_t length;
               int stream;                 /* 1 == stdout, 2 == stderr */
               int status;                 /* Exit status of remote command. */
               int error;                  /* Remote error code. */
           };

       where the type field will have one of the following values:

           REMCTL_OUT_OUTPUT
           REMCTL_OUT_STATUS
           REMCTL_OUT_ERROR
           REMCTL_OUT_DONE

       A command rejected by the remctl server will return a single output token of type
       REMCTL_OUT_ERROR.  A successful command will return zero or more REMCTL_OUT_OUTPUT tokens
       representing the output of the command followed by a REMCTL_OUT_STATUS token giving the
       exit status of the command.  Therefore, for each command issued, the caller should call
       remctl_command() or remctl_commandv() and then call remctl_output() repeatedly to retrieve
       each output token until remctl_output() returns a token of type REMCTL_OUT_ERROR or
       REMCTL_OUT_STATUS.

       A REMCTL_OUT_OUTPUT token will have data in the data field, whose length is given by the
       length field.  The output stream will be given by the stream field, with a value of 1
       indicating standard output and a value of 2 indicating standard error.  All other stream
       values are reserved for future use.

       A REMCTL_OUT_STATUS token will hold the exit status of the remote command in the status
       field.  Following the standard Unix convention, a 0 status should normally be considered
       success and any non-zero status should normally be considered failure, although a given
       command may have its own exit status conventions.

       A REMCTL_OUT_ERROR token will have the error message from the server in the data field
       (with length stored in length) and the protocol error code in the error field.  The latter
       is the most reliable indicator of the error; the message stored in the error field is
       free-form text, may or may not be localized, and should not be used for programmatic
       comparisons.  For the possible error code values and their meanings, see the remctl
       protocol specification.

       If remctl_output() is called when there is no pending output from the remote server (after
       a REMCTL_OUT_ERROR or REMCTL_OUT_STATUS token has already been returned, for example), a
       token of type REMCTL_OUT_DONE will be returned.  REMCTL_OUT_DONE tokens do not use any of
       the other fields of the remctl_output struct.

       The returned remctl_output struct must not be freed by the caller.  It will be invalidated
       on any subsequent call to any other remctl API function other than remctl_error() on the
       same remctl client object; the caller should therefore copy out of the remctl_output
       struct any data it wishes to preserve before making any subsequent remctl API calls.

RETURN VALUE

       remctl_output() returns a pointer to a remctl_output struct on success and NULL on
       failure.  On failure, the caller should call remctl_error() to retrieve the error message.

AUTHOR

       Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

       Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior University

       Copying and distribution of this file, with or without modification, are permitted in any
       medium without royalty provided the copyright notice and this notice are preserved.  This
       file is offered as-is, without any warranty.

       SPDX-License-Identifier: FSFAP

SEE ALSO

       remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3), remctl_error(3)

       The current version of the remctl library and complete details of the remctl protocol are
       available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>.