---
name: "remctl_output"
section: "3"
platform: "linux"
package: "libremctl-dev"
version: "3.18-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/remctl_output"
---

# remctl\_output(3)

Retrieve the results of a remctl command

## NAME

remctl\_output - Retrieve the results of a remctl command

## SYNOPSIS

\#include \<remctl.h\>

struct remctl\_output \***remctl\_output**(struct remctl \**r*);

## DESCRIPTION

**remctl\_output()** retrieves the next output token from the remote remctl server.  *r* is a remctl client object created with **remctl\_new()**, which should have previously been used as the argument to **remctl\_open()** and then either **remctl\_command()** or **remctl\_commandv()**.

The returned remctl\_output struct has the following members:

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

where the type field will have one of the following values:

```
    REMCTL_OUT_OUTPUT
    REMCTL_OUT_STATUS
    REMCTL_OUT_ERROR
    REMCTL_OUT_DONE
```

A command rejected by the remctl server will return a single output token of type REMCTL\_OUT\_ERROR.  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. Therefore, for each command issued, 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.

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.

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.

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.  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.

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.

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; the caller should therefore copy out of the remctl\_output struct any data it wishes to preserve before making any subsequent remctl API calls.

## RETURN VALUE

**remctl\_output()** returns a pointer to a remctl\_output struct on success and NULL on failure.  On failure, the caller should call **remctl\_error()** to retrieve the error message.

## 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_new/3.md), [**remctl\_open**(3)](/remctl_open/3.md), [**remctl\_command**(3)](/remctl_command/3.md), [**remctl\_commandv**(3)](/remctl_commandv/3.md), [**remctl\_error**(3)](/remctl_error/3.md)

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/\>.