.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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 "2012-06-19" "3.2" "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 .PP struct remctl_output *\fBremctl_output\fR(struct remctl *\fIr\fR); .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIremctl_output()\fR retrieves the next output token from the remote remctl server. \fIr\fR is a remctl client object created with \fIremctl_new()\fR, which should have previously been used as the argument to \fIremctl_open()\fR and then either \fIremctl_command()\fR or \fIremctl_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 \&\fIremctl_command()\fR or \fIremctl_commandv()\fR and then call \fIremctl_output()\fR repeatedly to retrieve each output token until \fIremctl_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 \fIremctl_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 \fIremctl_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" \&\fIremctl_output()\fR returns a pointer to a remctl_output struct on success and \&\s-1NULL\s0 on failure. On failure, the caller should call \fIremctl_error()\fR to retrieve the error message. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIremctl_new\fR\|(3), \fIremctl_open\fR\|(3), \fIremctl_command\fR\|(3), \fIremctl_commandv\fR\|(3), \&\fIremctl_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 . .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .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.