Add '--enable-api-docs' for doxygen-generated public API docs.

.gitignore

@@ -118,6 +118,7 @@ doc/ja/legacy/*.1
 doc/legacy/*.1
 doc/manpage.links
 doc/manpage.refs
+doc/api/html/*
 
 m4/
 

configure.ac

@@ -108,6 +108,19 @@ else
 fi
 AC_SUBST(docdtd)
 
+# Documentation (API)
+AC_ARG_ENABLE([api-docs],
+	[AC_HELP_STRING([--enable-api-docs],
+	[make API documentation (requires doxygen to be installed) [default=auto]])],
+	[], [enable_api_docs=auto])
+
+if test "x$enable_api_docs" = "xyes" -o "x$enable_api_docs" = "xauto"; then
+    AC_CHECK_PROGS([HAVE_DOXYGEN],[doxygen])
+    AC_SUBST([HAVE_DOXYGEN])
+fi
+
+AM_CONDITIONAL([ENABLE_API_DOCS], [test ! -z "$HAVE_DOXYGEN"])
+
 # Apparmor
 AC_ARG_ENABLE([apparmor],
 	[AC_HELP_STRING([--enable-apparmor], [enable apparmor])],
@@ -431,6 +444,7 @@ AC_CONFIG_FILES([
 	config/Makefile
 
 	doc/Makefile
+	doc/api/Makefile
 	doc/legacy/lxc-ls.sgml
 	doc/lxc-attach.sgml
 	doc/lxc-cgroup.sgml

doc/Makefile.am

 SUBDIRS = examples rootfs
-DIST_SUBDIRS = examples rootfs ja
+DIST_SUBDIRS = examples rootfs ja api
 
 if USE_DOCBOOK2X
 SUBDIRS += ja
 endif
 
+if ENABLE_API_DOCS
+SUBDIRS += api
+endif
+
 EXTRA_DIST = \
 	FAQ.txt
 

doc/api/Makefile.am

+EXTRA_DIST = Doxyfile
+
+if ENABLE_API_DOCS
+html: Doxyfile
+	doxygen
+endif
+
+.PHONY: html
+
+all-local: html
+
+clean-local:
+	$(RM) -rf html

src/lxc/attach_options.h

-/*
+/*! \file
+ *
  * lxc: linux Container library
  *
  * (C) Copyright IBM Corp. 2007, 2008
@@ -26,74 +27,107 @@
 
 #include <sys/types.h>
 
+/*!
+ * LXC environment policy.
+ */
 typedef enum lxc_attach_env_policy_t {
-	LXC_ATTACH_KEEP_ENV,
-	LXC_ATTACH_CLEAR_ENV
+	LXC_ATTACH_KEEP_ENV,   //!< Retain the environment
+	LXC_ATTACH_CLEAR_ENV   //!< Clear the environment
 } lxc_attach_env_policy_t;
 
 enum {
 	/* the following are on by default: */
-	LXC_ATTACH_MOVE_TO_CGROUP        = 0x00000001,
-	LXC_ATTACH_DROP_CAPABILITIES     = 0x00000002,
-	LXC_ATTACH_SET_PERSONALITY       = 0x00000004,
-	LXC_ATTACH_LSM_EXEC              = 0x00000008,
+	LXC_ATTACH_MOVE_TO_CGROUP        = 0x00000001, //!< Move to cgroup
+	LXC_ATTACH_DROP_CAPABILITIES     = 0x00000002, //!< Drop capabilities
+	LXC_ATTACH_SET_PERSONALITY       = 0x00000004, //!< Set personality
+	LXC_ATTACH_LSM_EXEC              = 0x00000008, //!< Execute under a Linux Security Module 
 
 	/* the following are off by default */
-	LXC_ATTACH_REMOUNT_PROC_SYS      = 0x00010000,
-	LXC_ATTACH_LSM_NOW               = 0x00020000,
+	LXC_ATTACH_REMOUNT_PROC_SYS      = 0x00010000, //!< Remount /proc filesystem
+	LXC_ATTACH_LSM_NOW               = 0x00020000, //!< FIXME: unknown
 
 	/* we have 16 bits for things that are on by default
 	 * and 16 bits that are off by default, that should
 	 * be sufficient to keep binary compatibility for
 	 * a while
 	 */
-	LXC_ATTACH_DEFAULT               = 0x0000FFFF
+	LXC_ATTACH_DEFAULT               = 0x0000FFFF  //!< Mask of flags to apply by default
 };
 
