src/liblxc/lxc.h

   1 /*
   2  * lxc: linux Container library
   3  *
   4  * (C) Copyright IBM Corp. 2007, 2008
   5  *
   6  * Authors:
   7  * Daniel Lezcano <dlezcano at fr.ibm.com>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  22  */
  23 #ifndef __lxc_h
  24 #define __lxc_h
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  Following code is for liblxc.
  32
  33  liblxc/lxc.h will contain exports of liblxc
  34  **/
  35
  36 #include <liblxc/lxc_state.h>
  37 #include <liblxc/lxc_list.h>
  38 #include <liblxc/lxc_conf.h>
  39 #include <liblxc/lxc_log.h>
  40 #include <liblxc/lxc_lock.h>
  41 #include <liblxc/lxc_cgroup.h>
  42 #include <liblxc/lxc_namespace.h>
  43 #include <liblxc/lxc_utils.h>
  44
  45 #define LXCPATH "/var/lxc"
  46 #define MAXPIDLEN 20
  47
  48 struct lxc_mem_stat;
  49
  50 typedef int (*lxc_callback_t)(const char *name, int argc,
  51                               char *argv[], void *data);
  52
  53 /*
  54  * Create the container object. Creates the /lxc/<name> directory
  55  * and fills it with the files corresponding to the configuration
  56  * structure passed as parameter.
  57  * The first container will create the /lxc directory.
  58  * @name : the name of the container
  59  * @conf : the configuration data for the container
  60  * Returns 0 on success, < 0 otherwise
  61  */
  62 extern int lxc_create(const char *name, struct lxc_conf *conf);
  63
  64 /*
  65  * Destroy the container object. Removes the files into the /lxc/<name>
  66  * directory and removes the <name> directory.
  67  * The last container will remove the /lxc directory.
  68  * @name : the name of the container to be detroyed
  69  * Returns 0 on success, < 0 otherwise
  70  */
  71 extern int lxc_destroy(const char *name);
  72
  73 /*
  74  * Start the container previously created with lxc_create.
  75  * @name     : the name of the container
  76  * @argc     : the number of arguments of the command line
  77  * @argv     : an array of char * corresponding to the commande line
  78  * @prestart : hooks will be called just before the command execs
  79  * Returns 0 on sucess, < 0 otherwise
  80  */
  81 extern int lxc_start(const char *name, int argc, char *argv[],
  82                      lxc_callback_t prestart, void *data);
  83
  84 /*
  85  * Create the container and start it directly, using the argc, argv
  86  * parameter. This command is for application container.
  87  * At the end of the exec'ed command, the container will
  88  * automatically autodestroy.
  89  * @name    : the name of the container
  90  * @conf    : the configuration data
  91  * @argc    : the number of arguments of the command line
  92  * @argv    : an array of char * corresponding to the commande line
  93  * @preexec : hooks will be called just before the command execs
  94  * Returns 0 on success, < 0 otherwise
  95  */
  96 extern int lxc_execute(const char *name, int argc, char *argv[],
  97                        lxc_callback_t preexec, void *data);
  98
  99 /*
 100  * Stop the container previously started with lxc_start or lxc_exec
 101  * @name : the name of the container
 102  * Returns 0 on success, < 0 otherwise
 103  */
 104 extern int lxc_stop(const char *name);
 105
 106 /*
 107  * Monitor the container, each time the state of the container
 108  * is changed, a state data is send through a file descriptor passed to
 109  * the function with output_fd.
 110  * The function will block until the container is destroyed.
 111  * @name : the name of the container
 112  * @output_fd : the file descriptor where to send the states
 113  * Returns 0 on success, < 0 otherwise
 114  */
 115 extern int lxc_monitor(const char *name, int output_fd);
 116
 117 /*
 118  * Open the monitoring mechanism for a specific container
 119  * The function will return an fd corresponding to the events
 120  * @name  : the name of the container
 121  * Returns a file descriptor on success, < 0 otherwise
 122  */
 123 extern int lxc_monitor_open(const char *name);
 124
 125 /*
 126  * Read the state of the container if this one has changed
 127  * The function will block until there is an event available
 128  * @fd : the file descriptor provided by lxc_monitor_open
 129  * @state : the variable which will be filled with the state
 130  * Returns 0 if the monitored container has exited, > 0 if
 131  * data was readen, < 0 otherwise
 132  */
 133 extern int lxc_monitor_read(int fd, lxc_state_t *state);
 134
 135 /*
 136  * Close the fd associated with the monitoring
 137  * @fd : the file descriptor provided by lxc_monitor_open
 138  * Returns 0 on success, < 0 otherwise
 139  */
 140 extern int lxc_monitor_close(int fd);
 141
 142 /*
 143  * Show the console of the container.
 144  * @name : the name of container
 145  * Returns 0 on sucess, < 0 otherwise
 146  */
 147 extern int lxc_console(const char *name);
 148
 149 /*
 150  * Freeze all the tasks running inside the container <name>
 151  * @name : the container name
 152  * Returns 0 on success, < 0 otherwise
 153  */
 154 extern int lxc_freeze(const char *name);
 155
 156 /*
 157  * Unfreeze all previously frozen tasks.
 158  * @name : the name of the container
 159  * Return 0 on sucess, < 0 otherwise
 160  */
 161 extern int lxc_unfreeze(const char *name);
 162
 163 /*
 164  * Retrieve the container state
 165  * @name : the name of the container
 166  * Returns the state of the container on success, < 0 otherwise
 167  */
 168 extern lxc_state_t lxc_state(const char *name);
 169
 170 /*
 171  * Send a signal to all processes of the container. This is the same
 172  * behavior of the well-known 'killpg' command except it is related
 173  * to all tasks belonging to a container.
 174  * @name   : the name of the container
 175  * @signum : the signal number to be sent
 176  * Returns 0 on success, < 0 otherwise
 177  */
 178 extern int lxc_kill(const char *name, int signum);
 179
 180 /*
 181  * Change the priority of the container
 182  * @name     : the name of the container
 183  * @priority : an integer representing the desired priority
 184  * Returns 0 on success, < 0 otherwise
 185  */
 186 extern int lxc_cgroup_set_priority(const char *name, int priority);
 187
 188 /*
 189  * Retrieve the priority of the container
 190  * @name     : the name of the container
 191  * @priority : a pointer to an int where the priority will be stored
 192  * Returns 0 on success, < 0 otherwise
 193  */
 194 extern int lxc_cgroup_get_priority(const char *name, int *priority);
 195
 196 /*
 197  * Set the maximum memory usable by the container
 198  * @name   : the name of the container
 199  * @memmax : the maximum usable memory in bytes
 200  * Returns 0 on sucess, < 0 otherwise
 201  */
 202 extern int lxc_cgroup_set_memory(const char *name, size_t memmax);
 203
 204 /*
 205  * Get the maximum memory usable by the container
 206  * @name : the name of the container
 207  * @memmax : a pointer to a size_t where the value will be stored
 208  * Returns 0 on sucess, < 0 otherwise
 209  */
 210 extern int lxc_cgroup_get_memory(const char *name, size_t *memmax);
 211
 212 /*
 213  * Get the memory statistics of the container
 214  * @name    : the name of the container
 215  * @memstat : a pointer to a structure defining the memory statistic
 216  * Returns 0 on sucess, < 0 otherwise
 217  */
 218 extern int lxc_cgroup_get_memstat(const char *name,
 219                                   struct lxc_mem_stat *memstat);
 220
 221 /*
 222  * Set the cpuset for the container
 223  * @name    : the name of the container
 224  * @cpumask : a bitmask representing the cpu maps
 225  * @len     : the len of the bitmask
 226  * @shared  : a boolean specifying if the cpu could be shared with
 227  *            processes not belonging to the container
 228  * Returns 0 on sucess, < 0 otherwise
 229  */
 230 extern int lxc_cgroup_set_cpuset(const char *name, long *cpumask,
 231                                  int len, int shared);
 232
 233 /*
 234  * Get the actual cpuset for the container
 235  * @cpumask : a bitmask representing the cpu maps
 236  * @len     : the len of the bitmask
 237  * @shared  : a boolean specifying if the cpu is shared with
 238  *            processes not belonging to the container
 239  * Returns 0 on sucess, < 0 otherwise
 240  */
 241 extern int lxc_cgroup_get_cpuset(const char *name, long *cpumask,
 242                                  int len, int *shared);
 243
 244 /*
 245  * Get the cpu usage of the container
 246  * @name  : the name of the container
 247  * @usage : a value to be filled with the current container cpu usage
 248  * Returns 0 on sucess, < 0 otherwise
 249  */
 250 extern int lxc_cgroup_get_cpu_usage(const char *name, long long *usage);
 251
 252 #ifdef __cplusplus
 253 }
 254 #endif
 255
 256 #endif