source: web/old/remctl-2.14/docs/api/remctl_output.3 @ 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: 7.8 KB
Line 
1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings.  \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27.    ds -- \(*W-
28.    ds PI pi
29.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31.    ds L" ""
32.    ds R" ""
33.    ds C` ""
34.    ds C' ""
35'br\}
36.el\{\
37.    ds -- \|\(em\|
38.    ds PI \(*p
39.    ds L" ``
40.    ds R" ''
41'br\}
42.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el       .ds Aq '
46.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD.  Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
51.ie \nF \{\
52.    de IX
53.    tm Index:\\$1\t\\n%\t"\\$2"
54..
55.    nr % 0
56.    rr F
57.\}
58.el \{\
59.    de IX
60..
61.\}
62.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65.    \" fudge factors for nroff and troff
66.if n \{\
67.    ds #H 0
68.    ds #V .8m
69.    ds #F .3m
70.    ds #[ \f1
71.    ds #] \fP
72.\}
73.if t \{\
74.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75.    ds #V .6m
76.    ds #F 0
77.    ds #[ \&
78.    ds #] \&
79.\}
80.    \" simple accents for nroff and troff
81.if n \{\
82.    ds ' \&
83.    ds ` \&
84.    ds ^ \&
85.    ds , \&
86.    ds ~ ~
87.    ds /
88.\}
89.if t \{\
90.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96.\}
97.    \" troff and (daisy-wheel) nroff accents
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
107.    \" corrections for vroff
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110.    \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
113.    ds : e
114.    ds 8 ss
115.    ds o a
116.    ds d- d\h'-1'\(ga
117.    ds D- D\h'-1'\(hy
118.    ds th \o'bp'
119.    ds Th \o'LP'
120.    ds ae ae
121.    ds Ae AE
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "REMCTL_OUTPUT 3"
127.TH REMCTL_OUTPUT 3 "2009-05-22" "2.14" "remctl Library Reference"
128.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
132.SH "NAME"
133remctl_output \- Retrieve the results of a remctl command
134.SH "SYNOPSIS"
135.IX Header "SYNOPSIS"
136#include <remctl.h>
137.PP
138struct remctl_output *\fBremctl_output\fR(struct remctl *\fIr\fR);
139.SH "DESCRIPTION"
140.IX Header "DESCRIPTION"
141\&\fIremctl_output()\fR retrieves the next output token from the remote remctl
142server.  \fIr\fR is a remctl client object created with \fIremctl_new()\fR, which
143should have previously been used as the argument to \fIremctl_open()\fR and then
144either \fIremctl_command()\fR or \fIremctl_commandv()\fR.
145.PP
146The returned remctl_output struct has the following members:
147.PP
148.Vb 8
149\&    struct remctl_output {
150\&        enum remctl_output_type type;
151\&        char *data;
152\&        size_t length;
153\&        int stream;                 /* 1 == stdout, 2 == stderr */
154\&        int status;                 /* Exit status of remote command. */
155\&        int error;                  /* Remote error code. */
156\&    };
157.Ve
158.PP
159where the type field will have one of the following values:
160.PP
161.Vb 4
162\&    REMCTL_OUT_OUTPUT
163\&    REMCTL_OUT_STATUS
164\&    REMCTL_OUT_ERROR
165\&    REMCTL_OUT_DONE
166.Ve
167.PP
168A command rejected by the remctl server will return a single output token
169of type \s-1REMCTL_OUT_ERROR\s0.  A successful command will return zero or more
170\&\s-1REMCTL_OUT_OUTPUT\s0 tokens representing the output of the command followed
171by a \s-1REMCTL_OUT_STATUS\s0 token giving the exit status of the command.
172Therefore, for each command issued, the caller should call
173\&\fIremctl_command()\fR or \fIremctl_commandv()\fR and then call \fIremctl_output()\fR
174repeatedly to retrieve each output token until \fIremctl_output()\fR returns a
175token of type \s-1REMCTL_OUT_ERROR\s0 or \s-1REMCTL_OUT_STATUS\s0.
176.PP
177A \s-1REMCTL_OUT_OUTPUT\s0 token will have data in the data field, whose length
178is given by the length field.  The output stream will be given by the
179stream field, with a value of 1 indicating standard output and a value of
1802 indicating standard error.  All other stream values are reserved for
181future use.
182.PP
183A \s-1REMCTL_OUT_STATUS\s0 token will hold the exit status of the remote command
184in the status field.  Following the standard Unix convention, a 0 status
185should normally be considered success and any non-zero status should
186normally be considered failure, although a given command may have its own
187exit status conventions.
188.PP
189A \s-1REMCTL_OUT_ERROR\s0 token will have the error message from the server in
190the data field (with length stored in length) and the protocol error code
191in the error field.  The latter is the most reliable indicator of the
192error; the message stored in the error field is free-form text, may or may
193not be localized, and should not be used for programmatic comparisons.
194For the possible error code values and their meanings, see the remctl
195protocol specification.
196.PP
197If \fIremctl_output()\fR is called when there is no pending output from the
198remote server (after a \s-1REMCTL_OUT_ERROR\s0 or \s-1REMCTL_OUT_STATUS\s0 token has
199already been returned, for example), a token of type \s-1REMCTL_OUT_DONE\s0 will
200be returned.  \s-1REMCTL_OUT_DONE\s0 tokens do not use any of the other fields of
201the remctl_output struct.
202.PP
203The returned remctl_output struct must not be freed by the caller.  It
204will be invalidated on any subsequent call to any other remctl \s-1API\s0
205function other than \fIremctl_error()\fR on the same remctl client object; the
206caller should therefore copy out of the remctl_output struct any data it
207wishes to preserve before making any subsequent remctl \s-1API\s0 calls.
208.SH "RETURN VALUE"
209.IX Header "RETURN VALUE"
210\&\fIremctl_output()\fR returns a pointer to a remctl_output struct on success and
211\&\s-1NULL\s0 on failure.  On failure, the caller should call \fIremctl_error()\fR to
212retrieve the error message.
213.SH "SEE ALSO"
214.IX Header "SEE ALSO"
215\&\fIremctl_new\fR\|(3), \fIremctl_open\fR\|(3), \fIremctl_command\fR\|(3), \fIremctl_commandv\fR\|(3),
216\&\fIremctl_error\fR\|(3)
217.PP
218The current version of the remctl library and complete details of the
219remctl protocol are available from its web page at
220<http://www.eyrie.org/~eagle/software/remctl/>.
221.SH "AUTHOR"
222.IX Header "AUTHOR"
223Russ Allbery <rra@stanford.edu>
Note: See TracBrowser for help on using the repository browser.