+/*! All Linux Security Module flags */
 #define LXC_ATTACH_LSM (LXC_ATTACH_LSM_EXEC | LXC_ATTACH_LSM_NOW)
 
-typedef struct lxc_attach_options_t lxc_attach_options_t;
+/*! LXC attach function type.
+ *
+ * Function to run in container.
+ *
+ * \param payload \ref lxc_attach_command_t to run.
+ *
+ * \return Function should return \c 0 on success, and any other value to denote failure.
+ */
 typedef int (*lxc_attach_exec_t)(void* payload);
 
-struct lxc_attach_options_t {
-	/* any combination of the above enum */
+/*!
+ * LXC attach options for \ref lxc_container \c attach().
+ */
+typedef struct lxc_attach_options_t {
+	/*! Any combination of LXC_ATTACH_* flags */
 	int attach_flags;
-	/* the namespaces to attach to (CLONE_NEW... flags) */
+
+	/*! The namespaces to attach to (CLONE_NEW... flags) */
 	int namespaces;
-	/* initial personality, -1 to autodetect
-	 * (may be ignored if lxc is compiled w/o personality support) */
+
+	/*! Initial personality (\c -1 to autodetect).
+	 * \warning This may be ignored if lxc is compiled without personality support)
+	 */
 	long personality;
 
-	/* inital current directory, use NULL to use cwd
-	 * (might not exist in container, then / will be
-	 * used because of kernel defaults)
+	/*! Inital current directory, use \c NULL to use cwd.
+	 * If the current directory does not exist in the container, the
+	 * root directory will be used instead because of kernel defaults.
 	 */
 	char* initial_cwd;
 
-	/* the uid and gid to attach to,
-	 * -1 for default (init uid/gid for userns containers,
-	 * otherwise or if detection fails 0/0)
+	/*! The user-id to run as.
+	 *
+	 * \note Set to \c -1 for default behaviour (init uid for userns
+	 * containers or \c 0 (super-user) if detection fails).
 	 */
 	uid_t uid;
+
+	/*! The group-id to run as.
+	 *
+	 * \note Set to \c -1 for default behaviour (init gid for userns
+	 * containers or \c 0 (super-user) if detection fails).
+	 */
 	gid_t gid;
 
-	/* environment handling */
+	/*! Environment policy */
 	lxc_attach_env_policy_t env_policy;
+
+	/*! Extra environment variables to set in the container environment */
 	char** extra_env_vars;
+
+	/*! Names of environment variables in existing environment to retain
+	 * in container environment.
+	 */
 	char** extra_keep_env;
 
-	/* file descriptors for stdin, stdout and stderr,
-	 * dup2() will be used before calling exec_function,
-	 * (assuming not 0, 1 and 2 are specified) and the
+	/**@{*/
+	/*! File descriptors for stdin, stdout and stderr,
+	 * \c dup2() will be used before calling exec_function,
+	 * (assuming not \c 0, \c 1 and \c 2 are specified) and the
 	 * original fds are closed before passing control
-	 * over. Any O_CLOEXEC flag will be removed after
-	 * that
+	 * over. Any \c O_CLOEXEC flag will be removed after
+	 * that.
 	 */
-	int stdin_fd;
-	int stdout_fd;
-	int stderr_fd;
-};
+	int stdin_fd; /*!< stdin file descriptor */
+	int stdout_fd; /*!< stdout file descriptor */
+	int stderr_fd; /*!< stderr file descriptor */
+	/**@}*/
+} lxc_attach_options_t;
 
