---
name: "libpowerman"
section: "3"
platform: "linux"
package: "powerman"
version: "2.4.4-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/libpowerman"
---

# libpowerman(3)

PowerMan Client API

## NAME

libpowerman - PowerMan Client API

## SYNOPSIS

```
#include <libpowerman.h>

pm_err_t pm_connect (char *server, void *arg, pm_handle_t *hp,
                     int flags);

void pm_disconnect (pm_handle_t h);

pm_err_t pm_node_on (pm_handle_t h, char *node);

pm_err_t pm_node_off (pm_handle_t h, char *node);

pm_err_t pm_node_cycle (pm_handle_t h, char *node);

pm_err_t pm_node_status (pm_handle_t h, char *node,
                         pm_node_state_t sp);

pm_err_t pm_node_iterator_create (pm_handle_t h,
                                  pm_node_iterator_t *ip);

void pm_node_iterator_destroy (pm_node_iterator_t i);

char * pm_node_next (pm_node_iterator_t i);

void pm_node_iterator_reset (pm_node_iterator_t i);

char * pm_strerror (pm_err_t err, char * str, int len);

cc ... -lpowerman
```

## DESCRIPTION

The **pm\_connect**() function establishes a connection with *server*, a string containing *host\[:port\]* or NULL for defaults; and returns a handle in *hp*.  The *arg* parameter is currently unused. The *flags* parameter should be zero or one or more logically-OR'ed flags:

- **PM\_CONN\_INET6**

  Establish connection to the powerman server using (only) IPv6 protocol. Without this flag, any available address family will be used.

The **pm\_disconnect**() function tears down the server connection and frees storage associated with handle *h*.

The **pm\_node\_on**(), **pm\_node\_off**(), and **pm\_node\_cycle**() functions issue on, off, and cycle commands acting on *node* to the server on handle *h*.

The **pm\_node\_status**() function issues a status query acting on *node* to the server on handle *h*.  The result is resturned in *sp* which will be one of the values:

- **PM\_ON**

  Node is powered on.

- **PM\_OFF**

  Node is powered off.

- **PM\_UNKNOWN**

  Node state is unknown.  Some devices may return this even when the query is successful, for example X10 devices controlled by **plmpower**.

To use the above functions you must know the name of the node you wish to control.  Calling **pm\_node\_iterator\_create**() on handle *h* returns an iterator *ip* which can be used to walk the list of valid node names.  **pm\_node\_next**() returns the next node in the list, or NULL when the end of the list is reached.  **pm\_node\_iterator\_reset**() rewinds iterator *i* to the beginning of the list. Finally, **pm\_node\_iterator\_destroy**() destroys an iterator and reclaims its storage.

## RETURN VALUE

Most functions have a return type of *pm\_err\_t*. **pm\_strerror**() is available to convert an error code *err* to a human-readable string using storage *str* of length *len* passed in by the caller.

## ERRORS

- **PM\_ESUCCESS**

  Success.

- **PM\_ERRNOVALID**

  System call failed, see system errno.

- **PM\_ENOADDR**

  Failed to get address info for server.

- **PM\_ECONNECT**

  Connect failed.

- **PM\_ENOMEM**

  Out of memory.

- **PM\_EBADHAND**

  Bad server handle.

- **PM\_EBADARG**

  Bad argument.

- **PM\_ESERVEREOF**

  Received unexpected EOF from server.

- **PM\_ESERVERPARSE**

  Received unexpected response from server.

- **PM\_EUNKNOWN**

  Server responded with \`\`unknown command''.

- **PM\_EPARSE**

  Server responded with \`\`parse error''.

- **PM\_ETOOLONG**

  Server responded with \`\`command too long''.

- **PM\_EINTERNAL**

  Server responded with \`\`internal error''.

- **PM\_EHOSTLIST**

  Server responded with \`\`hostlist error''.

- **PM\_EINPROGRESS**

  Server responded with \`\`command in progress''.

- **PM\_ENOSUCHNODES**

  Server responded with \`\`no such nodes''.

- **PM\_ECOMMAND**

  Server responded with \`\`command completed with errors''.

- **PM\_EQUERY**

  Server responded with \`\`query completed with errors''.

- **PM\_EUNIMPL**

  Server responded with \`\`not implemented by device''.

## EXAMPLE

This example program queries the list of valid nodes and turns them all on.

```
#include <stdio.h>
#include <stdlib.h>
#include <libpowerman.h>

int
main(int argc, char *argv[])
{
    pm_err_t err;
    pm_node_state_t s;
    pm_handle_t h;
    pm_node_iterator_t i;
    char ebuf[64], *node;

    if ((err = pm_connect (NULL, NULL, &h, 0)) != PM_ESUCCESS) {
        fprintf (stderr, "pm_connect: %s\n",
                pm_strerror (err, ebuf, sizeof (ebuf)));
        exit(1);
    }

    if ((err = pm_node_iterator_create (h, &i)) != PM_ESUCCESS) {
        fprintf (stderr, "pm_node_iterator_create: %s\n",
                pm_strerror (err, ebuf, sizeof (ebuf)));
        exit(1);
    }
    while ((node = pm_node_next (i))) {
        if ((err = pm_node_on (h, node)) != PM_ESUCCESS) {
            fprintf (stderr, "pm_node_on: %s\n",
                    pm_strerror (err, ebuf, sizeof(ebuf)));
            exit (1);
        }
    }
    pm_node_iterator_destroy (i);

    pm_disconnect (h);
    exit (0);
}
```

## FILES

/usr/lib/x86\_64-linux-gnu/libpowerman.\*\
 /usr/include/libpowerman.h

## ORIGIN

PowerMan was originally developed by Andrew Uselton on LLNL's Linux clusters. This software is open source and distributed under the terms of the GNU GPL.

## SEE ALSO

[**powerman**(1)](/powerman/1.md), [**powermand**(8)](/powermand/8.md), [**httppower**(8)](/httppower/8.md), [**plmpower**(8)](/plmpower/8.md), [**vpcd**(8)](/vpcd/8.md), [**powerman.conf**(5)](/powerman.conf/5.md), [**powerman.dev**(5)](/powerman.dev/5.md).

**http://github.com/chaos/powerman**