1REMCTL_OUTPUT(3)           remctl Library Reference           REMCTL_OUTPUT(3)
2
3
4

NAME

6       remctl_output - Retrieve the results of a remctl command
7

SYNOPSIS

9       #include <remctl.h>
10
11       struct remctl_output *remctl_output(struct remctl *r);
12

DESCRIPTION

14       remctl_output() retrieves the next output token from the remote remctl
15       server.  r is a remctl client object created with remctl_new(), which
16       should have previously been used as the argument to remctl_open() and
17       then either remctl_command() or remctl_commandv().
18
19       The returned remctl_output struct has the following members:
20
21           struct remctl_output {
22               enum remctl_output_type type;
23               char *data;
24               size_t length;
25               int stream;                 /* 1 == stdout, 2 == stderr */
26               int status;                 /* Exit status of remote command. */
27               int error;                  /* Remote error code. */
28           };
29
30       where the type field will have one of the following values:
31
32           REMCTL_OUT_OUTPUT
33           REMCTL_OUT_STATUS
34           REMCTL_OUT_ERROR
35           REMCTL_OUT_DONE
36
37       A command rejected by the remctl server will return a single output
38       token of type REMCTL_OUT_ERROR.  A successful command will return zero
39       or more REMCTL_OUT_OUTPUT tokens representing the output of the command
40       followed by a REMCTL_OUT_STATUS token giving the exit status of the
41       command.  Therefore, for each command issued, the caller should call
42       remctl_command() or remctl_commandv() and then call remctl_output()
43       repeatedly to retrieve each output token until remctl_output() returns
44       a token of type REMCTL_OUT_ERROR or REMCTL_OUT_STATUS.
45
46       A REMCTL_OUT_OUTPUT token will have data in the data field, whose
47       length is given by the length field.  The output stream will be given
48       by the stream field, with a value of 1 indicating standard output and a
49       value of 2 indicating standard error.  All other stream values are
50       reserved for future use.
51
52       A REMCTL_OUT_STATUS token will hold the exit status of the remote
53       command in the status field.  Following the standard Unix convention, a
54       0 status should normally be considered success and any non-zero status
55       should normally be considered failure, although a given command may
56       have its own exit status conventions.
57
58       A REMCTL_OUT_ERROR token will have the error message from the server in
59       the data field (with length stored in length) and the protocol error
60       code in the error field.  The latter is the most reliable indicator of
61       the error; the message stored in the error field is free-form text, may
62       or may not be localized, and should not be used for programmatic
63       comparisons.  For the possible error code values and their meanings,
64       see the remctl protocol specification.
65
66       If remctl_output() is called when there is no pending output from the
67       remote server (after a REMCTL_OUT_ERROR or REMCTL_OUT_STATUS token has
68       already been returned, for example), a token of type REMCTL_OUT_DONE
69       will be returned.  REMCTL_OUT_DONE tokens do not use any of the other
70       fields of the remctl_output struct.
71
72       The returned remctl_output struct must not be freed by the caller.  It
73       will be invalidated on any subsequent call to any other remctl API
74       function other than remctl_error() on the same remctl client object;
75       the caller should therefore copy out of the remctl_output struct any
76       data it wishes to preserve before making any subsequent remctl API
77       calls.
78

RETURN VALUE

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

AUTHOR

85       Russ Allbery <eagle@eyrie.org>
86

88       Copyright 2007, 2009 The Board of Trustees of the Leland Stanford
89       Junior University
90
91       Copying and distribution of this file, with or without modification,
92       are permitted in any medium without royalty provided the copyright
93       notice and this notice are preserved.  This file is offered as-is,
94       without any warranty.
95
96       SPDX-License-Identifier: FSFAP
97

SEE ALSO

99       remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3),
100       remctl_error(3)
101
102       The current version of the remctl library and complete details of the
103       remctl protocol are available from its web page at
104       <https://www.eyrie.org/~eagle/software/remctl/>.
105
106
107
1083.18                              2022-05-09                  REMCTL_OUTPUT(3)
Impressum