source: web/old/remctl-2.14/docs/api/remctl_output.pod @ f6f3e91

web
Last change on this file since f6f3e91 was f6f3e91, checked in by Jessica B. Hamrick <jhamrick@…>, 15 years ago

Preserve directory hierarchy (not sure what happened to it)

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