lxc_container Struct Reference

#include <lxccontainer.h>

Collaboration diagram for lxc_container:
Collaboration graph
[legend]

Data Fields

char * error_string
int error_num
bool daemonize
char * config_path
bool(* is_defined )(struct lxc_container *c)
 Determine if /var/lib/lxc/$name/config exists.
const char *(* state )(struct lxc_container *c)
 Determine state of container.
bool(* is_running )(struct lxc_container *c)
 Determine if container is running.
bool(* freeze )(struct lxc_container *c)
 Freeze running container.
bool(* unfreeze )(struct lxc_container *c)
 Thaw a frozen container.
pid_t(* init_pid )(struct lxc_container *c)
 Determine process ID of the containers init process.
bool(* load_config )(struct lxc_container *c, const char *alt_file)
 Load the specified configuration for the container.
bool(* start )(struct lxc_container *c, int useinit, char *const argv[])
 Start the container.
bool(* startl )(struct lxc_container *c, int useinit,...)
 Start the container (list variant).
bool(* stop )(struct lxc_container *c)
 Stop the container.
bool(* want_daemonize )(struct lxc_container *c, bool state)
 Determine if the container wants to run disconnected from the terminal.
bool(* want_close_all_fds )(struct lxc_container *c, bool state)
 Determine whether container wishes all file descriptors to be closed on startup.
char *(* config_file_name )(struct lxc_container *c)
 Return current config file name.
bool(* wait )(struct lxc_container *c, const char *state, int timeout)
 Wait for container to reach a particular state.
bool(* set_config_item )(struct lxc_container *c, const char *key, const char *value)
 Set a key/value configuration option.
bool(* destroy )(struct lxc_container *c)
 Delete the container.
bool(* save_config )(struct lxc_container *c, const char *alt_file)
 Save configuaration to a file.
bool(* create )(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags, char *const argv[])
 Create a container.
bool(* createl )(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags,...)
 Create a container (list variant).
bool(* rename )(struct lxc_container *c, const char *newname)
 Rename a container.
bool(* reboot )(struct lxc_container *c)
 Request the container reboot by sending it SIGINT.
bool(* shutdown )(struct lxc_container *c, int timeout)
 Request the container shutdown by sending it SIGPWR.
void(* clear_config )(struct lxc_container *c)
 Completely clear the containers in-memory configuration.
bool(* clear_config_item )(struct lxc_container *c, const char *key)
 Clear a configuration item.
int(* get_config_item )(struct lxc_container *c, const char *key, char *retv, int inlen)
 Retrieve the value of a config item.
char *(* get_running_config_item )(struct lxc_container *c, const char *key)
 Retrieve the value of a config item from running container.
int(* get_keys )(struct lxc_container *c, const char *key, char *retv, int inlen)
 Retrieve a list of config item keys given a key prefix.
char **(* get_interfaces )(struct lxc_container *c)
 Obtain a list of network interfaces.
char **(* get_ips )(struct lxc_container *c, const char *interface, const char *family, int scope)
 Determine the list of container IP addresses.
int(* get_cgroup_item )(struct lxc_container *c, const char *subsys, char *retv, int inlen)
 Retrieve the specified cgroup subsystem value for the container.
bool(* set_cgroup_item )(struct lxc_container *c, const char *subsys, const char *value)
 Set the specified cgroup subsystem value for the container.
const char *(* get_config_path )(struct lxc_container *c)
 Determine full path to the containers configuration file. Each container can have a custom configuration path. However by default it will be set to either the LXCPATH configure variable, or the lxcpath value in the LXC_GLOBAL_CONF configuration file (i.e. /etc/lxc/lxc.conf). The value for a specific container can be changed using set_config_path. There is no other way to specify this in general at the moment.
bool(* set_config_path )(struct lxc_container *c, const char *path)
 Set the full path to the containers configuration file.
struct lxc_container *(* clone )(struct lxc_container *c, const char *newname, const char *lxcpath, int flags, const char *bdevtype, const char *bdevdata, uint64_t newsize, char **hookargs)
 Copy a stopped container.
