REMCTL_OUTPUT(3)

💖 REMCTL_OUTPUT — the remctl_output(3) page, but make it cute ✨

okay bestie, pull up a chair 🪑 because we're about to talk about remctl_output(3) from the remctl Library Reference, and honestly? it's giving results. literally. it retrieves results. i'm obsessed.

---

✨ NAME ✨

remctl_output — Retrieve the results of a remctl command 🎀

---

🌸 SYNOPSIS 🌸

#include <remctl.h>

struct remctl_output *remctl_output(struct remctl *r);

---

💅 DESCRIPTION 💅

so remctl_output() retrieves the next output token from the remote remctl server. iconic behavior, no notes. 🫶

r is a remctl client object that you made with remctl_new(), and it should have already been used as the argument to remctl_open() and then to either remctl_command() or remctl_commandv(). like, the whole pipeline, bestie. you can't skip steps. 💀

🦋 the struct 🦋

the returned remctl_output struct has these members, and yes we're listing all of them, every single one:

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. */
};

and the type field is gonna be one of these four values, periodt:

REMCTL_OUT_OUTPUT
REMCTL_OUT_STATUS
REMCTL_OUT_ERROR
REMCTL_OUT_DONE

🌈 the flow of it all 🌈

a command that the remctl server rejects will return a single output token of type REMCTL_OUT_ERROR. rude, but okay.

a successful command will return zero or more REMCTL_OUT_OUTPUT tokens representing the output of the command, followed by a REMCTL_OUT_STATUS token giving the exit status of the command. the way that works is so clean honestly ✨

so for each command you issue, the caller should call remctl_command() or remctl_commandv() and then call remctl_output() repeatedly to retrieve each output token — until remctl_output() returns a token of type REMCTL_OUT_ERROR or REMCTL_OUT_STATUS. that's your stopping condition. that's the vibe check. 🎯

🍓 token by token 🍓

• a REMCTL_OUT_OUTPUT 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 👀 so don't go reading meaning into them.
• a REMCTL_OUT_STATUS 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. (some commands are just built different, iykyk.)
• a REMCTL_OUT_ERROR 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. and listen, the error code 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. do not do it. i'm serious. 🚫 for the possible error code values and their meanings, see the remctl protocol specification.
• if remctl_output() is called when there is no pending output from the remote server (after a REMCTL_OUT_ERROR or REMCTL_OUT_STATUS token has already been returned, for example), a token of type REMCTL_OUT_DONE will be returned. REMCTL_OUT_DONE tokens do not use any of the other fields of the remctl_output struct. they're just there to say "we're done here bestie, go home" 🏠

⚠️ big important one, do not skip this: the returned remctl_output struct must not be freed by the caller. it will be invalidated on any subsequent call to any other remctl API function other than remctl_error() on the same remctl client object. so the caller should therefore copy out of the remctl_output struct any data it wishes to preserve before making any subsequent remctl API calls. copy it or lose it, babe. 😭

---

💖 RETURN VALUE 💖

remctl_output() returns a pointer to a remctl_output struct on success and NULL on failure. and on failure, the caller should call remctl_error() to retrieve the error message. that's your lifeline, use it. 🫶

---

👑 AUTHOR 👑

Russ Allbery <eagle@eyrie.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior University

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.

SPDX-License-Identifier: FSFAP

---

🌟 SEE ALSO 🌟

remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3), remctl_error(3)

the current version of the remctl library and complete details of the remctl protocol are available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>.

---

and that's the whole page, bestie 💜 this was remctl Library Reference version 3.18, dated 2022-05-09 — go forth and retrieve your tokens responsibly, mwah 🧚✨