#include <lxccontainer.h>

Collaboration diagram for lxc_container:

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. More...

const char (	state )(struct lxc_container *c)
	Determine state of container. More...

bool(*	is_running )(struct lxc_container *c)
	Determine if container is running. More...

bool(*	freeze )(struct lxc_container *c)
	Freeze running container. More...

bool(*	unfreeze )(struct lxc_container *c)
	Thaw a frozen container. More...

pid_t(*	init_pid )(struct lxc_container *c)
	Determine process ID of the containers init process. More...

bool(*	load_config )(struct lxc_container c, const char alt_file)
	Load the specified configuration for the container. More...

bool(*	start )(struct lxc_container c, int useinit, char const argv[])
	Start the container. More...

bool(*	startl )(struct lxc_container *c, int useinit,...)
	Start the container (list variant). More...

bool(*	stop )(struct lxc_container *c)
	Stop the container. More...

bool(*	want_daemonize )(struct lxc_container *c, bool state)
	Change whether the container wants to run disconnected from the terminal. More...

bool(*	want_close_all_fds )(struct lxc_container *c, bool state)
	Change whether the container wishes all file descriptors to be closed on startup. More...

char (	config_file_name )(struct lxc_container *c)
	Return current config file name. More...

bool(*	wait )(struct lxc_container c, const char state, int timeout)
	Wait for container to reach a particular state. More...

bool(*	set_config_item )(struct lxc_container c, const char key, const char *value)
	Set a key/value configuration option. More...

bool(*	destroy )(struct lxc_container *c)
	Delete the container. More...

bool(*	save_config )(struct lxc_container c, const char alt_file)
	Save configuaration to a file. More...

bool(*	create )(struct lxc_container c, const char t, const char bdevtype, struct bdev_specs specs, int flags, char *const argv[])
	Create a container. More...

bool(*	createl )(struct lxc_container c, const char t, const char bdevtype, struct bdev_specs specs, int flags,...)
	Create a container (list variant). More...

bool(*	rename )(struct lxc_container c, const char newname)
	Rename a container. More...

bool(*	reboot )(struct lxc_container *c)
	Request the container reboot by sending it `SIGINT`. More...

bool(*	shutdown )(struct lxc_container *c, int timeout)
	Request the container shutdown by sending it `SIGPWR`. More...

void(*	clear_config )(struct lxc_container *c)
	Completely clear the containers in-memory configuration. More...

bool(*	clear_config_item )(struct lxc_container c, const char key)
	Clear a configuration item. More...

int(*	get_config_item )(struct lxc_container c, const char key, char *retv, int inlen)
	Retrieve the value of a config item. More...

char (	get_running_config_item )(struct lxc_container c, const char key)
	Retrieve the value of a config item from running container. More...

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. More...

char *(	get_interfaces )(struct lxc_container *c)
	Obtain a list of network interfaces. More...

char *(	get_ips )(struct lxc_container c, const char interface, const char *family, int scope)
	Determine the list of container IP addresses. More...

int(*	get_cgroup_item )(struct lxc_container c, const char subsys, char *retv, int inlen)
	Retrieve the specified cgroup subsystem value for the container. More...

bool(*	set_cgroup_item )(struct lxc_container c, const char subsys, const char *value)
	Set the specified cgroup subsystem value for the container. More...

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. More...

bool(*	set_config_path )(struct lxc_container c, const char path)
	Set the full path to the containers configuration file. More...

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. More...

int(*	console_getfd )(struct lxc_container c, int ttynum, int *masterfd)
	Allocate a console tty for the container. More...

int(*	console )(struct lxc_container *c, int ttynum, int stdinfd, int stdoutfd, int stderrfd, int escape)
	Allocate and run a console tty. More...

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. More...

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. More...

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). More...

int(*	snapshot )(struct lxc_container c, const char commentfile)
	Create a container snapshot. More...

int(*	snapshot_list )(struct lxc_container c, struct lxc_snapshot *snapshots)
	Obtain a list of container snapshots. More...

bool(*	snapshot_restore )(struct lxc_container c, const char snapname, const char *newname)
	Create a new container based on a snapshot. More...

bool(*	snapshot_destroy )(struct lxc_container c, const char snapname)
	Destroy the specified snapshot. More...

bool(*	may_control )(struct lxc_container *c)
	Determine if the caller may control the container. More...

bool(*	add_device_node )(struct lxc_container c, const char src_path, const char *dest_path)
	Add specified device to the container. More...

bool(*	remove_device_node )(struct lxc_container c, const char src_path, const char *dest_path)
	Remove specified device from the container. More...

Detailed Description

An LXC container.

Note that changing the order of struct members is an API change, as callers will end up having the wrong offset when calling a function. So when making changes, whenever possible stick to simply appending new members.

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.

void(* lxc_container::clear_config)(struct lxc_container *c)

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)

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: LXC_CLONE_KEEPNAME LXC_CLONE_KEEPMACADDR LXC_CLONE_SNAPSHOT
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.

char*(* lxc_container::config_file_name)(struct lxc_container *c)

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.

char* lxc_container::config_path

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.

bool lxc_container::daemonize

Whether container wishes to be daemonized

bool(* lxc_container::destroy)(struct lxc_container *c)

Delete the container.

Parameters

c	Container.

Returns: true on success, else false.

Note: Container must be stopped and have no dependent snapshots.

int lxc_container::error_num

Last error number

char* lxc_container::error_string

Human-readable string representing last error

bool(* lxc_container::freeze)(struct lxc_container *c)

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, nothing will be written to retv and still return the length of config item value.

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.

char**(* lxc_container::get_interfaces)(struct lxc_container *c)

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.

pid_t(* lxc_container::init_pid)(struct lxc_container *c)

Determine process ID of the containers init process.

Parameters

c	Container.

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

bool(* lxc_container::is_defined)(struct lxc_container *c)

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

Parameters

c	Container.

Returns: true if container is defined, else false.

bool(* lxc_container::is_running)(struct lxc_container *c)

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.

bool(* lxc_container::may_control)(struct lxc_container *c)

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.

bool(* lxc_container::reboot)(struct lxc_container *c)

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.

bool(* lxc_container::unfreeze)(struct lxc_container *c)

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.

bool(* lxc_container::want_close_all_fds)(struct lxc_container *c, bool state)

Change whether the 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 on success, else false.

bool(* lxc_container::want_daemonize)(struct lxc_container *c, bool state)

Change whether the container wants to run disconnected from the terminal.

Parameters

c	Container.
state	Value for the daemonize bit (0 or 1).

Returns: true on success, else false.

The documentation for this struct was generated from the following file:

lxccontainer.h

Data Fields

Detailed Description

Field Documentation