int(* console_getfd )(struct lxc_container *c, int *ttynum, int *masterfd)
 Allocate a console tty for the container.
int(* console )(struct lxc_container *c, int ttynum, int stdinfd, int stdoutfd, int stderrfd, int escape)
 Allocate and run a console tty.
int(* attach )(struct lxc_container *c, lxc_attach_exec_t exec_function, void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process)
 Create a sub-process attached to a container and run a function inside it.
int(* attach_run_wait )(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *const argv[])
 Run a program inside a container and wait for it to exit.
int(* attach_run_waitl )(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg,...)
 Run a program inside a container and wait for it to exit (list variant).
int(* snapshot )(struct lxc_container *c, const char *commentfile)
 Create a container snapshot.
int(* snapshot_list )(struct lxc_container *c, struct lxc_snapshot **snapshots)
 Obtain a list of container snapshots.
bool(* snapshot_restore )(struct lxc_container *c, const char *snapname, const char *newname)
 Create a new container based on a snapshot.
bool(* snapshot_destroy )(struct lxc_container *c, const char *snapname)
 Destroy the specified snapshot.
bool(* may_control )(struct lxc_container *c)
 Determine if the caller may control the container.
bool(* add_device_node )(struct lxc_container *c, const char *src_path, const char *dest_path)
 Add specified device to the container.
bool(* remove_device_node )(struct lxc_container *c, const char *src_path, const char *dest_path)
 Remove specified device from the container.

Detailed Description

An LXC container.


Field Documentation

bool(* lxc_container::add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path)

Add specified device to the container.

Parameters:
c Container.
src_path Full path of the device.
dest_path Alternate path in the container (or NULL to use src_path).
Returns:
true on success, else false.
int(* lxc_container::attach)(struct lxc_container *c, lxc_attach_exec_t exec_function, void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process)

Create a sub-process attached to a container and run a function inside it.

Parameters:
c Container.
exec_function Function to run.
exec_payload Data to pass to exec_function.
options lxc_attach_options_t.
[out] attached_process Process ID of process running inside container c that is running exec_function.
Returns:
0 on success, -1 on error.
int(* lxc_container::attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *const argv[])

Run a program inside a container and wait for it to exit.

Parameters:
c Container.
options See attach options.
program Full path inside container of program to run.
argv Array of arguments to pass to program.
Returns:
waitpid(2) status of exited process that ran program, or -1 on error.
int(* lxc_container::attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg,...)

Run a program inside a container and wait for it to exit (list variant).

Parameters:
c Container.
options See attach options.
program Full path inside container of program to run.
... Command-line to pass to program (must end in NULL).
Returns:
waitpid(2) status of exited process that ran program, or -1 on error.

Completely clear the containers in-memory configuration.

Parameters:
c Container.
bool(* lxc_container::clear_config_item)(struct lxc_container *c, const char *key)

Clear a configuration item.

Parameters:
c Container.
key Name of option to clear.
Returns:
true on success, else false.
Note:
Analog of set_config_item.
struct lxc_container*(* lxc_container::clone)(struct lxc_container *c, const char *newname, const char *lxcpath, int flags, const char *bdevtype, const char *bdevdata, uint64_t newsize, char **hookargs) [read]

Copy a stopped container.

Parameters:
c Original container.
newname New name for the container. If NULL, the same name is used and a new lxcpath MUST be specified.
lxcpath lxcpath in which to create the new container. If NULL, the original container's lxcpath will be used. (XXX: should we use the default instead?)
flags Additional LXC_CLONE* flags to change the cloning behaviour:

bdevtype Optionally force the cloned bdevtype to a specified plugin. By default the original is used (subject to snapshot requirements).
bdevdata Information about how to create the new storage (i.e. fstype and fsdata).
newsize In case of a block device backing store, an optional size. If 0, the original backing store's size will be used if possible. Note this only applies to the rootfs. For any other filesystems, the original size will be duplicated.
hookargs Additional arguments to pass to the clone hook script.
Returns:
Newly-allocated copy of container c, or NULL on error.
Note:
If devtype was not specified, and flags contains LXC_CLONE_SNAPSHOT then use the native bdevtype if possible, else use an overlayfs.

