src/lxc/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 #include <stddef.h>
  31 #include <lxc/state.h>
  32
  33 struct lxc_msg;
  34 struct lxc_conf;
  35 struct lxc_arguments;
  36
  37 /**
  38  Following code is for liblxc.
  39
  40  lxc/lxc.h will contain exports of liblxc
  41  **/
  42
  43 /*
  44  * Start the specified command inside a system container
  45  * @name     : the name of the container
  46  * @argv     : an array of char * corresponding to the commande line
  47  * @conf     : configuration
  48  * Returns 0 on sucess, < 0 otherwise
  49  */
  50 extern int lxc_start(const char *name, char *const argv[], struct lxc_conf *conf,
  51                      const char *lxcpath);
  52
  53 /*
  54  * Stop the container previously started with lxc_start, all
  55  * the processes running inside this container will be killed.
  56  * @name : the name of the container
  57  * Returns 0 on success, < 0 otherwise
  58  */
  59 extern int lxc_stop(const char *name, const char *lxcpath);
  60
  61 /*
  62  * Start the specified command inside an application container
  63  * @name     : the name of the container
  64  * @argv     : an array of char * corresponding to the commande line
  65  * @quiet    : if != 0 then lxc-init won't produce any output
  66  * @conf     : configuration
  67  * Returns 0 on sucess, < 0 otherwise
  68  */
  69 extern int lxc_execute(const char *name, char *const argv[], int quiet,
  70                        struct lxc_conf *conf, const char *lxcpath);
  71
  72 /*
  73  * Open the monitoring mechanism for a specific container
  74  * The function will return an fd corresponding to the events
  75  * Returns a file descriptor on success, < 0 otherwise
  76  */
  77 extern int lxc_monitor_open(const char *lxcpath);
  78
  79 /*
  80  * Read the state of the container if this one has changed
  81  * The function will block until there is an event available
  82  * @fd : the file descriptor provided by lxc_monitor_open
  83  * @state : the variable which will be filled with the state
  84  * Returns 0 if the monitored container has exited, > 0 if
  85  * data was readen, < 0 otherwise
  86  */
  87 extern int lxc_monitor_read(int fd, struct lxc_msg *msg);
  88 extern int lxc_monitor_read_timeout(int fd, struct lxc_msg *msg, int timeout);
  89
  90 /*
  91  * Close the fd associated with the monitoring
  92  * @fd : the file descriptor provided by lxc_monitor_open
  93  * Returns 0 on success, < 0 otherwise
  94  */
  95 extern int lxc_monitor_close(int fd);
  96
  97 /*
  98  * Show the console of the container.
  99  * @name : the name of container
 100  * @tty  : the tty number
 101  * @fd   : a pointer to a tty file descriptor
 102  * Returns 0 on sucess, < 0 otherwise
 103  */
 104 extern int lxc_console(const char *name, int ttynum, int *fd, const char *lxcpath);
 105
 106 /*
 107  * Freeze all the tasks running inside the container <name>
 108  * @name : the container name
 109  * Returns 0 on success, < 0 otherwise
 110  */
 111 extern int lxc_freeze(const char *name, const char *lxcpath);
 112
 113 /*
 114  * Unfreeze all previously frozen tasks.
 115  * @name : the name of the container
 116  * Return 0 on sucess, < 0 otherwise
 117  */
 118 extern int lxc_unfreeze(const char *name, const char *lxcpath);
 119
 120 /*
 121  * Unfreeze all previously frozen tasks.
 122  * This is the function to use from inside the monitor
 123  * @name : the name of the container
 124  * Return 0 on sucess, < 0 otherwise
 125  */
 126 extern int lxc_unfreeze_bypath(const char *cgpath);
 127
 128 /*
 129  * Retrieve the container state
 130  * @name : the name of the container
 131  * Returns the state of the container on success, < 0 otherwise
 132  */
 133 extern lxc_state_t lxc_state(const char *name, const char *lxcpath);
 134
 135 /*
 136  * Set a specified value for a specified subsystem. The specified
 137  * subsystem must be fully specified, eg. "cpu.shares"
 138  * @cgpath    : the cgroup path of the container
 139  * @filename  : the cgroup attribute filename
 140  * @value     : the value to be set
 141  * Returns 0 on success, < 0 otherwise
 142  */
 143 extern int lxc_cgroup_set_bypath(const char *cgpath, const char *filename, const char *value);
 144
 145 /*
 146  * Set a specified value for a specified subsystem. The specified
 147  * subsystem must be fully specified, eg. "cpu.shares"
 148  * @name      : the name of the container
 149  * @filename  : the cgroup attribute filename
 150  * @value     : the value to be set
 151  * @lxcpath   : lxc config path for container
 152  * Returns 0 on success, < 0 otherwise
 153  */
 154 extern int lxc_cgroup_set(const char *name, const char *filename, const char *value, const char *lxcpath);
 155
 156 /*
 157  * Get a specified value for a specified subsystem. The specified
 158  * subsystem must be fully specified, eg. "cpu.shares"
 159  * @name      : the name of the container
 160  * @filename  : the cgroup attribute filename
 161  * @value     : the value to be set
 162  * @len       : the len of the value variable
 163  * @lxcpath   : lxc config path for container
 164  * Returns the number of bytes read, < 0 on error
 165  */
 166 extern int lxc_cgroup_get(const char *name, const char *filename,
 167                           char *value, size_t len, const char *lxcpath);
 168
 169 /*
 170  * Retrieve the error string associated with the error returned by
 171  * the function.
 172  * @error : the value of the error
 173  * Returns a string on success or NULL otherwise.
 174  */
 175 extern const char *lxc_strerror(int error);
 176
 177 /*
 178  * Checkpoint a container
 179  * @name : the name of the container being checkpointed
 180  * @sfd: fd on which the container is checkpointed
 181  * @flags : checkpoint flags (an ORed value)
 182  * Returns 0 on success, < 0 otherwise
 183  */
 184 extern int lxc_checkpoint(const char *name, int sfd, int flags);
 185 #define LXC_FLAG_PAUSE 1
 186 #define LXC_FLAG_HALT  2
 187
 188 /*
 189  * Restart a container
 190  * @name : the name of the container being restarted
 191  * @sfd: fd from which the container is restarted
 192  * @conf: lxc_conf structure.
 193  * @flags : restart flags (an ORed value)
 194  * @lxcpath: container path
 195  * Returns 0 on success, < 0 otherwise
 196  */
 197 extern int lxc_restart(const char *, int, struct lxc_conf *, int, const char *);
 198
 199 /*
 200  * Create and return a new lxccontainer struct.
 201  */
 202 extern struct lxc_container *lxc_container_new(const char *name, const char *configpath);
 203
 204 /*
 205  * Returns 1 on success, 0 on failure.
 206  */
 207 extern int lxc_container_get(struct lxc_container *c);
 208
 209 /*
 210  * Put a lxccontainer struct reference.
 211  * Return -1 on error.
 212  * Return 0 if this was not the last reference.
 213  * If it is the last reference, free the lxccontainer and return 1.
 214  */
 215 extern int lxc_container_put(struct lxc_container *c);
 216
 217 /*
 218  * Get a list of valid wait states.
 219  * If states is NULL, simply return the number of states
 220  */
 221 extern int lxc_get_wait_states(const char **states);
 222
 223 #ifdef __cplusplus
 224 }
 225 #endif
 226
 227 #endif