1 | =for stopwords |
---|
2 | remctl API Allbery |
---|
3 | |
---|
4 | =head1 NAME |
---|
5 | |
---|
6 | remctl_output - Retrieve the results of a remctl command |
---|
7 | |
---|
8 | =head1 SYNOPSIS |
---|
9 | |
---|
10 | #include <remctl.h> |
---|
11 | |
---|
12 | struct remctl_output *B<remctl_output>(struct remctl *I<r>); |
---|
13 | |
---|
14 | =head1 DESCRIPTION |
---|
15 | |
---|
16 | remctl_output() retrieves the next output token from the remote remctl |
---|
17 | server. I<r> is a remctl client object created with remctl_new(), which |
---|
18 | should have previously been used as the argument to remctl_open() and then |
---|
19 | either remctl_command() or remctl_commandv(). |
---|
20 | |
---|
21 | The returned remctl_output struct has the following members: |
---|
22 | |
---|
23 | struct remctl_output { |
---|
24 | enum remctl_output_type type; |
---|
25 | char *data; |
---|
26 | size_t length; |
---|
27 | int stream; /* 1 == stdout, 2 == stderr */ |
---|
28 | int status; /* Exit status of remote command. */ |
---|
29 | int error; /* Remote error code. */ |
---|
30 | }; |
---|
31 | |
---|
32 | where the type field will have one of the following values: |
---|
33 | |
---|
34 | REMCTL_OUT_OUTPUT |
---|
35 | REMCTL_OUT_STATUS |
---|
36 | REMCTL_OUT_ERROR |
---|
37 | REMCTL_OUT_DONE |
---|
38 | |
---|
39 | A command rejected by the remctl server will return a single output token |
---|
40 | of type REMCTL_OUT_ERROR. A successful command will return zero or more |
---|
41 | REMCTL_OUT_OUTPUT tokens representing the output of the command followed |
---|
42 | by a REMCTL_OUT_STATUS token giving the exit status of the command. |
---|
43 | Therefore, for each command issued, the caller should call |
---|
44 | remctl_command() or remctl_commandv() and then call remctl_output() |
---|
45 | repeatedly to retrieve each output token until remctl_output() returns a |
---|
46 | token of type REMCTL_OUT_ERROR or REMCTL_OUT_STATUS. |
---|
47 | |
---|
48 | A REMCTL_OUT_OUTPUT token will have data in the data field, whose length |
---|
49 | is given by the length field. The output stream will be given by the |
---|
50 | stream field, with a value of 1 indicating standard output and a value of |
---|
51 | 2 indicating standard error. All other stream values are reserved for |
---|
52 | future use. |
---|
53 | |
---|
54 | A REMCTL_OUT_STATUS token will hold the exit status of the remote command |
---|
55 | in the status field. Following the standard Unix convention, a 0 status |
---|
56 | should normally be considered success and any non-zero status should |
---|
57 | normally be considered failure, although a given command may have its own |
---|
58 | exit status conventions. |
---|
59 | |
---|
60 | A REMCTL_OUT_ERROR token will have the error message from the server in |
---|
61 | the data field (with length stored in length) and the protocol error code |
---|
62 | in the error field. The latter is the most reliable indicator of the |
---|
63 | error; the message stored in the error field is free-form text, may or may |
---|
64 | not be localized, and should not be used for programmatic comparisons. |
---|
65 | For the possible error code values and their meanings, see the remctl |
---|
66 | protocol specification. |
---|
67 | |
---|
68 | If remctl_output() is called when there is no pending output from the |
---|
69 | remote server (after a REMCTL_OUT_ERROR or REMCTL_OUT_STATUS token has |
---|
70 | already been returned, for example), a token of type REMCTL_OUT_DONE will |
---|
71 | be returned. REMCTL_OUT_DONE tokens do not use any of the other fields of |
---|
72 | the remctl_output struct. |
---|
73 | |
---|
74 | The returned remctl_output struct must not be freed by the caller. It |
---|
75 | will be invalidated on any subsequent call to any other remctl API |
---|
76 | function other than remctl_error() on the same remctl client object; the |
---|
77 | caller should therefore copy out of the remctl_output struct any data it |
---|
78 | wishes to preserve before making any subsequent remctl API calls. |
---|
79 | |
---|
80 | =head1 RETURN VALUE |
---|
81 | |
---|
82 | remctl_output() returns a pointer to a remctl_output struct on success and |
---|
83 | NULL on failure. On failure, the caller should call remctl_error() to |
---|
84 | retrieve the error message. |
---|
85 | |
---|
86 | =head1 SEE ALSO |
---|
87 | |
---|
88 | remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3), |
---|
89 | remctl_error(3) |
---|
90 | |
---|
91 | The current version of the remctl library and complete details of the |
---|
92 | remctl protocol are available from its web page at |
---|
93 | L<http://www.eyrie.org/~eagle/software/remctl/>. |
---|
94 | |
---|
95 | =head1 AUTHOR |
---|
96 | |
---|
97 | Russ Allbery <rra@stanford.edu> |
---|
98 | |
---|
99 | =cut |
---|