+/*! Default attach options to use */
 #define LXC_ATTACH_OPTIONS_DEFAULT \
 	{ \
 		/* .attach_flags = */   LXC_ATTACH_DEFAULT, \
@@ -108,16 +142,30 @@ struct lxc_attach_options_t {
 		/* .stdin_fd = */       0, 1, 2 \
 	}
 
+/*!
+ * Representation of a command to run in a container.
+ */
 typedef struct lxc_attach_command_t {
-	char* program; /* the program to run (passed to execvp) */
-	char** argv;   /* the argv pointer of that program, including the program itself in argv[0] */
+	char* program; /*!< The program to run (passed to execvp) */
+	char** argv;   /*!< The argv pointer of that program, including the program itself in argv[0] */
 } lxc_attach_command_t;
 
-/* default execution functions:
- *   run_command: pointer to lxc_attach_command_t
- *   run_shell:   no payload, will be ignored
+/*!
+ * \brief Run a command in the container.
+ *
+ * \param payload \ref lxc_attach_command_t to run.
+ *
+ * \return \c -1 on error, exit code of lxc_attach_command_t program on success.
  */
 extern int lxc_attach_run_command(void* payload);
+
+/*!
+ * \brief Run a shell command in the container.
+ *
+ * \param payload Not used.
+ *
+ * \return Exit code of shell.
+ */
 extern int lxc_attach_run_shell(void* payload);
 
 #endif

src/lxc/lxclock.h

-#ifndef __LXCLOCK_H
-#define __LXCLOCK_H
-/* liblxcapi
+/*! \file
+ *
+ * liblxcapi
  *
  * Copyright © 2012 Serge Hallyn <serge.hallyn@ubuntu.com>.
  * Copyright © 2012 Canonical Ltd.
@@ -9,17 +9,20 @@
  *  modify it under the terms of the GNU Lesser General Public
  *  License as published by the Free Software Foundation; either
  *  version 2.1 of the License, or (at your option) any later version.
-
+ *
  *  This library is distributed in the hope that it will be useful,
  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  *  Lesser General Public License for more details.
-
+ *
  *  You should have received a copy of the GNU Lesser General Public
  *  License along with this library; if not, write to the Free Software
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
+#ifndef __LXCLOCK_H
+#define __LXCLOCK_H
+
 #include <fcntl.h>           /* For O_* constants */
 #include <sys/stat.h>        /* For mode constants */
 #include <sys/file.h>
@@ -27,72 +30,140 @@
 #include <string.h>
 #include <time.h>
 
-#define LXC_LOCK_ANON_SEM 1
-#define LXC_LOCK_FLOCK 2
+#define LXC_LOCK_ANON_SEM 1 /*!< Anonymous semaphore lock */
+#define LXC_LOCK_FLOCK    2 /*!< flock(2) lock */
+
+// private
+/*!
+ * LXC Lock
+*/
 struct lxc_lock {
-	short type;
+	short type; //!< Lock type
+
 	union {
-		sem_t *sem; // an anonymous semaphore
+		sem_t *sem; //!< Anonymous semaphore (LXC_LOCK_ANON_SEM)
+		/*! LXC_LOCK_FLOCK details */
 		struct {
-			int fd; // fd on which a lock is held (if not -1)
-			char *fname;
+			int   fd; //!< fd on which a lock is held (if not -1)
+			char *fname; //!< Name of lock
 		} f;
-	} u;
+	} u; //!< Container for lock type elements
 };
 
