X-Git-Url: http://git.linux-vserver.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=util-vserver%2Flib%2Fvserver.h;h=467fa7eb56fd7cb258d672255d053798839961b9;hb=319929791248f823537ac5fb2fe10a01b5b820b9;hp=4c71fadb34c0e26c64a111db9eaf5f2a75eb036a;hpb=a40a1c7e557e92c0ccdc5aa67266cddecb487e3b;p=util-vserver.git
diff --git a/util-vserver/lib/vserver.h b/util-vserver/lib/vserver.h
index 4c71fad..467fa7e 100644
--- a/util-vserver/lib/vserver.h
+++ b/util-vserver/lib/vserver.h
@@ -33,14 +33,16 @@
#if defined(__GNUC__)
# define VC_ATTR_UNUSED __attribute__((__unused__))
# define VC_ATTR_NORETURN __attribute__((__noreturn__))
-# if __GNUC__>3 || (__GNUC__==3 && __GNUC_MINOR__>=3)
+# define VC_ATTR_CONST __attribute__((__const__))
+# define VC_ATTR_DEPRECATED __attribute__((__deprecated__))
+# if __GNUC__*0x10000 + __GNUC_MINOR__*0x100 + __GNUC_PATCHLEVEL__ >= 0x30300
# define VC_ATTR_NONNULL(ARGS) __attribute__((__nonnull__ ARGS))
# define VC_ATTR_ALWAYSINLINE __attribute__((__always_inline__))
# else
# define VC_ATTR_NONNULL(ARGS)
# define VC_ATTR_ALWAYSINLINE
# endif
-# if __GNUC__>3
+# if __GNUC__*0x10000 + __GNUC_MINOR__*0x100 + __GNUC_PATCHLEVEL__ >= 0x30303
# define VC_ATTR_PURE __attribute__((__pure__))
# else
# define VC_ATTR_PURE
@@ -50,17 +52,23 @@
# define VC_ATTR_UNUSED
# define VC_ATTR_NORETURN
# define VC_ATTR_ALWAYSINLINE
+# define VC_ATTR_DEPRECATED
# define VC_ATTR_PURE
+# define VC_ATTR_CONST
#endif
#endif // IS_DOXYGEN
/** the value which is returned in error-case (no ctx found) */
#define VC_NOCTX ((xid_t)(-1))
+#define VC_NOXID ((xid_t)(-1))
/** the value which means a random (the next free) ctx */
#define VC_DYNAMIC_XID ((xid_t)(-1))
/** the value which means the current ctx */
#define VC_SAMECTX ((xid_t)(-2))
+#define VC_NONID ((nid_t)(-1))
+#define VC_DYNAMIC_NID ((nid_t)(-1))
+
#define VC_LIM_INFINITY (~0ULL)
#define VC_LIM_KEEP (~1ULL)
@@ -128,20 +136,68 @@
#define VC_CAP_LEASE 28
#define VC_CAP_QUOTACTL 29
-#define VC_IMMUTABLE_FILE_FL 0x00000010l
-#define VC_IMMUTABLE_LINK_FL 0x00008000l
+#define VC_IMMUTABLE_FILE_FL 0x0000010lu
+#define VC_IMMUTABLE_LINK_FL 0x0008000lu
#define VC_IMMUTABLE_ALL (VC_IMMUTABLE_LINK_FL|VC_IMMUTABLE_FILE_FL)
-#define VC_IATTR_XID 0x01000000
+#define VC_IATTR_XID 0x01000000u
+
+#define VC_IATTR_ADMIN 0x00000001u
+#define VC_IATTR_WATCH 0x00000002u
+#define VC_IATTR_HIDE 0x00000004u
+#define VC_IATTR_FLAGS 0x00000007u
+
+#define VC_IATTR_BARRIER 0x00010000u
+#define VC_IATTR_IUNLINK 0x00020000u
+#define VC_IATTR_IMMUTABLE 0x00040000u
+
+
+// the flags
+#define VC_VXF_INFO_LOCK 0x00000001ull
+#define VC_VXF_INFO_NPROC 0x00000004ull
+#define VC_VXF_INFO_PRIVATE 0x00000008ull
+#define VC_VXF_INFO_INIT 0x00000010ull
+
+#define VC_VXF_INFO_HIDEINFO 0x00000020ull
+#define VC_VXF_INFO_ULIMIT 0x00000040ull
+#define VC_VXF_INFO_NAMESPACE 0x00000080ull
+
+#define VC_VXF_SCHED_HARD 0x00000100ull
+#define VC_VXF_SCHED_PRIO 0x00000200ull
+#define VC_VXF_SCHED_PAUSE 0x00000400ull
+
+#define VC_VXF_VIRT_MEM 0x00010000ull
+#define VC_VXF_VIRT_UPTIME 0x00020000ull
+#define VC_VXF_VIRT_CPU 0x00040000ull
+
+#define VC_VXF_HIDE_MOUNT 0x01000000ull
+#define VC_VXF_HIDE_NETIF 0x02000000ull
+
+#define VC_VXF_STATE_SETUP (1ULL<<32)
+#define VC_VXF_STATE_INIT (1ULL<<33)
+
+// the ccapabilities
+#define VC_VXC_SET_UTSNAME 0x00000001ull
+#define VC_VXC_SET_RLIMIT 0x00000002ull
-#define VC_IATTR_ADMIN 0x00000001
-#define VC_IATTR_WATCH 0x00000002
-#define VC_IATTR_HIDE 0x00000004
-#define VC_IATTR_FLAGS 0x00000007
+#define VC_VXC_ICMP_PING 0x00000100ull
-#define VC_IATTR_BARRIER 0x00010000
-#define VC_IATTR_IUNLINK 0x00020000
-#define VC_IATTR_IMMUTABLE 0x00040000
+#define VC_VXC_SECURE_MOUNT 0x00010000ull
+
+
+/** \defgroup syscalls Syscall wrappers
+ * Functions which are calling the vserver syscall directly. */
+
+/** \defgroup helper Helper functions
+ * Functions which are doing general helper tasks like parameter parsing. */
+
+/** \typedef an_unsigned_integer_type xid_t
+ * The identifier of a context. */
+
+#ifdef IS_DOXYGEN
+typedef an_unsigned_integer_type xid_t;
+typedef an_unsigned_integer_type nid_t;
+#endif
#ifdef __cplusplus
extern "C" {
@@ -149,15 +205,31 @@ extern "C" {
struct vc_ip_mask_pair {
uint32_t ip;
- uint32_t mask;
+ uint32_t mask;
};
+ /** \brief The generic vserver syscall
+ * \ingroup syscalls
+ *
+ * This function executes the generic vserver syscall. It uses the
+ * correct syscallnumber (which may differ between the different
+ * architectures).
+ *
+ * \params cmd the command to be executed
+ * \params xid the xid on which the cmd shall be applied
+ * \params data additional arguments; depends on \c cmd
+ * \returns depends on \c cmd; usually, -1 stands for an error
+ */
+ int vc_syscall(uint32_t cmd, xid_t xid, void *data);
+
/** \brief Returns the version of the current kernel API.
- \returns The versionnumber of the kernel API
+ * \ingroup syscalls
+ * \returns The versionnumber of the kernel API
*/
int vc_get_version();
/** \brief Moves current process into a context
+ * \ingroup syscalls
*
* Puts current process into context \a ctx, removes the capabilities
* given in \a remove_cap and sets \a flags.
@@ -176,11 +248,21 @@ extern "C" {
xid_t vc_new_s_context(xid_t ctx, unsigned int remove_cap, unsigned int flags);
/** \brief Sets the ipv4root information.
+ * \ingroup syscalls
* \pre \a nb < NB_IPV4ROOT && \a ips != 0 */
int vc_set_ipv4root(uint32_t bcast, size_t nb,
struct vc_ip_mask_pair const *ips) VC_ATTR_NONNULL((3));
+ /** \brief Returns the value of NB_IPV4ROOT.
+ * \ingroup helper
+ *
+ * This function returns the value of NB_IPV4ROOT which was used when the
+ * library was built, but \b not the value which is used by the currently
+ * running kernel. */
+ size_t vc_get_nb_ipv4root() VC_ATTR_CONST VC_ATTR_PURE;
+
/** \brief Creates a context without starting it.
+ * \ingroup syscalls
*
* This functions initializes a new context. When already in a freshly
* created context, this old context will be discarded.
@@ -190,30 +272,46 @@ extern "C" {
*
* \returns the xid of the created context, or VC_NOCTX on errors. errno
* will be set appropriately. */
- xid_t vc_create_context(xid_t xid);
+ xid_t vc_ctx_create(xid_t xid);
/** \brief Moves the current process into the specified context.
+ * \ingroup syscalls
*
* \param xid The new context
* \returns 0 on success, -1 on errors */
- int vc_migrate_context(xid_t xid);
+ int vc_ctx_migrate(xid_t xid);
/* rlimit related functions */
+
+ /** \brief The type which is used for a single limit value.
+ *
+ * Special values are
+ * - VC_LIM_INFINITY ... which is the infinite value
+ * - VC_LIM_KEEP ... which is used to mark values which shall not be
+ * modified by the vc_set_rlimit() operation.
+ *
+ * Else, the interpretation of the value depends on the corresponding
+ * resource; it might be bytes, pages, seconds or litres of beer. */
typedef uint_least64_t vc_limit_t;
-
+
+ /** \brief The limits of a resources.
+ *
+ * This is a triple consisting of a minimum, soft and hardlimit. */
struct vc_rlimit {
- vc_limit_t min; //< the guaranted minimum of a resources
- vc_limit_t soft; //< the softlimit of a resource
- vc_limit_t hard; //< the absolute hardlimit of a resource
+ vc_limit_t min; ///< the guaranted minimum of a resources
+ vc_limit_t soft; ///< the softlimit of a resource
+ vc_limit_t hard; ///< the absolute hardlimit of a resource
};
+ /** \brief Masks describing the supported limits. */
struct vc_rlimit_mask {
- uint_least32_t min; //< mask of resources supporting a minimum limit
- uint_least32_t soft; //< mask of resources supporting a soft limit
- uint_least32_t hard; //< mask of resources supporting a hard limit
+ uint_least32_t min; ///< masks the resources supporting a minimum limit
+ uint_least32_t soft; ///< masks the resources supporting a soft limit
+ uint_least32_t hard; ///< masks the resources supporting a hard limit
};
- /** \brief Returns the current limits of \a resource.
+ /** \brief Returns the limits of \a resource.
+ * \ingroup syscalls
*
* \param xid The id of the context
* \param resource The resource which will be queried
@@ -222,20 +320,90 @@ extern "C" {
* \returns 0 on success, and -1 on errors. */
int vc_get_rlimit(xid_t xid, int resource,
struct vc_rlimit /*@out@*/ *lim) VC_ATTR_NONNULL((3));
+ /** \brief Sets the limits of \a resource.
+ * \ingroup syscalls
+ *
+ * \param xid The id of the context
+ * \param resource The resource which will be queried
+ * \param lim The new limits
+ *
+ * \returns 0 on success, and -1 on errors. */
int vc_set_rlimit(xid_t xid, int resource,
struct vc_rlimit const /*@in@*/ *lim) VC_ATTR_NONNULL((3));
int vc_get_rlimit_mask(xid_t xid,
struct vc_rlimit_mask *lim) VC_ATTR_NONNULL((2));
- bool vc_parseLimit(char const *str, vc_limit_t *res) VC_ATTR_NONNULL((1,2));
+ /** \brief Parses a string describing a limit
+ * \ingroup helper
+ *
+ * This function parses \a str and interprets special words like \p "inf"
+ * or suffixes. Valid suffixes are
+ * - \p k ... 1000
+ * - \p m ... 1000000
+ * - \p K ... 1024
+ * - \p M ... 1048576
+ *
+ * \param str The string which shall be parsed
+ * \param res Will be filled with the interpreted value; in errorcase,
+ * this value is undefined.
+ *
+ * \returns \a true, iff the string \a str could be parsed. \a res will
+ * be filled with the interpreted value in this case.
+ *
+ * \pre \a str!=0 && \a res!=0
+ */
+ bool vc_parseLimit(char const /*@in@*/ *str, vc_limit_t /*@out@*/ *res) VC_ATTR_NONNULL((1,2));
- /** sends a signal to a context/pid
- Special values for pid are:
- * -1 which means every process in ctx except the init-process
- * 0 which means every process in ctx inclusive the init-process */
+ /** \brief Sends a signal to a context/pid
+ * \ingroup syscalls
+ *
+ * Special values for \a pid are:
+ * - -1 which means every process in ctx except the init-process
+ * - 0 which means every process in ctx inclusive the init-process */
int vc_ctx_kill(xid_t ctx, pid_t pid, int sig);
+ struct vc_nx_info {
+ nid_t nid;
+ };
+
+ nid_t vc_get_task_nid(pid_t pid);
+ int vc_get_nx_info(nid_t nid, struct vc_nx_info *) VC_ATTR_NONNULL((2));
+
+ typedef enum { vcNET_IPV4, vcNET_IPV6, vcNET_IPV4R, vcNET_IPV6R } vc_net_nx_type;
+
+ struct vc_net_nx {
+ vc_net_nx_type type;
+ size_t count;
+ uint32_t ip;
+ uint32_t mask;
+ };
+
+ nid_t vc_net_create(nid_t nid);
+ int vc_net_migrate(nid_t nid);
+
+ int vc_net_add(nid_t nid, struct vc_net_nx const *info);
+ int vc_net_remove(nid_t nid, struct vc_net_nx const *info);
+
+ struct vc_net_flags {
+ uint_least64_t flagword;
+ uint_least64_t mask;
+ };
+
+ int vc_get_nflags(nid_t, struct vc_net_flags *);
+ int vc_set_nflags(nid_t, struct vc_net_flags const *);
+
+
+ struct vc_net_caps {
+ uint_least64_t ncaps;
+ uint_least64_t cmask;
+ };
+
+ int vc_get_ncaps(nid_t, struct vc_net_caps *);
+ int vc_set_ncaps(nid_t, struct vc_net_caps const *);
+
+
+
int vc_set_iattr(char const *filename, xid_t xid,
uint_least32_t flags, uint_least32_t mask) VC_ATTR_NONNULL((1));
@@ -248,7 +416,12 @@ extern "C" {
pid_t initpid;
};
- /** Returns the context of the given process. pid==0 means the current process. */
+ /** \brief Returns the context of the given process.
+ *
+ * \params pid the process-id whose xid shall be determined;
+ * pid==0 means the current process.
+ * \returns the xid of process \c pid or -1 on errors
+ */
xid_t vc_get_task_xid(pid_t pid);
int vc_get_vx_info(xid_t xid, struct vc_vx_info *info) VC_ATTR_NONNULL((2));
@@ -262,38 +435,113 @@ extern "C" {
int vc_get_vhi_name(xid_t xid, vc_uts_type type,
char *val, size_t len) VC_ATTR_NONNULL((3));
+ /** Returns true iff \a xid is a dynamic xid */
+ bool vc_is_dynamic_xid(xid_t xid);
int vc_enter_namespace(xid_t xid);
int vc_set_namespace();
int vc_cleanup_namespace();
+
+ /** \brief Flags of process-contexts
+ */
struct vc_ctx_flags {
+ /** \brief Mask of set context flags */
uint_least64_t flagword;
+ /** \brief Mask of set and unset context flags when used by set
+ * operations, or modifiable flags when used by get
+ * operations */
uint_least64_t mask;
};
-
+
+ /** \brief Capabilities of process-contexts */
struct vc_ctx_caps {
+ /** \brief Mask of set common system capabilities */
uint_least64_t bcaps;
+ /** \brief Mask of set and unset common system capabilities when used by
+ * set operations, or the modifiable capabilities when used by
+ * get operations */
+ uint_least64_t bmask;
+ /** \brief Mask of set process context capabilities */
uint_least64_t ccaps;
+ /** \brief Mask of set and unset process context capabilities when used
+ * by set operations, or the modifiable capabilities when used
+ * by get operations */
uint_least64_t cmask;
};
+ /** \brief Information about parsing errors
+ * \ingroup helper
+ */
struct vc_err_listparser {
- char const *ptr;
- size_t len;
+ char const *ptr; ///< Pointer to the first character of an erroneous string
+ size_t len; ///< Length of the erroneous string
};
- int vc_get_flags(xid_t xid, struct vc_ctx_flags *) VC_ATTR_NONNULL((2));
- int vc_set_flags(xid_t xid, struct vc_ctx_flags const *) VC_ATTR_NONNULL((2));
+ int vc_get_cflags(xid_t xid, struct vc_ctx_flags *) VC_ATTR_NONNULL((2));
+ int vc_set_cflags(xid_t xid, struct vc_ctx_flags const *) VC_ATTR_NONNULL((2));
int vc_get_ccaps(xid_t xid, struct vc_ctx_caps *);
int vc_set_ccaps(xid_t xid, struct vc_ctx_caps const *);
- uint_least64_t vc_text2bcap(char const *, size_t len);
- char const * vc_lobcap2text(uint_least64_t *);
- int vc_list2bcap(char const *, size_t len,
+ /** \brief Converts a single string into bcapability
+ * \ingroup helper
+ *
+ * \param str The string to be parsed;
+ * both "CAP_xxx" and "xxx" will be accepted
+ * \param len The length of the string, or \c 0 for automatic detection
+ *
+ * \returns 0 on error; a bitmask on success
+ * \pre \a str != 0
+ */
+ uint_least64_t vc_text2bcap(char const *str, size_t len);
+
+ /** \brief Converts the lowest bit of a bcapability or the entire value
+ * (when possible) to a textual representation
+ * \ingroup helper
+ *
+ * \param val The string to be converted; on success, the detected bit(s)
+ * will be unset, in errorcase only the lowest set bit
+ *
+ * \returns A textual representation of \a val resp. of its lowest set bit;
+ * or \c NULL in errorcase.
+ * \pre \a val!=0
+ * \post \a *valold \c != 0 \c <-->
+ * \a *valold > \a *valnew
+ * \post \a *valold \c == 0 \c ---> \a result == 0
+ */
+ char const * vc_lobcap2text(uint_least64_t *val) VC_ATTR_NONNULL((1));
+
+ /** \brief Converts a string into a bcapability-bitmask
+ * \ingroup helper
+ *
+ * Syntax of \a str: \verbinclude list2xxx.syntax
+ *
+ * When the \c `~' prefix is used, the bits will be unset and a `~' after
+ * another `~' will cancel both ones. The \c `^' prefix specifies a
+ * bitnumber instead of a bitmask.
+ *
+ * "literal name" is everything which will be accepted by the
+ * vc_text2bcap() function. The special values for \c NAME will be
+ * recognized case insensitively
+ *
+ * \param str The string to be parsed
+ * \param len The length of the string, or \c 0 for automatic detection
+ * \param err Pointer to a structure for error-information, or \c NULL.
+ * \param cap Pointer to a vc_ctx_caps structure holding the results;
+ * only the \a bcaps and \a bmask fields will be changed and
+ * already set values will not be honored. When an error
+ * occured, \a cap will have the value of all processed valid
+ * \c BCAP parts.
+ *
+ * \returns 0 on success, -1 on error. In error case, \a err will hold
+ * position and length of the first not understood BCAP part
+ * \pre \a str != 0 && \a cap != 0;
+ * \a cap->bcaps and \a cap->bmask must be initialized
+ */
+ int vc_list2bcap(char const *str, size_t len,
struct vc_err_listparser *err,
- struct vc_ctx_caps *);
+ struct vc_ctx_caps *cap) VC_ATTR_NONNULL((1,4));
uint_least64_t vc_text2ccap(char const *, size_t len);
char const * vc_loccap2text(uint_least64_t *);
@@ -301,36 +549,43 @@ extern "C" {
struct vc_err_listparser *err,
struct vc_ctx_caps *);
- int vc_list2flag(char const *, size_t len,
+ int vc_list2cflag(char const *, size_t len,
struct vc_err_listparser *err,
struct vc_ctx_flags *flags);
- uint_least64_t vc_text2flag(char const *, size_t len);
- char const * vc_loflag2text(uint_least64_t *);
+ uint_least64_t vc_text2cflag(char const *, size_t len);
+ char const * vc_locflag2text(uint_least64_t *);
- uint_least32_t vc_list2flag_compat(char const *, size_t len,
+ uint_least32_t vc_list2cflag_compat(char const *, size_t len,
struct vc_err_listparser *err);
- uint_least32_t vc_text2flag_compat(char const *, size_t len);
- char const * vc_hiflag2text_compat(uint_least32_t);
+ uint_least32_t vc_text2cflag_compat(char const *, size_t len);
+ char const * vc_hicflag2text_compat(uint_least32_t);
+
+ int vc_text2cap(char const *);
+ char const * vc_cap2text(unsigned int);
+
- int vc_text2cap(char const *);
- char const * vc_cap2text(unsigned int);
-
- inline static uint_least32_t vc_get_securecaps() {
- return ( (1<