Return current config file name.

Parameters:
c Container.
Returns:
config file name, or NULL on error.
Note:
The result is allocated, so the caller must free the result.

Full path to configuration file

int(* lxc_container::console)(struct lxc_container *c, int ttynum, int stdinfd, int stdoutfd, int stderrfd, int escape)

Allocate and run a console tty.

Parameters:
c Container.
ttynum Terminal number to attempt to allocate, -1 to allocate the first available tty or 0 to allocate the console.
stdinfd File descriptor to read input from.
stdoutfd File descriptor to write output to.
stderrfd File descriptor to write error output to.
escape The escape character (1 == 'a', 2 == 'b', ...).
Returns:
0 on success, -1 on failure.
Note:
This function will not return until the console has been exited by the user.
int(* lxc_container::console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd)

Allocate a console tty for the container.

Parameters:
c Container.
[in,out] ttynum Terminal number to attempt to allocate, or -1 to allocate the first available tty.
[out] masterfd File descriptor referring to the master side of the pty.
Returns:
tty file descriptor number on success, or -1 on failure.
Note:
On successful return, ttynum will contain the tty number that was allocated.
The returned file descriptor is used to keep the tty allocated. The caller should call close(2) on the returned file descriptor when no longer required so that it may be allocated by another caller.
bool(* lxc_container::create)(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags, char *const argv[])

Create a container.

Parameters:
c Container (with lxcpath, name and a starting configuration set).
t Template to execute to instantiate the root filesystem and adjust the configuration.
bdevtype Backing store type to use (if NULL, dir will be used).
specs Additional parameters for the backing store (for example LVM volume group to use).
flags LXC_CREATE_* options (currently only LXC_CREATE_QUIET is supported).
argv Arguments to pass to the template, terminated by NULL (if no arguments are required, just pass NULL).
Returns:
true on success, else false.
bool(* lxc_container::createl)(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags,...)

Create a container (list variant).

Parameters:
c Container (with lxcpath, name and a starting configuration set).
t Template to execute to instantiate the root filesystem and adjust the configuration.
bdevtype Backing store type to use (if NULL, dir will be used).
specs Additional parameters for the backing store (for example LVM volume group to use).
flags LXC_CREATE_* options (currently only LXC_CREATE_QUIET is supported).
... Command-line to pass to init (must end in NULL).
Returns:
true on success, else false.
Note:
Identical to create except that the template arguments are specified as a list rather than an array of pointers.

Whether container wishes to be daemonized

Delete the container.

Parameters:
c Container.
Returns:
true on success, else false.
Note:
Container must be stopped and have no dependent snapshots.

Last error number

Human-readable string representing last error

Freeze running container.

Parameters:
c Container.
Returns:
true on success, else false.
int(* lxc_container::get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen)

Retrieve the specified cgroup subsystem value for the container.

Parameters:
c Container.
subsys cgroup subsystem to retrieve.
[out] retv Caller-allocated buffer to write value of subsys into (or NULL to determine length of value).
inlen length of retv (may be zero).
Returns:
Length of subsys value, or < 0 on error.
Note:
If retv is NULL, inlen is ignored.
If inlen is smaller than required, the value written to retv will be truncated.
int(* lxc_container::get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen)

Retrieve the value of a config item.

Parameters:
c Container.
key Name of option to get.
[out] retv Caller-allocated buffer to write value of key into (or NULL to determine length of value).
inlen Length of retv (may be zero).
Returns:
Length of config items value, or < 0 on error.
Note:
The caller can (and should) determine how large a buffer to allocate for retv by initially passing its value as NULL and considering the return value. This function can then be called again passing a newly-allocated suitably-sized buffer.
If retv is NULL, inlen is ignored.
If inlen is smaller than required, the value written to retv will be truncated.
const char*(* lxc_container::get_config_path)(struct lxc_container *c)