-/*
- * lxc_newlock: Create a new (unlocked) lock.
+/*!
+ * \brief Create a new (unlocked) lock.
+ *
+ * \param lxcpath lxcpath lock should relate to.
+ * \param name Name for lock.
+ *
+ * \return Newly-allocated lxclock on success, \c NULL on failure.
+
+ * \note If \p name is not given, create an unnamed semaphore
+ *  (used to protect against racing threads).
+ *
+ * \note Note that an unnamed sem was malloced by us and needs to be freed.
  *
- * if name is not given, create an unnamed semaphore.  We use these
- * to protect against racing threads.
- * Note that an unnamed sem was malloced by us and needs to be freed.
+ * \internal \ref sem is initialized to a value of \c 1.
+ * A 'sem_t *' which can be passed to \ref lxclock() and \ref lxcunlock()
+ * will be placed in \c l->u.sem.
  *
- * sem is initialized to value of 1
- * A sem_t * which can be passed to lxclock() and lxcunlock()
- * will be placed in l->u.sem
+ * If \ref lxcpath and \ref name are given (both must be given if either is
+ * given) then a lockfile is created as \c $lxcpath/$lxcname/locks/$name.
+ * The lock is used to protect the containers on-disk representation.
  *
- * If lxcpath and name are given (both must be given if either is
- * given) then a lockfile is created, $lxcpath/$lxcname/locks/$name.
- * We use that to protect the containers as represented on disk.
- * lxc_newlock() for the named lock only allocates the pathname in
- * memory so we can quickly open+lock it at lxclock.
- * l->u.f.fname will contain the malloc'ed name (which must be
- * freed when the container is freed), and u.f.fd = -1.
+ * \internal This function allocates the pathname for the given lock in memory
+ * such that it can be can quickly opened and locked by \ref lxclock().
+ * \c l->u.f.fname will contain the malloc'ed name (which must be
+ * freed when the container is freed), and \c u.f.fd = -1.
  *
- * return lxclock on success, NULL on failure.
  */
 extern struct lxc_lock *lxc_newlock(const char *lxcpath, const char *name);
 
-/*
- * lxclock: take an existing lock.  If timeout is 0, wait
- * indefinately.  Otherwise use given timeout.
- * return 0 if we got the lock, -2 on failure to set timeout, or -1
- * otherwise in which case errno will be set by sem_wait()).
+/*!
+ * \brief Take an existing lock.
+ *
+ * \param lock Lock to operate on.
+ * \param timeout Seconds to wait to take lock (\c 0 signifies an
+ * indefinite wait).
  *
- * Note that timeout is (currently?) only supported for privlock, not
+ * \return \c 0 if lock obtained, \c -2 on failure to set timeout,
+ *  or \c -1 on any other error (\c errno will be set by \c sem_wait(3)).
+ *
+ * \note \p timeout is (currently?) only supported for privlock, not
  * for slock.  Since currently there is not a single use of the timeout
  * (except in the test case) I may remove the support for it in sem as
  * well.
  */
 extern int lxclock(struct lxc_lock *lock, int timeout);
 
-/*
- * lxcunlock: unlock given sem.  Return 0 on success, or -2 if we did not
- * have the lock.  Otherwise returns -1 with errno saved from flock
- * or sem_post function.
+/*!
+ * \brief Unlock specified lock previously locked using \ref lxclock().
+ *
+ * \param lock \ref lxc_lock.
+ *
+ * \return \c 0 on success, \c -2 if provided lock was not already held,
+ * otherwise \c -1 with \c errno saved from \c flock(2) or sem_post function.
  */
 extern int lxcunlock(struct lxc_lock *lock);
 
-extern void lxc_putlock(struct lxc_lock *l);
+/*!
+ * \brief Free a lock created by \ref lxc_newlock().
+ *
+ * \param lock Lock.
+ */
+extern void lxc_putlock(struct lxc_lock *lock);
 
+/*!
+ * \brief Lock the current process.
+ */
 extern void process_lock(void);
+
+/*!
+ * \brief Unlock the current process.
+ */
 extern void process_unlock(void);
+
+/*!
+ * \brief Lock global data.
+ */
 extern void static_lock(void);
+
+/*!
+ * \brief Unlock global data.
+ */
 extern void static_unlock(void);
 
 struct lxc_container;
+
+/*!
+ * \brief Lock the containers memory.
+ *
+ * \param c Container.
+ *
+ * \return As for \ref lxclock().
+ */
 extern int container_mem_lock(struct lxc_container *c);
+
+/*!
+ * \brief Unlock the containers memory.
+ *
+ * \param c Container.
+ */
 extern void container_mem_unlock(struct lxc_container *c);
+
+/*!
+ * \brief Lock the containers disk data.
+ *
+ * \param c Container.
+ *
+ * \return \c 0 on success, or an \ref lxclock() error return
+ * values on error.
+ */
 extern int container_disk_lock(struct lxc_container *c);
+
+/*!
+ * \brief Unlock the containers disk data.
+ */
 extern void container_disk_unlock(struct lxc_container *c);
+
 #endif