libpowerman(3)

1libpowerman(3)                     powerman                     libpowerman(3)
2
3
4

NAME

6       libpowerman - PowerMan Client API
7
8

SYNOPSIS

10       #include <libpowerman.h>
11
12       pm_err_t pm_connect (char *server, void *arg, pm_handle_t *hp,
13                            int flags);
14
15       void pm_disconnect (pm_handle_t h);
16
17       pm_err_t pm_node_on (pm_handle_t h, char *node);
18
19       pm_err_t pm_node_off (pm_handle_t h, char *node);
20
21       pm_err_t pm_node_cycle (pm_handle_t h, char *node);
22
23       pm_err_t pm_node_status (pm_handle_t h, char *node,
24                                pm_node_state_t sp);
25
26       pm_err_t pm_node_iterator_create (pm_handle_t h,
27                                         pm_node_iterator_t *ip);
28
29       void pm_node_iterator_destroy (pm_node_iterator_t i);
30
31       char * pm_node_next (pm_node_iterator_t i);
32
33       void pm_node_iterator_reset (pm_node_iterator_t i);
34
35       char * pm_strerror (pm_err_t err, char * str, int len);
36
37       cc ... -lpowerman
38
39

DESCRIPTION

41       The  pm_connect()  function  establishes  a  connection  with server, a
42       string containing host[:port] or NULL for defaults; and returns a  han‐
43       dle  in hp.  The arg parameter is currently unused. The flags parameter
44       should be zero or one or more logically-OR'ed flags:
45
46       PM_CONN_INET6
47              Establish connection to the powerman server  using  (only)  IPv6
48              protocol.   Without this flag, any available address family will
49              be used.
50
51       The pm_disconnect() function tears down the server connection and frees
52       storage associated with handle h.
53
54       The  pm_node_on(),  pm_node_off(),  and pm_node_cycle() functions issue
55       on, off, and cycle commands acting on node to the server on handle h.
56
57       The pm_node_status() function issues a status query acting on  node  to
58       the  server  on  handle h.  The result is resturned in sp which will be
59       one of the values:
60
61       PM_ON  Node is powered on.
62
63       PM_OFF Node is powered off.
64
65       PM_UNKNOWN
66              Node state is unknown.  Some devices may return this  even  when
67              the  query  is successful, for example X10 devices controlled by
68              plmpower.
69
70       To use the above functions you must know the name of the node you  wish
71       to  control.   Calling pm_node_iterator_create() on handle h returns an
72       iterator ip which can be used to walk the list  of  valid  node  names.
73       pm_node_next()  returns the next node in the list, or NULL when the end
74       of the list is reached.  pm_node_iterator_reset() rewinds iterator i to
75       the   beginning   of  the  list.   Finally,  pm_node_iterator_destroy()
76       destroys an iterator and reclaims its storage.
77
78

RETURN VALUE

80       Most functions have a return type of pm_err_t.  pm_strerror() is avail‐
81       able  to  convert  an  error  code err to a human-readable string using
82       storage str of length len passed in by the caller.
83
84

ERRORS

86       PM_ESUCCESS
87              Success.
88
89       PM_ERRNOVALID
90              System call failed, see system errno.
91
92       PM_ENOADDR
93              Failed to get address info for server.
94
95       PM_ECONNECT
96              Connect failed.
97
98       PM_ENOMEM
99              Out of memory.
100
101       PM_EBADHAND
102              Bad server handle.
103
104       PM_EBADARG
105              Bad argument.
106
107       PM_ESERVEREOF
108              Received unexpected EOF from server.
109
110       PM_ESERVERPARSE
111              Received unexpected response from server.
112
113       PM_EUNKNOWN
114              Server responded with ``unknown command''.
115
116       PM_EPARSE
117              Server responded with ``parse error''.
118
119       PM_ETOOLONG
120              Server responded with ``command too long''.
121
122       PM_EINTERNAL
123              Server responed with ``internal error''.
124
125       PM_EHOSTLIST
126              Server responded with ``hostlist error''.
127
128       PM_EINPROGRESS
129              Server responded with ``command in progress''.
130
131       PM_ENOSUCHNODES
132              Server responded with ``no such nodes''.
133
134       PM_ECOMMAND
135              Server responded with ``command completed with errors''.
136
137       PM_EQUERY
138              Server responded with ``query completed with errors''.
139
140       PM_EUNIMPL
141              Server responded with ``not implemented by device''.
142
143

EXAMPLE

145       This example program queries the list of valid nodes and turns them all
146       on.
147
148       #include <stdio.h>
149       #include <stdlib.h>
150       #include <libpowerman.h>
151
152       int
153       main(int argc, char *argv[])
154       {
155           pm_err_t err;
156           pm_node_state_t s;
157           pm_handle_t h;
158           pm_node_iterator_t i;
159           char ebuf[64], *node;
160
161           if ((err = pm_connect (NULL, NULL, &h, 0)) != PM_ESUCCESS) {
162               fprintf (stderr, "pm_connect: %s\n",
163                       pm_strerror (err, ebuf, sizeof (ebuf)));
164               exit(1);
165           }
166
167           if ((err = pm_node_iterator_create (h, &i)) != PM_ESUCCESS) {
168               fprintf (stderr, "pm_node_iterator_create: %s\n",
169                       pm_strerror (err, ebuf, sizeof (ebuf)));
170               exit(1);
171           }
172           while ((node = pm_node_next (i))) {
173               if ((err = pm_node_on (h, node)) != PM_ESUCCESS) {
174                   fprintf (stderr, "pm_node_on: %s\n",
175                           pm_strerror (err, ebuf, sizeof(ebuf)));
176                   exit (1);
177               }
178           }
179           pm_node_iterator_destroy (i);
180
181           pm_disconnect (h);
182           exit (0);
183       }
184
185

FILES

187       /usr/lib/libpowerman.*
188       /usr/lib64/libpowerman.*
189       /usr/include/libpowerman.h
190
191

ORIGIN

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