oracular (3) libpowerman.3.gz

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 responed 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), powermand(8), httppower(8), plmpower(8), vpcd(8), powerman.conf(5), powerman.dev(5).

       http://github.com/chaos/powerman