.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "REMCTL_OUTPUT 3"
.TH REMCTL_OUTPUT 3 "2022-05-09" "3.18" "remctl Library Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
remctl_output \- Retrieve the results of a remctl command
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
#include <remctl.h>
.PP
struct remctl_output *\fBremctl_output\fR(struct remctl *\fIr\fR);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBremctl_output()\fR retrieves the next output token from the remote remctl
server.  \fIr\fR is a remctl client object created with \fBremctl_new()\fR, which
should have previously been used as the argument to \fBremctl_open()\fR and then
either \fBremctl_command()\fR or \fBremctl_commandv()\fR.
.PP
The returned remctl_output struct has the following members:
.PP
.Vb 8
\&    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. */
\&    };
.Ve
.PP
where the type field will have one of the following values:
.PP
.Vb 4
\&    REMCTL_OUT_OUTPUT
\&    REMCTL_OUT_STATUS
\&    REMCTL_OUT_ERROR
\&    REMCTL_OUT_DONE
.Ve
.PP
A command rejected by the remctl server will return a single output token
of type \s-1REMCTL_OUT_ERROR.\s0  A successful command will return zero or more
\&\s-1REMCTL_OUT_OUTPUT\s0 tokens representing the output of the command followed
by a \s-1REMCTL_OUT_STATUS\s0 token giving the exit status of the command.
Therefore, for each command issued, the caller should call
\&\fBremctl_command()\fR or \fBremctl_commandv()\fR and then call \fBremctl_output()\fR
repeatedly to retrieve each output token until \fBremctl_output()\fR returns a
token of type \s-1REMCTL_OUT_ERROR\s0 or \s-1REMCTL_OUT_STATUS.\s0
.PP
A \s-1REMCTL_OUT_OUTPUT\s0 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.
.PP
A \s-1REMCTL_OUT_STATUS\s0 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.
.PP
A \s-1REMCTL_OUT_ERROR\s0 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.
.PP
If \fBremctl_output()\fR is called when there is no pending output from the
remote server (after a \s-1REMCTL_OUT_ERROR\s0 or \s-1REMCTL_OUT_STATUS\s0 token has
already been returned, for example), a token of type \s-1REMCTL_OUT_DONE\s0 will
be returned.  \s-1REMCTL_OUT_DONE\s0 tokens do not use any of the other fields of
the remctl_output struct.
.PP
The returned remctl_output struct must not be freed by the caller.  It
will be invalidated on any subsequent call to any other remctl \s-1API\s0
function other than \fBremctl_error()\fR 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 \s-1API\s0 calls.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
\&\fBremctl_output()\fR returns a pointer to a remctl_output struct on success and
\&\s-1NULL\s0 on failure.  On failure, the caller should call \fBremctl_error()\fR to
retrieve the error message.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery <eagle@eyrie.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior
University
.PP
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.
.PP
SPDX-License-Identifier: \s-1FSFAP\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBremctl_new\fR\|(3), \fBremctl_open\fR\|(3), \fBremctl_command\fR\|(3), \fBremctl_commandv\fR\|(3),
\&\fBremctl_error\fR\|(3)
.PP
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/>.