Determine full path to the containers configuration file. Each container can have a custom configuration path. However by default it will be set to either the LXCPATH configure variable, or the lxcpath value in the LXC_GLOBAL_CONF configuration file (i.e. /etc/lxc/lxc.conf). The value for a specific container can be changed using set_config_path. There is no other way to specify this in general at the moment.

Parameters:
c Container.
Returns:
Static string representing full path to configuration file.
Note:
Returned string must not be freed.

Obtain a list of network interfaces.

Parameters:
c Container.
Returns:
Newly-allocated array of network interfaces, or NULL on error.
Note:
The returned array is allocated, so the caller must free it.
The returned array is terminated with a NULL entry.
char**(* lxc_container::get_ips)(struct lxc_container *c, const char *interface, const char *family, int scope)

Determine the list of container IP addresses.

Parameters:
c Container.
interface Network interface name to consider.
family Network family (for example "inet", "inet6").
scope IPv6 scope id (ignored if family is not "inet6").
Returns:
Newly-allocated array of network interfaces, or NULL on error.
Note:
The returned array is allocated, so the caller must free it.
The returned array is terminated with a NULL entry.
int(* lxc_container::get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen)

Retrieve a list of config item keys given a key prefix.

Parameters:
c Container.
key Name of option to get.
[out] retv Caller-allocated buffer to write list of keys to (or NULL to determine overall length of keys list).
inlen Length of retv (may be zero).
Returns:
Length of keys list, or < 0 on error.
Note:
The list values written to retv are separated by a newline character ('\n').
The caller can (and should) determine how large a buffer to allocate for retv by initially passing its value as NULL and considering the return value. This function can then be called again passing a newly-allocated suitably-sized buffer.
If retv is NULL, inlen is ignored.
If inlen is smaller than required, the value written to retv will be truncated.
char*(* lxc_container::get_running_config_item)(struct lxc_container *c, const char *key)

Retrieve the value of a config item from running container.

Parameters:
c Container.
key Name of option to get.
Returns:
the item or NULL on error.
Note:
Returned string must be freed by the caller.

Determine process ID of the containers init process.

Parameters:
c Container.
Returns:
pid of init process as seen from outside the container.

Determine if /var/lib/lxc/$name/config exists.

Parameters:
c Container.
Returns:
true if container is defined, else false.

Determine if container is running.

Parameters:
c Container.
Returns:
true on success, else false.
bool(* lxc_container::load_config)(struct lxc_container *c, const char *alt_file)

Load the specified configuration for the container.

Parameters:
c Container.
alt_file Full path to alternate configuration file, or NULL to use the default configuration file.
Returns:
true on success, else false.

Determine if the caller may control the container.

Parameters:
c Container.
Returns:
false if there is a control socket for the container monitor and the caller may not access it, otherwise returns true.

Request the container reboot by sending it SIGINT.

Parameters:
c Container.
Returns:
true if reboot request successful, else false.
bool(* lxc_container::remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path)

Remove specified device from the container.

Parameters:
c Container.
src_path Full path of the device.
dest_path Alternate path in the container (or NULL to use src_path).
Returns:
true on success, else false.
bool(* lxc_container::rename)(struct lxc_container *c, const char *newname)

Rename a container.

Parameters:
c Container.
newname New name to be used for the container.
Returns:
true on success, else false.
bool(* lxc_container::save_config)(struct lxc_container *c, const char *alt_file)

Save configuaration to a file.

Parameters:
c Container.
alt_file Full path to file to save configuration in.
Returns:
true on success, else false.
bool(* lxc_container::set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value)

Set the specified cgroup subsystem value for the container.

Parameters:
c Container.
subsys cgroup subsystem to consider.
value Value to set for subsys.
Returns:
true on success, else false.
bool(* lxc_container::set_config_item)(struct lxc_container *c, const char *key, const char *value)

Set a key/value configuration option.

Parameters:
c Container.
key Name of option to set.
value Value of name to set.
Returns:
true on success, else false.
bool(* lxc_container::set_config_path)(struct lxc_container *c, const char *path)

Set the full path to the containers configuration file.

