libpowerman(3)

💖 NAME 💖

libpowerman — the PowerMan Client API ✨ (it's a library functions manual page, section 3, you're in the right place bestie 🫶)

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, all the functions, exactly as they are:

#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

like, that last line is literally just how you link it. cc ... -lpowerman. slay. 💅

---

🦋 DESCRIPTION 🦋

so the pm_connect() function establishes a connection with server, which is a string containing host[:port], or NULL for defaults 🫶 — and it hands you back a handle in hp. the arg parameter is currently unused (it's giving decorative, it's giving set dressing, we love it anyway). the flags parameter should be zero, or one or more logically-OR'ed flags:

• PM_CONN_INET6 — establish the connection to the powerman server using only IPv6 protocol. without this flag, any available address family will be used. so if you don't set it, it's a ✨choose your own adventure✨ situation for the address family.

The pm_disconnect() function tears down the server connection and frees the storage associated with handle h. bye bestie 👋

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. power on, power off, power cycle — the holy trinity of "have you tried turning it off and on again" 🔥

The pm_node_status() function issues a status query acting on node to the server on handle h. the result is returned in sp, which will be one of these 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. so no, that's not you messing up, that's the device being mysterious and unbothered 🙈

now, to use all of 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 you can use 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 (the rewind button of your dreams 🎀). finally, pm_node_iterator_destroy() destroys an iterator and reclaims its storage. clean up after yourself, the storage has feelings 🫶

---

⭐ RETURN VALUE ⭐

most functions have a return type of pm_err_t. and pm_strerror() is available to convert an error code err to a human-readable string, using storage str of length len that you pass in as the caller. yes, you provide the buffer. it's a bring-your-own-storage situation 💅

---

👑 ERRORS 👑

here's the full roster, no skips, no cuts, every single one:

• PM_ESUCCESS — success. we love to see it 💖
• 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 🌈

bestie this one is iconic: it queries the list of valid nodes and turns them all on. every single one. main character energy 🔥

#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. periodt. 💜

---

🌟 SEE ALSO 🌟

powerman(1), powermand(8), httppower(8), plmpower(8), vpcd(8), powerman.conf(5), powerman.dev(5).

http://github.com/chaos/powerman

---

and that's the whole page bestie, no cap 🫶 this was powerman-2.4.4, dated 2 December 2008 — yes it's vintage, yes it still ate, go power cycle something responsibly 💅✨