---
name: "upscli_list_start"
section: "3"
platform: "linux"
package: "nut"
version: "2.8.5-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/upscli_list_start"
---

# upscli\_list\_start(3)

Begin multi-item retrieval from a UPS

## NAME

upscli\_list\_start - Begin multi-item retrieval from a UPS

## SYNOPSIS

```
        #include <upsclient.h>
        int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query)
```

## DESCRIPTION

The **upscli\_list\_start()** function takes the pointer *ups* to a UPSCONN\_t state structure, and the pointer *query* to an array of *numq* query elements. It builds a properly-formatted request from those elements and transmits it to [**upsd**(8)](/upsd/8.md).

Upon success, the caller must call [**upscli\_list\_next**(3)](/upscli_list_next/3.md) to retrieve the elements of the list. Failure to retrieve the list will most likely result in the client getting out of sync with the server due to buffered data.

## USES

This function implements the "LIST" command in the protocol. As a result, you can use it to request many different things from the server. Some examples are:

• LIST UPS

• LIST VAR \<ups\>

• LIST RW \<ups\>

• LIST CMD \<ups\>

• LIST ENUM \<ups\> \<var\>

• LIST RANGE \<ups\> \<var\>

## QUERY FORMATTING

To see the list of variables on a UPS called *su700*, the protocol command would be LIST VAR su700. To start that list with this function, you would populate query and numq as follows:

```
        size_t numq;
        const char *query[2];
        query[0] = "VAR";
        query[1] = "su700";
        numq = 2;
```

All escaping of special characters and quoting of elements with spaces are handled for you inside this function.

## ERROR CHECKING

This function checks the response from [**upsd**(8)](/upsd/8.md) against your query. If it is not starting a list, or is starting the wrong type of list, it will return an error code.

When this happens, [**upscli\_upserror**(3)](/upscli_upserror/3.md) will return UPSCLI\_ERR\_PROTOCOL.

## RETURN VALUE

The **upscli\_list\_start()** function returns *0* on success, or *-1* if an error occurs.

## SEE ALSO

[**upscli\_fd**(3)](/upscli_fd/3.md), [**upscli\_get**(3)](/upscli_get/3.md), [**upscli\_readline**(3)](/upscli_readline/3.md), [**upscli\_sendline**(3)](/upscli_sendline/3.md), [**upscli\_ssl**(3)](/upscli_ssl/3.md), [**upscli\_strerror**(3)](/upscli_strerror/3.md), [**upscli\_upserror**(3)](/upscli_upserror/3.md)