Parameters:
c Container.
path Full path to configuration file.
Returns:
true on success, else false.
bool(* lxc_container::shutdown)(struct lxc_container *c, int timeout)

Request the container shutdown by sending it SIGPWR.

Parameters:
c Container.
timeout Seconds to wait before returning false. (-1 to wait forever, 0 to avoid waiting).
Returns:
true if the container was shutdown successfully, else false.
int(* lxc_container::snapshot)(struct lxc_container *c, const char *commentfile)

Create a container snapshot.

Assuming default paths, snapshots will be created as /var/lib/lxcsnaps/<c>/snap<n> where <c> represents the container name and <n> represents the zero-based snapshot number.

Parameters:
c Container.
commentfile Full path to file containing a description of the snapshot.
Returns:
-1 on error, or zero-based snapshot number.
Note:
commentfile may be NULL but this is discouraged.
bool(* lxc_container::snapshot_destroy)(struct lxc_container *c, const char *snapname)

Destroy the specified snapshot.

Parameters:
c Container.
snapname Name of snapshot.
Returns:
true on success, else false.
int(* lxc_container::snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots)

Obtain a list of container snapshots.

Parameters:
c Container.
[out] snapshots Dynamically-allocated Array of lxc_snapshot's.
Returns:
Number of snapshots.
Note:
The array returned in snapshots is allocated, so the caller must free it.
To free an individual snapshot as returned in snapshots, call the snapshots free function (see src/tests/snapshot.c for an example).
bool(* lxc_container::snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname)

Create a new container based on a snapshot.

The restored container will be a copy (not snapshot) of the snapshot, and restored in the lxcpath of the original container.

Parameters:
c Container.
snapname Name of snapshot.
newname Name to be used for the restored snapshot.
Returns:
true on success, else false.
Warning:
If newname is the same as the current container name, the container will be destroyed. However, this will fail if the snapshot is overlay-based, since the snapshots will pin the original container.
Note:
As an example, if the container exists as /var/lib/lxc/c1, snapname might be 'snap0' (representing /var/lib/lxcsnaps/c1/snap0). If newname is c2, then snap0 will be copied to /var/lib/lxc/c2.
bool(* lxc_container::start)(struct lxc_container *c, int useinit, char *const argv[])

Start the container.

Parameters:
c Container.
useinit Use lxcinit rather than /sbin/init.
argv Array of arguments to pass to init.
Returns:
true on success, else false.
bool(* lxc_container::startl)(struct lxc_container *c, int useinit,...)

Start the container (list variant).

Parameters:
c Container.
useinit Use lxcinit rather than /sbin/init.
... Command-line to pass to init (must end in NULL).
Returns:
true on success, else false.
Note:
Identical to start except that that the init arguments are specified via a list rather than an array of pointers.
const char*(* lxc_container::state)(struct lxc_container *c)

Determine state of container.

Parameters:
c Container.
Returns:
Static upper-case string representing state of container.
Note:
Returned string must not be freed.
bool(* lxc_container::stop)(struct lxc_container *c)

Stop the container.

Parameters:
c Container.
Returns:
true on success, else false.

Thaw a frozen container.

Parameters:
c Container.
Returns:
true on success, else false.
bool(* lxc_container::wait)(struct lxc_container *c, const char *state, int timeout)

Wait for container to reach a particular state.

Parameters:
c Container.
state State to wait for.
timeout Timeout in seconds.
Returns:
true if state reached within timeout, else false.
Note:
A timeout of -1 means wait forever. A timeout of 0 means do not wait.

Determine whether container wishes all file descriptors to be closed on startup.

Parameters:
c Container.
state Value for the close_all_fds bit (0 or 1).
Returns:
true if container wants all file descriptors closed, else false.

Determine if the container wants to run disconnected from the terminal.

Parameters:
c Container.
state Value for the daemonize bit (0 or 1).
Returns:
true if container wants to be daemonised, else false.

The documentation for this struct was generated from the following file:
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 10 Dec 2015 for LXC by  doxygen 1.6.1